isaacscript-common 4.0.5 → 4.2.0

package/functions/enums.d.ts

@@ -55,6 +55,12 @@ export declare function getEnumLength<T>(transpiledEnum: T): int;
  * https://isaacscript.github.io/gotchas#iterating-over-enums
  */
 export declare 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.
+ */
 export declare function getLastEnumValue<T>(transpiledEnum: T): T[keyof T];
 /**
  * Helper function to get a random value from the provided enum.
@@ -66,8 +72,9 @@ export declare function getLastEnumValue<T>(transpiledEnum: T): T[keyof T];
  */
 export declare function getRandomEnumValue<T>(transpiledEnum: T, seedOrRNG?: Seed | RNG, exceptions?: Array<T[keyof T]> | ReadonlyArray<T[keyof T]>): T[keyof T];
 /**
- * Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
- * because many methods of the Isaac class return -1 if they fail.
+ * 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
+ * fail.
  *
  * For example:
  *
@@ -80,3 +87,9 @@ export declare function getRandomEnumValue<T>(transpiledEnum: T, seedOrRNG?: See
  * ```
  */
 export declare function validateCustomEnum(transpiledEnumName: string, transpiledEnum: unknown): void;
+/**
+ * Helper function to validate if every value in an enum is contiguous, starting at 0.
+ *
+ * This is useful to automate checking large enums for typos.
+ */
+export declare function validateEnumContiguous<T>(transpiledEnumName: string, transpiledEnum: T): void;

package/functions/enums.lua

@@ -1,6 +1,8 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArrayMap = ____lualib.__TS__ArrayMap
+local Set = ____lualib.Set
+local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____array = require("functions.array")
 local getRandomArrayElement = ____array.getRandomArrayElement
@@ -8,6 +10,8 @@ local ____rng = require("functions.rng")
 local getRandomSeed = ____rng.getRandomSeed
 local ____types = require("functions.types")
 local isString = ____types.isString
+local ____utils = require("functions.utils")
+local irange = ____utils.irange
 --- TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
 -- when you iterate over them, you will get both the names of the enums and the values of the enums,
 -- in a random order. Use this helper function to get the entries of the enum with the reverse
@@ -101,6 +105,10 @@ function ____exports.getEnumValues(self, transpiledEnum)
         end
     )
 end
+--- 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.
 function ____exports.getLastEnumValue(self, transpiledEnum)
     local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
     local lastElement = enumValues[#enumValues]
@@ -125,8 +133,9 @@ function ____exports.getRandomEnumValue(self, transpiledEnum, seedOrRNG, excepti
     local enumValues = ____exports.getEnumValues(nil, transpiledEnum)
     return getRandomArrayElement(nil, enumValues, seedOrRNG, exceptions)
 end
---- Helper function to check every value of a custom enum for -1. This is helpful as a run-time check
--- because many methods of the Isaac class return -1 if they fail.
+--- 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
+-- fail.
 -- 
 -- For example:
 -- 
@@ -142,7 +151,26 @@ function ____exports.validateCustomEnum(self, transpiledEnumName, transpiledEnum
         local key = ____value[1]
         local value = ____value[2]
         if value == -1 then
-            error((("Failed to find custom enum value: " .. transpiledEnumName) .. ".") .. key)
+            error((("Failed to find the custom enum value: " .. transpiledEnumName) .. ".") .. key)
+        end
+    end
+end
+--- Helper function to validate if every value in an enum is contiguous, starting at 0.
+-- 
+-- This is useful to automate checking large enums for typos.
+function ____exports.validateEnumContiguous(self, transpiledEnumName, transpiledEnum)
+    local values = ____exports.getEnumValues(nil, transpiledEnum)
+    local valuesSet = __TS__New(Set, values)
+    local lastValue = values[#values]
+    if lastValue == nil then
+        error("Failed to validate that an enum was contiguous, since the last value was undefined.")
+    end
+    if type(lastValue) ~= "number" then
+        error("Failed to validate that an enum was contiguous, since the last value was not a number.")
+    end
+    for ____, value in ipairs(irange(nil, lastValue)) do
+        if not valuesSet:has(value) then
+            error((("Failed to find a custom enum value of " .. tostring(value)) .. " for: ") .. transpiledEnumName)
         end
     end
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "4.0.5",
+  "version": "4.2.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,6 @@
   "main": "index",
   "types": "index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^3.0.6"
+    "isaac-typescript-definitions": "^3.0.7"
   }
 }