isaacscript-common 57.1.0 → 57.2.0

package/dist/index.rollup.d.ts

@@ -1238,6 +1238,16 @@ export declare function assertDefined<T>(value: T, ...[msg]: [undefined] extends
 "The assertion is useless because the provided value does not contain undefined."
 ]): asserts value is Exclude<T, undefined>;
 
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `null`.
+ *
+ * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+ */
+export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T] ? [string] : [
+"The assertion is useless because the provided value does not contain null."
+]): asserts value is Exclude<T, null>;
+
 /**
  * Helper function to safely cast an enum to a `string`. (This is better than using the `as`
  * TypeScript keyword to do a type assertion, since that can obfuscate compiler errors. )
@@ -8224,7 +8234,7 @@ export declare function inBossRoomOf(bossID: BossID): boolean;
  * This is useful when the normal `Array.includes` produces a type error from an array that uses an
  * `as const` assertion.
  */
-export declare function includes<T, S extends WidenLiteral<T>>(haystack: readonly S[], needle: WidenLiteral<T>): needle is S;
+export declare function includes<T, TupleElement extends WidenLiteral<T>>(array: readonly TupleElement[], searchElement: WidenLiteral<T>): searchElement is TupleElement;
 
 /**
  * Helper function for determining whether the current room is a crawl space. Use this function over

package/dist/isaacscript-common.lua

@@ -1,6 +1,6 @@
 --[[
 
-isaacscript-common 57.1.0
+isaacscript-common 57.2.0
 
 This is the "isaacscript-common" library, which was created with the IsaacScript tool.
 
@@ -16259,6 +16259,14 @@ function ____exports.assertDefined(self, value, ...)
         error(msg)
     end
 end
+function ____exports.assertNotNull(self, value, ...)
+    local ____bindingPattern0 = {...}
+    local msg
+    msg = ____bindingPattern0[1]
+    if value == nil then
+        error(msg)
+    end
+end
 function ____exports.eRange(self, start, ____end, increment)
     if increment == nil then
         increment = 1
@@ -17208,9 +17216,9 @@ function ____exports.getRandomArrayElementAndRemove(self, array, seedOrRNG, exce
     ____exports.arrayRemoveInPlace(nil, array, randomArrayElement)
     return randomArrayElement
 end
-function ____exports.includes(self, haystack, needle)
-    local _haystack = haystack
-    return __TS__ArrayIncludes(_haystack, needle)
+function ____exports.includes(self, array, searchElement)
+    local widenedArray = array
+    return __TS__ArrayIncludes(widenedArray, searchElement)
 end
 function ____exports.isArray(self, object, ensureContiguousValues)
     if ensureContiguousValues == nil then

package/dist/src/functions/array.d.ts

@@ -185,7 +185,7 @@ export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOr
  * This is useful when the normal `Array.includes` produces a type error from an array that uses an
  * `as const` assertion.
  */
-export declare function includes<T, S extends WidenLiteral<T>>(haystack: readonly S[], needle: WidenLiteral<T>): needle is S;
+export declare function includes<T, TupleElement extends WidenLiteral<T>>(array: readonly TupleElement[], searchElement: WidenLiteral<T>): searchElement is TupleElement;
 /**
  * Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
  * particular table is being used as an array. `isArray` returns true if:

package/dist/src/functions/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}

package/dist/src/functions/array.lua

@@ -455,9 +455,9 @@ end
 -- 
 -- This is useful when the normal `Array.includes` produces a type error from an array that uses an
 -- `as const` assertion.
-function ____exports.includes(self, haystack, needle)
-    local _haystack = haystack
-    return __TS__ArrayIncludes(_haystack, needle)
+function ____exports.includes(self, array, searchElement)
+    local widenedArray = array
+    return __TS__ArrayIncludes(widenedArray, searchElement)
 end
 --- Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a
 -- particular table is being used as an array. `isArray` returns true if:

package/dist/src/functions/utils.d.ts

@@ -8,6 +8,15 @@
 export declare 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>;
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `null`.
+ *
+ * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+ */
+export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T] ? [string] : [
+    "The assertion is useless because the provided value does not contain null."
+]): asserts value is Exclude<T, null>;
 /**
  * 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,

package/dist/src/functions/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/functions/utils.ts"],"names":[],"mappings":";AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,MAAM,CAAC,GACR;IACE,iFAAiF;CAClF,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAIxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,GAAG,EAAE,CAkBlE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,GAAG,EAAE,CAQlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAI3D;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAG"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/functions/utils.ts"],"names":[],"mappings":";AAIA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,MAAM,CAAC,GACR;IACE,iFAAiF;CAClF,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAIxC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GACxB,CAAC,MAAM,CAAC,GACR;IACE,4EAA4E;CAC7E,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAInC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,GAAG,EAAE,CAkBlE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,SAAS,SAAI,GAAG,GAAG,EAAE,CAQlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAMvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI,CAI3D;AAED;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAG"}

package/dist/src/functions/utils.lua

@@ -20,6 +20,18 @@ function ____exports.assertDefined(self, value, ...)
         error(msg)
     end
 end
+--- Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+-- to `null`.
+-- 
+-- This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+function ____exports.assertNotNull(self, value, ...)
+    local ____bindingPattern0 = {...}
+    local msg
+    msg = ____bindingPattern0[1]
+    if value == nil then
+        error(msg)
+    end
+end
 --- 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,
 -- this function works in a similar way as the built-in `range` function from Python.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "57.1.0",
+  "version": "57.2.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/src/functions/array.ts

@@ -473,12 +473,12 @@ export function getRandomArrayIndex<T>(
  * This is useful when the normal `Array.includes` produces a type error from an array that uses an
  * `as const` assertion.
  */
-export function includes<T, S extends WidenLiteral<T>>(
-  haystack: readonly S[],
-  needle: WidenLiteral<T>,
-): needle is S {
-  const _haystack: ReadonlyArray<WidenLiteral<T>> = haystack;
-  return _haystack.includes(needle);
+export function includes<T, TupleElement extends WidenLiteral<T>>(
+  array: readonly TupleElement[],
+  searchElement: WidenLiteral<T>,
+): searchElement is TupleElement {
+  const widenedArray: ReadonlyArray<WidenLiteral<T>> = array;
+  return widenedArray.includes(searchElement);
 }
 
 /**

package/src/functions/utils.ts

@@ -21,6 +21,25 @@ export function assertDefined<T>(
   }
 }
 
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `null`.
+ *
+ * This is useful to have TypeScript narrow a `T | null` value to `T` in a concise way.
+ */
+export function assertNotNull<T>(
+  value: T,
+  ...[msg]: [null] extends [T]
+    ? [string]
+    : [
+        "The assertion is useless because the provided value does not contain null.",
+      ]
+): asserts value is Exclude<T, null> {
+  if (value === null) {
+    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,