isaacscript-common 6.9.0 → 6.10.2

package/src/features/saveDataManager/merge.ts

@@ -12,7 +12,7 @@ import { isDefaultMap, isTSTLMap, isTSTLSet } from "../../functions/tstlClass";
 import { isTable } from "../../functions/types";
 import { getTraversalDescription } from "../../functions/utils";
 import { SAVE_DATA_MANAGER_DEBUG } from "./saveDataManagerConstants";
-import { isSerializationBrand } from "./serializationBrand";
+import { isSerializationBrand } from "./serializationBrands";
 
 /**
  * `merge` takes the values from a new table and recursively merges them into an old object (while
@@ -20,7 +20,7 @@ import { isSerializationBrand } from "./serializationBrand";
  *
  * It supports the following object types:
  *
- * - `LuaTable` / basic TSTL objects
+ * - Basic TSTL objects / tables
  * - TSTL `Map`
  * - TSTL `Set`
  * - TSTL classes
@@ -38,10 +38,10 @@ import { isSerializationBrand } from "./serializationBrand";
  */
 export function merge(
   oldObject:
-    | LuaTable<AnyNotNil, unknown>
+    | LuaMap<AnyNotNil, unknown>
     | Map<AnyNotNil, unknown>
     | Set<AnyNotNil>,
-  newTable: LuaTable<AnyNotNil, unknown>,
+  newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
 ): void {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -73,8 +73,8 @@ export function merge(
 }
 
 function mergeArray(
-  oldArray: LuaTable<AnyNotNil, unknown>,
-  newArray: LuaTable<AnyNotNil, unknown>,
+  oldArray: LuaMap<AnyNotNil, unknown>,
+  newArray: LuaMap<AnyNotNil, unknown>,
 ) {
   // Assume that we should blow away all array values with whatever is present in the incoming
   // array.
@@ -90,7 +90,7 @@ function mergeArray(
 
 function mergeTSTLObject(
   oldObject: Map<AnyNotNil, unknown> | Set<AnyNotNil>,
-  newTable: LuaTable<AnyNotNil, unknown>,
+  newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
 ) {
   // We blow away the old object and recursively copy over all of the incoming values.
@@ -140,8 +140,8 @@ function mergeTSTLObject(
 }
 
 function mergeTable(
-  oldTable: LuaTable<AnyNotNil, unknown>,
-  newTable: LuaTable<AnyNotNil, unknown>,
+  oldTable: LuaMap<AnyNotNil, unknown>,
+  newTable: LuaMap<AnyNotNil, unknown>,
   traversalDescription: string,
 ) {
   iterateTableInOrder(
@@ -170,12 +170,12 @@ function mergeTable(
       }
 
       if (isTable(value)) {
-        let oldValue = oldTable.get(key) as LuaTable<AnyNotNil, unknown>;
+        let oldValue = oldTable.get(key) as LuaMap<AnyNotNil, unknown>;
         if (!isTable(oldValue)) {
           // The child table does not exist on the old table. However, we still need to copy over
           // the new table, because we need to handle data types like "Foo | null". Thus, set up a
           // blank sub-table on the old table, and continue to recursively merge..
-          oldValue = new LuaTable();
+          oldValue = new LuaMap();
           oldTable.set(key, oldValue);
         }
 

package/src/features/saveDataManager/save.ts

@@ -11,8 +11,8 @@ import {
 
 export function saveToDisk(
   mod: Mod,
-  saveDataMap: LuaTable<string, SaveData>,
-  saveDataConditionalFuncMap: Map<string, () => boolean>,
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<string, () => boolean>,
 ): void {
   const allSaveData = getAllSaveDataToWriteToDisk(
     saveDataMap,
@@ -26,10 +26,10 @@ export function saveToDisk(
 }
 
 function getAllSaveDataToWriteToDisk(
-  saveDataMap: LuaTable<string, SaveData>,
-  saveDataConditionalFuncMap: Map<string, () => boolean>,
+  saveDataMap: LuaMap<string, SaveData>,
+  saveDataConditionalFuncMap: LuaMap<string, () => boolean>,
 ) {
-  const allSaveData = new LuaTable<AnyNotNil, unknown>();
+  const allSaveData = new LuaMap<AnyNotNil, unknown>();
 
   iterateTableInOrder(
     saveDataMap,
@@ -60,7 +60,7 @@ function getAllSaveDataToWriteToDisk(
       // that is unnecessary. Make a copy of the data and recursively convert all TypeScriptToLua
       // Maps into Lua tables.
       const saveDataCopy = deepCopy(
-        saveDataWithoutRoom as LuaTable,
+        saveDataWithoutRoom as LuaMap,
         SerializationType.SERIALIZE,
         subscriberName,
       );

package/src/functions/array.ts

@@ -443,9 +443,7 @@ export function isArray(object: unknown): object is unknown[] {
     return false;
   }
 
-  // Third, handle the case of an "empty" table. We cannot use the "LuaTable.length" method to
-  // determine this, since that will not actually return the number of keys. (It will only work
-  // properly for tables that are being used as arrays, which is not necessarily the case here.)
+  // Third, handle the case of an "empty" table.
   const tableLength = Object.keys(object).length;
   if (tableLength === 0) {
     return true;
@@ -453,7 +451,7 @@ export function isArray(object: unknown): object is unknown[] {
 
   // Third, check for non-contiguous elements. (Lua tables start at an index of 1.)
   for (let i = 1; i <= tableLength; i++) {
-    const element = object.get(i) as unknown;
+    const element = object.get(i);
     if (element === undefined) {
       return false;
     }

package/src/functions/color.ts

@@ -4,7 +4,7 @@ import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedColor = LuaTable<string, unknown> & {
+type SerializedColor = LuaMap<string, unknown> & {
   readonly __serializedColorBrand: symbol;
 };
 
@@ -65,7 +65,7 @@ export function copyColor(
         );
       }
 
-      const colorTable = new LuaTable<string, unknown>();
+      const colorTable = new LuaMap<string, unknown>();
       copyValuesToTable(color, KEYS, colorTable);
       colorTable.set(SerializationBrand.COLOR, "");
       return colorTable as SerializedColor;
@@ -79,7 +79,7 @@ export function copyColor(
       }
 
       const [r, g, b, a, ro, go, bo] = getNumbersFromTable(
-        color as LuaTable<string, unknown>,
+        color as LuaMap<string, unknown>,
         OBJECT_NAME,
         ...KEYS,
       );

package/src/functions/deepCopy.ts

@@ -3,12 +3,12 @@ import { CopyableIsaacAPIClassType } from "../enums/private/CopyableIsaacAPIClas
 import { SerializationBrand } from "../enums/private/SerializationBrand";
 import { SerializationType } from "../enums/SerializationType";
 import { SAVE_DATA_MANAGER_DEBUG } from "../features/saveDataManager/saveDataManagerConstants";
-import { isSerializationBrand } from "../features/saveDataManager/serializationBrand";
+import { isSerializationBrand } from "../features/saveDataManager/serializationBrands";
 import { TSTLClass } from "../types/private/TSTLClass";
 import { isArray } from "./array";
 import { getEnumValues } from "./enums";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
-import { log, logTable } from "./log";
+import { log } from "./log";
 import {
   copyIsaacAPIClass,
   deserializeIsaacAPIClass,
@@ -36,7 +36,7 @@ const COPYABLE_ISAAC_API_CLASS_TYPES_SET = new Set<string>(
  * It supports the following object types:
  *
  * - Primitives (i.e. strings, numbers, and booleans)
- * - `LuaTable` / basic TSTL objects
+ * - Basic TSTL objects / tables
  * - TSTL `Map`
  * - TSTL `Set`
  * - TSTL classes
@@ -101,9 +101,9 @@ export function deepCopy(
     }
 
     case "table": {
-      const luaTable = value as LuaTable<AnyNotNil, unknown>;
+      const luaMap = value as LuaMap<AnyNotNil, unknown>;
       return deepCopyTable(
-        luaTable,
+        luaMap,
         serializationType,
         traversalDescription,
         insideMap,
@@ -117,40 +117,40 @@ export function deepCopy(
 }
 
 function deepCopyTable(
-  luaTable: LuaTable<AnyNotNil, unknown>,
+  luaMap: LuaMap<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)) {
+  if (isDefaultMap(luaMap) || luaMap.has(SerializationBrand.DEFAULT_MAP)) {
     return deepCopyDefaultMap(
-      luaTable,
+      luaMap,
       serializationType,
       traversalDescription,
       insideMap,
     );
   }
 
-  if (isTSTLMap(luaTable) || luaTable.has(SerializationBrand.MAP)) {
+  if (isTSTLMap(luaMap) || luaMap.has(SerializationBrand.MAP)) {
     return deepCopyMap(
-      luaTable,
+      luaMap,
       serializationType,
       traversalDescription,
       insideMap,
     );
   }
 
-  if (isTSTLSet(luaTable) || luaTable.has(SerializationBrand.SET)) {
+  if (isTSTLSet(luaMap) || luaMap.has(SerializationBrand.SET)) {
     return deepCopySet(
-      luaTable,
+      luaMap,
       serializationType,
       traversalDescription,
       insideMap,
     );
   }
 
-  const className = getTSTLClassName(luaTable);
+  const className = getTSTLClassName(luaMap);
 
   if (className === "WeakMap") {
     error(
@@ -164,9 +164,9 @@ function deepCopyTable(
     );
   }
 
-  if (isUserDefinedTSTLClass(luaTable)) {
+  if (isUserDefinedTSTLClass(luaMap)) {
     return deepCopyTSTLClass(
-      luaTable,
+      luaMap,
       serializationType,
       traversalDescription,
       insideMap,
@@ -174,20 +174,20 @@ function deepCopyTable(
   }
 
   // This is not a TSTL Map/Set/class. If it has a metatable, abort.
-  checkMetatable(luaTable, traversalDescription);
+  checkMetatable(luaMap, traversalDescription);
 
   // Handle the special case of serialized Isaac API classes.
   if (
-    isSerializedIsaacAPIClass(luaTable) &&
+    isSerializedIsaacAPIClass(luaMap) &&
     serializationType === SerializationType.DESERIALIZE
   ) {
-    return deserializeIsaacAPIClass(luaTable);
+    return deserializeIsaacAPIClass(luaMap);
   }
 
   // Handle the special case of an array.
-  if (isArray(luaTable)) {
+  if (isArray(luaMap)) {
     return deepCopyArray(
-      luaTable,
+      luaMap,
       serializationType,
       traversalDescription,
       insideMap,
@@ -196,7 +196,7 @@ function deepCopyTable(
 
   // Base case: copy a normal Lua table
   return deepCopyNormalLuaTable(
-    luaTable,
+    luaMap,
     serializationType,
     traversalDescription,
     insideMap,
@@ -204,11 +204,16 @@ function deepCopyTable(
 }
 
 function deepCopyDefaultMap(
-  defaultMap: DefaultMap<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
+  defaultMap: DefaultMap<AnyNotNil, unknown> | LuaMap<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
   insideMap: boolean,
 ) {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying a DefaultMap.");
+  }
+
   const constructorArg = isDefaultMap(defaultMap)
     ? defaultMap.getConstructorArg()
     : undefined; // The undefined case is handled explicitly in the "getNewDefaultMap" function.
@@ -287,11 +292,11 @@ function deepCopyDefaultMap(
  * whether we are serializing or not.
  */
 function getNewDefaultMap(
-  defaultMap: DefaultMap<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
+  defaultMap: DefaultMap<AnyNotNil, unknown> | LuaMap<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
   constructorArg: unknown,
-) {
+): DefaultMap<AnyNotNil, unknown> | LuaMap<AnyNotNil, unknown> {
   switch (serializationType) {
     case SerializationType.NONE: {
       // eslint-disable-next-line isaacscript/no-invalid-default-map
@@ -301,7 +306,7 @@ function getNewDefaultMap(
     case SerializationType.SERIALIZE: {
       // Since we are serializing, the new object will be a Lua table. (At this point, we already
       // handled the special case of a DefaultMap instantiated with a factory function.)
-      const newDefaultMap = new LuaTable<AnyNotNil, unknown>();
+      const newDefaultMap = new LuaMap<AnyNotNil, unknown>();
       newDefaultMap.set(SerializationBrand.DEFAULT_MAP, "");
       newDefaultMap.set(SerializationBrand.DEFAULT_MAP_VALUE, constructorArg);
 
@@ -331,15 +336,20 @@ function getNewDefaultMap(
 }
 
 function deepCopyMap(
-  map: Map<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>,
+  map: Map<AnyNotNil, unknown> | LuaMap<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
   insideMap: boolean,
 ) {
-  let newMap: Map<AnyNotNil, unknown> | LuaTable<AnyNotNil, unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying a Map.");
+  }
+
+  let newMap: Map<AnyNotNil, unknown> | LuaMap<AnyNotNil, unknown>;
   if (serializationType === SerializationType.SERIALIZE) {
     // Since we are serializing, the new object will be a Lua table.
-    newMap = new LuaTable<AnyNotNil, unknown>();
+    newMap = new LuaMap<AnyNotNil, unknown>();
     newMap.set(SerializationBrand.MAP, "");
   } else {
     newMap = new Map();
@@ -379,16 +389,21 @@ function deepCopyMap(
 }
 
 function deepCopySet(
-  set: Set<AnyNotNil> | LuaTable<AnyNotNil, unknown>,
+  set: Set<AnyNotNil> | LuaMap<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
   insideMap: boolean,
 ) {
-  let newSet: Set<AnyNotNil> | LuaTable<AnyNotNil, string>;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying a Set.");
+  }
+
+  let newSet: Set<AnyNotNil> | LuaMap<AnyNotNil, string>;
   if (serializationType === SerializationType.SERIALIZE) {
     // For serialization purposes, we represent a `Set` as a table with keys that match the
     // keys/values in the Set and values of an empty string.
-    newSet = new LuaTable<AnyNotNil, string>();
+    newSet = new LuaMap<AnyNotNil, string>();
     newSet.set(SerializationBrand.SET, "");
   } else {
     newSet = new Set();
@@ -405,7 +420,7 @@ function deepCopySet(
     // Differentiating between the two types looks superfluous but is necessary for TSTL to produce
     // the proper set method call.
     if (isTSTLSet(newSet)) {
-      // We should never be serializing an object of type Set.
+      // We should never be serializing an object of type `Set`.
       error(
         "The deep copy function cannot convert number keys to strings for a Set.",
       );
@@ -433,10 +448,15 @@ function deepCopyTSTLClass(
   traversalDescription: string,
   insideMap: boolean,
 ) {
-  let newClass: TSTLClass | LuaTable<AnyNotNil, unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying a TSTL class.");
+  }
+
+  let newClass: TSTLClass | LuaMap<AnyNotNil, unknown>;
   if (serializationType === SerializationType.SERIALIZE) {
     // Since we are serializing, the new object will be a Lua table.
-    newClass = new LuaTable<AnyNotNil, unknown>();
+    newClass = new LuaMap<AnyNotNil, unknown>();
     // (We do not brand it with the class type because we will not have the associated class
     // constructor during deserialization, so knowing what type of class it is is pointless.)
   } else {
@@ -467,6 +487,11 @@ function deepCopyArray(
   traversalDescription: string,
   insideMap: boolean,
 ) {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying an array.");
+  }
+
   const newArray: unknown[] = [];
 
   for (const value of array) {
@@ -483,14 +508,19 @@ function deepCopyArray(
 }
 
 function deepCopyNormalLuaTable(
-  luaTable: LuaTable<AnyNotNil, unknown>,
+  luaMap: LuaMap<AnyNotNil, unknown>,
   serializationType: SerializationType,
   traversalDescription: string,
   insideMap: boolean,
 ) {
-  const newTable = new LuaTable<AnyNotNil, unknown>();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying a normal Lua table.");
+  }
+
+  const newTable = new LuaMap<AnyNotNil, unknown>();
   const { entries, convertedNumberKeysToStrings } = getCopiedEntries(
-    luaTable,
+    luaMap,
     serializationType,
     traversalDescription,
     insideMap,
@@ -535,10 +565,17 @@ function getCopiedEntries(
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (SAVE_DATA_MANAGER_DEBUG) {
-    logTable(entries);
     entries.sort(twoDimensionalSort);
   }
 
+  // During serialization, we brand some Lua tables with a special identifier to signify that it has
+  // keys that should be deserialized to numbers.
+  const convertStringKeysToNumbers =
+    serializationType === SerializationType.DESERIALIZE &&
+    entries.some(
+      ([key]) => key === (SerializationBrand.OBJECT_WITH_NUMBER_KEYS as string),
+    );
+
   const hasNumberKeys = entries.some(([key]) => isNumber(key));
   const convertNumberKeysToStrings =
     serializationType === SerializationType.SERIALIZE && hasNumberKeys;
@@ -560,7 +597,16 @@ function getCopiedEntries(
       insideMap,
     );
 
-    const keyToUse = convertNumberKeysToStrings ? tostring(key) : key;
+    let keyToUse = key;
+    if (convertStringKeysToNumbers) {
+      const numberKey = tonumber(key);
+      if (numberKey !== undefined) {
+        keyToUse = numberKey;
+      }
+    }
+    if (convertNumberKeysToStrings) {
+      keyToUse = tostring(key);
+    }
     copiedEntries.push([keyToUse, newValue]);
   }
 
@@ -575,8 +621,11 @@ function getCopiedEntries(
  * copy function will refuse to copy a table type that has a metatable, outside of specifically
  * supported TSTL objects.
  */
-function checkMetatable(luaTable: LuaTable, traversalDescription: string) {
-  const metatable = getmetatable(luaTable);
+function checkMetatable(
+  luaMap: LuaMap<AnyNotNil, unknown>,
+  traversalDescription: string,
+) {
+  const metatable = getmetatable(luaMap);
   if (metatable === undefined) {
     return;
   }
@@ -597,6 +646,11 @@ function deepCopyUserdata(
   serializationType: SerializationType,
   traversalDescription: string,
 ) {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (SAVE_DATA_MANAGER_DEBUG) {
+    log("deepCopy is copying userdata.");
+  }
+
   const classType = getIsaacAPIClassName(value);
   if (classType === undefined) {
     error(