isaacscript-common 2.3.1 → 3.1.0

package/callbacks/subscriptions/postPurchase.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postPurchaseHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postPurchaseRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postPurchaseFire(self, player, pickup)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postRockRender.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostRockRenderRegisterParameters = [
     callback: (rock: GridEntityRock) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postRockRender.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postRockRenderHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postRockRenderRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postRockRenderFire(self, rock)
     local gridEntityVariant = rock:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postRockUpdate.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostRockUpdateRegisterParameters = [
     callback: (rock: GridEntityRock) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postRockUpdate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postRockUpdateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postRockUpdateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postRockUpdateFire(self, rock)
     local gridEntityVariant = rock:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postRoomClearChanged.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postRoomClearChangedHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postRoomClearChangedRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postRoomClearChangedFire(self, roomClear)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSacrifice.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSacrificeHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSacrificeRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSacrificeFire(self, player, numSacrifices)
     local character = player:GetPlayerType()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postSlotAnimationChanged.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSlotAnimationChangedHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSlotAnimationChangedRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSlotAnimationChangedFire(self, slot, previousAnimation, currentAnimation)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSlotDestroyed.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSlotDestroyedHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSlotDestroyedRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSlotDestroyedFire(self, slot)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSlotInit.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSlotInitHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSlotInitRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSlotInitFire(self, slot)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSlotRender.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSlotRenderHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSlotRenderRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSlotRenderFire(self, slot)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSlotUpdate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSlotUpdateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSlotUpdateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSlotUpdateFire(self, slot)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postSpikesRender.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostSpikesRenderRegisterParameters = [
     callback: (spikes: GridEntitySpikes) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postSpikesRender.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSpikesRenderHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSpikesRenderRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSpikesRenderFire(self, spikes)
     local gridEntityVariant = spikes:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postSpikesUpdate.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostSpikesUpdateRegisterParameters = [
     callback: (spikes: GridEntitySpikes) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postSpikesUpdate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postSpikesUpdateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postSpikesUpdateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postSpikesUpdateFire(self, spikes)
     local gridEntityVariant = spikes:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postTNTRender.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostTNTRenderRegisterParameters = [
     callback: (tnt: GridEntityTNT) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postTNTRender.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTNTRenderHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTNTRenderRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTNTRenderFire(self, tnt)
     local gridEntityVariant = tnt:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postTNTUpdate.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type PostTNTUpdateRegisterParameters = [
     callback: (tnt: GridEntityTNT) => void,
     gridEntityVariant?: int

package/callbacks/subscriptions/postTNTUpdate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTNTUpdateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTNTUpdateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTNTUpdateFire(self, tnt)
     local gridEntityVariant = tnt:GetVariant()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/postTearInitLate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTearInitLateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTearInitLateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTearInitLateFire(self, tear)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postTearInitVeryLate.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTearInitVeryLateHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTearInitVeryLateRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTearInitVeryLateFire(self, tear)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postTransformation.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTransformationHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTransformationRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTransformationFire(self, player, playerForm, hasForm)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/postTrinketBreak.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.postTrinketBreakHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.postTrinketBreakRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.postTrinketBreakFire(self, player, trinketType)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/preBerserkDeath.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.preBerserkDeathHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.preBerserkDeathRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.preBerserkDeathFire(self, player)
     local character = player:GetPlayerType()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/preCustomRevive.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.preCustomReviveHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.preCustomReviveRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.preCustomReviveFire(self, player)
     local character = player:GetPlayerType()
     for ____, ____value in ipairs(subscriptions) do

package/callbacks/subscriptions/preItemPickup.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.preItemPickupHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.preItemPickupRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.preItemPickupFire(self, player, pickingUpItem)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/callbacks/subscriptions/preNewLevel.lua

@@ -1,12 +1,18 @@
 local ____exports = {}
 local subscriptions = {}
+---
+-- @internal
 function ____exports.preNewLevelHasSubscriptions(self)
     return #subscriptions > 0
 end
+---
+-- @internal
 function ____exports.preNewLevelRegister(self, ...)
     local args = {...}
     subscriptions[#subscriptions + 1] = args
 end
+---
+-- @internal
 function ____exports.preNewLevelFire(self, player)
     for ____, ____value in ipairs(subscriptions) do
         local callback = ____value[1]

package/classes/DefaultMap.d.ts

@@ -1,79 +1,110 @@
 /**
- * A function that creates the value for your default map. For example, if it was a default map
- * containing maps, the factory function would be: `() => new Map()`
+ * A function that creates the default value for your `DefaultMap`. For example, if it was a
+ * `DefaultMap` containing maps, the factory function would be: `() => new Map()`
  */
 export declare type FactoryFunction<V, Args extends unknown[]> = (...extraArgs: Args) => V;
-declare type FirstArg<K, V, Args extends unknown[]> = Iterable<[K, V]> | V | FactoryFunction<V, Args>;
-declare type SecondArg<V, Args extends unknown[]> = V | FactoryFunction<V, Args>;
 /**
- * An extended `Map` with some new methods:
+ * `DefaultMap` is a data structure that makes working with default values easier.
  *
- * - `getAndSetDefault` - If the key exists, this will return the same thing as the `get` method.
- *   Otherwise, it will set a default value to the key, and then return the default value.
- * - `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.
+ * 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.
  *
- * When instantiating a new DefaultMap, you must specify either a default value or a function that
- * returns a default value.
+ * 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.
  *
- * For example:
+ * 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 defaultMapWithPrimitive = new DefaultMap<string, string>("foo");
+ * const defaultMapWithString = new DefaultMap<string, string>("foo");
  *
- * // Initializes a new empty DefaultMap with a default value of a new Map.
- * const defaultMapWithFactory = new DefaultMap<string, Map<string, string>>(() => {
- *   return new Map();
- * })
+ * const value = defaultMapWithString.getAndSetDefault("bar");
+ * // value is now "foo" and an entry for "bar" is now set.
+ * ```
  *
- * // Initializes a DefaultMap with some initial values and a default value of "bar".
- * const defaultMapWithInitialValues = new DefaultMap<string, string>([
- *   ["a1", "a2"],
- *   ["b1", "b2"],
- * ], "bar");
+ * 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);
  * ```
  *
- * If specified, the first argument of a factory function must always be equal to the key:
+ * 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
- * const defaultMapWithConditionalDefaultValue = new DefaultMap<number, number>((key: number) => {
- *   return isOdd(key) ? 0 : 1;
- * });
+ * // Initializes a new empty DefaultMap with a default value of a new empty array.
+ * const factoryFunction = () => [] as ;
+ * const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
  * ```
  *
- * You can also specify a factory function that takes a generic amount of arguments beyond the
- * first:
+ * 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 defaultMapWithExtraArgs = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+ * 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).
+ * - `getWithoutDefault` - Calls the original `Map.get` function (without setting the default
+ *   value).
+ * - `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.
  */
-export declare class DefaultMap<K, V, Args extends unknown[] = []> extends Map<K, V> {
+export declare class DefaultMap<Key, Value, Args extends unknown[] = []> extends Map<Key, Value> {
     private defaultValue;
     private defaultValueFactory;
     /**
      * See the main `DefaultMap` documentation:
      * https://isaacscript.github.io/isaacscript-common/classes/classes_DefaultMap.DefaultMap
      */
-    constructor(iterableOrDefaultValueOrDefaultValueFactory: FirstArg<K, V, Args>, defaultValueOrDefaultValueFactory?: SecondArg<V, Args>);
+    constructor(defaultValueOrFactoryFunction: Value | FactoryFunction<Value, Args>, initializerArray?: Iterable<[Key, Value]>);
     /**
-     * If the key exists, this will return the same thing as the `get` method. Otherwise, it will set
-     * a default value to the key, and then return the default value.
+     * 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.
      */
-    getAndSetDefault(key: K, ...extraArgs: Args): V;
+    getAndSetDefault(key: Key, ...extraArgs: Args): Value;
+    getWithoutDefault(key: Key): Value | undefined;
     /**
      * 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(...extraArgs: Args): V;
+    getDefaultValue(...extraArgs: Args): Value;
     /**
      * Helper method for cloning the map. Returns either the default value or a reference to the
      * factory function.
      */
-    getConstructorArg(): V | FactoryFunction<V, Args>;
+    getConstructorArg(): Value | FactoryFunction<Value, Args>;
 }
-export {};