warscript 0.0.1-dev.dd8349d → 0.0.1-dev.e147c49

package/utility/linked-set.d.ts

@@ -14,7 +14,7 @@ export interface ReadonlyLinkedSet<T extends AnyNotNil> extends LuaPairsKeyItera
     next(key: T): T | undefined;
     previous(key: T): T | undefined;
     contains(key: AnyNotNil): key is T & OneSidedTypeGuard;
-    size: number;
+    readonly size: number;
     forEach<Args extends any[]>(action: (value: T, ...args: Args) => void, ...args: Args): void;
     toArray(): T[];
     sumOf(selector: ((value: T) => number) | KeysOfType<T, number>): number;
@@ -36,9 +36,11 @@ export declare class LinkedSet<T extends AnyNotNil> implements ReadonlyLinkedSet
     copyOf(): LinkedSet<T>;
     first(): T | undefined;
     last(): T | undefined;
+    pop(): T | undefined;
     next(key: T): T | undefined;
     previous(key: T): T | undefined;
     add(key: T): boolean;
+    protected addBefore(value: T, key: T): boolean;
     remove(key: T): boolean;
     contains(key: AnyNotNil): key is T & OneSidedTypeGuard;
     clear(): void;
@@ -47,6 +49,7 @@ export declare class LinkedSet<T extends AnyNotNil> implements ReadonlyLinkedSet
     toArray(): T[];
     sumOf(selector: ((value: T) => number) | KeysOfType<T, number>): number;
     sortBy<R>(selector: ((value: T) => R) | KeysOfType<T, R>): void;
+    protected __len(): number;
     protected __pairs(this: LinkedSet<T>): LuaIterator<T | undefined, IteratorState<T>>;
 }
 export declare const emptyLinkedSet: <T extends AnyNotNil>() => ReadonlyLinkedSet<T>;

package/utility/linked-set.lua

@@ -42,6 +42,23 @@ end
 function LinkedSet.prototype.last(self)
     return self.l
 end
+function LinkedSet.prototype.pop(self)
+    local f = self.f
+    if f == nil then
+        return nil
+    end
+    local n = self.n
+    local next = n[f]
+    n[f] = nil
+    self.f = next
+    if next ~= nil then
+        self.p[next] = nil
+    else
+        self.l = nil
+    end
+    self.s = self.s - 1
+    return f
+end
 function LinkedSet.prototype.next(self, key)
     return self.n[key]
 end
@@ -68,6 +85,23 @@ function LinkedSet.prototype.add(self, key)
     end
     return true
 end
+function LinkedSet.prototype.addBefore(self, value, key)
+    local n = self.n
+    local p = self.p
+    local previous = p[value]
+    if previous ~= nil then
+        n[previous] = key
+        p[key] = previous
+    elseif value == self.f then
+        self.f = key
+    else
+        return false
+    end
+    n[key] = value
+    p[value] = key
+    self.s = self.s + 1
+    return true
+end
 function LinkedSet.prototype.remove(self, key)
     local n = self.n
     local next = n[key]
@@ -107,8 +141,9 @@ function LinkedSet.prototype.forEach(self, action, ...)
     local n = self.n
     local c = self.f
     while c ~= nil do
+        local next = n[c]
         action(c, ...)
-        c = n[c]
+        c = next
     end
 end
 function LinkedSet.prototype.toArray(self)
@@ -153,6 +188,9 @@ function LinkedSet.prototype.sortBy(self, selector)
     self.f = array[1]
     self.l = array[s]
 end
+function LinkedSet.prototype.__len(self)
+    return self.s
+end
 function LinkedSet.prototype.__pairs(self)
     return linkedSetNext, {t = self.n, n = self.f}, nil
 end
@@ -164,6 +202,7 @@ __TS__SetDescriptor(
     end},
     true
 )
+local emptyIteratorState = {t = {}}
 local EmptyLinkedSet = __TS__Class()
 EmptyLinkedSet.name = "EmptyLinkedSet"
 __TS__ClassExtends(EmptyLinkedSet, ____exports.LinkedSet)
@@ -173,6 +212,12 @@ function EmptyLinkedSet.prototype.add(self)
         0
     )
 end
+function EmptyLinkedSet.prototype.__len(self)
+    return 0
+end
+function EmptyLinkedSet.prototype.__pairs(self)
+    return linkedSetNext, emptyIteratorState, nil
+end
 local EMPTY_LINKED_SET = __TS__New(EmptyLinkedSet)
 ____exports.emptyLinkedSet = function()
     return EMPTY_LINKED_SET

package/utility/lua-maps.d.ts

@@ -1,8 +1,18 @@
 /** @noSelfInFile */
 import { Flatten, TupleOf } from "./types";
+export declare const emptyLuaMap: <K extends AnyNotNil, V>() => ReadonlyLuaMap<K, V>;
 export declare const mutableLuaMap: <K extends AnyNotNil, V>() => LuaMap<K, V>;
 export declare const mutableWeakLuaMap: <K extends AnyNotNil, V>() => LuaMap<K, V>;
 export declare const luaMapOf: <K extends AnyNotNil, V>(...pairs: Flatten<TupleOf<[K, V], 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40>>) => LuaMap<K, V>;
-export declare const luaMapInvert: <K extends AnyNotNil, V extends AnyNotNil>(luaMap: LuaMap<K, V>) => LuaMap<V, K>;
-export declare const mapValues: <K extends AnyNotNil, V1, V2>(luaMap: LuaMap<K, V1>, transform: (value: V1) => V2) => LuaMap<K, V2>;
+export declare const luaMapInvert: <K extends AnyNotNil, V extends AnyNotNil>(luaMap: ReadonlyLuaMap<K, V | undefined | null>) => LuaMap<V, K>;
+export declare const toLuaMap: <K extends PropertyKey, V>(record: Record<K, V>) => LuaMap<K, V>;
+export declare const flattenKeys: <K extends AnyNotNil, V>(luaMap: ReadonlyLuaMap<readonly K[], V> | ReadonlyLuaMap<K[], V>) => LuaMap<K, V>;
+export declare const mapKeys: {
+    <K1 extends AnyNotNil, K2 extends AnyNotNil, V>(luaMap: ReadonlyLuaMap<K1, V>, transform: (value: K1) => K2): LuaMap<K2, V>;
+    <K1 extends AnyNotNil, K2 extends keyof K1, V>(luaMap: ReadonlyLuaMap<K1, V>, key: K2): K1[K2] extends AnyNotNil ? LuaMap<K1[K2], V> : never;
+};
+export declare const mapValues: {
+    <K extends AnyNotNil, V1, V2>(luaMap: ReadonlyLuaMap<K, V1>, transform: (value: V1) => V2): LuaMap<K, V2>;
+    <K extends AnyNotNil, V1, V2 extends keyof V1>(luaMap: ReadonlyLuaMap<K, V1>, key: V2): LuaMap<K, V1[V2]>;
+};
 export declare const getOrPut: <K extends AnyNotNil, V>(luaMap: LuaMap<K, V>, key: K, defaultValue: () => V) => V;

package/utility/lua-maps.lua

@@ -2,6 +2,10 @@ local ____exports = {}
 local select = _G.select
 local setmetatable = _G.setmetatable
 local weakKeysMetatable = {__mode = "k"}
+local EMPTY_LUA_MAP = {}
+____exports.emptyLuaMap = function()
+    return EMPTY_LUA_MAP
+end
 ____exports.mutableLuaMap = function()
     return {}
 end
@@ -23,10 +27,41 @@ ____exports.luaMapInvert = function(luaMap)
     end
     return invertLuaMap
 end
+____exports.toLuaMap = function(record)
+    return record
+end
+____exports.flattenKeys = function(luaMap)
+    local result = {}
+    for keys, value in pairs(luaMap) do
+        for ____, key in ipairs(keys) do
+            result[key] = value
+        end
+    end
+    return result
+end
+____exports.mapKeys = function(luaMap, transform)
+    local result = {}
+    if type(transform) == "function" then
+        for key, value in pairs(luaMap) do
+            result[transform(key)] = value
+        end
+    else
+        for key, value in pairs(luaMap) do
+            result[key[transform]] = value
+        end
+    end
+    return result
+end
 ____exports.mapValues = function(luaMap, transform)
     local result = {}
-    for key, value in pairs(luaMap) do
-        result[key] = transform(value)
+    if type(transform) == "function" then
+        for key, value in pairs(luaMap) do
+            result[key] = transform(value)
+        end
+    else
+        for key, value in pairs(luaMap) do
+            result[key] = value[transform]
+        end
     end
     return result
 end

package/utility/lua-sets.d.ts

@@ -1,4 +1,5 @@
 /** @noSelfInFile */
+export declare const emptyLuaSet: <T extends AnyNotNil>() => ReadonlyLuaSet<T>;
 export declare const mutableLuaSet: <T extends AnyNotNil>() => LuaSet<T>;
 export declare const luaSetOf: <T extends AnyNotNil>(...elements: readonly T[]) => LuaSet<T>;
 export declare const luaSetOfNotNull: <T extends AnyNotNil>(...elements: readonly (T | undefined | null)[]) => LuaSet<T>;

package/utility/lua-sets.lua

@@ -1,5 +1,9 @@
 local ____exports = {}
 local select = _G.select
+local EMPTY_LUA_SET = {}
+____exports.emptyLuaSet = function()
+    return EMPTY_LUA_SET
+end
 ____exports.mutableLuaSet = function()
     return {}
 end

package/utility/random.d.ts

@@ -0,0 +1,102 @@
+/** @noSelfInFile */
+import { ReadonlyNonEmptyArray } from "./types";
+/**
+ * A client-local pseudorandom generator that is safe to advance inside a local block.
+ *
+ * Instances are independent of each other and of the game's synchronous randomness.
+ */
+export declare class AsyncRandom {
+    private a;
+    private b;
+    private c;
+    private d;
+    /**
+     * Creates a generator seeded with the given `seed`,
+     * or with client-local entropy if no seed is given.
+     */
+    constructor(seed?: number);
+    /** Resets the generator to the state defined by the given `seed`. */
+    setSeed(seed: number): void;
+    /**
+     * Folds freshly gathered client-local entropy, optionally together with the given `value`,
+     * into the current state.
+     *
+     * Useful to make streams of different clients diverge even further, e.g. by mixing in values
+     * that are local by definition, such as the local player's id or the local mouse position.
+     */
+    addEntropy(value?: number | string): void;
+    /** Advances the state and returns the next 32-bit word. */
+    private next;
+    /** Returns a uniformly distributed value in `[0, bound)`, where `bound` is in `[1, 2^32]`. */
+    private nextBounded;
+    /** Returns the given amount (`0` to `32`) of random bits as a non-negative integer. */
+    nextBits(bitCount: number): number;
+    /**
+     * Returns a uniformly distributed integer, both bounds being inclusive:
+     * in `[0, upperBound]` when called with a single bound, in `[lowerBound, upperBound]` otherwise.
+     */
+    nextInteger(upperBound?: number): number;
+    nextInteger(lowerBound: number, upperBound: number): number;
+    /**
+     * Returns a uniformly distributed float with 53 bits of precision, the upper bound being
+     * exclusive: in `[0, upperBound)` when called with a single bound,
+     * in `[lowerBound, upperBound)` otherwise.
+     */
+    nextFloat(upperBound?: number): number;
+    nextFloat(lowerBound: number, upperBound: number): number;
+    /** Returns `true` with the given `probability`, or with a probability of one half by default. */
+    nextBoolean(probability?: number): boolean;
+    /** Returns a uniformly distributed angle in degrees, in `[0, 360)`. */
+    nextAngle(): number;
+    /** Returns a uniformly distributed point within `range` of the given center. */
+    nextXY(centerX: number, centerY: number, range: number): LuaMultiReturn<[x: number, y: number]>;
+    /** Returns a uniformly distributed element of the given `array`. */
+    nextElement<T>(array: ReadonlyNonEmptyArray<T>): T;
+    nextElement<T>(array: ReadonlyArray<T>): T | undefined;
+    /** Returns a uniformly distributed one of the given `elements`. */
+    nextOf<T>(element: T, ...elements: T[]): T;
+    nextOf<T>(...elements: T[]): T | undefined;
+    /** Shuffles the given `array` in place, each permutation being equally likely. */
+    shuffle(array: unknown[]): void;
+}
+/**
+ * Folds freshly gathered client-local entropy, optionally together with the given `value`,
+ * into the state of the generator backing the `asyncRandom*` functions.
+ */
+export declare const addAsyncRandomEntropy: (value?: number | string) => void;
+/** Returns the given amount (`0` to `32`) of random bits as a non-negative integer. */
+export declare const asyncRandomBits: (bitCount: number) => number;
+/**
+ * Returns a uniformly distributed integer, both bounds being inclusive:
+ * in `[0, upperBound]` when called with a single bound, in `[lowerBound, upperBound]` otherwise.
+ */
+export declare const asyncRandomInteger: {
+    (upperBound?: number): number;
+    (lowerBound: number, upperBound: number): number;
+};
+/**
+ * Returns a uniformly distributed float with 53 bits of precision, the upper bound being exclusive:
+ * in `[0, upperBound)` when called with a single bound, in `[lowerBound, upperBound)` otherwise.
+ */
+export declare const asyncRandomFloat: {
+    (upperBound?: number): number;
+    (lowerBound: number, upperBound: number): number;
+};
+/** Returns `true` with the given `probability`, or with a probability of one half by default. */
+export declare const asyncRandomBoolean: (probability?: number) => boolean;
+/** Returns a uniformly distributed angle in degrees, in `[0, 360)`. */
+export declare const asyncRandomAngle: () => number;
+/** Returns a uniformly distributed point within `range` of the given center. */
+export declare const asyncRandomXY: (centerX: number, centerY: number, range: number) => LuaMultiReturn<[x: number, y: number]>;
+/** Returns a uniformly distributed element of the given `array`. */
+export declare const asyncRandomElement: {
+    <T>(array: ReadonlyNonEmptyArray<T>): T;
+    <T>(array: ReadonlyArray<T>): T | undefined;
+};
+/** Returns a uniformly distributed one of the given `elements`. */
+export declare const asyncRandom: {
+    <T>(element: T, ...elements: T[]): T;
+    <T>(...elements: T[]): T | undefined;
+};
+/** Shuffles the given `array` in place, each permutation being equally likely. */
+export declare const asyncShuffle: (array: unknown[]) => void;

package/utility/random.lua

@@ -0,0 +1,273 @@
+local ____lualib = require("lualib_bundle")
+local __TS__Class = ____lualib.__TS__Class
+local __TS__New = ____lualib.__TS__New
+local ____exports = {}
+local ____exception = require("exception")
+local IllegalArgumentException = ____exception.IllegalArgumentException
+local ____math = require("math")
+local MAXIMUM_INTEGER = ____math.MAXIMUM_INTEGER
+local PI = ____math.PI
+local cos = ____math.cos
+local sin = ____math.sin
+local sqrt = ____math.sqrt
+local clock = os.clock
+local time = os.time
+local byte = string.byte
+local pack = string.pack
+local ____unpack = string.unpack
+local select = _G.select
+local toString = _G.tostring
+local globals = _G
+local UINT32_MASK = 4294967295
+local POW_2_32 = 4294967296
+--- 2^26, used to join two draws into a 53-bit mantissa.
+local POW_2_26 = 67108864
+--- 2^53, the amount of representable values of a 53-bit mantissa.
+local POW_2_53 = 9007199254740992
+local GOLDEN_RATIO_32 = 2654435769
+local FNV_PRIME_32 = 16777619
+--- The SplitMix32 finalizer: avalanches a 32-bit value.
+local function mix(value)
+    local z = value & UINT32_MASK
+    z = (z ~ z >> 16) * 569420461 & UINT32_MASK
+    z = (z ~ z >> 15) * 1935289751 & UINT32_MASK
+    return (z ~ z >> 15) & UINT32_MASK
+end
+--- Folds the bytes of `value` into `hash` (FNV-1a).
+local function hashString(hash, value)
+    for i = 1, #value do
+        hash = (hash ~ byte(value, i)) * FNV_PRIME_32 & UINT32_MASK
+    end
+    return hash
+end
+--- Folds the exact bit pattern of `value` into `hash`, without assuming it is an integer.
+local function hashNumber(hash, value)
+    local low, high = ____unpack(
+        "<i4i4",
+        pack("<d", value)
+    )
+    return mix(mix(hash ~ low & UINT32_MASK) ~ high & UINT32_MASK)
+end
+local entropyCounter = 0
+--- Gathers 32 bits of client-local entropy.
+-- 
+-- Every source is local by nature: the wall clock and the process CPU time drift apart between
+-- machines, and the heap addresses of freshly allocated tables and of loaded code differ between
+-- processes. The CPU time is read once more at the end, so that the time the gathering itself took
+-- contributes as well.
+local function collectEntropy()
+    entropyCounter = entropyCounter + 1
+    local entropy = mix(GOLDEN_RATIO_32 ~ entropyCounter)
+    entropy = mix(entropy ~ time() & UINT32_MASK)
+    entropy = hashNumber(
+        entropy,
+        clock()
+    )
+    entropy = mix(hashString(
+        entropy,
+        toString({})
+    ))
+    entropy = mix(hashString(
+        entropy,
+        toString({})
+    ))
+    entropy = mix(hashString(
+        entropy,
+        toString(globals)
+    ))
+    entropy = mix(hashString(
+        entropy,
+        toString(mix)
+    ))
+    return hashNumber(
+        entropy,
+        clock()
+    )
+end
+--- A client-local pseudorandom generator that is safe to advance inside a local block.
+-- 
+-- Instances are independent of each other and of the game's synchronous randomness.
+____exports.AsyncRandom = __TS__Class()
+local AsyncRandom = ____exports.AsyncRandom
+AsyncRandom.name = "AsyncRandom"
+function AsyncRandom.prototype.____constructor(self, seed)
+    self.a = 0
+    self.b = 0
+    self.c = 0
+    self.d = 0
+    self:setSeed(seed or collectEntropy())
+end
+function AsyncRandom.prototype.setSeed(self, seed)
+    local z = hashNumber(GOLDEN_RATIO_32, seed)
+    z = z + GOLDEN_RATIO_32 & UINT32_MASK
+    local a = mix(z)
+    z = z + GOLDEN_RATIO_32 & UINT32_MASK
+    local b = mix(z)
+    z = z + GOLDEN_RATIO_32 & UINT32_MASK
+    local c = mix(z)
+    z = z + GOLDEN_RATIO_32 & UINT32_MASK
+    local d = mix(z)
+    self.a = a
+    self.b = b
+    self.c = c
+    self.d = a | b | c | d ~= 0 and d or GOLDEN_RATIO_32
+end
+function AsyncRandom.prototype.addEntropy(self, value)
+    local entropy = collectEntropy()
+    if type(value) == "number" then
+        entropy = hashNumber(entropy, value)
+    elseif value ~= nil then
+        entropy = hashString(entropy, value)
+    end
+    local a = self.a ~ mix(entropy)
+    local b = self.b ~ mix(a)
+    local c = self.c ~ mix(b)
+    local d = self.d ~ mix(c)
+    self.a = a
+    self.b = b
+    self.c = c
+    self.d = a | b | c | d ~= 0 and d or GOLDEN_RATIO_32
+    self:next()
+end
+function AsyncRandom.prototype.next(self)
+    local a = self.a
+    local b = self.b
+    local result = b * 5 & UINT32_MASK
+    result = (result << 7 | result >> 25) & UINT32_MASK
+    result = result * 9 & UINT32_MASK
+    local t = b << 9 & UINT32_MASK
+    local c = self.c ~ a
+    local d = self.d ~ b
+    self.a = a ~ d
+    self.b = b ~ c
+    self.c = c ~ t
+    self.d = (d << 11 | d >> 21) & UINT32_MASK
+    return result
+end
+function AsyncRandom.prototype.nextBounded(self, bound)
+    if bound <= 1 then
+        return 0
+    end
+    local limit = POW_2_32 - POW_2_32 % bound
+    local value = self:next()
+    while value >= limit do
+        value = self:next()
+    end
+    return value % bound
+end
+function AsyncRandom.prototype.nextBits(self, bitCount)
+    return self:next() >> 32 - bitCount
+end
+function AsyncRandom.prototype.nextInteger(self, m, n)
+    local lowerBound = n ~= nil and m or 0
+    local upperBound = n ~= nil and n or (m or MAXIMUM_INTEGER)
+    if upperBound < lowerBound then
+        error(
+            __TS__New(
+                IllegalArgumentException,
+                ((("Upper bound (" .. tostring(upperBound)) .. ") is less than lower bound (") .. tostring(lowerBound)) .. ")."
+            ),
+            0
+        )
+    end
+    return lowerBound + self:nextBounded(upperBound - lowerBound + 1)
+end
+function AsyncRandom.prototype.nextFloat(self, m, n)
+    local high = self:next() >> 5
+    local low = self:next() >> 6
+    local value = (high * POW_2_26 + low) / POW_2_53
+    return n ~= nil and m + value * (n - m) or value * (m or MAXIMUM_INTEGER)
+end
+function AsyncRandom.prototype.nextBoolean(self, probability)
+    local ____temp_0
+    if probability == nil then
+        ____temp_0 = self:next() >> 31 ~= 0
+    else
+        ____temp_0 = self:nextFloat() < probability
+    end
+    return ____temp_0
+end
+function AsyncRandom.prototype.nextAngle(self)
+    return self:nextFloat() * 360
+end
+function AsyncRandom.prototype.nextXY(self, centerX, centerY, range)
+    local r = range * sqrt(self:nextFloat())
+    local t = self:nextFloat() * 2 * PI
+    return centerX + r * cos(t), centerY + r * sin(t)
+end
+function AsyncRandom.prototype.nextElement(self, array)
+    local length = #array
+    local ____temp_1
+    if length ~= 0 then
+        ____temp_1 = array[self:nextBounded(length) + 1]
+    else
+        ____temp_1 = nil
+    end
+    return ____temp_1
+end
+function AsyncRandom.prototype.nextOf(self, ...)
+    local count = select("#", ...)
+    local ____temp_2
+    if count ~= 0 then
+        ____temp_2 = (select(
+            self:nextBounded(count) + 1,
+            ...
+        ))
+    else
+        ____temp_2 = nil
+    end
+    return ____temp_2
+end
+function AsyncRandom.prototype.shuffle(self, array)
+    for i = #array - 1, 1, -1 do
+        local j = self:nextBounded(i + 1)
+        local value = array[i + 1]
+        array[i + 1] = array[j + 1]
+        array[j + 1] = value
+    end
+end
+local defaultAsyncRandom
+local function getDefaultAsyncRandom()
+    defaultAsyncRandom = defaultAsyncRandom or __TS__New(____exports.AsyncRandom)
+    return defaultAsyncRandom
+end
+--- Folds freshly gathered client-local entropy, optionally together with the given `value`,
+-- into the state of the generator backing the `asyncRandom*` functions.
+____exports.addAsyncRandomEntropy = function(value)
+    getDefaultAsyncRandom():addEntropy(value)
+end
+--- Returns the given amount (`0` to `32`) of random bits as a non-negative integer.
+____exports.asyncRandomBits = function(bitCount)
+    return getDefaultAsyncRandom():nextBits(bitCount)
+end
+--- Returns a uniformly distributed integer, both bounds being inclusive:
+-- in `[0, upperBound]` when called with a single bound, in `[lowerBound, upperBound]` otherwise.
+____exports.asyncRandomInteger = function(m, n) return n ~= nil and getDefaultAsyncRandom():nextInteger(m, n) or getDefaultAsyncRandom():nextInteger(m) end
+--- Returns a uniformly distributed float with 53 bits of precision, the upper bound being exclusive:
+-- in `[0, upperBound)` when called with a single bound, in `[lowerBound, upperBound)` otherwise.
+____exports.asyncRandomFloat = function(m, n) return n ~= nil and getDefaultAsyncRandom():nextFloat(m, n) or getDefaultAsyncRandom():nextFloat(m) end
+--- Returns `true` with the given `probability`, or with a probability of one half by default.
+____exports.asyncRandomBoolean = function(probability)
+    return getDefaultAsyncRandom():nextBoolean(probability)
+end
+--- Returns a uniformly distributed angle in degrees, in `[0, 360)`.
+____exports.asyncRandomAngle = function()
+    return getDefaultAsyncRandom():nextAngle()
+end
+--- Returns a uniformly distributed point within `range` of the given center.
+____exports.asyncRandomXY = function(centerX, centerY, range)
+    return getDefaultAsyncRandom():nextXY(centerX, centerY, range)
+end
+--- Returns a uniformly distributed element of the given `array`.
+____exports.asyncRandomElement = function(array)
+    return getDefaultAsyncRandom():nextElement(array)
+end
+--- Returns a uniformly distributed one of the given `elements`.
+____exports.asyncRandom = function(...)
+    return getDefaultAsyncRandom():nextOf(...)
+end
+--- Shuffles the given `array` in place, each permutation being equally likely.
+____exports.asyncShuffle = function(array)
+    getDefaultAsyncRandom():shuffle(array)
+end
+return ____exports

package/utility/records.lua

@@ -1,9 +1,28 @@
 local ____exports = {}
+local ____pairs = _G.pairs
+local tableSort = table.sort
 ____exports.invertRecord = function(record)
     local invertRecord = {}
-    for key, value in pairs(record) do
+    for key, value in ____pairs(record) do
         invertRecord[value] = key
     end
     return invertRecord
 end
+local sortedKeysInternal = {}
+local lastSortedKeysLength = 0
+---
+-- @internal For use by internal systems only.
+____exports.sortedKeysUnnested = function(record)
+    local length = 0
+    for key in ____pairs(record) do
+        length = length + 1
+        sortedKeysInternal[length] = key
+    end
+    for i = length + 1, lastSortedKeysLength do
+        sortedKeysInternal[i] = nil
+    end
+    lastSortedKeysLength = length
+    tableSort(sortedKeysInternal)
+    return sortedKeysInternal
+end
 return ____exports

package/utility/types.d.ts

@@ -37,4 +37,7 @@ export type Flatten<T extends readonly any[], A extends readonly any[] = []> = T
 export type Prohibit<T, K extends keyof any> = T & {
     [P in K]?: never;
 };
+type TupleSplit<T, N extends number, O extends readonly any[] = readonly []> = O["length"] extends N ? [O, T] : T extends readonly [infer F, ...infer R] ? TupleSplit<readonly [...R], N, readonly [...O, F]> : [O, T];
+export type TakeFirst<T extends readonly any[], N extends number> = TupleSplit<T, N>[0];
+export type SkipFirst<T extends readonly any[], N extends number> = TupleSplit<T, N>[1];
 export {};

package/utility/unordered-map.d.ts

@@ -0,0 +1,27 @@
+/** @noSelfInFile */
+type OneSidedTypeGuard = {
+    readonly __oneSidedTypeGuard: unique symbol;
+};
+export interface ReadonlyUnorderedMap<K extends AnyNotNil, V> extends LuaPairsIterable<K, V> {
+    get(key: K): V | undefined;
+    contains(key: AnyNotNil): key is K & OneSidedTypeGuard;
+    readonly size: number;
+}
+export interface UnorderedMap<K extends AnyNotNil, V> extends LuaPairsIterable<K, V> {
+    readonly __unorderedMap: unique symbol;
+}
+export declare class UnorderedMap<K extends AnyNotNil, V> implements ReadonlyUnorderedMap<K, V> {
+    private readonly v;
+    private s;
+    get(key: K): V | undefined;
+    getOrPut(key: K, defaultValue: (this: void) => V): V;
+    put(key: K, value: V): void;
+    remove(key: K): boolean;
+    contains(key: AnyNotNil): key is K & OneSidedTypeGuard;
+    get size(): number;
+    protected __len(): number;
+    protected __pairs(this: UnorderedMap<K, V>): ReturnType<typeof pairs>;
+}
+export declare const emptyUnorderedMap: <K extends AnyNotNil, V>() => ReadonlyUnorderedMap<K, V>;
+export declare const mutableUnorderedMap: <K extends AnyNotNil, V>() => UnorderedMap<K, V>;
+export {};