isaacscript-common 84.0.0 → 84.1.0

package/dist/functions/run.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setUnseeded = exports.setRunSeed = exports.restart = exports.onVictoryLap = exports.onSetSeed = exports.getSeedEffects = exports.anySeedEffectEnabled = exports.anyEasterEggEnabled = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedEnumValues_1 = require("../arrays/cachedEnumValues");
+const cachedClasses_1 = require("../core/cachedClasses");
+const characters_1 = require("./characters");
+const log_1 = require("./log");
+const types_1 = require("./types");
+/** Alias for the `anySeedEffectEnabled` function. */
+function anyEasterEggEnabled(exceptions) {
+    return anySeedEffectEnabled(exceptions);
+}
+exports.anyEasterEggEnabled = anyEasterEggEnabled;
+/**
+ * Helper function to see if any seed effects (i.e. Easter Eggs) are enabled for the current run.
+ *
+ * @param exceptions Optional. An array of seed effects to ignore.
+ */
+function anySeedEffectEnabled(exceptions) {
+    const seeds = cachedClasses_1.game.GetSeeds();
+    if (exceptions === undefined) {
+        const numSeedEffects = seeds.CountSeedEffects();
+        return numSeedEffects > 0;
+    }
+    const exceptionsSet = new Set(exceptions);
+    return cachedEnumValues_1.SEED_EFFECTS.some((seedEffect) => seeds.HasSeedEffect(seedEffect) && !exceptionsSet.has(seedEffect));
+}
+exports.anySeedEffectEnabled = anySeedEffectEnabled;
+/**
+ * Helper function to get the seed effects (i.e. Easter Eggs) that are enabled for the current run.
+ */
+function getSeedEffects() {
+    const seeds = cachedClasses_1.game.GetSeeds();
+    return cachedEnumValues_1.SEED_EFFECTS.filter((seedEffect) => seedEffect !== isaac_typescript_definitions_1.SeedEffect.NORMAL && seeds.HasSeedEffect(seedEffect));
+}
+exports.getSeedEffects = getSeedEffects;
+/**
+ * Helper function to check whether the player is playing on a set seed (i.e. that they entered in a
+ * specific seed by pressing tab on the character selection screen). When the player resets the game
+ * on a set seed, the game will not switch to a different seed.
+ *
+ * Under the hood, this checks if the current challenge is `Challenge.NULL` and the
+ * `Seeds.IsCustomRun` method.
+ */
+function onSetSeed() {
+    const seeds = cachedClasses_1.game.GetSeeds();
+    const customRun = seeds.IsCustomRun();
+    const challenge = Isaac.GetChallenge();
+    return challenge === isaac_typescript_definitions_1.Challenge.NULL && customRun;
+}
+exports.onSetSeed = onSetSeed;
+/**
+ * Helper function to check whether the player is on a Victory Lap (i.e. they answered "yes" to the
+ * popup that happens after defeating The Lamb).
+ */
+function onVictoryLap() {
+    const numVictoryLaps = cachedClasses_1.game.GetVictoryLap();
+    return numVictoryLaps > 0;
+}
+exports.onVictoryLap = onVictoryLap;
+/**
+ * Helper function to restart the run using the console command of "restart". If the player is
+ * playing a seeded run, then it will restart the game to the beginning of the seed. Otherwise, it
+ * will put the player on a run with an entirely new seed.
+ *
+ * You can optionally specify a `PlayerType` to restart the game as that character.
+ */
+function restart(character) {
+    if (character === undefined) {
+        const command = "restart";
+        (0, log_1.log)(`Restarting the run with a console command of: ${command}`);
+        Isaac.ExecuteCommand(command);
+        return;
+    }
+    if (character < isaac_typescript_definitions_1.PlayerType.ISAAC) {
+        error(`Restarting as a character of ${character} would crash the game.`);
+    }
+    const command = `restart ${character}`;
+    const characterName = (0, characters_1.getCharacterName)(character);
+    (0, log_1.log)(`Restarting the run as ${characterName} (${character}) with a console command of: ${command}`);
+    Isaac.ExecuteCommand(command);
+}
+exports.restart = restart;
+/**
+ * Helper function to restart the run on a particular starting seed.
+ *
+ * Under the hood, this function executes the `seed` console command.
+ *
+ * @param startSeedOrStartSeedString Either the numerical start seed (e.g. 268365970) or the start
+ *                                 seed string (e.g. "AAJ2 8V9C").
+ */
+function setRunSeed(startSeedOrStartSeedString) {
+    const startSeedString = (0, types_1.isString)(startSeedOrStartSeedString)
+        ? startSeedOrStartSeedString
+        : Seeds.Seed2String(startSeedOrStartSeedString);
+    const command = `seed ${startSeedString}`;
+    (0, log_1.log)(`Restarting the run to set a seed with a console command of: ${command}`);
+    Isaac.ExecuteCommand(command);
+}
+exports.setRunSeed = setRunSeed;
+/**
+ * Helper function to change the run status to that of an unseeded run with a new random seed.
+ *
+ * This is useful to revert the behavior where playing on a set seed and restarting the game will
+ * not take you to a new seed.
+ *
+ * Under the hood, this function calls the `Seeds.Reset` method and the
+ * `Seeds.Restart(Challenge.NULL)` method.
+ */
+function setUnseeded() {
+    const seeds = cachedClasses_1.game.GetSeeds();
+    // Invoking the `Seeds.Reset` method will cause the start seed to be set to 0. Subsequently, the
+    // `Seeds.GetStartSeed` method will return 0, and can cause crashes (due to RNG objects not being
+    // able to handle a seed of 0). It also causes the log to be spammed with: "[ASSERT] - Error: Game
+    // Start Seed was not set." Thus, we must immediately re-initialize the game start seed by using
+    // the `Seeds.Restart` method.
+    seeds.Reset();
+    seeds.Restart(isaac_typescript_definitions_1.Challenge.NULL);
+}
+exports.setUnseeded = setUnseeded;

package/dist/functions/seeds.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextSeed = exports.getStartSeedString = void 0;
+const cachedClasses_1 = require("../core/cachedClasses");
+const rng_1 = require("./rng");
+/** Alias for the `Seeds.GetStartSeedString` method. */
+function getStartSeedString() {
+    const seeds = cachedClasses_1.game.GetSeeds();
+    return seeds.GetStartSeedString();
+}
+exports.getStartSeedString = getStartSeedString;
+/**
+ * Helper function to get the next seed value.
+ *
+ * This function is useful when you are working with seed values directly over RNG objects.
+ */
+function nextSeed(seed) {
+    const rng = (0, rng_1.newRNG)(seed);
+    rng.Next();
+    return rng.GetSeed();
+}
+exports.nextSeed = nextSeed;

package/dist/functions/serialization.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeIsaacAPIClass = exports.isSerializedIsaacAPIClass = exports.isCopyableIsaacAPIClass = exports.deserializeIsaacAPIClass = exports.copyIsaacAPIClass = void 0;
+const isaacAPIClassTypeToBrand_1 = require("../objects/isaacAPIClassTypeToBrand");
+const isaacAPIClassTypeToFunctions_1 = require("../objects/isaacAPIClassTypeToFunctions");
+const isaacAPIClass_1 = require("./isaacAPIClass");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+/**
+ * Helper function to generically copy an Isaac API class without knowing what specific type of
+ * class it is. (This is used by the save data manager.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+function copyIsaacAPIClass(isaacAPIClass) {
+    if (!(0, types_1.isUserdata)(isaacAPIClass)) {
+        error(`Failed to copy an Isaac API class since the provided object was of type: ${typeof isaacAPIClass}`);
+    }
+    const isaacAPIClassType = (0, isaacAPIClass_1.getIsaacAPIClassName)(isaacAPIClass);
+    (0, utils_1.assertDefined)(isaacAPIClassType, "Failed to copy an Isaac API class since it does not have a class type.");
+    const copyableIsaacAPIClassType = isaacAPIClassType;
+    const functions = isaacAPIClassTypeToFunctions_1.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
+    (0, utils_1.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);
+}
+exports.copyIsaacAPIClass = copyIsaacAPIClass;
+/**
+ * Helper function to generically deserialize an Isaac API class without knowing what specific type
+ * of class it is. (This is used by the save data manager when reading data from the "save#.dat"
+ * file.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+function deserializeIsaacAPIClass(serializedIsaacAPIClass) {
+    if (!(0, types_1.isTable)(serializedIsaacAPIClass)) {
+        error(`Failed to deserialize an Isaac API class since the provided object was of type: ${typeof serializedIsaacAPIClass}`);
+    }
+    const copyableIsaacAPIClassType = getSerializedTableType(serializedIsaacAPIClass);
+    (0, utils_1.assertDefined)(copyableIsaacAPIClassType, "Failed to deserialize an Isaac API class since a valid class type brand was not found.");
+    const functions = isaacAPIClassTypeToFunctions_1.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
+    (0, utils_1.assertDefined)(functions, `Failed to deserialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`);
+    return functions.deserialize(serializedIsaacAPIClass);
+}
+exports.deserializeIsaacAPIClass = deserializeIsaacAPIClass;
+/**
+ * In order to find out what type of serialized Isaac API class this is, we search through the
+ * serialized table for brands.
+ */
+function getSerializedTableType(serializedIsaacAPIClass) {
+    for (const [copyableIsaacAPIClassType, serializationBrand] of Object.entries(isaacAPIClassTypeToBrand_1.ISAAC_API_CLASS_TYPE_TO_BRAND)) {
+        if (serializedIsaacAPIClass.has(serializationBrand)) {
+            return copyableIsaacAPIClassType;
+        }
+    }
+    return undefined;
+}
+/**
+ * Helper function to generically check if a given object is a copyable Isaac API class. (This is
+ * used by the save data manager when determining what is safe to copy.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+function isCopyableIsaacAPIClass(object) {
+    const allFunctions = Object.values(isaacAPIClassTypeToFunctions_1.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS);
+    const isFunctions = allFunctions.map((functions) => functions.is);
+    return isFunctions.some((identityFunction) => identityFunction(object));
+}
+exports.isCopyableIsaacAPIClass = isCopyableIsaacAPIClass;
+/**
+ * Helper function to generically check if a given Lua table is a serialized Isaac API class. (This
+ * is used by the save data manager when reading data from the "save#.dat" file.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+function isSerializedIsaacAPIClass(object) {
+    const allFunctions = Object.values(isaacAPIClassTypeToFunctions_1.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS);
+    const isSerializedFunctions = allFunctions.map((functions) => functions.isSerialized);
+    return isSerializedFunctions.some((identityFunction) => identityFunction(object));
+}
+exports.isSerializedIsaacAPIClass = isSerializedIsaacAPIClass;
+/**
+ * Helper function to generically serialize an Isaac API class without knowing what specific type of
+ * class it is. (This is used by the save data manager when writing data to the "save#.dat" file.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+function serializeIsaacAPIClass(isaacAPIClass) {
+    if (!(0, types_1.isUserdata)(isaacAPIClass)) {
+        error(`Failed to serialize an Isaac API class since the provided object was of type: ${typeof isaacAPIClass}`);
+    }
+    const isaacAPIClassType = (0, isaacAPIClass_1.getIsaacAPIClassName)(isaacAPIClass);
+    (0, utils_1.assertDefined)(isaacAPIClassType, "Failed to serialize an Isaac API class since it does not have a class name.");
+    const copyableIsaacAPIClassType = isaacAPIClassType;
+    const functions = isaacAPIClassTypeToFunctions_1.ISAAC_API_CLASS_TYPE_TO_FUNCTIONS[copyableIsaacAPIClassType];
+    (0, utils_1.assertDefined)(functions, `Failed to serialize an Isaac API class since the associated functions were not found for class type: ${copyableIsaacAPIClassType}`);
+    return functions.serialize(isaacAPIClass);
+}
+exports.serializeIsaacAPIClass = serializeIsaacAPIClass;

package/dist/functions/set.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sumSet = exports.setHas = exports.setAdd = exports.objectValuesToSet = exports.objectValuesToReadonlySet = exports.objectKeysToSet = exports.objectKeysToReadonlySet = exports.getSortedSetValues = exports.getSetCombinations = exports.getRandomSetElement = exports.deleteSetsFromSet = exports.copySet = exports.combineSets = exports.addSetsToSet = void 0;
+const ReadonlySet_1 = require("../types/ReadonlySet");
+const array_1 = require("./array");
+const types_1 = require("./types");
+/**
+ * Helper function to add all of the values in one set to another set. The first set passed will be
+ * modified in place.
+ *
+ * This function is variadic, meaning that you can specify N sets to add to the first set.
+ */
+function addSetsToSet(
+// eslint-disable-next-line isaacscript/prefer-readonly-parameter-types
+mainSet, ...setsToAdd) {
+    for (const set of setsToAdd) {
+        for (const value of set) {
+            mainSet.add(value);
+        }
+    }
+}
+exports.addSetsToSet = addSetsToSet;
+/**
+ * Helper function to create a new set that is the composition of two or more sets.
+ *
+ * This function is variadic, meaning that you can specify N sets.
+ */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function combineSets(...sets) {
+    const newSet = new Set();
+    for (const set of sets) {
+        for (const value of set) {
+            newSet.add(value);
+        }
+    }
+    return newSet;
+}
+exports.combineSets = combineSets;
+/** Helper function to copy a set. (You can also use a Set constructor to accomplish this task.) */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function copySet(oldSet) {
+    const newSet = new Set();
+    for (const value of oldSet) {
+        newSet.add(value);
+    }
+    return newSet;
+}
+exports.copySet = copySet;
+/**
+ * Helper function to delete all of the values in one set from another set. The first set passed
+ * will be modified in place.
+ *
+ * This function is variadic, meaning that you can specify N sets to remove from the first set.
+ */
+function deleteSetsFromSet(
+// eslint-disable-next-line isaacscript/prefer-readonly-parameter-types
+mainSet, ...setsToRemove) {
+    for (const set of setsToRemove) {
+        for (const value of set) {
+            mainSet.delete(value);
+        }
+    }
+}
+exports.deleteSetsFromSet = deleteSetsFromSet;
+/**
+ * Helper function to get a random element from the provided set.
+ *
+ * If you want to get an unseeded element, you must explicitly pass `undefined` to the `seedOrRNG`
+ * parameter.
+ *
+ * @param set The set to get an element from.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param exceptions Optional. An array of elements to skip over if selected.
+ */
+function getRandomSetElement(set, seedOrRNG, exceptions = []) {
+    const array = getSortedSetValues(set);
+    return (0, array_1.getRandomArrayElement)(array, seedOrRNG, exceptions);
+}
+exports.getRandomSetElement = getRandomSetElement;
+/**
+ * Helper function to get all possible combinations of the given set. This includes the combination
+ * of an empty set.
+ *
+ * For example, if this function is provided a set containing 1, 2, and 3, then it will return an
+ * array containing the following sets:
+ *
+ * - [] (if `includeEmptyArray` is set to true)
+ * - [1]
+ * - [2]
+ * - [3]
+ * - [1, 2]
+ * - [1, 3]
+ * - [2, 3]
+ * - [1, 2, 3]
+ *
+ * @param set The set to get the combinations of.
+ * @param includeEmptyArray Whether to include an empty array in the combinations.
+ */
+function getSetCombinations(set, includeEmptyArray) {
+    const values = getSortedSetValues(set);
+    const combinations = (0, array_1.getArrayCombinations)(values, includeEmptyArray);
+    return combinations.map((array) => new ReadonlySet_1.ReadonlySet(array));
+}
+exports.getSetCombinations = getSetCombinations;
+/**
+ * Helper function to get a sorted array based on the contents of a set.
+ *
+ * Normally, set values are returned in insertion order, so use this function when the ordering of
+ * the contents is important.
+ */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function getSortedSetValues(set) {
+    const values = [...set];
+    // Check for problematic types in order to throw a helpful error message.
+    const firstElement = values[0];
+    if (firstElement !== undefined) {
+        const arrayType = type(firstElement);
+        if (!(0, types_1.isPrimitive)(arrayType)) {
+            error(`Failed to get the sorted set values because the provided set was of type "${arrayType}". Having sets with non-primitive types doesn't make much sense in general, so you might need to rethink what you are doing.`);
+        }
+    }
+    values.sort();
+    return values;
+}
+exports.getSortedSetValues = getSortedSetValues;
+/**
+ * Helper function to convert the keys of an object to a read-only set.
+ *
+ * Note that the set values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectKeysToSet` function.
+ */
+function objectKeysToReadonlySet(object) {
+    return objectKeysToSet(object);
+}
+exports.objectKeysToReadonlySet = objectKeysToReadonlySet;
+/**
+ * Helper function to convert the keys of an object to a set.
+ *
+ * Note that the set values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectKeysToReadonlySet` function.
+ */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function objectKeysToSet(object) {
+    const set = new Set();
+    for (const key of Object.keys(object)) {
+        set.add(key);
+    }
+    return set;
+}
+exports.objectKeysToSet = objectKeysToSet;
+/**
+ * Helper function to convert the values of an object to a read-only set.
+ *
+ * Note that the set values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectValuesToSet` function.
+ */
+function objectValuesToReadonlySet(object) {
+    return objectValuesToSet(object);
+}
+exports.objectValuesToReadonlySet = objectValuesToReadonlySet;
+/**
+ * Helper function to convert the values of an object to a set.
+ *
+ * Note that the set values will be inserted in a random order, due to how `pairs` works under the
+ * hood.
+ *
+ * Also see the `objectValuesToReadonlySet` function.
+ */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function objectValuesToSet(object) {
+    const set = new Set();
+    for (const key of Object.values(object)) {
+        set.add(key);
+    }
+    return set;
+}
+exports.objectValuesToSet = objectValuesToSet;
+/**
+ * Helper function to add one or more elements to a set at once without having to repeatedly call
+ * the `Set.add` method.
+ *
+ * This function is variadic, meaning that you can pass as many things as you want to add.
+ */
+// eslint-disable-next-line isaacscript/prefer-readonly-parameter-types
+function setAdd(set, ...elements) {
+    for (const element of elements) {
+        set.add(element);
+    }
+}
+exports.setAdd = setAdd;
+/**
+ * Helper function to check for one or more elements in a set at once without having to repeatedly
+ * call the `Set.has` method.
+ *
+ * This function is variadic, meaning that you can pass as many things as you want to check for. It
+ * will return true if one or more elements are found.
+ */
+function setHas(set, ...elements) {
+    return elements.some((element) => set.has(element));
+}
+exports.setHas = setHas;
+/** Helper function to sum every value in a set together. */
+function sumSet(set) {
+    const values = [...set];
+    return (0, array_1.sumArray)(values);
+}
+exports.sumSet = sumSet;

package/dist/functions/slots.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSlotMachine = exports.getSlotName = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const slotNames_1 = require("../objects/slotNames");
+const ReadonlySet_1 = require("../types/ReadonlySet");
+const entityTypes_1 = require("./entityTypes");
+const SLOT_MACHINE_VARIANTS = new ReadonlySet_1.ReadonlySet([
+    isaac_typescript_definitions_1.SlotVariant.SLOT_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.BLOOD_DONATION_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.FORTUNE_TELLING_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.DONATION_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.SHOP_RESTOCK_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.GREED_DONATION_MACHINE,
+    isaac_typescript_definitions_1.SlotVariant.MOMS_DRESSING_TABLE,
+    isaac_typescript_definitions_1.SlotVariant.CRANE_GAME,
+    isaac_typescript_definitions_1.SlotVariant.CONFESSIONAL, // 17
+]);
+/**
+ * Helper function to get the name of a slot, as listed in the "entities2.xml" file. Returns
+ * "Unknown" if the provided slot variant is not valid.
+ *
+ * This function only works for vanilla slot variants.
+ *
+ * For example, `getSlotName(SlotVariant.BLOOD_DONATION_MACHINE)` would return "Blood Donation
+ * Machine".
+ */
+function getSlotName(slotVariant) {
+    // Handle modded slots.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return slotNames_1.SLOT_NAMES[slotVariant] ?? slotNames_1.DEFAULT_SLOT_NAME;
+}
+exports.getSlotName = getSlotName;
+/** Returns true for the specific variants of `EntityType.SLOT` that are machines. */
+function isSlotMachine(entity) {
+    if (!(0, entityTypes_1.isSlot)(entity)) {
+        return false;
+    }
+    return SLOT_MACHINE_VARIANTS.has(entity.Variant);
+}
+exports.isSlotMachine = isSlotMachine;

package/dist/functions/sort.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableSort = exports.sortTwoDimensionalArray = exports.sortObjectArrayByKey = void 0;
+const types_1 = require("./types");
+function sortNormal(a, b) {
+    if (!(0, types_1.isNumber)(a) && !(0, types_1.isString)(a)) {
+        error(`Failed to normal sort since the first value was not a number or string and was instead: ${type(a)}`);
+    }
+    if (!(0, types_1.isNumber)(b) && !(0, types_1.isString)(b)) {
+        error(`Failed to normal sort since the second value was not a number or string and was instead: ${type(b)}`);
+    }
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Helper function to sort an array of objects by one of the object keys.
+ *
+ * For example:
+ *
+ * ```ts
+ * const myArray = [
+ *   {
+ *     name: "alice",
+ *     age: 30,
+ *   },
+ *   {
+ *     name: "bob",
+ *     age: 20,
+ *   },
+ * ];
+ * myArray.sort(sortObjectArrayByKey("age"));
+ * ```
+ */
+function sortObjectArrayByKey(key) {
+    return (a, b) => {
+        if (!(0, types_1.isTable)(a)) {
+            error(`Failed to sort an object array by the key of "${key}" since the first element was not a table and was instead: ${type(a)}`);
+        }
+        if (!(0, types_1.isTable)(b)) {
+            error(`Failed to sort an object array by the key of "${key}" since the second element was not a table and was instead: ${type(b)}.`);
+        }
+        const aValue = a.get(key);
+        const bValue = b.get(key);
+        return sortNormal(aValue, bValue);
+    };
+}
+exports.sortObjectArrayByKey = sortObjectArrayByKey;
+/**
+ * Helper function to sort a two-dimensional array by the first element.
+ *
+ * For example:
+ *
+ * ```ts
+ * const myArray = [[1, 2], [2, 3], [3, 4]];
+ * myArray.sort(twoDimensionalSort);
+ * ```
+ *
+ * This function also properly handles when the array elements are strings or numbers (instead of
+ * another array).
+ *
+ * From:
+ * https://stackoverflow.com/questions/16096872/how-to-sort-2-dimensional-array-by-column-value
+ */
+function sortTwoDimensionalArray(a, b) {
+    const aType = type(a);
+    const bType = type(b);
+    if (aType !== bType) {
+        error(`Failed to two-dimensional sort since the two elements were disparate types: ${a} & ${b} (${aType} & ${bType})`);
+    }
+    if (aType === "string" || aType === "number") {
+        return sortNormal(a, b);
+    }
+    if (aType !== "table") {
+        error("Failed to two-dimensional sort since the first element was not a string, number, or table.");
+    }
+    if (bType !== "table") {
+        error("Failed to two-dimensional sort since the second element was not a string, number, or table.");
+    }
+    const firstElement1 = a[0];
+    const firstElement2 = b[0];
+    if (firstElement1 === undefined || firstElement1 === null) {
+        error("Failed to two-dimensional sort since the first element of the first array was undefined.");
+    }
+    if (firstElement2 === undefined || firstElement2 === null) {
+        error("Failed to two-dimensional sort since the first element of the second array was undefined.");
+    }
+    const elementType1 = type(firstElement1);
+    const elementType2 = type(firstElement2);
+    if (elementType1 !== elementType2) {
+        error(`Failed to two-dimensional sort since the first element of each array were disparate types: ${firstElement1} & ${firstElement2} (${elementType1} & ${elementType2})`);
+    }
+    return sortNormal(firstElement1, firstElement2);
+}
+exports.sortTwoDimensionalArray = sortTwoDimensionalArray;
+/**
+ * Helper function to sort an array in a stable way.
+ *
+ * This is useful because by default, the transpiled `Array.sort` method from TSTL is not stable.
+ *
+ * Under the hood, this uses the merge sort algorithm.
+ */
+// eslint-disable-next-line isaacscript/no-mutable-return
+function stableSort(
+// eslint-disable-next-line isaacscript/prefer-readonly-parameter-types
+array, sortFunc = sortNormal) {
+    // Base case: an array of zero or one elements is already sorted
+    if (array.length <= 1) {
+        return array;
+    }
+    // Split the array into two halves.
+    const middleIndex = Math.floor(array.length / 2);
+    const leftArray = array.slice(0, middleIndex);
+    const rightArray = array.slice(middleIndex);
+    // Recursively sort each half.
+    const sortedLeftArray = stableSort(leftArray, sortFunc);
+    const sortedRightArray = stableSort(rightArray, sortFunc);
+    // Merge the two sorted halves.
+    const mergedArray = [];
+    let leftIndex = 0;
+    let rightIndex = 0;
+    while (leftIndex < sortedLeftArray.length &&
+        rightIndex < sortedRightArray.length) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const left = sortedLeftArray[leftIndex];
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const right = sortedRightArray[rightIndex];
+        const sortResult = sortFunc(left, right);
+        if (sortResult === -1 || sortResult === 0) {
+            mergedArray.push(left);
+            leftIndex++;
+        }
+        else {
+            mergedArray.push(right);
+            rightIndex++;
+        }
+    }
+    // Add any remaining elements from the left array.
+    while (leftIndex < sortedLeftArray.length) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const left = sortedLeftArray[leftIndex];
+        mergedArray.push(left);
+        leftIndex++;
+    }
+    // Add any remaining elements from the right array.
+    while (rightIndex < sortedRightArray.length) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const right = sortedRightArray[rightIndex];
+        mergedArray.push(right);
+        rightIndex++;
+    }
+    return mergedArray;
+}
+exports.stableSort = stableSort;