isaacscript-common 14.1.2 → 14.2.0

package/src/functions/jsonRoom.ts

@@ -19,6 +19,8 @@ interface JSONObject {
 /**
  * Helper function to calculate what the resulting `BitFlags<DoorSlotFlag>` value would be for a
  * given JSON room.
+ *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
  */
 export function getJSONRoomDoorSlotFlags(
   jsonRoom: JSONRoom,
@@ -75,6 +77,8 @@ export function getJSONRoomDoorSlotFlags(
 /**
  * Helper function to find a specific room from an array of JSON rooms.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * @param jsonRooms The array of rooms to search through.
  * @param variant The room variant to select. (The room variant can be thought of as the ID of the
  *                room.)
@@ -107,6 +111,8 @@ export function getJSONRoomOfVariant(
 /**
  * Helper function to find all of the JSON rooms that match the sub-type provided.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * @param jsonRooms The array of rooms to search through.
  * @param subType The sub-type to match.
  */
@@ -124,6 +130,9 @@ export function getJSONRoomsOfSubType(
 /**
  * Helper function to get a random JSON entity from an array of JSON entities.
  *
+ * (A JSON entity is an entity inside of a JSON room. A JSON room is an XML file converted to JSON
+ * so that it can be directly imported into your mod.)
+ *
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers
@@ -163,6 +172,8 @@ export function getRandomJSONEntity(
 /**
  * Helper function to get a random JSON room from an array of JSON rooms.
  *
+ * (A JSON room is an XML file converted to JSON so that it can be directly imported into your mod.)
+ *
  * Note that this function does not simply choose a random element in the provided array; it will
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers

package/src/functions/kColor.ts

@@ -1,5 +1,5 @@
 import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
-import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getRandom } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
@@ -92,8 +92,8 @@ export function isKColor(object: unknown): object is KColor {
 }
 
 /**
- * Used to determine is the given table is a serialized `KColor` object created by the save data
- * manager and/or the `deepCopy` function.
+ * Used to determine is the given table is a serialized `KColor` object created by the `deepCopy`
+ * function.
  */
 export function isSerializedKColor(
   object: unknown,

package/src/functions/logMisc.ts

@@ -307,8 +307,8 @@ export function logSounds(): void {
 }
 
 /**
- * Helper function for logging every key and value of a table. This is a deep log; the function will
- * recursively call itself if it counters a table within a table.
+ * Helper function for logging every key and value of a Lua table. This is a deep log; the function
+ * will recursively call itself if it counters a table within a table.
  *
  * This function will only work on tables that have string keys (because it logs the keys in order,
  * instead of randomly). It will throw a run-time error if it encounters a non-string key.
@@ -399,6 +399,32 @@ export function logTableDifferences<K extends AnyNotNil, V>(
   }
 }
 
+/**
+ * Helper function to log the keys of a Lua table. This is not a deep log; only the keys of the
+ * top-most table will be logged.
+ *
+ * This function is useful for tables that have recursive references.
+ */
+export function logTableKeys(luaTable: unknown): void {
+  log("Printing out the keys of a Lua table:");
+
+  if (!isTable(luaTable)) {
+    log(
+      `  n/a (encountered a variable of type "${typeof luaTable}" instead of a table)`,
+    );
+    return;
+  }
+
+  let numElements = 0;
+  iterateTableInOrder(luaTable, (key) => {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    log(`${key}`);
+    numElements++;
+  });
+
+  log(`  The size of the table was: ${numElements}`);
+}
+
 /** Helper function for printing out every tear flag that is turned on. Useful when debugging. */
 export function logTearFlags(flags: TearFlag | BitFlags<TearFlag>): void {
   logFlags(flags, TearFlag, "tear");

package/src/{features/saveDataManager → functions}/merge.ts

@@ -1,41 +1,55 @@
-import { SerializationBrand } from "../../enums/private/SerializationBrand";
-import { SerializationType } from "../../enums/SerializationType";
-import { isArray } from "../../functions/array";
-import { deepCopy } from "../../functions/deepCopy";
-import { log } from "../../functions/log";
+import { SerializationBrand } from "../enums/SerializationBrand";
+import { SerializationType } from "../enums/SerializationType";
+import { SAVE_DATA_MANAGER_DEBUG } from "../features/saveDataManager/constants";
+import { AnyClass } from "../types/AnyClass";
+import { isArray } from "./array";
+import { deepCopy } from "./deepCopy";
+import { log } from "./log";
 import {
   deserializeIsaacAPIClass,
+  isSerializationBrand,
   isSerializedIsaacAPIClass,
-} from "../../functions/serialization";
-import { clearTable, iterateTableInOrder } from "../../functions/table";
-import { isDefaultMap, isTSTLMap, isTSTLSet } from "../../functions/tstlClass";
-import { isTable } from "../../functions/types";
-import { getTraversalDescription } from "../../functions/utils";
-import { SAVE_DATA_MANAGER_DEBUG } from "./constants";
-import { isSerializationBrand } from "./serializationBrands";
+} from "./serialization";
+import { clearTable, iterateTableInOrder } from "./table";
+import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
+import { isTable } from "./types";
+import { getTraversalDescription } from "./utils";
 
 /**
  * `merge` takes the values from a new table and recursively merges them into an old object (while
  * performing appropriate deserialization).
  *
- * It supports the following object types:
+ * This function is used to merge incoming data from the "save#.dat" file into a mod's variables.
+ * Merging is useful instead of blowing away a table entirely because mod code often relies on the
+ * local table/object references.
  *
- * - Basic TSTL objects / tables
- * - TSTL `Map`
- * - TSTL `Set`
- * - TSTL classes
- * - `DefaultMap`
- * - Isaac `BitSet128` objects
- * - Isaac `Color` objects
- * - Isaac `KColor` objects
- * - Isaac `RNG` objects
- * - Isaac `Vector` objects
+ * This function always assumes that the new table is serialized data and will attempt to perform
+ * deserialization on the objects within. In other words, unlike the `deepCopy` function, the
+ * `merge` function will always operates in the mode of `SerializationType.DESERIALIZE`. For the
+ * types of objects that will be deserialized, see the documentation for the `deepCopy` function.
  *
- * Since it is common for a variable to have a type of `something | null`, we must iterate over the
- * new object and copy over all of the values. (A value of null transpiles to nil, which means the
- * table key does not exist.) The consequence of this is that it can copy over old variables that
- * are no longer used in the code, or copy over old variables of a different type, which can cause
- * run-time errors. In such cases, users will have to manually delete their save data.
+ * This function does not iterate over the old object, like you would naively expect. This is
+ * because it is common for a variable to have a type of `something | null`. If this is the case,
+ * the key would not appear when iterating over the old object (because a value of null transpiles
+ * to nil, which means the table key does not exist). Thus, we must instead iterate over the new
+ * object and copy the values backwards. The consequence of this is that `merge` can copy over old
+ * variables that are no longer used in the code, or copy over old variables of a different type,
+ * which can cause run-time errors. In such cases, users will have to manually delete their save
+ * data.
+ *
+ * @param oldObject The old object to merge the values into. This can be either a Lua table, a TSTL
+ *                  map, or a TSTL set.
+ * @param newTable The new table to merge the values from. This must be a Lua table that represents
+ *                 serialized data. In other words, it should be created with the `deepCopy`
+ *                 function using `SerializationType.SERIALIZE`.
+ * @param traversalDescription Used to track the current key that we are operating on for debugging
+ *                             purposes. Use a name that corresponds to the name of the merging
+ *                             table.
+ * @param classConstructors Optional. A Lua table that maps the name of a user-defined TSTL class to
+ *                          its corresponding constructor. If the `deepCopy` function finds any
+ *                          user-defined TSTL classes when recursively iterating through the given
+ *                          object, it will use this map to instantiate a new class. Default is an
+ *                          empty Lua table.
  */
 export function merge(
   oldObject:
@@ -44,6 +58,7 @@ export function merge(
     | Set<AnyNotNil>,
   newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
+  classConstructors = new LuaMap<string, AnyClass>(),
 ): void {
   if (SAVE_DATA_MANAGER_DEBUG) {
     log(`merge is traversing: ${traversalDescription}`);
@@ -59,16 +74,31 @@ export function merge(
 
   // First, handle the special case of an array with a shallow copy.
   if (isArray(oldObject) && isArray(newTable)) {
-    mergeSerializedArray(oldObject, newTable, traversalDescription);
+    mergeSerializedArray(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
     return;
   }
 
   // Depending on whether we are working on a Lua table or a TypeScriptToLua object, we need to
   // iterate in a specific way.
   if (isTSTLMap(oldObject) || isTSTLSet(oldObject) || isDefaultMap(oldObject)) {
-    mergeSerializedTSTLObject(oldObject, newTable, traversalDescription);
+    mergeSerializedTSTLObject(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
   } else {
-    mergeSerializedTable(oldObject, newTable, traversalDescription);
+    mergeSerializedTable(
+      oldObject,
+      newTable,
+      traversalDescription,
+      classConstructors,
+    );
   }
 }
 
@@ -76,6 +106,7 @@ function mergeSerializedArray(
   oldArray: LuaMap<AnyNotNil, unknown>,
   newArray: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
 ) {
   if (SAVE_DATA_MANAGER_DEBUG) {
     log(`merge encountered an array: ${traversalDescription}`);
@@ -87,7 +118,13 @@ function mergeSerializedArray(
   iterateTableInOrder(
     newArray,
     (key, value) => {
-      oldArray.set(key, value);
+      const deserializedValue = deepCopy(
+        value,
+        SerializationType.DESERIALIZE,
+        traversalDescription,
+        classConstructors,
+      );
+      oldArray.set(key, deserializedValue);
     },
     SAVE_DATA_MANAGER_DEBUG,
   );
@@ -97,6 +134,7 @@ function mergeSerializedTSTLObject(
   oldObject: Map<AnyNotNil, unknown> | Set<AnyNotNil>,
   newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
 ) {
   if (SAVE_DATA_MANAGER_DEBUG) {
     log(`merge encountered a TSTL object: ${traversalDescription}`);
@@ -128,18 +166,13 @@ function mergeSerializedTSTLObject(
       }
 
       if (isTSTLMap(oldObject) || isDefaultMap(oldObject)) {
-        let valueCopy: unknown;
-        if (isTable(value)) {
-          valueCopy = deepCopy(
-            value,
-            SerializationType.DESERIALIZE,
-            traversalDescription,
-          );
-        } else {
-          valueCopy = value;
-        }
-
-        oldObject.set(keyToUse, valueCopy);
+        const deserializedValue = deepCopy(
+          value,
+          SerializationType.DESERIALIZE,
+          traversalDescription,
+          classConstructors,
+        );
+        oldObject.set(keyToUse, deserializedValue);
       } else if (isTSTLSet(oldObject)) {
         oldObject.add(keyToUse);
       }
@@ -152,6 +185,7 @@ function mergeSerializedTable(
   oldTable: LuaMap<AnyNotNil, unknown>,
   newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
+  classConstructors: LuaMap<string, AnyClass>,
 ) {
   if (SAVE_DATA_MANAGER_DEBUG) {
     log(`merge encountered a Lua table: ${traversalDescription}`);
@@ -194,7 +228,7 @@ function mergeSerializedTable(
           key,
           traversalDescription,
         );
-        merge(oldValue, value, traversalDescription);
+        merge(oldValue, value, traversalDescription, classConstructors);
       } else {
         // Base case: copy the value
         oldTable.set(key, value);

package/src/functions/mergeTests.ts

@@ -1,16 +1,15 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { SerializationType } from "../enums/SerializationType";
-import { merge } from "../features/saveDataManager/merge";
 import { deepCopy } from "./deepCopy";
 import { log } from "./log";
+import { merge } from "./merge";
 import { isRNG, newRNG } from "./rng";
 import { isSerializedIsaacAPIClass } from "./serialization";
 import { printConsole } from "./utils";
 import { isVector, serializeVector } from "./vector";
 
 /**
- * Run the suite of tests that prove that the "merge" function works properly. (This function is not
- * exported but is used internally in the save data manager.)
+ * Run the suite of tests that prove that the "merge" function works properly.
  *
  * This function is only useful if you are troubleshooting the save data manager.
  */

package/src/functions/rng.ts

@@ -1,6 +1,6 @@
 import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
-import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
@@ -71,8 +71,8 @@ export function isRNG(object: unknown): object is RNG {
 }
 
 /**
- * Used to determine is the given table is a serialized `RNG` object created by the save data
- * manager and/or the `deepCopy` function.
+ * Used to determine is the given table is a serialized `RNG` object created by the `deepCopy`
+ * function.
  */
 export function isSerializedRNG(object: unknown): object is SerializedRNG {
   if (!isTable(object)) {

package/src/functions/serialization.ts

@@ -1,4 +1,5 @@
 import { CopyableIsaacAPIClassType } from "isaac-typescript-definitions";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { ISAAC_API_CLASS_TYPE_TO_BRAND } from "../objects/isaacAPIClassTypeToBrand";
 import {
   CopyableIsaacAPIClass,
@@ -8,8 +9,14 @@ import {
   ISAAC_API_CLASS_TYPE_TO_FUNCTIONS,
   SerializedIsaacAPIClass,
 } from "../objects/isaacAPIClassTypeToFunctions";
+import { getEnumValues } from "./enums";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
-import { isTable, isUserdata } from "./types";
+import { isString, isTable, isUserdata } from "./types";
+
+const SERIALIZATION_BRANDS = getEnumValues(SerializationBrand);
+const SERIALIZATION_BRAND_SET: ReadonlySet<string> = new Set(
+  SERIALIZATION_BRANDS,
+);
 
 /**
  * Helper function to generically copy an Isaac API class without knowing what specific type of
@@ -136,6 +143,23 @@ export function isCopyableIsaacAPIClass(
   return isFunctions.some((identityFunction) => identityFunction(object));
 }
 
+/**
+ * Helper function to check if a key of a table in the "save#.dat" file is a serialization brand
+ * inserted by the save data manager (i.e. the `deepCopy` function).
+ *
+ * This is marked internal because end-users would not normally be iterating through a serialized
+ * object directly.
+ *
+ * @internal
+ */
+export function isSerializationBrand(key: unknown): boolean {
+  if (!isString(key)) {
+    return false;
+  }
+
+  return SERIALIZATION_BRAND_SET.has(key);
+}
+
 /**
  * Helper function to generically check if a given Lua table is a serialized Isaac API class. (This
  * is used by the save data manager when reading data from the "save#.dat" file.)

package/src/functions/table.ts

@@ -140,7 +140,7 @@ export function getStringsFromTable(
 export function isTableEmpty(luaMap: LuaMap<AnyNotNil, unknown>): boolean {
   // Using `next` does not seem to work properly, so we use `pairs` instead.
   // eslint-disable-next-line no-unreachable-loop
-  for (const [_key, _value] of pairs(luaMap)) {
+  for (const [_key, _value] of luaMap) {
     return false;
   }
 

package/src/functions/tstlClass.ts

@@ -1,15 +1,7 @@
 import { DefaultMap } from "../classes/DefaultMap";
 import { TSTLClassMetatable } from "../interfaces/TSTLClassMetatable";
 import { TSTLClass } from "../types/TSTLClass";
-import { isString, isTable } from "./types";
-
-const VANILLA_TSTL_CLASSES = new Set(["Map", "Set", "WeakMap", "WeakSet"]);
-
-const TSTL_CLASS_METATABLE_KEYS: ReadonlySet<string> = new Set([
-  "____constructor",
-  "__index",
-  "constructor",
-]);
+import { isTable } from "./types";
 
 /**
  * Helper function to get the constructor from an instantiated TypeScriptToLua class, which is
@@ -64,14 +56,6 @@ export function isDefaultMap(
   return className === "DefaultMap";
 }
 
-/**
- * Returns whether or not this is a class that is provided by the `isaacscript-common` library, such
- * as a `DefaultMap`.
- */
-export function isIsaacScriptCommonClass(object: unknown): boolean {
-  return isDefaultMap(object);
-}
-
 /**
  * Helper function to determine if a given object is a TypeScriptToLua `Map`.
  *
@@ -98,46 +82,8 @@ export function isTSTLSet(object: unknown): object is Set<AnyNotNil> {
 
 /** TypeScriptToLua classes are Lua tables that have a metatable with a certain amount of keys. */
 export function isUserDefinedTSTLClass(object: unknown): object is TSTLClass {
-  if (isVanillaTSTLClass(object) || isIsaacScriptCommonClass(object)) {
-    return false;
-  }
-
-  if (!isTable(object)) {
-    return false;
-  }
-
-  const metatable = getmetatable(object);
-  if (metatable === undefined) {
-    return false;
-  }
-
-  let numKeys = 0;
-  for (const [key] of pairs(metatable)) {
-    numKeys++;
-
-    if (!isString(key)) {
-      return false;
-    }
-
-    if (!TSTL_CLASS_METATABLE_KEYS.has(key)) {
-      return false;
-    }
-  }
-
-  return numKeys === TSTL_CLASS_METATABLE_KEYS.size;
-}
-
-/**
- * Returns whether or not this is a class that is provided as part of the TypeScriptToLua
- * transpiler, such as a `Map` or a `Set`.
- */
-export function isVanillaTSTLClass(object: unknown): boolean {
-  const className = getTSTLClassName(object);
-  if (className === undefined) {
-    return false;
-  }
-
-  return VANILLA_TSTL_CLASSES.has(className);
+  const tstlClassName = getTSTLClassName(object);
+  return tstlClassName !== undefined;
 }
 
 /**

package/src/functions/vector.ts

@@ -2,7 +2,7 @@ import {
   CopyableIsaacAPIClassType,
   Direction,
 } from "isaac-typescript-definitions";
-import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationBrand } from "../enums/SerializationBrand";
 import { angleToDirection } from "./direction";
 import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getRandomFloat } from "./random";
@@ -82,8 +82,8 @@ export function getRandomVector(
 }
 
 /**
- * Used to determine is the given table is a serialized `Vector` object created by the save data
- * manager and/or the `deepCopy` function.
+ * Used to determine is the given table is a serialized `Vector` object created by the `deepCopy`
+ * function.
  */
 export function isSerializedVector(
   object: unknown,

package/src/functions/weighted.ts

@@ -1,16 +1,35 @@
 import { WeightedArray } from "../types/WeightedArray";
-import { arrayToString, sumArray } from "./array";
+import { sumArray } from "./array";
 import { getRandomFloat } from "./random";
 import { getRandomSeed } from "./rng";
 
-/** Get a random value from a `WeightedArray`. (The second element in the array is the weight.) */
+/**
+ * Get a random value from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
+ * first element in the tuple is a value, and the second element in the tuple is a float
+ * corresponding to the value's weight.)
+ */
 export function getRandomFromWeightedArray<T>(
   weightedArray: WeightedArray<T>,
   seedOrRNG: Seed | RNG = getRandomSeed(),
 ): T {
+  const randomIndex = getRandomIndexFromWeightedArray(weightedArray, seedOrRNG);
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const randomElement = weightedArray[randomIndex]!;
+  return randomElement[0];
+}
+
+/**
+ * Get a random index from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
+ * first element in the tuple is a value, and the second element in the tuple is a float
+ * corresponding to the value's weight.)
+ */
+export function getRandomIndexFromWeightedArray<T>(
+  weightedArray: WeightedArray<T>,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+): int {
   if (weightedArray.length === 0) {
     error(
-      "Failed to get a random element from a weighted array since the provided array was empty.",
+      "Failed to get a random index from a weighted array since the provided array was empty.",
     );
   }
 
@@ -19,18 +38,16 @@ export function getRandomFromWeightedArray<T>(
   const randomWeight = getRandomFloat(0, totalWeight, seedOrRNG);
 
   let weightAccumulator = 0;
-  for (const tuple of weightedArray) {
-    const [element, weight] = tuple;
+  for (let i = 0; i < weightedArray.length; i++) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const tuple = weightedArray[i]!;
+    const [_element, weight] = tuple;
 
     weightAccumulator += weight;
     if (weightAccumulator >= randomWeight) {
-      return element;
+      return i;
     }
   }
 
-  error(
-    `Failed to get a random element from a weighted array: ${arrayToString(
-      weightedArray,
-    )}`,
-  );
+  error("Failed to get a random index from a weighted array.");
 }

package/src/index.ts

@@ -15,6 +15,7 @@ export * from "./enums/ModCallbackCustom2";
 export * from "./enums/PocketItemType";
 export * from "./enums/RockAltType";
 export * from "./enums/SaveDataKey";
+export * from "./enums/SerializationBrand";
 export * from "./enums/SerializationType";
 export * from "./enums/SlotDestructionType";
 export * from "./enums/StatType";
@@ -23,6 +24,7 @@ export * from "./features/characterStats";
 export * from "./features/collectibleItemPoolType";
 export * from "./features/customGridEntity";
 export * from "./features/customHotkeys";
+export * from "./features/customItemPool";
 export * from "./features/customPickup";
 export * from "./features/customStage/exports";
 export * from "./features/customTrapdoor/exports";
@@ -107,6 +109,7 @@ export * from "./functions/logEntities";
 export * from "./functions/logMisc";
 export * from "./functions/map";
 export * from "./functions/math";
+export * from "./functions/merge";
 export * from "./functions/mergeTests";
 export * from "./functions/minimap";
 export * from "./functions/nextStage";
@@ -179,11 +182,13 @@ export * from "./objects/kColors";
 export * from "./types/AllButFirst";
 export * from "./types/AllButLast";
 export * from "./types/AnyEntity";
+export * from "./types/AnyFunction";
 export * from "./types/AnyGridEntity";
 export * from "./types/CollectibleIndex";
 export * from "./types/Constructor";
 export * from "./types/FunctionTuple";
 export * from "./types/HasAllEnumKeys";
+export * from "./types/HasFunction";
 export * from "./types/Immutable";
 export * from "./types/LowercaseKeys";
 export * from "./types/PickingUpItem";