isaacscript-common 31.4.0 → 31.6.0

package/src/functions/roomShapeWalls.ts

@@ -7,6 +7,7 @@ import { ReadonlySet } from "../types/ReadonlySet";
 import { getGridIndexesBetween } from "./gridIndex";
 import { getRoomShapeCorners, isLRoomShape } from "./roomShape";
 import { inBossRoomOf, inHomeCloset } from "./rooms";
+import { assertDefined } from "./utils";
 
 const ROOM_SHAPE_TO_WALL_GRID_INDEX_SET: ReadonlyMap<
   RoomShape,
@@ -329,10 +330,8 @@ export function isVanillaWallGridIndex(gridIndex: int): boolean {
     wallGridIndexSet = MOTHER_ROOM_CORNERS_SET;
   } else {
     wallGridIndexSet = ROOM_SHAPE_TO_WALL_GRID_INDEX_SET.get(roomShape);
-  }
-
-  if (wallGridIndexSet === undefined) {
-    error(
+    assertDefined(
+      wallGridIndexSet,
       `Failed to find the wall grid index set for: RoomShape.${RoomShape[roomShape]} (${roomShape})`,
     );
   }

package/src/functions/roomTransition.ts

@@ -5,6 +5,7 @@ import {
 } from "isaac-typescript-definitions";
 import { game } from "../core/cachedClasses";
 import { getRoomData, getRoomGridIndex } from "./roomData";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to reload the current room using `Game.StartRoomTransition`.
@@ -40,11 +41,10 @@ export function teleport(
   const level = game.GetLevel();
 
   const roomData = getRoomData(roomGridIndex);
-  if (roomData === undefined) {
-    error(
-      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
-    );
-  }
+  assertDefined(
+    roomData,
+    `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
+  );
 
   // This must be set before every `Game.StartRoomTransition` method invocation or else the function
   // can send you to the wrong room.

package/src/functions/rooms.ts

@@ -48,7 +48,7 @@ import { isLRoomShape } from "./roomShape";
 import { reloadRoom } from "./roomTransition";
 import { getGotoCommand } from "./stage";
 import { asNumber } from "./types";
-import { iRange } from "./utils";
+import { assertDefined, iRange } from "./utils";
 
 const SECRET_ROOM_TYPES = new ReadonlySet([
   RoomType.SECRET,
@@ -65,11 +65,10 @@ export function changeRoom(roomGridIndex: int): void {
   const level = game.GetLevel();
 
   const roomData = getRoomData(roomGridIndex);
-  if (roomData === undefined) {
-    error(
-      `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
-    );
-  }
+  assertDefined(
+    roomData,
+    `Failed to change the room to grid index ${roomGridIndex} because that room does not exist.`,
+  );
 
   // LeaveDoor must be set before every `Game.ChangeRoom` invocation or else the function can send
   // you to the wrong room.

package/src/functions/serialization.ts

@@ -10,6 +10,7 @@ import type {
 import { ISAAC_API_CLASS_TYPE_TO_FUNCTIONS } from "../objects/isaacAPIClassTypeToFunctions";
 import { getIsaacAPIClassName } from "./isaacAPIClass";
 import { isTable, isUserdata } from "./types";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to generically copy an Isaac API class without knowing what specific type of
@@ -27,11 +28,10 @@ export function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(
   }
 
   const isaacAPIClassType = getIsaacAPIClassName(isaacAPIClass);
-  if (isaacAPIClassType === undefined) {
-    error(
-      "Failed to copy an Isaac API class since it does not have a class type.",
-    );
-  }
+  assertDefined(
+    isaacAPIClassType,
+    "Failed to copy an Isaac API class since it does not have a class type.",
+  );
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
@@ -48,11 +48,10 @@ export function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to copy an Isaac API class since the associated functions were not found for Isaac API class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to copy an Isaac API class since the associated functions were not found for Isaac API class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.copy(isaacAPIClass);
 }
@@ -78,11 +77,10 @@ export function deserializeIsaacAPIClass<
   const copyableIsaacAPIClassType = getSerializedTableType(
     serializedIsaacAPIClass,
   );
-  if (copyableIsaacAPIClassType === undefined) {
-    error(
-      "Failed to deserialize an Isaac API class since a valid class type brand was not found.",
-    );
-  }
+  assertDefined(
+    copyableIsaacAPIClassType,
+    "Failed to deserialize an Isaac API class since a valid class type brand was not found.",
+  );
 
   type ThisIsaacAPIClassType = IsaacAPIClassTypeToType[SerializedT["__kind"]];
   type ThisSerializedIsaacAPIClassType = SerializedT;
@@ -95,11 +93,10 @@ export function deserializeIsaacAPIClass<
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.deserialize(serializedIsaacAPIClass);
 }
@@ -170,11 +167,10 @@ export function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(
   }
 
   const isaacAPIClassType = getIsaacAPIClassName(isaacAPIClass);
-  if (isaacAPIClassType === undefined) {
-    error(
-      "Failed to serialize an Isaac API class since it does not have a class type.",
-    );
-  }
+  assertDefined(
+    isaacAPIClassType,
+    "Failed to serialize an Isaac API class since it does not have a class name.",
+  );
 
   const copyableIsaacAPIClassType =
     isaacAPIClassType as CopyableIsaacAPIClassType;
@@ -191,11 +187,10 @@ export function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(
         ThisSerializedIsaacAPIClassType
       >
     | undefined;
-  if (functions === undefined) {
-    error(
-      `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
-    );
-  }
+  assertDefined(
+    functions,
+    `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`,
+  );
 
   return functions.serialize(isaacAPIClass);
 }

package/src/functions/table.ts

@@ -1,4 +1,5 @@
 import { isBoolean, isNumber, isString, isUserdata } from "./types";
+import { assertDefined } from "./utils";
 
 /**
  * In a `Map`, you can use the `clear` method to delete every element. However, in a `LuaMap`, the
@@ -47,11 +48,10 @@ export function getBooleansFromTable(
   const booleans: boolean[] = [];
   for (const key of keys) {
     const value = luaMap.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
+    assertDefined(
+      value,
+      `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+    );
 
     if (isBoolean(value)) {
       booleans.push(value);
@@ -79,21 +79,20 @@ export function getNumbersFromTable(
   const numbers: number[] = [];
   for (const key of keys) {
     const value = luaMap.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
+    assertDefined(
+      value,
+      `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+    );
 
     if (isNumber(value)) {
       numbers.push(value);
     } else if (isString(value)) {
       const number = tonumber(value);
-      if (number === undefined) {
-        error(
-          `Failed to convert the "${key}" value of a table representing a "${objectName}" object to a number: ${value}`,
-        );
-      }
+      assertDefined(
+        number,
+        `Failed to convert the "${key}" value of a table representing a "${objectName}" object to a number: ${value}`,
+      );
+
       numbers.push(number);
     } else {
       error(
@@ -119,11 +118,10 @@ export function getStringsFromTable(
   const strings: string[] = [];
   for (const key of keys) {
     const value = luaMap.get(key);
-    if (value === undefined) {
-      error(
-        `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
-      );
-    }
+    assertDefined(
+      value,
+      `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
+    );
 
     if (isString(value)) {
       strings.push(value);

package/src/functions/tstlClass.ts

@@ -2,6 +2,7 @@ import type { DefaultMap } from "../classes/DefaultMap";
 import type { TSTLClassMetatable } from "../interfaces/TSTLClassMetatable";
 import type { TSTLClass } from "../types/TSTLClass";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 /**
  * Helper function to get the constructor from an instantiated TypeScriptToLua class, which is
@@ -94,11 +95,10 @@ export function isTSTLSet(object: unknown): object is Set<AnyNotNil> {
  */
 export function newTSTLClass(oldClass: TSTLClass): TSTLClass {
   const constructor = getTSTLClassConstructor(oldClass);
-  if (constructor === undefined) {
-    error(
-      "Failed to instantiate a new TypeScriptToLua class since the provided old class does not have a metatable/constructor.",
-    );
-  }
+  assertDefined(
+    constructor,
+    "Failed to instantiate a new TypeScriptToLua class since the provided old class does not have a metatable/constructor.",
+  );
 
   // We re-implement some of the logic from the transpiled "__TS__New" function.
   const newClass = new LuaMap<AnyNotNil, unknown>();

package/src/functions/utils.ts

@@ -1,9 +1,26 @@
-import { RenderMode } from "isaac-typescript-definitions";
-import { game } from "../core/cachedClasses";
 import { ReadonlySet } from "../types/ReadonlySet";
 import { getAllPlayers } from "./playerIndex";
 import { isFunction } from "./types";
 
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+export function assertDefined<T>(
+  value: T,
+  ...[msg]: [undefined] extends [T]
+    ? [string]
+    : [
+        "The assertion is useless because the provided value does not contain undefined.",
+      ]
+): asserts value is Exclude<T, undefined> {
+  if (value === undefined) {
+    error(msg);
+  }
+}
+
 /**
  * Helper function to return an array of integers with the specified range, inclusive on the lower
  * end and exclusive on the high end. (The "e" in the function name stands for exclusive.) Thus,
@@ -123,21 +140,6 @@ export function isMultiplayer(): boolean {
   return controllerIndexesSet.size > 1;
 }
 
-/**
- * Helper function to see if the current render callback is rendering a water reflection.
- *
- * When the player is in a room with water, things will be rendered twice: once for the normal
- * rendering, and once for the reflecting rendering. Thus, any mod code in a render callback will
- * run twice per frame in these situations, which may be unexpected or cause bugs.
- *
- * This function is typically used to early return from a render function if it returns true.
- */
-export function isReflectionRender(): boolean {
-  const room = game.GetRoom();
-  const renderMode = room.GetRenderMode();
-  return renderMode === RenderMode.WATER_REFLECT;
-}
-
 /**
  * Helper function to check if the player is using Afterbirth+ or Repentance.
  *
@@ -148,16 +150,18 @@ export function isReflectionRender(): boolean {
  */
 export function isRepentance(): boolean {
   const metatable = getmetatable(Sprite) as LuaMap<string, unknown> | undefined;
-  if (metatable === undefined) {
-    error("Failed to get the metatable of the Sprite global table.");
-  }
+  assertDefined(
+    metatable,
+    "Failed to get the metatable of the Sprite global table.",
+  );
 
   const classTable = metatable.get("__class") as
     | LuaMap<string, unknown>
     | undefined;
-  if (classTable === undefined) {
-    error('Failed to get the "__class" key of the Sprite metatable.');
-  }
+  assertDefined(
+    classTable,
+    'Failed to get the "__class" key of the Sprite metatable.',
+  );
 
   const getAnimation = classTable.get("GetAnimation");
   return isFunction(getAnimation);

package/src/functions/vector.ts

@@ -13,6 +13,7 @@ import {
   tableHasKeys,
 } from "./table";
 import { isTable } from "./types";
+import { assertDefined } from "./utils";
 
 export type SerializedVector = LuaMap<string, unknown> & {
   readonly __serializedVectorBrand: symbol;
@@ -46,16 +47,14 @@ export function deserializeVector(vector: SerializedVector): Vector {
 
   const [x, y] = getNumbersFromTable(vector, OBJECT_NAME, ...KEYS);
 
-  if (x === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: X`,
-    );
-  }
-  if (y === undefined) {
-    error(
-      `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Y`,
-    );
-  }
+  assertDefined(
+    x,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: X`,
+  );
+  assertDefined(
+    y,
+    `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: Y`,
+  );
 
   return Vector(x, y);
 }

package/src/functions/weighted.ts

@@ -2,6 +2,7 @@ import type { WeightedArray } from "../types/WeightedArray";
 import { sumArray } from "./array";
 import { getRandomFloat } from "./random";
 import { getRandomSeed } from "./rng";
+import { assertDefined } from "./utils";
 
 /**
  * Get a random value from a `WeightedArray`. (A `WeightedArray` is an array of tuples, where the
@@ -15,11 +16,10 @@ export function getRandomFromWeightedArray<T>(
   const randomIndex = getRandomIndexFromWeightedArray(weightedArray, seedOrRNG);
 
   const randomElement = weightedArray[randomIndex];
-  if (randomElement === undefined) {
-    error(
-      `Failed to get an element from a weighted array using a random index of: ${randomIndex}`,
-    );
-  }
+  assertDefined(
+    randomElement,
+    `Failed to get an element from a weighted array using a random index of: ${randomIndex}`,
+  );
 
   return randomElement[0];
 }

package/src/index.ts

@@ -95,6 +95,7 @@ export * from "./functions/pressurePlate";
 export * from "./functions/projectiles";
 export * from "./functions/random";
 export * from "./functions/readOnly";
+export * from "./functions/render";
 export * from "./functions/revive";
 export * from "./functions/rng";
 export * from "./functions/rockAlt";
@@ -157,6 +158,7 @@ export * from "./types/AnyGridEntity";
 export * from "./types/ConversionHeartSubType";
 export * from "./types/Decrement";
 export * from "./types/EntityID";
+export * from "./types/Expand";
 export * from "./types/FunctionTuple";
 export * from "./types/GridEntityID";
 export * from "./types/HasFunction";

package/src/sets/bossSets.ts

@@ -31,6 +31,7 @@ import {
 } from "isaac-typescript-definitions";
 import { parseEntityTypeVariantString } from "../functions/entities";
 import { copySet } from "../functions/set";
+import { assertDefined } from "../functions/utils";
 import { ReadonlyMap } from "../types/ReadonlyMap";
 import { ReadonlySet } from "../types/ReadonlySet";
 import { STORY_BOSSES_SET } from "./storyBossesSet";
@@ -489,11 +490,10 @@ function getAllBossesExcludingStoryBossesSet(): ReadonlySet<string> {
   const allBosses = [...ALL_BOSSES_SET.values()];
   for (const entityTypeVariantString of allBosses) {
     const tuple = parseEntityTypeVariantString(entityTypeVariantString);
-    if (tuple === undefined) {
-      error(
-        "Failed to parse a boss tuple when constructing the story boss set.",
-      );
-    }
+    assertDefined(
+      tuple,
+      "Failed to parse a boss tuple when constructing the story boss set.",
+    );
 
     const [entityType, _variant] = tuple;
     if (STORY_BOSSES_SET.has(entityType)) {

package/src/types/Expand.ts

@@ -0,0 +1,5 @@
+/**
+ * From:
+ * https://stackoverflow.com/questions/57683303/how-can-i-see-the-full-expanded-contract-of-a-typescript-type
+ */
+export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;