isaacscript-common 6.6.3 → 6.7.0

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/{entity.ts → entities.ts}

@@ -13,10 +13,10 @@ import { isPrimitive } from "./types";
  * `Isaac.CountEntities` method to avoid having to specify a spawner and to handle ignoring charmed
  * enemies.
  *
- * @param entityType Default is -1. -1 matches every entity type.
- * @param variant Default is -1. -1 matches every variant.
- * @param subType Default is -1. -1 matches every sub-type.
- * @param ignoreFriendly Default is false.
+ * @param entityType Optional. Default is -1, which matches every entity type.
+ * @param variant Optional. Default is -1, which matches every variant.
+ * @param subType Optional. Default is -1, which matches every sub-type.
+ * @param ignoreFriendly Optional. Default is false.
  */
 export function countEntities(
   entityType: EntityType = -1,
@@ -43,10 +43,10 @@ export function countEntities(
  * Helper function to check if one or more of a specific kind of entity is present in the current
  * room. It uses the `countEntities` helper function to determine this.
  *
- * @param entityType Default is -1. -1 matches every entity type.
- * @param variant Default is -1. -1 matches every variant.
- * @param subType Default is -1. -1 matches every sub-type.
- * @param ignoreFriendly Default is false.
+ * @param entityType Optional. Default is -1, which matches every entity type.
+ * @param variant Optional. Default is -1, which matches every variant.
+ * @param subType Optional. Default is -1, which matches every sub-type.
+ * @param ignoreFriendly Optional. Default is false.
  */
 export function doesEntityExist(
   entityType: EntityType = -1,
@@ -99,28 +99,29 @@ export function getClosestEntityTo<T extends AnyEntity>(
  * For example:
  *
  * ```ts
- * // Make all of the entities in the room invisible
+ * // Make all of the entities in the room invisible.
  * for (const entity of getEntities()) {
  *   entity.Visible = false;
  * }
  * ```
  *
- * @param entityType Optional. If specified, will only return NPCs that match this entity type.
- * @param variant Optional. If specified, will only return NPCs that match this variant. Default is
- *                -1. -1 matches every variant.
- * @param subType Optional. If specified, will only return NPCs that match this sub-type. Default is
- *                -1. -1 matches every sub-type.
+ * @param entityType Optional. If specified, will only get the entities that match the type. Default
+ *                   is -1, which matches every type.
+ * @param variant Optional. If specified, will only get the entities that match the variant. Default
+ *                is -1, which matches every variant.
+ * @param subType Optional. If specified, will only get the entities that match the sub-type.
+ *                Default is -1, which matches every sub-type.
  * @param ignoreFriendly Optional. If set to true, it will exclude friendly NPCs from being
- *                       returned. Default is false. Will only be taken into account if
- *                       `matchingEntityType` is specified.
+ *                       returned. Default is false. Will only be taken into account if the
+ *                       `entityType` is specified.
  */
 export function getEntities(
-  entityType?: EntityType,
+  entityType: EntityType = -1,
   variant = -1,
   subType = -1,
   ignoreFriendly = false,
 ): Entity[] {
-  if (entityType === undefined) {
+  if ((entityType as int) === -1) {
     return Isaac.GetRoomEntities();
   }
 
@@ -317,8 +318,9 @@ export function parseEntityTypeVariantString(
  * Helper function to remove all of the matching entities in the room.
  *
  * @param entityType The entity type to match.
- * @param entityVariant Optional. The variant to match. Default is -1. -1 matches every variant.
- * @param entitySubType Optional. The sub-type to match. Default is -1. -1 matches every sub-type.
+ * @param entityVariant Optional. The variant to match. Default is -1, which matches every variant.
+ * @param entitySubType Optional. The sub-type to match. Default is -1, which matches every
+ *                      sub-type.
  * @param cap Optional. If specified, will only remove the given amount of collectibles.
  * @returns An array of the entities that were removed.
  */
@@ -353,7 +355,7 @@ export function removeEntities<T extends AnyEntity>(
 
     entitiesRemoved.push(entity);
     if (cap !== undefined && entitiesRemoved.length >= cap) {
-      return entitiesRemoved;
+      break;
     }
   }