isaacscript-common 6.6.2 → 6.6.5

package/src/functions/deepCopy.ts

@@ -51,15 +51,19 @@ const COPYABLE_ISAAC_API_CLASS_TYPES_SET = new Set<string>(
  * - other Isaac API objects such as `EntityPtr` (that have a type of "userdata")
  *
  * @param value The primitive or object to copy.
- * @param serializationType Has 3 possible values. Can leave objects as-is, or can serialize objects
- *                          to Lua tables, or can deserialize Lua tables to objects. Default is
- *                          `SerializationType.NONE`.
- * @param traversalDescription Used to track the current key that we are operating on.
+ * @param serializationType Optional. Has 3 possible values. Can copy objects as-is, or can
+ *                          serialize objects to Lua tables, or can deserialize Lua tables to
+ *                          objects. Default is `SerializationType.NONE`.
+ * @param traversalDescription Optional. Used to track the current key that we are operating on.
+ *                             Default is an empty string.
+ * @param insideMap Optional. Tracks whether or not the deep copy function is in the process of
+ *                  recursively copying a TSTL Map. Default is false.
  */
 export function deepCopy(
   value: unknown,
   serializationType = SerializationType.NONE,
   traversalDescription = "",
+  insideMap = false,
 ): unknown {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (SAVE_DATA_MANAGER_DEBUG) {
@@ -98,7 +102,12 @@ export function deepCopy(
 
     case "table": {
       const luaTable = value as LuaTable<AnyNotNil, unknown>;
-      return deepCopyTable(luaTable, serializationType, traversalDescription);
+      return deepCopyTable(
+        luaTable,
+        serializationType,
+        traversalDescription,
+        insideMap,
+      );
     }
 
     case "userdata": {
@@ -111,6 +120,7 @@ function deepCopyTable(
   luaTable: LuaTable<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   // First, handle the cases of TSTL classes or serialized TSTL classes.
   if (isDefaultMap(luaTable) || luaTable.has(SerializationBrand.DEFAULT_MAP)) {
@@ -118,15 +128,26 @@ function deepCopyTable(
       luaTable,
       serializationType,
       traversalDescription,
+      insideMap,
     );
   }
 
   if (isTSTLMap(luaTable) || luaTable.has(SerializationBrand.MAP)) {
-    return deepCopyMap(luaTable, serializationType, traversalDescription);
+    return deepCopyMap(
+      luaTable,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
   }
 
   if (isTSTLSet(luaTable) || luaTable.has(SerializationBrand.SET)) {
-    return deepCopySet(luaTable, serializationType, traversalDescription);
+    return deepCopySet(
+      luaTable,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
   }
 
   const className = getTSTLClassName(luaTable);
@@ -144,7 +165,12 @@ function deepCopyTable(
   }
 
   if (isUserDefinedTSTLClass(luaTable)) {
-    return deepCopyTSTLClass(luaTable, serializationType, traversalDescription);
+    return deepCopyTSTLClass(
+      luaTable,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
   }
 
   // This is not a TSTL Map/Set/class. If it has a metatable, abort.
@@ -160,7 +186,12 @@ function deepCopyTable(
 
   // Handle the special case of an array.
   if (isArray(luaTable)) {
-    return deepCopyArray(luaTable, serializationType, traversalDescription);
+    return deepCopyArray(
+      luaTable,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
   }
 
   // Base case: copy a normal Lua table
@@ -168,6 +199,7 @@ function deepCopyTable(
     luaTable,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 }
 
@@ -175,19 +207,39 @@ function deepCopyDefaultMap(
   defaultMap: DefaultMap<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
-  // First, handle the special case of serializing a DefaultMap instantiated with a factory
-  // function. If this is the case, then we cannot serialize it, so we serialize it as a normal
-  // `Map` instead. We do not throw a runtime error because the merge function does not need to
-  // instantiate the DefaultMap class in most circumstances.
   const constructorArg = isDefaultMap(defaultMap)
     ? defaultMap.getConstructorArg()
-    : undefined;
+    : undefined; // The undefined case is handled explicitly in the "getNewDefaultMap" function.
+
+  // First, handle the special case of serializing a DefaultMap instantiated with a factory
+  // function. If this is the case, then we cannot serialize it (because there is no way to
+  // serialize a function).
   if (
     serializationType === SerializationType.SERIALIZE &&
     !isPrimitive(constructorArg)
   ) {
-    return deepCopyMap(defaultMap, serializationType, traversalDescription);
+    if (insideMap) {
+      // The case of a DefaultMap within another map is complicated. Unlike a DefaultMap attached to
+      // a "normal" object, the `merge` function will have no reference to the factory function that
+      // was used to instantiate it. Thus, there is no way to copy this object. In this case, we
+      // throw a run-time error to immediately alert the end-user that their data structure is
+      // invalid.
+      error(
+        'Failed to deep copy a DefaultMap because it was instantiated with a factory function and was also inside of another map. You cannot use a nested DefaultMap in this way because factory functions are not serializable. (In other words, there is no way to copy the function that you are using for the DefaultMap into the "save#.dat" file.) Instead, refactor your data structure so that the DefaultMap is not nested.',
+      );
+    } else {
+      // In most cases, the DefaultMap will be attached to a normal table element. In this case, if
+      // we serialize it as a normal `Map`, then everything will work out fine, because the `merge`
+      // function only needs to copy the values (and not instantiate the object itself).
+      return deepCopyMap(
+        defaultMap,
+        serializationType,
+        traversalDescription,
+        insideMap,
+      );
+    }
   }
 
   const newDefaultMap = getNewDefaultMap(
@@ -196,11 +248,13 @@ function deepCopyDefaultMap(
     traversalDescription,
     constructorArg,
   );
+  insideMap = true;
 
   const { entries, convertedNumberKeysToStrings } = getCopiedEntries(
     defaultMap,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 
   if (convertedNumberKeysToStrings) {
@@ -223,12 +277,14 @@ function deepCopyDefaultMap(
     }
   }
 
+  insideMap = false;
+
   return newDefaultMap;
 }
 
 /**
- * The new default map with either be a TSTL `DefaultMap` class or a Lua table, depending on whether
- * we are serializing or not.
+ * The new copied default map with either be a TSTL `DefaultMap` class or a Lua table, depending on
+ * whether we are serializing or not.
  */
 function getNewDefaultMap(
   defaultMap: DefaultMap<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
@@ -278,6 +334,7 @@ function deepCopyMap(
   map: Map<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   let newMap: Map<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>;
   if (serializationType === SerializationType.SERIALIZE) {
@@ -287,11 +344,13 @@ function deepCopyMap(
   } else {
     newMap = new Map();
   }
+  insideMap = true;
 
   const { entries, convertedNumberKeysToStrings } = getCopiedEntries(
     map,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 
   if (convertedNumberKeysToStrings) {
@@ -314,6 +373,8 @@ function deepCopyMap(
     }
   }
 
+  insideMap = false;
+
   return newMap;
 }
 
@@ -321,6 +382,7 @@ function deepCopySet(
   set: Set<AnyNotNil> | LuaTable<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   let newSet: Set<AnyNotNil> | LuaTable<AnyNotNil, string>;
   if (serializationType === SerializationType.SERIALIZE) {
@@ -336,6 +398,7 @@ function deepCopySet(
     set,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 
   if (convertedNumberKeysToStrings) {
@@ -368,6 +431,7 @@ function deepCopyTSTLClass(
   tstlClass: TSTLClass,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   let newClass: TSTLClass | LuaTable<AnyNotNil, unknown>;
   if (serializationType === SerializationType.SERIALIZE) {
@@ -383,6 +447,7 @@ function deepCopyTSTLClass(
     tstlClass,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 
   if (convertedNumberKeysToStrings) {
@@ -400,11 +465,17 @@ function deepCopyArray(
   array: unknown[],
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   const newArray: unknown[] = [];
 
   for (const value of array) {
-    const newValue = deepCopy(value, serializationType, traversalDescription);
+    const newValue = deepCopy(
+      value,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
     newArray.push(newValue);
   }
 
@@ -415,12 +486,14 @@ function deepCopyNormalLuaTable(
   luaTable: LuaTable<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ) {
   const newTable = new LuaTable<AnyNotNil, unknown>();
   const { entries, convertedNumberKeysToStrings } = getCopiedEntries(
     luaTable,
     serializationType,
     traversalDescription,
+    insideMap,
   );
 
   if (convertedNumberKeysToStrings) {
@@ -442,6 +515,7 @@ function getCopiedEntries(
   object: unknown,
   serializationType: SerializationType,
   traversalDescription: string,
+  insideMap: boolean,
 ): {
   entries: Array<[key: AnyNotNil, value: unknown]>;
   convertedNumberKeysToStrings: boolean;
@@ -479,7 +553,12 @@ function getCopiedEntries(
     }
 
     traversalDescription = getTraversalDescription(key, traversalDescription);
-    const newValue = deepCopy(value, serializationType, traversalDescription);
+    const newValue = deepCopy(
+      value,
+      serializationType,
+      traversalDescription,
+      insideMap,
+    );
 
     const keyToUse = convertNumberKeysToStrings ? tostring(key) : key;
     copiedEntries.push([keyToUse, newValue]);

package/src/functions/deepCopyTests.ts

@@ -7,7 +7,12 @@ import { log } from "./log";
 import { isDefaultMap, isTSTLMap, isTSTLSet } from "./tstlClass";
 import { isNumber, isString, isTable } from "./types";
 
-export function deepCopyTests(): void {
+/**
+ * Run the suite of tests that prove that the "deepCopy" helper function works properly.
+ *
+ * This function is only useful if you are troubleshooting the "deepCopy" function.
+ */
+export function runDeepCopyTests(): void {
   copiedObjectIsTable();
   copiedObjectHasKeyAndValueString();
   copiedTableHasKeyAndValueNumber();
@@ -34,7 +39,11 @@ function copiedObjectIsTable() {
   const oldObject = {
     abc: "def",
   };
-  const newObject = deepCopy(oldObject as unknown as LuaTable);
+  const newObject = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectIsTable",
+  );
   if (!isTable(newObject)) {
     error(`The copied object had a type of: ${typeof newObject}`);
   }
@@ -46,7 +55,11 @@ function copiedObjectHasKeyAndValueString() {
   const oldObject = {
     abc: valueToLookFor,
   };
-  const newTable = deepCopy(oldObject as unknown as LuaTable);
+  const newTable = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectHasKeyAndValueString",
+  );
   const newObject = newTable as typeof oldObject;
 
   const value = newObject[keyToLookFor];
@@ -69,7 +82,11 @@ function copiedTableHasKeyAndValueNumber() {
   const oldTable = new LuaTable<AnyNotNil, unknown>();
   oldTable.set(keyToLookFor, valueToLookFor);
 
-  const newObject = deepCopy(oldTable);
+  const newObject = deepCopy(
+    oldTable,
+    SerializationType.NONE,
+    "copiedTableHasKeyAndValueNumber",
+  );
   const newTable = newObject as LuaTable<AnyNotNil, unknown>;
 
   const value = newTable.get(keyToLookFor) as number | undefined;
@@ -91,7 +108,11 @@ function copiedTableDoesNotCoerceTypes() {
   const oldTable = new LuaTable<AnyNotNil, unknown>();
   oldTable.set(keyToLookFor, valueToLookFor);
 
-  const newObject = deepCopy(oldTable);
+  const newObject = deepCopy(
+    oldTable,
+    SerializationType.NONE,
+    "copiedTableDoesNotCoerceTypes",
+  );
   const newTable = newObject as LuaTable<AnyNotNil, unknown>;
 
   const keyString = tostring(keyToLookFor);
@@ -110,6 +131,7 @@ function copiedTableDoesNotCoerceTypes() {
   }
 }
 
+/** In this context, a reference is a pointer. */
 function copiedObjectHasNoReferencesForPrimitivesForward() {
   const originalStringValue = "abcdef";
   const originalNumberValue = 123;
@@ -117,7 +139,11 @@ function copiedObjectHasNoReferencesForPrimitivesForward() {
     abc: originalStringValue,
     def: originalNumberValue,
   };
-  const newTable = deepCopy(oldObject as unknown as LuaTable);
+  const newTable = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectHasNoReferencesForPrimitivesForward",
+  );
   const newObject = newTable as typeof oldObject;
 
   oldObject.abc = "newValue";
@@ -138,7 +164,11 @@ function copiedObjectHasNoReferencesForPrimitivesBackward() {
     abc: originalStringValue,
     def: originalNumberValue,
   };
-  const newTable = deepCopy(oldObject as unknown as LuaTable);
+  const newTable = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectHasNoReferencesForPrimitivesBackward",
+  );
   const newObject = newTable as typeof oldObject;
 
   newObject.abc = "newValue";
@@ -152,11 +182,16 @@ function copiedObjectHasNoReferencesForPrimitivesBackward() {
   }
 }
 
+/** In this context, a reference is a pointer. */
 function copiedObjectHasNoReferencesForArray() {
   const oldObject = {
     abc: [1, 2, 3],
   };
-  const newTable = deepCopy(oldObject as unknown as LuaTable);
+  const newTable = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectHasNoReferencesForArray",
+  );
   const newObject = newTable as typeof oldObject;
 
   if (oldObject.abc === newObject.abc) {
@@ -167,21 +202,21 @@ function copiedObjectHasNoReferencesForArray() {
     error("The copied object does not have an equal array.");
   }
 
-  oldObject.abc[0] += 1;
+  oldObject.abc[0]++;
   if (arrayEquals(oldObject.abc, newObject.abc)) {
     error(
       "The copied object has an equal array after a modification to the old array.",
     );
   }
-  oldObject.abc[0] -= 1;
+  oldObject.abc[0]--;
 
-  newObject.abc[0] += 1;
+  newObject.abc[0]++;
   if (arrayEquals(oldObject.abc, newObject.abc)) {
     error(
       "The copied object has an equal array after a modification to the new array.",
     );
   }
-  newObject.abc[0] -= 1;
+  newObject.abc[0]--;
 }
 
 function copiedObjectHasChildObject() {
@@ -193,7 +228,11 @@ function copiedObjectHasChildObject() {
       def: valueToLookFor,
     },
   };
-  const newTable = deepCopy(oldObject as unknown as LuaTable);
+  const newTable = deepCopy(
+    oldObject as unknown as LuaTable,
+    SerializationType.NONE,
+    "copiedObjectHasChildObject",
+  );
   const newObject = newTable as typeof oldObject;
 
   const childObject = newObject[childObjectIndex];
@@ -226,7 +265,7 @@ function copiedMapIsMap() {
   const oldMap = new Map<string, string>();
   oldMap.set(keyToLookFor, valueToLookFor);
 
-  const newObject = deepCopy(oldMap);
+  const newObject = deepCopy(oldMap, SerializationType.NONE, "copiedMapIsMap");
   const newMap = newObject as Map<string, string>;
 
   if (!isTable(newMap)) {
@@ -243,7 +282,11 @@ function copiedMapHasValue() {
   const oldMap = new Map<string, string>();
   oldMap.set(keyToLookFor, valueToLookFor);
 
-  const newTable = deepCopy(oldMap);
+  const newTable = deepCopy(
+    oldMap,
+    SerializationType.NONE,
+    "copiedMapHasValue",
+  );
   const newMap = newTable as typeof oldMap;
 
   const value = newMap.get(keyToLookFor);
@@ -260,7 +303,7 @@ function copiedSetIsSet() {
   const oldSet = new Set<string>();
   oldSet.add(valueToLookFor);
 
-  const newTable = deepCopy(oldSet);
+  const newTable = deepCopy(oldSet, SerializationType.NONE, "copiedSetIsSet");
   const newSet = newTable as Set<string>;
 
   if (!isTable(newSet)) {
@@ -276,7 +319,11 @@ function copiedSetHasValue() {
   const oldSet = new Set<string>();
   oldSet.add(valueToLookFor);
 
-  const newTable = deepCopy(oldSet);
+  const newTable = deepCopy(
+    oldSet,
+    SerializationType.NONE,
+    "copiedSetHasValue",
+  );
   const newSet = newTable as Set<string>;
 
   const hasValue = newSet.has(valueToLookFor);
@@ -295,7 +342,11 @@ function copiedMapHasChildMap() {
   const oldMap = new Map<string, Map<number, number>>();
   oldMap.set(keyToLookFor, oldChildMap);
 
-  const newTable = deepCopy(oldMap);
+  const newTable = deepCopy(
+    oldMap,
+    SerializationType.NONE,
+    "copiedMapHasChildMap",
+  );
   const newMap = newTable as typeof oldMap;
 
   const newChildMap = newMap.get(keyToLookFor);
@@ -332,7 +383,11 @@ function copiedDefaultMapHasChildDefaultMap() {
   oldChildMap.getAndSetDefault(childMapKey1);
   oldChildMap.set(childMapKey2, childMapCustomValue);
 
-  const newTable = deepCopy(oldParentMap);
+  const newTable = deepCopy(
+    oldParentMap,
+    SerializationType.NONE,
+    "copiedDefaultMapHasChildDefaultMap",
+  );
   const newParentMap = newTable as typeof oldParentMap;
 
   const newChildMap = newParentMap.get(parentMapKey);
@@ -376,6 +431,7 @@ function copiedDefaultMapHasBrand() {
   const newTable = deepCopy(
     oldDefaultMap,
     SerializationType.SERIALIZE,
+    "copiedDefaultMapHasBrand",
   ) as LuaTable<AnyNotNil, unknown>;
 
   if (!newTable.has(SerializationBrand.DEFAULT_MAP)) {

package/src/functions/log.ts

@@ -228,7 +228,7 @@ export function logEntities(
       msg += `  - CanShutDoors: ${npc.CanShutDoors}\n`;
     }
 
-    numMatchedEntities += 1;
+    numMatchedEntities++;
   });
 
   if (numMatchedEntities === 0) {
@@ -404,7 +404,7 @@ export function logGridEntities(
       msg += `  - TargetRoomType: ${door.TargetRoomType}\n`;
     }
 
-    numMatchedEntities += 1;
+    numMatchedEntities++;
   });
 
   if (numMatchedEntities === 0) {
@@ -572,7 +572,7 @@ export function logSounds(this: void): void {
  * 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 runtime error if it encounters a non-string key.
+ * instead of randomly). It will throw a run-time error if it encounters a non-string key.
  */
 export function logTable(
   this: void,
@@ -587,9 +587,14 @@ export function logTable(
   const indentation = " ".repeat(numSpaces);
 
   if (!isTable(luaTable)) {
-    log(
-      `${indentation}n/a (encountered a variable of type "${typeof luaTable}" instead of a table)`,
-    );
+    // Put it in an IIFE so that the it will show as "func" instead of "logTable" and align with the
+    // other text.
+    (() => {
+      log(
+        `${indentation}n/a (encountered a variable of type "${typeof luaTable}" instead of a table)`,
+      );
+    })();
+
     return;
   }
 
@@ -608,7 +613,11 @@ export function logTable(
     }
   });
 
-  log(`${indentation}The size of the table was: ${luaTable.length()}`);
+  // Put it in an IIFE so that the it will show as "func" instead of "logTable" and align with the
+  // other text.
+  (() => {
+    log(`${indentation}The size of the table was: ${luaTable.length()}`);
+  })();
 }
 
 /**