isaacscript-common 31.5.0 → 31.6.0

package/src/functions/array.ts

@@ -2,7 +2,7 @@ import { ReadonlySet } from "../types/ReadonlySet";
 import { getRandomInt } from "./random";
 import { getRandomSeed, isRNG, newRNG } from "./rng";
 import { isNumber, isTable } from "./types";
-import { eRange } from "./utils";
+import { assertDefined, eRange } from "./utils";
 
 /**
  * Helper function for determining if two arrays contain the exact same elements. Note that this
@@ -344,6 +344,9 @@ export function getArrayIndexes<T>(array: T[] | readonly T[]): int[] {
  * Helper function to return the last element of an array.
  *
  * If the array is empty, this will return undefined.
+ *
+ * (Note that TSTL does not support `Array.at(-1)`, which would make this helper function largely
+ * unnecessary.)
  */
 export function getLastElement<T>(array: T[]): T | undefined {
   return array[array.length - 1];
@@ -372,11 +375,10 @@ export function getRandomArrayElement<T>(
     exceptions.length > 0 ? arrayRemove(array, ...exceptions) : array;
   const randomIndex = getRandomArrayIndex(arrayToUse, seedOrRNG);
   const randomElement = arrayToUse[randomIndex];
-  if (randomElement === undefined) {
-    error(
-      `Failed to get a random array element since the random index of ${randomIndex} was not valid.`,
-    );
-  }
+  assertDefined(
+    randomElement,
+    `Failed to get a random array element since the random index of ${randomIndex} was not valid.`,
+  );
 
   return randomElement;
 }

package/src/functions/bitSet128.ts

@@ -7,6 +7,7 @@ import {
   tableHasKeys,
 } from "./table";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 export type SerializedBitSet128 = LuaMap<string, unknown> & {
   readonly __serializedBitSet128Brand: symbol;
@@ -45,16 +46,14 @@ export function deserializeBitSet128(
 
   const [l, h] = getNumbersFromTable(bitSet128, OBJECT_NAME, ...KEYS);
 
-  if (l === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: l`,
-    );
-  }
-  if (h === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: h`,
-    );
-  }
+  assertDefined(
+    l,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: l`,
+  );
+  assertDefined(
+    h,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: h`,
+  );
 
   return BitSet128(l, h);
 }

package/src/functions/bitwise.ts

@@ -1,4 +1,5 @@
 import { addFlag } from "./flag";
+import { assertDefined } from "./utils";
 
 /** Helper function to convert a set of flags to a single `BitFlags` object. */
 export function arrayToBitFlags<T extends BitFlag | BitFlag128>(
@@ -33,9 +34,11 @@ export function convertDecimalToBinary(number: number, minLength?: int): int[] {
   const bitsString = number.toString(2);
   for (const bitString of bitsString) {
     const bit = tonumber(bitString);
-    if (bit === undefined) {
-      error(`Failed to convert the following number to binary: ${number}`);
-    }
+    assertDefined(
+      bit,
+      `Failed to convert the following number to binary: ${number}`,
+    );
+
     bits.push(bit);
   }
 

package/src/functions/color.ts

@@ -9,6 +9,7 @@ import {
   tableHasKeys,
 } from "./table";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 export type SerializedColor = LuaMap<string, unknown> & {
   readonly __serializedColorBrand: symbol;
@@ -58,21 +59,18 @@ export function deserializeColor(color: SerializedColor): Color {
     ...KEYS,
   );
 
-  if (r === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: R`,
-    );
-  }
-  if (g === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: G`,
-    );
-  }
-  if (b === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: B`,
-    );
-  }
+  assertDefined(
+    r,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: R`,
+  );
+  assertDefined(
+    g,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: G`,
+  );
+  assertDefined(
+    b,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: B`,
+  );
 
   return Color(r, g, b, a, ro, go, bo);
 }

package/src/functions/deepCopy.ts

@@ -24,7 +24,7 @@ import {
   newTSTLClass,
 } from "./tstlClass";
 import { asString, isNumber, isPrimitive } from "./types";
-import { getTraversalDescription } from "./utils";
+import { assertDefined, getTraversalDescription } from "./utils";
 
 /**
  * `deepCopy` is a semi-generic deep cloner. It will recursively copy all of the values so that none
@@ -361,11 +361,10 @@ function getNewDefaultMap(
       const defaultMapValue = defaultMap.get(
         SerializationBrand.DEFAULT_MAP_VALUE,
       );
-      if (defaultMapValue === undefined) {
-        error(
-          `Failed to deserialize a default map of "${traversalDescription}", since there was no serialization brand of: ${SerializationBrand.DEFAULT_MAP_VALUE}`,
-        );
-      }
+      assertDefined(
+        defaultMapValue,
+        `Failed to deserialize a default map of "${traversalDescription}", since there was no serialization brand of: ${SerializationBrand.DEFAULT_MAP_VALUE}`,
+      );
 
       // eslint-disable-next-line isaacscript/no-invalid-default-map
       return new DefaultMap(defaultMapValue);
@@ -518,21 +517,21 @@ function deepCopyTSTLClass(
       const tstlClassName = tstlClass.get(SerializationBrand.TSTL_CLASS) as
         | string
         | undefined;
-      if (tstlClassName === undefined) {
-        error(
-          "Failed to deserialize a TSTL class since the brand did not contain the class name.",
-        );
-      }
+      assertDefined(
+        tstlClassName,
+        "Failed to deserialize a TSTL class since the brand did not contain the class name.",
+      );
 
       const classConstructor = classConstructors.get(tstlClassName);
-      if (classConstructor === undefined) {
-        error(
-          `Failed to deserialize a TSTL class since there was no constructor registered for a class name of "${tstlClassName}". If this mod is using the save data manager, it must register the class constructor with the "saveDataManagerRegisterClass" method.`,
-        );
-      }
+      assertDefined(
+        classConstructor,
+        `Failed to deserialize a TSTL class since there was no constructor registered for a class name of "${tstlClassName}". If this mod is using the save data manager, it must register the class constructor with the "saveDataManagerRegisterClass" method.`,
+      );
 
       // eslint-disable-next-line new-cap
       newClass = new classConstructor() as TSTLClass;
+
+      break;
     }
   }
 
@@ -725,16 +724,10 @@ function deepCopyUserdata(
   serializationType: SerializationType,
   traversalDescription: string,
 ) {
-  const classType = getIsaacAPIClassName(value);
-  if (classType === undefined) {
-    error(
-      `The deep copy function was not able to derive the Isaac API class type for: ${traversalDescription}`,
-    );
-  }
-
   if (!isCopyableIsaacAPIClass(value)) {
+    const className = getIsaacAPIClassName(value) ?? "Unknown";
     error(
-      `The deep copy function does not support serializing "${traversalDescription}", since it is an Isaac API class of type: ${classType}`,
+      `The deep copy function does not support serializing "${traversalDescription}", since it is an Isaac API class of type: ${className}`,
     );
   }
 
@@ -747,6 +740,7 @@ function deepCopyUserdata(
       return serializeIsaacAPIClass(value);
     }
 
+    // eslint-disable-next-line isaacscript/require-break
     case SerializationType.DESERIALIZE: {
       error(
         `The deep copy function can not deserialize "${traversalDescription}", since it is userdata.`,

package/src/functions/deepCopyTests.ts

@@ -69,8 +69,7 @@ function copiedObjectHasKeyAndValueString() {
     "copiedObjectHasKeyAndValueString",
   );
 
-  const value = newObject[keyToLookFor];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const value = newObject[keyToLookFor] as string | undefined;
   if (value === undefined) {
     error(`The copied object did not have a key of: ${keyToLookFor}`);
   }
@@ -236,8 +235,9 @@ function copiedObjectHasChildObject() {
     "copiedObjectHasChildObject",
   );
 
-  const childObject = newObject[childObjectIndex];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const childObject = newObject[childObjectIndex] as
+    | (typeof oldObject)["abc"]
+    | undefined;
   if (childObject === undefined) {
     error(`Failed to find the child object at index: ${childObjectIndex}`);
   }
@@ -246,8 +246,7 @@ function copiedObjectHasChildObject() {
     error(`The copied child object had a type of: ${typeof childObject}`);
   }
 
-  const value = childObject[keyToLookFor];
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const value = childObject[keyToLookFor] as string | undefined;
   if (value === undefined) {
     error(`The child object did not have a key of: ${keyToLookFor}`);
   }

package/src/functions/entities.ts

@@ -13,6 +13,7 @@ import { isRNG, newRNG } from "./rng";
 import { setSpriteOpacity } from "./sprites";
 import { isTSTLSet } from "./tstlClass";
 import { isPrimitive } from "./types";
+import { assertDefined } from "./utils";
 import { doesVectorHaveLength, isVector, vectorToString } from "./vector";
 
 /** From DeadInfinity. */
@@ -167,21 +168,22 @@ export function getConstituentsFromEntityID(
   const [entityTypeString, variantString, subTypeString] = parts;
 
   const entityType = tonumber(entityTypeString);
-  if (entityType === undefined) {
-    error(`Failed to convert the entity type to a number: ${entityTypeString}`);
-  }
+  assertDefined(
+    entityType,
+    `Failed to convert the entity type to a number: ${entityTypeString}`,
+  );
 
   const variant = tonumber(variantString);
-  if (variant === undefined) {
-    error(`Failed to convert the entity variant to a number: ${variantString}`);
-  }
+  assertDefined(
+    variant,
+    `Failed to convert the entity variant to a number: ${variantString}`,
+  );
 
   const subType = tonumber(subTypeString);
-  if (subType === undefined) {
-    error(
-      `Failed to convert the entity sub-type to a number: ${subTypeString}`,
-    );
-  }
+  assertDefined(
+    subType,
+    `Failed to convert the entity sub-type to a number: ${subTypeString}`,
+  );
 
   return [entityType, variant, subType];
 }
@@ -241,9 +243,7 @@ export function getEntityFields(
   const metatable = getmetatable(entity) as
     | LuaMap<AnyNotNil, unknown>
     | undefined;
-  if (metatable === undefined) {
-    error("Failed to get the metatable for an entity.");
-  }
+  assertDefined(metatable, "Failed to get the metatable for an entity.");
 
   setPrimitiveEntityFields(entity, metatable, entityFields);
 
@@ -258,9 +258,10 @@ export function getEntityFields(
   const parentTable = metatable.get("__parent") as
     | LuaMap<AnyNotNil, unknown>
     | undefined;
-  if (parentTable === undefined) {
-    error('Failed to get the "__parent" table for an entity.');
-  }
+  assertDefined(
+    parentTable,
+    'Failed to get the "__parent" table for an entity.',
+  );
 
   setPrimitiveEntityFields(entity, parentTable, entityFields);
 
@@ -275,9 +276,10 @@ function setPrimitiveEntityFields(
   const propGetTable = metatable.get("__propget") as
     | LuaMap<AnyNotNil, unknown>
     | undefined;
-  if (propGetTable === undefined) {
-    error('Failed to get the "__propget" table for an entity.');
-  }
+  assertDefined(
+    propGetTable,
+    'Failed to get the "__propget" table for an entity.',
+  );
 
   for (const [key] of propGetTable) {
     // The values of this table are functions. Thus, we use the key to index the original entity.

package/src/functions/entitiesSpecific.ts

@@ -12,6 +12,7 @@ import type {
 import { EntityType } from "isaac-typescript-definitions";
 import { VectorZero } from "../core/constants";
 import { getEntities, removeEntities, spawn } from "./entities";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to get all of the bombs in the room. (Specifically, this refers to the
@@ -562,9 +563,7 @@ export function spawnBomb(
   );
 
   const bomb = entity.ToBomb();
-  if (bomb === undefined) {
-    error("Failed to spawn a bomb.");
-  }
+  assertDefined(bomb, "Failed to spawn a bomb.");
 
   return bomb;
 }
@@ -608,9 +607,7 @@ export function spawnEffect(
   );
 
   const effect = entity.ToEffect();
-  if (effect === undefined) {
-    error("Failed to spawn an effect.");
-  }
+  assertDefined(effect, "Failed to spawn an effect.");
 
   return effect;
 }
@@ -659,9 +656,7 @@ export function spawnFamiliar(
   );
 
   const familiar = entity.ToFamiliar();
-  if (familiar === undefined) {
-    error("Failed to spawn a familiar.");
-  }
+  assertDefined(familiar, "Failed to spawn a familiar.");
 
   return familiar;
 }
@@ -705,9 +700,7 @@ export function spawnKnife(
   );
 
   const knife = entity.ToKnife();
-  if (knife === undefined) {
-    error("Failed to spawn a knife.");
-  }
+  assertDefined(knife, "Failed to spawn a knife.");
 
   return knife;
 }
@@ -751,9 +744,7 @@ export function spawnLaser(
   );
 
   const laser = entity.ToLaser();
-  if (laser === undefined) {
-    error("Failed to spawn a laser.");
-  }
+  assertDefined(laser, "Failed to spawn a laser.");
 
   return laser;
 }
@@ -803,9 +794,7 @@ export function spawnNPC(
   );
 
   const npc = entity.ToNPC();
-  if (npc === undefined) {
-    error("Failed to spawn an NPC.");
-  }
+  assertDefined(npc, "Failed to spawn an NPC.");
 
   return npc;
 }
@@ -856,9 +845,7 @@ export function spawnPickup(
   );
 
   const pickup = entity.ToPickup();
-  if (pickup === undefined) {
-    error("Failed to spawn a pickup.");
-  }
+  assertDefined(pickup, "Failed to spawn a pickup.");
 
   return pickup;
 }
@@ -902,9 +889,7 @@ export function spawnProjectile(
   );
 
   const projectile = entity.ToProjectile();
-  if (projectile === undefined) {
-    error("Failed to spawn a projectile.");
-  }
+  assertDefined(projectile, "Failed to spawn a projectile.");
 
   return projectile;
 }
@@ -987,9 +972,7 @@ export function spawnTear(
   );
 
   const tear = entity.ToTear();
-  if (tear === undefined) {
-    error("Failed to spawn a tear.");
-  }
+  assertDefined(tear, "Failed to spawn a tear.");
 
   return tear;
 }

package/src/functions/enums.ts

@@ -1,8 +1,8 @@
 import { ReadonlySet } from "../types/ReadonlySet";
 import { getRandomArrayElement } from "./array";
 import { getRandomSeed } from "./rng";
-import { isString } from "./types";
-import { iRange } from "./utils";
+import { isNumber, isString } from "./types";
+import { assertDefined, iRange } from "./utils";
 
 /**
  * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
@@ -60,13 +60,17 @@ export function getEnumEntries<T>(
  * For a more in depth explanation, see:
  * https://isaacscript.github.io/main/gotchas#iterating-over-enums
  */
-export function getEnumKeys<T>(transpiledEnum: T): string[] {
+export function getEnumKeys(
+  transpiledEnum: Record<string | number, string | number>,
+): string[] {
   const enumEntries = getEnumEntries(transpiledEnum);
   return enumEntries.map(([key, _value]) => key);
 }
 
 /** Helper function to get the amount of entries inside of an enum. */
-export function getEnumLength<T>(transpiledEnum: T): int {
+export function getEnumLength(
+  transpiledEnum: Record<string | number, string | number>,
+): int {
   const enumEntries = getEnumEntries(transpiledEnum);
   return enumEntries.length;
 }
@@ -95,18 +99,17 @@ export function getEnumValues<T>(transpiledEnum: T): Array<T[keyof T]> {
 /**
  * Helper function to get the enum value with the highest value.
  *
- * Note that this is not necessarily the enum value that is declared last, since there is no way to
- * infer that at run-time.
+ * Note that this is not necessarily the enum value that is declared last in the code, since there
+ * is no way to infer that at run-time.
  */
 export function getHighestEnumValue<T>(transpiledEnum: T): T[keyof T] {
   const enumValues = getEnumValues(transpiledEnum);
 
   const lastElement = enumValues[enumValues.length - 1];
-  if (lastElement === undefined) {
-    error(
-      "Failed to get the last value from an enum since the enum was empty.",
-    );
-  }
+  assertDefined(
+    lastElement,
+    "Failed to get the last value from an enum since the enum was empty.",
+  );
 
   return lastElement;
 }
@@ -128,6 +131,15 @@ export function getRandomEnumValue<T>(
   return getRandomArrayElement(enumValues, seedOrRNG, exceptions);
 }
 
+/** Helper function to validate that a particular value exists inside of an enum. */
+export function isEnumValue(
+  value: number | string,
+  transpiledEnum: Record<string | number, string | number>,
+): boolean {
+  const enumValues = getEnumValues(transpiledEnum);
+  return enumValues.includes(value);
+}
+
 /**
  * Helper function to check every value of a custom enum for -1. Will throw an run-time error if any
  * -1 values are found. This is helpful because many methods of the Isaac class return -1 if they
@@ -167,12 +179,12 @@ export function validateEnumContiguous<T>(
 ): void {
   const values = getEnumValues(transpiledEnum);
   const lastValue = values[values.length - 1];
-  if (lastValue === undefined) {
-    error(
-      "Failed to validate that an enum was contiguous, since the last value was undefined.",
-    );
-  }
-  if (typeof lastValue !== "number") {
+  assertDefined(
+    lastValue,
+    "Failed to validate that an enum was contiguous, since the last value was undefined.",
+  );
+
+  if (!isNumber(lastValue)) {
     error(
       "Failed to validate that an enum was contiguous, since the last value was not a number.",
     );

package/src/functions/gridEntities.ts

@@ -23,7 +23,7 @@ import { getEffects } from "./entitiesSpecific";
 import { isCircleIntersectingRectangle } from "./math";
 import { roomUpdateSafe } from "./rooms";
 import { asNumber, isNumber } from "./types";
-import { eRange, iRange } from "./utils";
+import { assertDefined, eRange, iRange } from "./utils";
 import { isVector, vectorEquals } from "./vector";
 
 const BREAKABLE_GRID_ENTITY_TYPES_BY_EXPLOSIONS =
@@ -58,11 +58,11 @@ export function convertXMLGridEntityType(
   gridEntityXMLVariant: int,
 ): [GridEntityType, int] | undefined {
   const gridEntityArray = GRID_ENTITY_XML_MAP.get(gridEntityXMLType);
-  if (gridEntityArray === undefined) {
-    error(
-      `Failed to find an entry in the grid entity map for XML entity type: ${gridEntityXMLType}`,
-    );
-  }
+  assertDefined(
+    gridEntityArray,
+    `Failed to find an entry in the grid entity map for XML entity type: ${gridEntityXMLType}`,
+  );
+
   const gridEntityType = gridEntityArray[0];
   let variant = gridEntityArray[1];
 
@@ -165,18 +165,16 @@ export function getConstituentsFromGridEntityID(
   const [gridEntityTypeString, variantString] = parts;
 
   const gridEntityType = tonumber(gridEntityTypeString);
-  if (gridEntityType === undefined) {
-    error(
-      `Failed to convert the grid entity type to a number: ${gridEntityTypeString}`,
-    );
-  }
+  assertDefined(
+    gridEntityType,
+    `Failed to convert the grid entity type to a number: ${gridEntityTypeString}`,
+  );
 
   const variant = tonumber(variantString);
-  if (variant === undefined) {
-    error(
-      `Failed to convert the grid entity variant to a number: ${variantString}`,
-    );
-  }
+  assertDefined(
+    variant,
+    `Failed to convert the grid entity variant to a number: ${variantString}`,
+  );
 
   return [gridEntityType, variant];
 }