isaacscript-common 84.0.0 → 84.1.0

package/dist/classes/DefaultMap.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultMap = void 0;
+const types_1 = require("../functions/types");
+/**
+ * `DefaultMap` is a data structure that makes working with default values easier. It extends a
+ * `Map` and adds additional methods.
+ *
+ * It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
+ * a default value for the key, and then return the default value. `DefaultMap` abstracts this
+ * operation away by providing the `getAndSetDefault` method.
+ *
+ * Using a `DefaultMap` is nice because it makes code more declarative, since you specify what the
+ * default value is alongside the types of the keys/values.
+ *
+ * When instantiating a new `DefaultMap`, you must specify default value as the first argument. (The
+ * default value is the initial value that will be assigned to every new entry in the
+ * `getAndSetDefault` method.) For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value of "foo".
+ * const defaultMapWithString = new DefaultMap<string, string>("foo");
+ *
+ * const value = defaultMapWithString.getAndSetDefault("bar");
+ * // value is now "foo" and an entry for "bar" is now set.
+ * ```
+ *
+ * Sometimes, instead of having a static initial value for every entry in the map, you will want a
+ * dynamic initial value that is contingent upon the key or some other variable. In these cases, you
+ * can instead specify that the `DefaultMap` should run a function that will return the initial
+ * value. (This is referred to as a "factory function".) For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
+ * const factoryFunction = () => someGlobalVariable ? 0 : 1;
+ * const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);
+ * ```
+ *
+ * Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means
+ * that when the `DefaultMap` creates a new entry, if the default value is one of these 3 types, the
+ * values will be copied. On the other hand, arrays and maps and other complex data structures are
+ * "passed by reference". This means that when the `DefaultMap` creates a new entry, if the default
+ * value is an array, then it would not be copied. Instead, the same shared array would be assigned
+ * to every entry. Thus, to solve this problem, any variable that is passed by reference must be
+ * created using a factory function to ensure that each copy is unique. For example:
+ *
+ * ```ts
+ * // Initializes a new empty DefaultMap with a default value of a new empty array.
+ * const factoryFunction = () => [];
+ * const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
+ * ```
+ *
+ * In the previous two examples, the factory functions did not have any arguments. But you can also
+ * specify a factory function that takes one or more arguments:
+ *
+ * ```ts
+ * const factoryFunction = (arg: boolean) => arg ? 0 : 1;
+ * const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+ * ```
+ *
+ * Similar to a normal `Map`, you can also include an initializer list in the constructor as the
+ * second argument:
+ *
+ * ```ts
+ * // Initializes a DefaultMap with a default value of "foo" and some initial values.
+ * const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
+ *   ["a1", "a2"],
+ *   ["b1", "b2"],
+ * ], );
+ * ```
+ *
+ * Finally, note that `DefaultMap` has the following additional utility methods:
+ *
+ * - `getAndSetDefault` - The method that is called inside the overridden `get` method. In most
+ *   cases, you can use the overridden `get` method instead of calling this function directly.
+ *   However, if a factory function was provided during instantiation, and the factory function has
+ *   one or more arguments, then you must call this method instead (and provide the corresponding
+ *   arguments).
+ * - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
+ *   was provided during instantiation, this will execute the factory function.)
+ * - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
+ *   the reference to the factory function.
+ */
+class DefaultMap extends Map {
+    defaultValue;
+    defaultValueFactory;
+    /**
+     * See the main `DefaultMap` documentation:
+     * https://isaacscript.github.io/isaacscript-common/other/classes/DefaultMap
+     */
+    constructor(defaultValueOrFactoryFunction, initializerArray) {
+        const argIsPrimitive = (0, types_1.isPrimitive)(defaultValueOrFactoryFunction);
+        const argIsFunction = (0, types_1.isFunction)(defaultValueOrFactoryFunction);
+        if (!argIsPrimitive && !argIsFunction) {
+            error(`Failed to instantiate a DefaultMap since the provided default value was of type "${typeof defaultValueOrFactoryFunction}". This error usually means that you are trying to use an array (or some other non-primitive data structure that is passed by reference) as the default value. Instead, return the data structure in a factory function, like "() => []". See the DefaultMap documentation for more details.`);
+        }
+        super(initializerArray);
+        if (argIsFunction) {
+            this.defaultValue = undefined;
+            this.defaultValueFactory = defaultValueOrFactoryFunction;
+        }
+        else {
+            this.defaultValue = defaultValueOrFactoryFunction;
+            this.defaultValueFactory = undefined;
+        }
+    }
+    /**
+     * If the key exists, this will return the same thing as the normal `Map.get` method. Otherwise,
+     * it will set a default value for the provided key, and then return the default value.
+     *
+     * @allowEmptyVariadic
+     */
+    getAndSetDefault(key, ...args) {
+        const value = super.get(key);
+        if (value !== undefined) {
+            return value;
+        }
+        const defaultValue = this.getDefaultValue(...args);
+        this.set(key, defaultValue);
+        return defaultValue;
+    }
+    /**
+     * Returns the default value to be used for a new key. (If a factory function was provided during
+     * instantiation, this will execute the factory function.)
+     */
+    getDefaultValue(...args) {
+        if (this.defaultValue !== undefined) {
+            return this.defaultValue;
+        }
+        if (this.defaultValueFactory !== undefined) {
+            return this.defaultValueFactory(...args);
+        }
+        error("A DefaultMap was incorrectly instantiated.");
+    }
+    /**
+     * Helper method for cloning the map. Returns either the default value or a reference to the
+     * factory function.
+     */
+    getConstructorArg() {
+        if (this.defaultValue !== undefined) {
+            return this.defaultValue;
+        }
+        if (this.defaultValueFactory !== undefined) {
+            return this.defaultValueFactory;
+        }
+        error("A DefaultMap was incorrectly instantiated.");
+    }
+}
+exports.DefaultMap = DefaultMap;
+/* eslint-disable @typescript-eslint/no-unused-vars */
+function test() {
+    // Boolean
+    const myDefaultMapBoolean = new DefaultMap(false);
+    const myDefaultMapBooleanFactory = new DefaultMap(() => false);
+    const myDefaultMapBooleanWithoutParams = new DefaultMap(false);
+    // Number
+    const myDefaultMapNumber = new DefaultMap(123);
+    const myDefaultMapNumberFactory = new DefaultMap(() => 123);
+    const myDefaultMapNumberWithoutParams = new DefaultMap(123);
+    // String
+    const myDefaultMapString = new DefaultMap("foo");
+    const myDefaultMapStringFactory = new DefaultMap(() => "foo");
+    const myDefaultMapStringWithoutParams = new DefaultMap("foo");
+    // Array
+    const myDefaultMapArray = new DefaultMap(() => []);
+    const myDefaultMapArrayWithoutParams = new DefaultMap(() => []);
+    // Map
+    const myDefaultMapMap = new DefaultMap(() => new Map());
+    const myDefaultMapMapWithoutParams = new DefaultMap(() => new Map());
+}
+/* eslint-enable @typescript-eslint/no-unused-vars */

package/dist/classes/ModFeature.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModFeature = exports.MOD_FEATURE_CUSTOM_CALLBACKS_KEY = exports.MOD_FEATURE_CALLBACKS_KEY = void 0;
+const array_1 = require("../functions/array");
+const tstlClass_1 = require("../functions/tstlClass");
+const types_1 = require("../functions/types");
+const utils_1 = require("../functions/utils");
+exports.MOD_FEATURE_CALLBACKS_KEY = "__callbacks";
+exports.MOD_FEATURE_CUSTOM_CALLBACKS_KEY = "__customCallbacks";
+const WRAPPED_CALLBACK_METHODS_KEY = "__wrappedCallbackMethods";
+const WRAPPED_CUSTOM_CALLBACK_METHODS_KEY = "__wrappedCustomCallbacksMethods";
+/**
+ * Helper class for mods that want to represent their individual features as classes. Extend your
+ * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
+ * that automatically subscribe to callbacks.
+ *
+ * It is recommended that you use the `initModFeatures` helper function to instantiate all of your
+ * mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
+ * are properly registered with the save data manager; see below.
+ *
+ * If you are manually instantiating a mod feature yourself, then:
+ *
+ * - You must pass your upgraded mod as the first argument to the constructor.
+ * - In almost all cases, you will want the callback functions to be immediately subscribed after
+ *   instantiating the class. However, if this is not the case, you can pass `false` as the optional
+ *   second argument to the constructor.
+ *
+ * If your mod feature has a property called `v`, it will be assumed that these are variables that
+ * should be managed by the save data manager. Unfortunately, due to technical limitations with
+ * classes, this registration will only occur if you initialize the class with the `initModFeatures`
+ * helper function. (This is because the parent class does not have access to the child's properties
+ * upon first construction.)
+ */
+class ModFeature {
+    mod;
+    /**
+     * An optional method that allows for conditional callback execution. If specified, any class
+     * method that is annotated with a `@Callback` or `@CallbackCustom` decorator will only be fired
+     * if the executed conditional function returns true.
+     *
+     * This property is used to easily turn entire mod features on and off (rather than repeating
+     * conditional logic and early returning at the beginning of every callback function).
+     *
+     * Since the specific information for the firing callback is passed as arguments into the
+     * conditional method, you can also write logic that would only apply to a specific type of
+     * callback.
+     *
+     * By default, this is set to null, which means that all callback methods will fire
+     * unconditionally. Override this property in your class if you need to use it.
+     *
+     * The function has the following signature:
+     *
+     * ```ts
+     * <T extends boolean>(
+     *   vanilla: T, // Whether this is a vanilla or custom callback.
+     *   modCallback: T extends true ? ModCallback : ModCallbackCustom,
+     *   ...callbackArgs: unknown[] // This would be e.g. `pickup: EntityPickup` for the `POST_PICKUP_INIT` callback.
+     * ) => boolean;
+     * ```
+     */
+    shouldCallbackMethodsFire = null;
+    /**
+     * Whether the feature has registered its callbacks yet.
+     *
+     * This will almost always be equal to true unless you explicitly passed `false` to the second
+     * argument of the constructor.
+     */
+    initialized = false;
+    constructor(mod, init = true) {
+        this.mod = mod;
+        if (init) {
+            this.init();
+        }
+    }
+    /**
+     * Runs the `Mod.AddCallback` and `ModUpgraded.AddCallbackCustom` methods for all of the decorated
+     * callbacks. Also registers/unregisters the "v" variable on the save data manager.
+     *
+     * @param init Optional. Whether to initialize or uninitialize. Default is true.
+     */
+    init(init = true) {
+        if (this.initialized === init) {
+            return;
+        }
+        this.initialized = init;
+        const constructor = (0, tstlClass_1.getTSTLClassConstructor)(this);
+        (0, utils_1.assertDefined)(constructor, "Failed to get the TSTL class constructor for a mod feature.");
+        const tstlClassName = (0, tstlClass_1.getTSTLClassName)(this);
+        (0, utils_1.assertDefined)(tstlClassName, "Failed to get the TSTL class name for a mod feature.");
+        initDecoratedCallbacks(this, constructor, tstlClassName, true, init);
+        initDecoratedCallbacks(this, constructor, tstlClassName, false, init);
+        initSaveDataManager(this, tstlClassName, init);
+    }
+    /**
+     * Runs the `Mod.RemoveCallback` and `ModUpgraded.RemoveCallbackCustom` methods for all of the
+     * decorated callbacks.
+     *
+     * This is just an alias for `ModFeature.init(false)`.
+     */
+    uninit() {
+        this.init(false);
+    }
+}
+exports.ModFeature = ModFeature;
+function initDecoratedCallbacks(modFeature, constructor, tstlClassName, vanilla, init) {
+    const modFeatureConstructor = constructor;
+    const callbackTuplesKey = vanilla
+        ? exports.MOD_FEATURE_CALLBACKS_KEY
+        : exports.MOD_FEATURE_CUSTOM_CALLBACKS_KEY;
+    const callbackTuples = modFeatureConstructor[callbackTuplesKey];
+    if (callbackTuples === undefined) {
+        return;
+    }
+    if (!(0, array_1.isArray)(callbackTuples)) {
+        error(`Failed to initialize/uninitialize the decorated callbacks on a mod feature since the callback arguments on the key of "${callbackTuplesKey}" was not an array and was instead of type: ${type(callbackTuples)}`);
+    }
+    for (const callbackTuple of callbackTuples) {
+        if (!(0, array_1.isArray)(callbackTuple)) {
+            error(`Failed to initialize/uninitialize the decorated callbacks on a mod feature since one of the callback arguments on the key of "${callbackTuplesKey}" was not an array and was instead of type: ${type(callbackTuple)}`);
+        }
+        const modCallback = callbackTuple[0];
+        if (!(0, types_1.isInteger)(modCallback)) {
+            error(`Failed to get the callback number from the callback tuple for class: ${tstlClassName}`);
+        }
+        const priority = callbackTuple[1];
+        if (!(0, types_1.isInteger)(priority)) {
+            error(`Failed to get the callback priority from the callback tuple for class: ${tstlClassName}`);
+        }
+        const callback = callbackTuple[2];
+        if (!(0, types_1.isFunction)(callback)) {
+            error(`Failed to get the callback function from the callback tuple for class: ${tstlClassName}`);
+        }
+        const parameters = callbackTuple[3];
+        // We must pass false as the second argument to `isArray` since the callback parameters may not
+        // necessarily be contiguous. (They might be separated by `undefined` values.)
+        if (!(0, array_1.isArray)(parameters, false)) {
+            error(`Failed to get the callback parameters from the callback tuple for class: ${tstlClassName}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/dot-notation, @typescript-eslint/prefer-destructuring
+        const mod = modFeature["mod"];
+        if (init) {
+            addCallback(modFeature, modFeatureConstructor, mod, modCallback, // eslint-disable-line isaacscript/strict-enums
+            priority, callback, parameters, vanilla);
+        }
+        else {
+            removeCallback(modFeatureConstructor, mod, modCallback, // eslint-disable-line isaacscript/strict-enums
+            vanilla);
+        }
+    }
+}
+function addCallback(modFeature, modFeatureConstructor, mod, modCallback, priority, callback, // eslint-disable-line @typescript-eslint/ban-types
+parameters, vanilla) {
+    // We need to wrap the callback in a new function so that we can explicitly pass the class as the
+    // first argument. (Otherwise, the method will not be able to properly access `this`.
+    const wrappedCallback = (...callbackArgs) => {
+        // eslint-disable-next-line @typescript-eslint/dot-notation
+        const conditionalFunc = modFeature["shouldCallbackMethodsFire"];
+        if (conditionalFunc !== null) {
+            const shouldRun = conditionalFunc(vanilla, modCallback, ...callbackArgs);
+            if (!shouldRun) {
+                return undefined;
+            }
+        }
+        const castedCallback = callback;
+        return castedCallback(modFeature, ...callbackArgs);
+    };
+    // We need to save the wrapped function for later (so we can unregister them).
+    if (vanilla) {
+        const modCallbackVanilla = modCallback;
+        let wrappedMethodsMap = modFeatureConstructor[WRAPPED_CALLBACK_METHODS_KEY];
+        if (wrappedMethodsMap === undefined) {
+            wrappedMethodsMap = new Map();
+            modFeatureConstructor[WRAPPED_CALLBACK_METHODS_KEY] = wrappedMethodsMap;
+        }
+        wrappedMethodsMap.set(modCallbackVanilla, wrappedCallback);
+    }
+    else {
+        const modCallbackCustom = modCallback;
+        let wrappedMethodsMap = modFeatureConstructor[WRAPPED_CUSTOM_CALLBACK_METHODS_KEY];
+        if (wrappedMethodsMap === undefined) {
+            wrappedMethodsMap = new Map();
+            modFeatureConstructor[WRAPPED_CUSTOM_CALLBACK_METHODS_KEY] =
+                wrappedMethodsMap;
+        }
+        wrappedMethodsMap.set(modCallbackCustom, wrappedCallback);
+    }
+    if (vanilla) {
+        mod.AddPriorityCallback(modCallback, priority, wrappedCallback, ...parameters);
+    }
+    else {
+        mod.AddPriorityCallbackCustom(modCallback, priority, wrappedCallback, ...parameters);
+    }
+}
+function removeCallback(modFeatureConstructor, mod, modCallback, vanilla) {
+    if (vanilla) {
+        const modCallbackVanilla = modCallback;
+        const wrappedMethodsMap = modFeatureConstructor[WRAPPED_CALLBACK_METHODS_KEY];
+        if (wrappedMethodsMap === undefined) {
+            return;
+        }
+        const wrappedCallback = wrappedMethodsMap.get(modCallbackVanilla);
+        mod.RemoveCallback(modCallback, wrappedCallback);
+    }
+    else {
+        const modCallbackCustom = modCallback;
+        const wrappedMethodsMap = modFeatureConstructor[WRAPPED_CUSTOM_CALLBACK_METHODS_KEY];
+        if (wrappedMethodsMap === undefined) {
+            return;
+        }
+        const wrappedCallback = wrappedMethodsMap.get(modCallbackCustom);
+        mod.RemoveCallbackCustom(modCallback, wrappedCallback);
+    }
+}
+/**
+ * This will only work for end-users who are calling the `ModFeature.init` method explicitly. (See
+ * the discussion in the `ModFeature` comment.)
+ */
+function initSaveDataManager(modFeature, tstlClassName, init) {
+    // Do nothing if this class does not have any variables.
+    const { v } = modFeature;
+    if (v === undefined) {
+        return;
+    }
+    if (!(0, types_1.isTable)(v)) {
+        error('Failed to initialize a mod feature class due to having a "v" property that is not an object. (The "v" property is supposed to be an object that holds the variables for the class, managed by the save data manager.)');
+    }
+    // Do nothing if we have not enabled the save data manager.
+    // eslint-disable-next-line @typescript-eslint/dot-notation
+    const mod = modFeature["mod"];
+    const saveDataManagerMethodName = init
+        ? "saveDataManager"
+        : "saveDataManagerRemove";
+    const saveDataManagerMethod = mod[saveDataManagerMethodName];
+    (0, utils_1.assertDefined)(saveDataManagerMethod, 'Failed to initialize a mod feature class due to having a "v" object and not having the save data manager initialized. You must pass "ISCFeature.SAVE_DATA_MANAGER" to the "upgradeMod" function.');
+    if (typeof saveDataManagerMethod !== "function") {
+        error(`The "${saveDataManagerMethodName}" property of the "ModUpgraded" object was not a function.`);
+    }
+    if (init) {
+        saveDataManagerMethod(tstlClassName, v);
+    }
+    else {
+        saveDataManagerMethod(tstlClassName);
+    }
+}