isaacscript-common
Version:
Helper functions and features for IsaacScript mods.
163 lines • 7.65 kB
TypeScript
/**
* In Lua, tables can have number keys, but since this is a type only being validated in TypeScript,
* we can match the JavaScript definition, meaning that we can omit the number from the keys.
*/
export type TranspiledEnum = Record<string, string | number | BitFlag | BitFlag128>;
/**
* TypeScriptToLua will transpile TypeScript number enums to Lua tables that have a double mapping.
* Thus, when you iterate over them, you will get both the names of the enums and the values of the
* enums, in a random order. Use this helper function to get the entries of the enum with the
* reverse mappings filtered out.
*
* This function will return the enum values in a sorted order, which may not necessarily be the
* same order as which they were declared in. (It is impossible to get the declaration order at
* run-time.)
*
* This function will work properly for both number enums and string enums. (Reverse mappings are
* not created for string enums.)
*
* Also see the `getEnumKeys` and `getEnumValues` helper functions.
*
* For a more in depth explanation, see:
* https://isaacscript.github.io/main/gotchas#iterating-over-enums
*/
export declare function getEnumEntries<T extends TranspiledEnum>(transpiledEnum: T): ReadonlyArray<[key: string, value: T[keyof T]]>;
/**
* TypeScriptToLua will transpile TypeScript number enums to Lua tables that have a double mapping.
* Thus, when you iterate over them, you will get both the names of the enums and the values of the
* enums, in a random order. If all you need are the keys of an enum, use this helper function.
*
* This function will return the enum keys in a sorted order, which may not necessarily be the same
* order as which they were declared in. (It is impossible to get the declaration order at
* run-time.)
*
* This function will work properly for both number enums and string enums. (Reverse mappings are
* not created for string enums.)
*
* Also see the `getEnumEntries` and `getEnumValues` helper functions.
*
* For a more in depth explanation, see:
* https://isaacscript.github.io/main/gotchas#iterating-over-enums
*/
export declare function getEnumKeys(transpiledEnum: TranspiledEnum): readonly string[];
/** Helper function to get the amount of entries inside of an enum. */
export declare function getEnumLength(transpiledEnum: TranspiledEnum): int;
/**
* TypeScriptToLua will transpile TypeScript number enums to Lua tables that have a double mapping.
* Thus, when you iterate over them, you will get both the names of the enums and the values of the
* enums, in a random order. If all you need are the names of an enum from the reverse mapping, use
* this helper function.
*
* This function will return the enum names in a sorted order, which may not necessarily be the same
* order as which they were declared in. (It is impossible to get the declaration order at
* run-time.)
*
* This function will work properly for both number enums and string enums. (Reverse mappings are
* not created for string enums, so their names would be equivalent to what would be returned by the
* `getEnumKeys` function.)
*
* For a more in depth explanation, see:
* https://isaacscript.github.io/main/gotchas#iterating-over-enums
*/
export declare function getEnumNames(transpiledEnum: TranspiledEnum): readonly string[];
/**
* TypeScriptToLua will transpile TypeScript number enums to Lua tables that have a double mapping.
* Thus, when you iterate over them, you will get both the names of the enums and the values of the
* enums, in a random order. If all you need are the values of an enum, use this helper function.
*
* This function will return the enum values in a sorted order, which may not necessarily be the
* same order as which they were declared in. (It is impossible to get the declaration order at
* run-time.)
*
* This function will work properly for both number enums and string enums. (Reverse mappings are
* not created for string enums.)
*
* Also see the `getEnumEntries` and `getEnumKeys` helper functions.
*
* For a more in depth explanation, see:
* https://isaacscript.github.io/main/gotchas#iterating-over-enums
*/
export declare function getEnumValues<T extends TranspiledEnum>(transpiledEnum: T): ReadonlyArray<T[keyof T]>;
/**
* Helper function to get the enum value with the highest value.
*
* Note that this is not necessarily the enum value that is declared last in the code, since there
* is no way to infer that at run-time.
*
* Throws an error if the provided enum is empty.
*/
export declare function getHighestEnumValue<T extends TranspiledEnum>(transpiledEnum: T): T[keyof T];
/**
* Helper function to get the enum value with the lowest value.
*
* Note that this is not necessarily the enum value that is declared first in the code, since there
* is no way to infer that at run-time.
*
* Throws an error if the provided enum is empty.
*/
export declare function getLowestEnumValue<T extends TranspiledEnum>(transpiledEnum: T): T[keyof T];
/**
* Helper function to get a random value from the provided enum.
*
* If you want an unseeded value, you must explicitly pass `undefined` to the `seedOrRNG` parameter.
*
* @param transpiledEnum The enum to get the value from.
* @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
* `RNG.Next` method will be called. If `undefined` is provided, it will default to
* a random seed.
* @param exceptions Optional. An array of elements to skip over if selected.
*/
export declare function getRandomEnumValue<T extends TranspiledEnum>(transpiledEnum: T, seedOrRNG: Seed | RNG | undefined, exceptions?: ReadonlyArray<T[keyof T]>): T[keyof T];
/**
* Helper function to validate that an interface contains all of the keys of an enum. You must
* specify both generic parameters in order for this to work properly (i.e. the interface and then
* the enum).
*
* For example:
*
* ```ts
* enum MyEnum {
* Value1,
* Value2,
* Value3,
* }
*
* interface MyEnumToType {
* [MyEnum.Value1]: boolean;
* [MyEnum.Value2]: number;
* [MyEnum.Value3]: string;
* }
*
* interfaceSatisfiesEnum<MyEnumToType, MyEnum>();
* ```
*
* This function is only meant to be used with interfaces (i.e. types that will not exist at
* run-time). If you are generating an object that will contain all of the keys of an enum, use the
* `satisfies` operator with the `Record` type instead.
*/
export declare function interfaceSatisfiesEnum<T extends Record<Enum, unknown>, Enum extends string | number>(): void;
/** Helper function to validate that a particular value exists inside of an enum. */
export declare function isEnumValue<T extends TranspiledEnum>(value: number | string | BitFlag | BitFlag128, transpiledEnum: T): value is T[keyof T];
/**
* Helper function to check every value of a custom enum for -1. Will throw an run-time error if any
* -1 values are found. This is helpful because many methods of the Isaac class return -1 if they
* fail.
*
* For example:
*
* ```ts
* enum EntityTypeCustom {
* FOO = Isaac.GetEntityTypeByName("Foo"),
* }
*
* validateCustomEnum("EntityTypeCustom", EntityTypeCustom);
* ```
*/
export declare function validateCustomEnum(transpiledEnumName: string, transpiledEnum: TranspiledEnum): void;
/**
* Helper function to validate if every value in a number enum is contiguous, starting at 0.
*
* This is useful to automate checking large enums for typos.
*/
export declare function validateEnumContiguous(transpiledEnumName: string, transpiledEnum: TranspiledEnum): void;
//# sourceMappingURL=enums.d.ts.map