isaacscript-common 3.15.0 → 3.15.3

package/functions/rng.lua

@@ -1,4 +1,5 @@
 local ____lualib = require("lualib_bundle")
+local __TS__TypeOf = ____lualib.__TS__TypeOf
 local __TS__ObjectValues = ____lualib.__TS__ObjectValues
 local ____exports = {}
 local RECOMMENDED_SHIFT_IDX, OBJECT_NAME
@@ -14,6 +15,8 @@ local isIsaacAPIClassOfType = ____isaacAPIClass.isIsaacAPIClassOfType
 local ____table = require("functions.table")
 local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
+local ____types = require("functions.types")
+local isTable = ____types.isTable
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 --- Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
@@ -86,8 +89,7 @@ function ____exports.copyRNG(self, rng, serializationType)
         ____cond3 = ____cond3 or ____switch3 == SerializationType.DESERIALIZE
         if ____cond3 then
             do
-                local rngType = type(rng)
-                if ____exports.isRNG(nil, rng) or rngType ~= "table" then
+                if not isTable(nil, rng) then
                     error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object was not a Lua table.")
                 end
                 local seedNumber = table.unpack(getNumbersFromTable(
@@ -110,16 +112,14 @@ end
 --- Used to determine is the given table is a serialized `RNG` object created by the save data
 -- manager and/or the `deepCopy` function.
 function ____exports.isSerializedRNG(self, object)
-    local objectType = type(object)
-    if objectType ~= "table" then
+    if not isTable(nil, object) then
         return false
     end
-    local ____table = object
     return tableHasKeys(
         nil,
-        ____table,
+        object,
         table.unpack(KEYS)
-    ) and ____table[SerializationBrand.RNG] ~= nil
+    ) and object[SerializationBrand.RNG] ~= nil
 end
 function ____exports.rngEquals(self, rng1, rng2)
     return isaacAPIClassEquals(nil, rng1, rng2, KEYS)
@@ -127,12 +127,10 @@ end
 --- Helper function to iterate over the provided object and set the seed for all of the values that
 -- are RNG objects equal to a particular seed.
 function ____exports.setAllRNGToSeed(self, object, seed)
-    local objectType = type(object)
-    if objectType ~= "table" then
-        error("Failed to iterate over the object containing RNG objects since the type of the provided object was: " .. objectType)
+    if not isTable(nil, object) then
+        error("Failed to iterate over the object containing RNG objects since the type of the provided object was: " .. __TS__TypeOf(object))
     end
-    local ____table = object
-    for ____, value in ipairs(__TS__ObjectValues(____table)) do
+    for ____, value in ipairs(__TS__ObjectValues(table)) do
         if ____exports.isRNG(nil, value) then
             ____exports.setSeed(nil, value, seed)
         end

package/functions/serialization.d.ts

@@ -5,7 +5,7 @@ export declare function copyIsaacAPIClass(isaacAPIClass: unknown, serializationT
  * Deserialization is a special case, so we make a dedicated function for this.
  *
  * There is no need for a corresponding "serializeIsaacAPIClass" function because the
- * "copyIsaacAPIClass" function can handles all serialization types.
+ * "copyIsaacAPIClass" function can handle all serialization types.
  */
 export declare function deserializeIsaacAPIClass(serializedIsaacAPIClass: SerializedIsaacAPIClass): unknown;
 export declare function isSerializedIsaacAPIClass(object: unknown): object is SerializedIsaacAPIClass;

package/functions/serialization.lua

@@ -1,4 +1,5 @@
 local ____lualib = require("lualib_bundle")
+local __TS__TypeOf = ____lualib.__TS__TypeOf
 local __TS__ObjectEntries = ____lualib.__TS__ObjectEntries
 local __TS__ObjectValues = ____lualib.__TS__ObjectValues
 local __TS__ArraySome = ____lualib.__TS__ArraySome
@@ -14,6 +15,9 @@ local ____serializedIsaacAPIClassTypeToIdentityFunction = require("objects.seria
 local SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION = ____serializedIsaacAPIClassTypeToIdentityFunction.SERIALIZED_ISAAC_API_CLASS_TYPE_TO_IDENTITY_FUNCTION
 local ____isaacAPIClass = require("functions.isaacAPIClass")
 local getIsaacAPIClassName = ____isaacAPIClass.getIsaacAPIClassName
+local ____types = require("functions.types")
+local isTable = ____types.isTable
+local isUserdata = ____types.isUserdata
 function getSerializedTableType(self, serializedIsaacAPIClass)
     for ____, ____value in ipairs(__TS__ObjectEntries(ISAAC_API_CLASS_TYPE_TO_BRAND)) do
         local copyableIsaacAPIClassType = ____value[1]
@@ -25,9 +29,8 @@ function getSerializedTableType(self, serializedIsaacAPIClass)
     return nil
 end
 function ____exports.copyIsaacAPIClass(self, isaacAPIClass, serializationType)
-    local objectType = type(isaacAPIClass)
-    if objectType ~= "userdata" then
-        error("Failed to copy an Isaac API class since the provided object was of type: " .. objectType)
+    if not isUserdata(nil, isaacAPIClass) then
+        error("Failed to copy an Isaac API class since the provided object was of type: " .. __TS__TypeOf(isaacAPIClass))
     end
     local isaacAPIClassType = getIsaacAPIClassName(nil, isaacAPIClass)
     if isaacAPIClassType == nil then
@@ -43,11 +46,10 @@ end
 --- Deserialization is a special case, so we make a dedicated function for this.
 -- 
 -- There is no need for a corresponding "serializeIsaacAPIClass" function because the
--- "copyIsaacAPIClass" function can handles all serialization types.
+-- "copyIsaacAPIClass" function can handle all serialization types.
 function ____exports.deserializeIsaacAPIClass(self, serializedIsaacAPIClass)
-    local objectType = type(serializedIsaacAPIClass)
-    if objectType ~= "table" then
-        error("Failed to deserialize an Isaac API class since the provided object was of type: " .. objectType)
+    if not isTable(nil, serializedIsaacAPIClass) then
+        error("Failed to deserialize an Isaac API class since the provided object was of type: " .. __TS__TypeOf(serializedIsaacAPIClass))
     end
     local copyableIsaacAPIClassType = getSerializedTableType(nil, serializedIsaacAPIClass)
     if copyableIsaacAPIClassType == nil then

package/functions/table.d.ts

@@ -3,46 +3,50 @@
  * In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
  * `clear` method does not exist. Use this helper function as a drop-in replacement for this.
  */
-export declare function clearTable(table: LuaTable): void;
+export declare function clearTable(luaTable: LuaTable): void;
 /** Helper function to copy specific values from a object to a table. */
-export declare function copyValuesToTable(object: unknown, keys: string[], table: LuaTable<string, unknown>): void;
+export declare function copyValuesToTable(object: unknown, keys: string[], luaTable: LuaTable<string, unknown>): void;
 /**
  * Helper function to safely get boolean values from a Lua table. Will throw an error if the
  * specific value does not exist on the table.
  *
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
-export declare function getBooleansFromTable(table: LuaTable<string, unknown>, objectName: string, ...keys: string[]): boolean[];
+export declare function getBooleansFromTable(luaTable: LuaTable<string, unknown>, objectName: string, ...keys: string[]): boolean[];
 /**
  * Helper function to safely get number values from a Lua table. Will throw an error if the specific
  * value does not exist on the table or if it cannot be converted to a number.
  *
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
-export declare function getNumbersFromTable(table: LuaTable<string, unknown>, objectName: string, ...keys: string[]): number[];
+export declare function getNumbersFromTable(luaTable: LuaTable<string, unknown>, objectName: string, ...keys: string[]): number[];
 /**
  * Helper function to safely get string values from a Lua table. Will throw an error if the specific
  * value does not exist on the table.
  *
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
-export declare function getStringsFromTable(table: LuaTable<string, unknown>, objectName: string, ...keys: string[]): string[];
+export declare function getStringsFromTable(luaTable: LuaTable<string, unknown>, objectName: string, ...keys: string[]): string[];
 /**
  * Helper function to iterate over a table deterministically. This is useful because by default, the
  * `pairs` function will return the keys of a Lua table in a random order.
  *
  * This function will sort the table entries based on the value of the key.
  *
- * @param table The table to iterate over.
+ * This function will only work on tables that have number keys or string keys. It will throw a
+ * runtime error if it encounters a key of another type.
+ *
+ * @param luaTable The table to iterate over.
  * @param func The function to run for each iteration.
- * @param deterministic Optional. Whether to iterate deterministically. True by default. You can
- *                      dynamically set to false in situations where you need extra performance.
+ * @param inOrder Optional. Whether to iterate in order. True by default. You can dynamically set to
+ *                false in situations where iterating randomly would not matter and you need the
+ *                extra performance.
  */
-export declare function iterateTableDeterministically<K, V>(table: LuaTable<K, V>, func: (key: K, value: V) => void, deterministic?: boolean): void;
+export declare function iterateTableInOrder<K, V>(luaTable: LuaTable<K, V>, func: (key: K, value: V) => void, inOrder?: boolean): void;
 /**
  * Helper function to check if a Lua table has all of the provided keys.
  *
  * This function is variadic, meaning that you can specify as many arguments as you want to check
  * for.
  */
-export declare function tableHasKeys(table: LuaTable<AnyNotNil, unknown>, ...keys: string[]): boolean;
+export declare function tableHasKeys(luaTable: LuaTable<AnyNotNil, unknown>, ...keys: string[]): boolean;

package/functions/table.lua

@@ -1,38 +1,41 @@
 local ____lualib = require("lualib_bundle")
 local __TS__TypeOf = ____lualib.__TS__TypeOf
-local __TS__ArraySort = ____lualib.__TS__ArraySort
+local __TS__ObjectKeys = ____lualib.__TS__ObjectKeys
 local __TS__ArrayEvery = ____lualib.__TS__ArrayEvery
+local __TS__ArraySort = ____lualib.__TS__ArraySort
 local ____exports = {}
-local ____utils = require("functions.utils")
-local twoDimensionalSort = ____utils.twoDimensionalSort
+local ____types = require("functions.types")
+local isBoolean = ____types.isBoolean
+local isNumber = ____types.isNumber
+local isString = ____types.isString
 --- In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
 -- `clear` method does not exist. Use this helper function as a drop-in replacement for this.
-function ____exports.clearTable(self, ____table)
-    for key in pairs(____table) do
-        ____table[key] = nil
+function ____exports.clearTable(self, luaTable)
+    for key in pairs(luaTable) do
+        luaTable[key] = nil
     end
 end
 --- Helper function to copy specific values from a object to a table.
-function ____exports.copyValuesToTable(self, object, keys, ____table)
+function ____exports.copyValuesToTable(self, object, keys, luaTable)
     local otherTable = object
     for ____, key in ipairs(keys) do
         local value = otherTable[key]
-        ____table[key] = value
+        luaTable[key] = value
     end
 end
 --- Helper function to safely get boolean values from a Lua table. Will throw an error if the
 -- specific value does not exist on the table.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to get N values.
-function ____exports.getBooleansFromTable(self, ____table, objectName, ...)
+function ____exports.getBooleansFromTable(self, luaTable, objectName, ...)
     local keys = {...}
     local booleans = {}
     for ____, key in ipairs(keys) do
-        local value = ____table[key]
+        local value = luaTable[key]
         if value == nil then
             error(((("Failed to find a value for \"" .. key) .. "\" in a table representing a \"") .. objectName) .. "\" object.")
         end
-        if type(value) == "boolean" then
+        if isBoolean(nil, value) then
             booleans[#booleans + 1] = value
         else
             error((((("Failed to get the boolean for the \"" .. key) .. "\" value of a table representing a \"") .. objectName) .. "\" object because the type was: ") .. __TS__TypeOf(value))
@@ -44,17 +47,17 @@ end
 -- value does not exist on the table or if it cannot be converted to a number.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to get N values.
-function ____exports.getNumbersFromTable(self, ____table, objectName, ...)
+function ____exports.getNumbersFromTable(self, luaTable, objectName, ...)
     local keys = {...}
     local numbers = {}
     for ____, key in ipairs(keys) do
-        local value = ____table[key]
+        local value = luaTable[key]
         if value == nil then
             error(((("Failed to find a value for \"" .. key) .. "\" in a table representing a \"") .. objectName) .. "\" object.")
         end
-        if type(value) == "number" then
+        if isNumber(nil, value) then
             numbers[#numbers + 1] = value
-        elseif type(value) == "string" then
+        elseif isString(nil, value) then
             local number = tonumber(value)
             if number == nil then
                 error((((("Failed to convert the \"" .. key) .. "\" value of a table representing a \"") .. objectName) .. "\" object to a number: ") .. value)
@@ -70,15 +73,15 @@ end
 -- value does not exist on the table.
 -- 
 -- This function is variadic, meaning that you can specify N arguments to get N values.
-function ____exports.getStringsFromTable(self, ____table, objectName, ...)
+function ____exports.getStringsFromTable(self, luaTable, objectName, ...)
     local keys = {...}
     local strings = {}
     for ____, key in ipairs(keys) do
-        local value = ____table[key]
+        local value = luaTable[key]
         if value == nil then
             error(((("Failed to find a value for \"" .. key) .. "\" in a table representing a \"") .. objectName) .. "\" object.")
         end
-        if type(value) == "string" then
+        if isString(nil, value) then
             strings[#strings + 1] = value
         else
             local ____string = tostring(value)
@@ -92,41 +95,55 @@ end
 -- 
 -- This function will sort the table entries based on the value of the key.
 -- 
--- @param table The table to iterate over.
+-- This function will only work on tables that have number keys or string keys. It will throw a
+-- runtime error if it encounters a key of another type.
+-- 
+-- @param luaTable The table to iterate over.
 -- @param func The function to run for each iteration.
--- @param deterministic Optional. Whether to iterate deterministically. True by default. You can
--- dynamically set to false in situations where you need extra performance.
-function ____exports.iterateTableDeterministically(self, ____table, func, deterministic)
-    if deterministic == nil then
-        deterministic = true
+-- @param inOrder Optional. Whether to iterate in order. True by default. You can dynamically set to
+-- false in situations where iterating randomly would not matter and you need the
+-- extra performance.
+function ____exports.iterateTableInOrder(self, luaTable, func, inOrder)
+    if inOrder == nil then
+        inOrder = true
     end
-    if not deterministic then
-        for key, value in pairs(____table) do
+    if not inOrder then
+        for key, value in pairs(luaTable) do
             func(nil, key, value)
         end
         return
     end
-    local entriesArray = {}
-    for key, value in pairs(____table) do
-        local entry = {key, value}
-        entriesArray[#entriesArray + 1] = entry
+    local keys = __TS__ObjectKeys(luaTable)
+    local hasAllNumberKeys = __TS__ArrayEvery(
+        keys,
+        function(____, key) return isNumber(nil, key) end
+    )
+    local hasAllStringKeys = __TS__ArrayEvery(
+        keys,
+        function(____, key) return isString(nil, key) end
+    )
+    if not hasAllNumberKeys and not hasAllStringKeys then
+        for key, value in pairs(luaTable) do
+            func(nil, key, value)
+        end
+        return
     end
-    __TS__ArraySort(entriesArray, twoDimensionalSort)
-    for ____, ____value in ipairs(entriesArray) do
-        local key = ____value[1]
-        local value = ____value[2]
-        func(nil, key, value)
+    __TS__ArraySort(keys)
+    for ____, key in ipairs(keys) do
+        local keyIndex = key
+        local value = luaTable[keyIndex]
+        func(nil, keyIndex, value)
     end
 end
 --- Helper function to check if a Lua table has all of the provided keys.
 -- 
 -- This function is variadic, meaning that you can specify as many arguments as you want to check
 -- for.
-function ____exports.tableHasKeys(self, ____table, ...)
+function ____exports.tableHasKeys(self, luaTable, ...)
     local keys = {...}
     return __TS__ArrayEvery(
         keys,
-        function(____, key) return ____table[key] ~= nil end
+        function(____, key) return luaTable[key] ~= nil end
     )
 end
 return ____exports

package/functions/tstlClass.lua

@@ -3,6 +3,9 @@ local Set = ____lualib.Set
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local newTSTLClassFromMetatable, VANILLA_TSTL_CLASSES
+local ____types = require("functions.types")
+local isString = ____types.isString
+local isTable = ____types.isTable
 --- Helper function to get the name of a TypeScriptToLua class. TSTL classes are Lua tables created
 -- with the `__TS__Class` Lua function from the TSTL lualib. Their name is contained within
 -- "constructor.name" metatable key.
@@ -12,7 +15,7 @@ local newTSTLClassFromMetatable, VANILLA_TSTL_CLASSES
 -- Returns undefined if the object is not a table or if the aforementioned metatable key does not
 -- exist.
 function ____exports.getTSTLClassName(self, object)
-    if type(object) ~= "table" then
+    if not isTable(nil, object) then
         return nil
     end
     local metatable = getmetatable(object)
@@ -76,8 +79,7 @@ function ____exports.isUserDefinedTSTLClass(self, object)
     if ____exports.isVanillaTSTLClass(nil, object) or ____exports.isIsaacScriptCommonClass(nil, object) then
         return false
     end
-    local objectType = type(object)
-    if objectType ~= "table" then
+    if not isTable(nil, object) then
         return false
     end
     local metatable = getmetatable(object)
@@ -87,7 +89,7 @@ function ____exports.isUserDefinedTSTLClass(self, object)
     local numKeys = 0
     for key in pairs(metatable) do
         numKeys = numKeys + 1
-        if type(key) ~= "string" then
+        if not isString(nil, key) then
             return false
         end
         if not TSTL_CLASS_METATABLE_KEYS:has(key) then

package/functions/types.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="typescript-to-lua/language-extensions" />
+/// <reference types="lua-types/5.3" />
+export declare function isBoolean(variable: unknown): variable is boolean;
+export declare function isFunction(variable: unknown): variable is Function;
+export declare function isNumber(variable: unknown): variable is number;
+/** Helper function to detect if a variable is a boolean, number, or string. */
+export declare function isPrimitive(variable: unknown): variable is boolean | number | string;
+export declare function isString(variable: unknown): variable is string;
+export declare function isTable(variable: unknown): variable is LuaTable;
+export declare function isUserdata(variable: unknown): variable is LuaUserdata;

package/functions/types.lua

@@ -0,0 +1,25 @@
+local ____exports = {}
+function ____exports.isBoolean(self, variable)
+    return type(variable) == "boolean"
+end
+function ____exports.isFunction(self, variable)
+    return type(variable) == "function"
+end
+function ____exports.isNumber(self, variable)
+    return type(variable) == "number"
+end
+--- Helper function to detect if a variable is a boolean, number, or string.
+function ____exports.isPrimitive(self, variable)
+    local variableType = type(variable)
+    return variableType == "boolean" or variableType == "number" or variableType == "string"
+end
+function ____exports.isString(self, variable)
+    return type(variable) == "string"
+end
+function ____exports.isTable(self, variable)
+    return type(variable) == "table"
+end
+function ____exports.isUserdata(self, variable)
+    return type(variable) == "userdata"
+end
+return ____exports

package/functions/utils.d.ts

@@ -66,8 +66,6 @@ export declare function hexToKColor(hexString: string, alpha: float): KColor;
  * If only one argument is specified, then it will assume that the start is 0.
  */
 export declare function irange(start: int, end?: int): int[];
-/** Helper function to detect if a variable is a boolean, number, or string. */
-export declare function isPrimitive(variable: unknown): boolean;
 /**
  * Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
  * be a non-zero value in reflections.

package/functions/utils.lua

@@ -1,7 +1,6 @@
 local ____lualib = require("lualib_bundle")
 local __TS__StringReplace = ____lualib.__TS__StringReplace
 local __TS__StringSubstr = ____lualib.__TS__StringSubstr
-local __TS__TypeOf = ____lualib.__TS__TypeOf
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local RenderMode = ____isaac_2Dtypescript_2Ddefinitions.RenderMode
@@ -120,11 +119,6 @@ function ____exports.irange(self, start, ____end)
     end
     return array
 end
---- Helper function to detect if a variable is a boolean, number, or string.
-function ____exports.isPrimitive(self, variable)
-    local ____type = __TS__TypeOf(variable)
-    return ____type == "boolean" or ____type == "number" or ____type == "string"
-end
 --- Since this is a UI element, we do not want to draw it in water reflections. `renderOffset` will
 -- be a non-zero value in reflections.
 function ____exports.isReflectionRender(self)

package/functions/vector.lua

@@ -13,6 +13,8 @@ local ____table = require("functions.table")
 local copyValuesToTable = ____table.copyValuesToTable
 local getNumbersFromTable = ____table.getNumbersFromTable
 local tableHasKeys = ____table.tableHasKeys
+local ____types = require("functions.types")
+local isTable = ____types.isTable
 local ____utils = require("functions.utils")
 local ensureAllCases = ____utils.ensureAllCases
 --- Helper function to check if something is an instantiated Vector object.
@@ -56,8 +58,7 @@ function ____exports.copyVector(self, vector, serializationType)
         ____cond3 = ____cond3 or ____switch3 == SerializationType.DESERIALIZE
         if ____cond3 then
             do
-                local vectorType = type(vector)
-                if ____exports.isVector(nil, vector) or vectorType ~= "table" then
+                if not isTable(nil, vector) then
                     error(("Failed to deserialize a " .. OBJECT_NAME) .. " object since the provided object was not a Lua table.")
                 end
                 local x, y = table.unpack(getNumbersFromTable(
@@ -85,16 +86,14 @@ end
 --- Used to determine is the given table is a serialized `Vector` object created by the save data
 -- manager and/or the `deepCopy` function.
 function ____exports.isSerializedVector(self, object)
-    local objectType = type(object)
-    if objectType ~= "table" then
+    if not isTable(nil, object) then
         return false
     end
-    local ____table = object
     return tableHasKeys(
         nil,
-        ____table,
+        object,
         table.unpack(KEYS)
-    ) and ____table[SerializationBrand.VECTOR] ~= nil
+    ) and object[SerializationBrand.VECTOR] ~= nil
 end
 function ____exports.vectorEquals(self, vector1, vector2)
     return isaacAPIClassEquals(nil, vector1, vector2, KEYS)

package/index.d.ts

@@ -108,6 +108,7 @@ export * from "./functions/trinketCacheFlag";
 export * from "./functions/trinketGive";
 export * from "./functions/trinkets";
 export * from "./functions/tstlClass";
+export * from "./functions/types";
 export * from "./functions/ui";
 export * from "./functions/utils";
 export * from "./functions/vector";

package/index.lua

@@ -854,6 +854,14 @@ do
         end
     end
 end
+do
+    local ____export = require("functions.types")
+    for ____exportKey, ____exportValue in pairs(____export) do
+        if ____exportKey ~= "default" then
+            ____exports[____exportKey] = ____exportValue
+        end
+    end
+end
 do
     local ____export = require("functions.ui")
     for ____exportKey, ____exportValue in pairs(____export) do

package/package.json

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