@oliversalzburg/js-utils 0.7.0 → 0.8.0

package/lib/async/async.d.ts

@@ -0,0 +1,44 @@
+import type { AnyAsyncFunction, AnyFunctionReturning, ConstructorOf } from "../core.js";
+/**
+ * Wraps the given asynchronous function in a new function that will ignore any outcome of
+ * the context as it resolves.
+ *
+ * This can be useful when providing asynchonous event handler to `.addEventlistener()`,
+ * which only expects synchronous functions.
+ * @param context - The asynchronous function to execute.
+ * @returns A function returning nothing.
+ */
+export declare const prepareAsyncContext: (context: AnyAsyncFunction) => (
+/**
+ * The arguments that our new function was called with.
+ */
+...args: Array<unknown>) => void;
+/**
+ * Executes an asynchronous function and resolves with an alternative result
+ * in case the function failed.
+ * @param executable - The asynchronous function to execute.
+ * @param to - The result we want to return when the function errors.
+ * @param filter - An {@linkcode !Error} subclass. If defined, only errors of
+ * this type will be coalesced.
+ * @typeParam TExecutableReturn - The return type of the function.
+ * @typeParam TCoalesce - The type of the object to coalesce to.
+ * @typeParam TFilter - The type of the error filter.
+ * @returns Whatever the function resolved to, or the provided replacement,
+ * in case the function failed.
+ */
+export declare const coalesceOnRejection: <TExecutableReturn, TCoalesce, TFilter extends ConstructorOf<Error>>(executable: AnyFunctionReturning<TExecutableReturn | Promise<TExecutableReturn>>, to: TCoalesce, filter?: TFilter) => Promise<TCoalesce | TExecutableReturn>;
+/**
+ * Wait a given period before continuing execution.
+ * @param duration - How many milliseconds to wait.
+ * @returns Nothing
+ */
+export declare const sleep: (duration: number) => Promise<void>;
+/**
+ * Executes an asynchronous function and retries the execution if it rejects.
+ * @param executable - The asynchronous function to execute.
+ * @param retryDelay - The duration to wait after a failed execution.
+ * @param retryCount - How often should the execution be retried?
+ * @typeParam TExecutableReturn - The return type of the function.
+ * @returns Whatever the function resolved to.
+ */
+export declare const retry: <TExecutableReturn>(executable: AnyFunctionReturning<TExecutableReturn | Promise<TExecutableReturn>>, retryDelay?: number, retryCount?: number) => Promise<TExecutableReturn>;

package/lib/async/async.js

@@ -0,0 +1,76 @@
+import { redirectErrorsToConsole } from "../errors/console.js";
+/**
+ * Wraps the given asynchronous function in a new function that will ignore any outcome of
+ * the context as it resolves.
+ *
+ * This can be useful when providing asynchonous event handler to `.addEventlistener()`,
+ * which only expects synchronous functions.
+ * @param context - The asynchronous function to execute.
+ * @returns A function returning nothing.
+ */
+export const prepareAsyncContext = (context) => {
+    return (
+    /**
+     * The arguments that our new function was called with.
+     */
+    ...args) => {
+        void context(...args)
+            .then(() => undefined)
+            .catch(redirectErrorsToConsole(console));
+    };
+};
+/**
+ * Executes an asynchronous function and resolves with an alternative result
+ * in case the function failed.
+ * @param executable - The asynchronous function to execute.
+ * @param to - The result we want to return when the function errors.
+ * @param filter - An {@linkcode !Error} subclass. If defined, only errors of
+ * this type will be coalesced.
+ * @typeParam TExecutableReturn - The return type of the function.
+ * @typeParam TCoalesce - The type of the object to coalesce to.
+ * @typeParam TFilter - The type of the error filter.
+ * @returns Whatever the function resolved to, or the provided replacement,
+ * in case the function failed.
+ */
+export const coalesceOnRejection = async (executable, to, filter) => {
+    try {
+        return await executable();
+    }
+    catch (error) {
+        if ((filter !== undefined && error instanceof filter) || !filter) {
+            return to;
+        }
+        throw error;
+    }
+};
+/**
+ * Wait a given period before continuing execution.
+ * @param duration - How many milliseconds to wait.
+ * @returns Nothing
+ */
+export const sleep = (duration) => {
+    return new Promise((resolve) => setTimeout(resolve, duration));
+};
+/**
+ * Executes an asynchronous function and retries the execution if it rejects.
+ * @param executable - The asynchronous function to execute.
+ * @param retryDelay - The duration to wait after a failed execution.
+ * @param retryCount - How often should the execution be retried?
+ * @typeParam TExecutableReturn - The return type of the function.
+ * @returns Whatever the function resolved to.
+ */
+export const retry = async (executable, retryDelay = 0, retryCount = 0) => {
+    try {
+        return await executable();
+    }
+    catch (error) {
+        if (0 < retryCount) {
+            if (0 < retryDelay) {
+                await sleep(retryDelay);
+            }
+            return retry(executable, retryDelay, --retryCount);
+        }
+        throw error;
+    }
+};
+//# sourceMappingURL=async.js.map

package/lib/async/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../source/async/async.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAyB,EAAE,EAAE;IAChE,OAAO;IACN;;OAEG;IACH,GAAG,IAAoB,EACtB,EAAE;QACH,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;aACnB,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;aACrB,KAAK,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EAKvC,UAEC,EACD,EAAa,EACb,MAAgB,EACf,EAAE;IACH,IAAI,CAAC;QACJ,OAAO,MAAM,UAAU,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,YAAY,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAClE,OAAO,EAAE,CAAC;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAiB,EAAE;IACxD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAChE,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EACzB,UAEC,EACD,UAAU,GAAG,CAAC,EACd,UAAU,GAAG,CAAC,EACe,EAAE;IAC/B,IAAI,CAAC;QACJ,OAAO,MAAM,UAAU,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;YACzB,CAAC;YACD,OAAO,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,UAAU,CAAC,CAAC;QACpD,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC,CAAC"}

package/lib/async/async.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/async/async.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert";
+import { it } from "node:test";
+import { prepareAsyncContext, sleep } from "./async.js";
+it("executes trivial callback", async () => {
+    let executed = false;
+    const callback = prepareAsyncContext(async () => {
+        await sleep(1);
+        executed = true;
+    });
+    callback();
+    await sleep(100);
+    assert.strictEqual(executed, true);
+});
+it("passes parameters to callback", async () => {
+    let executed = false;
+    const callback = prepareAsyncContext(async (event, eventId) => {
+        assert.strictEqual(event.name, "call");
+        assert.strictEqual(eventId, 42);
+        await sleep(1);
+        executed = true;
+    });
+    callback({ name: "call" }, 42);
+    await sleep(100);
+    assert.strictEqual(executed, true);
+});
+//# sourceMappingURL=async.test.js.map

package/lib/async/async.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.test.js","sourceRoot":"","sources":["../../source/async/async.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExD,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;IAC1C,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,IAAI,EAAE;QAC/C,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACf,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,QAAQ,EAAE,CAAC;IAEX,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAEjB,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;IAC9C,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,QAAQ,GAAG,mBAAmB,CACnC,KAAK,EAAE,KAA6B,EAAE,OAAe,EAAE,EAAE;QACxD,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAEhC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACf,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC,CACD,CAAC;IAEF,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAE/B,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAEjB,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC,CAAC,CAAC"}

package/lib/cli/args.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse CLI arguments.
+ * @param {Array<string>} argv - Expected to be process.argv
+ * @param {boolean} expectUnlabeled - Is the command line expected to have
+ * at least one trailing argument that is not labeled?
+ */
+export declare const parseArgv: (argv: Array<string>, expectUnlabeled?: boolean) => {
+    "": Array<string> | undefined;
+} & Record<string, boolean | string | Array<string>>;

package/lib/cli/args.js

@@ -0,0 +1,49 @@
+/**
+ * Parse CLI arguments.
+ * @param {Array<string>} argv - Expected to be process.argv
+ * @param {boolean} expectUnlabeled - Is the command line expected to have
+ * at least one trailing argument that is not labeled?
+ */
+export const parseArgv = (argv, expectUnlabeled = false) => argv.slice(2).reduce((acc, _, index, array) => {
+    let slot;
+    let value;
+    if (!_.startsWith("--")) {
+        if (acc.prev === undefined ||
+            (expectUnlabeled && index === array.length - 1)) {
+            slot = "";
+        }
+        else {
+            slot = acc.prev;
+            acc.prev = undefined;
+        }
+        value = _;
+    }
+    else {
+        const argument = _.substring(2);
+        const parts = argument.match(/^(?<name>[^=]+)=?(?<value>.*)$/);
+        if (parts === null || parts.groups === undefined) {
+            return acc;
+        }
+        slot = parts.groups.name ?? parts.groups.value;
+        value =
+            typeof parts.groups.value === "string" && parts.groups.value !== ""
+                ? parts.groups.value
+                : true;
+        if (parts.groups.value === "") {
+            acc.prev = slot;
+        }
+    }
+    const argSlot = acc.args[slot];
+    acc.args[slot] =
+        Array.isArray(argSlot) && typeof value === "string"
+            ? [...argSlot, value]
+            : slot === "" && typeof value === "string"
+                ? [value]
+                : typeof argSlot === "undefined" ||
+                    typeof argSlot === "boolean" ||
+                    typeof value === "boolean"
+                    ? value
+                    : [...(Array.isArray(argSlot) ? argSlot : [argSlot]), value];
+    return acc;
+}, { args: {} }).args;
+//# sourceMappingURL=args.js.map

package/lib/cli/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../source/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACxB,IAAmB,EACnB,eAAe,GAAG,KAAK,EAItB,EAAE,CACH,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CACnB,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;IACxB,IAAI,IAAY,CAAC;IACjB,IAAI,KAAoB,CAAC;IAEzB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,IACC,GAAG,CAAC,IAAI,KAAK,SAAS;YACtB,CAAC,eAAe,IAAI,KAAK,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAC9C,CAAC;YACF,IAAI,GAAG,EAAE,CAAC;QACX,CAAC;aAAM,CAAC;YACP,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YAChB,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,KAAK,GAAG,CAAC,CAAC;IACX,CAAC;SAAM,CAAC;QACP,MAAM,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAC/D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAClD,OAAO,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC;QAC/C,KAAK;YACJ,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE;gBAClE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK;gBACpB,CAAC,CAAC,IAAI,CAAC;QACT,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;YAC/B,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,CAAC;IACF,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QACb,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAClD,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC;YACrB,CAAC,CAAC,IAAI,KAAK,EAAE,IAAI,OAAO,KAAK,KAAK,QAAQ;gBACzC,CAAC,CAAC,CAAC,KAAK,CAAC;gBACT,CAAC,CAAC,OAAO,OAAO,KAAK,WAAW;oBAC9B,OAAO,OAAO,KAAK,SAAS;oBAC5B,OAAO,KAAK,KAAK,SAAS;oBAC3B,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAEjE,OAAO,GAAG,CAAC;AACZ,CAAC,EACD,EAAE,IAAI,EAAE,EAAE,EAMT,CACD,CAAC,IAAI,CAAC"}

package/lib/cli/args.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/cli/args.test.js

@@ -0,0 +1,31 @@
+import assert from "node:assert";
+import { it } from "node:test";
+import { parseArgv } from "./args.js";
+it("parses boolean parameters", () => {
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes"]), {
+        yes: true,
+    });
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes", "filename.ext"], true), {
+        "": ["filename.ext"],
+        yes: true,
+    });
+});
+it("parses parameters using '='", () => {
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes=true"]), {
+        yes: "true",
+    });
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes=true", "filename.ext"]), {
+        "": ["filename.ext"],
+        yes: "true",
+    });
+});
+it("parses parameters using ' '", () => {
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes", "true"]), {
+        yes: "true",
+    });
+    assert.deepStrictEqual(parseArgv(["node", "script.js", "--yes", "true", "filename.ext"]), {
+        "": ["filename.ext"],
+        yes: "true",
+    });
+});
+//# sourceMappingURL=args.test.js.map

package/lib/cli/args.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.test.js","sourceRoot":"","sources":["../../source/cli/args.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACpC,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE;QACjE,GAAG,EAAE,IAAI;KACT,CAAC,CAAC;IACH,MAAM,CAAC,eAAe,CACrB,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,EAC/D;QACC,EAAE,EAAE,CAAC,cAAc,CAAC;QACpB,GAAG,EAAE,IAAI;KACT,CACD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;IACtC,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,EAAE;QACtE,GAAG,EAAE,MAAM;KACX,CAAC,CAAC;IACH,MAAM,CAAC,eAAe,CACrB,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC,EAC9D;QACC,EAAE,EAAE,CAAC,cAAc,CAAC;QACpB,GAAG,EAAE,MAAM;KACX,CACD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;IACtC,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE;QACzE,GAAG,EAAE,MAAM;KACX,CAAC,CAAC;IACH,MAAM,CAAC,eAAe,CACrB,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,EACjE;QACC,EAAE,EAAE,CAAC,cAAc,CAAC;QACpB,GAAG,EAAE,MAAM;KACX,CACD,CAAC;AACH,CAAC,CAAC,CAAC"}

package/lib/core.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Describes a function that is a constructor for something.
+ * @typeParam TConstructed - The type this is a constructor for.
+ */
+export type ConstructorOf<TConstructed> = new (...args: Array<any>) => TConstructed;
+/**
+ * Describes any function.
+ */
+export type AnyFunction = (...args: Array<any>) => any;
+/**
+ * Describes any asynchronous function.
+ */
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>;
+/**
+ * Any constructor
+ */
+export type AnyConstructor = new (...args: Array<any>) => any;
+/**
+ * Describes a function returning an instance of a given type.
+ * @typeParam TReturned - The type of the item returned by the function.
+ */
+export type AnyFunctionReturning<TReturned = any> = (...args: Array<any>) => TReturned;
+/**
+ * Describes an async function returning an instance of a given type.
+ * @typeParam TReturned - The type of the item returned by the function.
+ */
+export type AnyAsyncFunctionReturning<TReturned = any> = (...args: Array<any>) => Promise<TReturned>;
+/**
+ * Describes a class "mixin", which is a function that returns a dynamically
+ * constructed class, based on the passed parameters.
+ *
+ * **Hint**: Don't use mixins.
+ * @typeParam TTarget - The type of the classed this mixin is being
+ * mixed in with.
+ */
+export type Mixin<TTarget extends AnyFunctionReturning> = InstanceType<ReturnType<TTarget>>;
+/**
+ * Recursive definition of a regular JS object, which is a key-value hash
+ * of strings to primitives, or another object of the same type.
+ */
+export type JsonObject = string | number | boolean | null | Array<JsonObject> | {
+    [key: string]: JsonObject;
+};

package/lib/core.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=core.js.map

package/lib/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../source/core.ts"],"names":[],"mappings":""}

package/lib/data/array.d.ts

@@ -0,0 +1,55 @@
+import type { ConstructorOf } from "../core.js";
+/**
+ * Places the items in the array in random order.
+ * The array is shuffled in-place, no copy is created. The returned array is exactly the passed array.
+ * @param array - The array to shuffle.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns The passed array in random order.
+ */
+export declare const shuffleArray: <TElements>(array: Array<TElements>) => TElements[];
+/**
+ * Returns an array that holds all items that appear in both
+ * passed arrays.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array which holds the items that appear in
+ * both passed arrays.
+ */
+export declare const intersect: <TElements>(a: Array<TElements>, b: Array<TElements>) => TElements[];
+/**
+ * Returns an array that holds all items that only appear in `a`.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array which holds the items that ony appear in `a`.
+ */
+export declare const difference: <TElements>(a: Array<TElements>, b: Array<TElements>) => TElements[];
+/**
+ * From an array with unknown contents, retrieve all the elements
+ * that are of a certain type and return them as a new array.
+ * @param array - The array to filter.
+ * @param InstanceType - The type to search for.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array with the filtered items.
+ */
+export declare const filterType: <TElements>(array: Array<unknown>, InstanceType: ConstructorOf<TElements>) => Array<TElements>;
+/**
+ * From an iterable with unknown contents, yield arrays that contain items from
+ * the iterable up to a given limit.
+ * @param iterable - The iterable to retrieve items from.
+ * @param limit - The amount of items in each chunk.
+ * @typeParam TElements - The type of the elements in the iterable.
+ * @yields Chunks from the provided iterable.
+ */
+export declare const chunkify: <TElements>(iterable: Iterable<TElements>, limit: number) => Generator<TElements[], void, unknown>;
+/**
+ * Group all elements of the input array, that produce the same identity,
+ * into a new array.
+ * @param array - The array with the items to group.
+ * @param ident - Callback that identifies the group of the element.
+ * @typeParam TElements - The type of the elements in the array.
+ * @typeParam TGroupKey - The type of the group identifier.
+ * @returns A map that correlates the group key to an array of all elements with that group key.
+ */
+export declare const groupBy: <TElements, TGroupKey>(array: Array<TElements>, ident: (element: TElements) => TGroupKey) => Map<TGroupKey, Array<TElements>>;

package/lib/data/array.js

@@ -0,0 +1,90 @@
+import { is } from "./nil.js";
+/**
+ * Places the items in the array in random order.
+ * The array is shuffled in-place, no copy is created. The returned array is exactly the passed array.
+ * @param array - The array to shuffle.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns The passed array in random order.
+ */
+export const shuffleArray = (array) => {
+    for (let index = array.length - 1; index > 0; index--) {
+        const targetIndex = Math.trunc(Math.random() * (index + 1));
+        const temp = array[index];
+        array[index] = array[targetIndex];
+        array[targetIndex] = temp;
+    }
+    return array;
+};
+/**
+ * Returns an array that holds all items that appear in both
+ * passed arrays.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array which holds the items that appear in
+ * both passed arrays.
+ */
+export const intersect = (a, b) => {
+    return a.filter((x) => b.includes(x));
+};
+/**
+ * Returns an array that holds all items that only appear in `a`.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array which holds the items that ony appear in `a`.
+ */
+export const difference = (a, b) => {
+    return a.filter((x) => !b.includes(x));
+};
+/**
+ * From an array with unknown contents, retrieve all the elements
+ * that are of a certain type and return them as a new array.
+ * @param array - The array to filter.
+ * @param InstanceType - The type to search for.
+ * @typeParam TElements - The type of the elements in the array.
+ * @returns A new array with the filtered items.
+ */
+export const filterType = (array, InstanceType) => array.filter((element) => is(element, InstanceType));
+/**
+ * From an iterable with unknown contents, yield arrays that contain items from
+ * the iterable up to a given limit.
+ * @param iterable - The iterable to retrieve items from.
+ * @param limit - The amount of items in each chunk.
+ * @typeParam TElements - The type of the elements in the iterable.
+ * @yields Chunks from the provided iterable.
+ */
+export const chunkify = function* (iterable, limit) {
+    let chunk = [];
+    for (const element of iterable) {
+        chunk.push(element);
+        if (chunk.length === limit) {
+            yield chunk;
+            chunk = [];
+        }
+    }
+    if (chunk.length) {
+        yield chunk;
+    }
+};
+/**
+ * Group all elements of the input array, that produce the same identity,
+ * into a new array.
+ * @param array - The array with the items to group.
+ * @param ident - Callback that identifies the group of the element.
+ * @typeParam TElements - The type of the elements in the array.
+ * @typeParam TGroupKey - The type of the group identifier.
+ * @returns A map that correlates the group key to an array of all elements with that group key.
+ */
+export const groupBy = (array, ident) => {
+    const result = new Map();
+    for (const element of array) {
+        const id = ident(element);
+        if (!result.has(id)) {
+            result.set(id, new Array());
+        }
+        result.get(id)?.push(element);
+    }
+    return result;
+};
+//# sourceMappingURL=array.js.map

package/lib/data/array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../source/data/array.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAY,KAAuB,EAAE,EAAE;IAClE,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACvD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;QAClC,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACxB,CAAmB,EACnB,CAAmB,EAClB,EAAE;IACH,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACzB,CAAmB,EACnB,CAAmB,EAClB,EAAE;IACH,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACzB,KAAqB,EACrB,YAAsC,EACrC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAqB,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,QAAQ,CAAC,EAChC,QAA6B,EAC7B,KAAa;IAEb,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC5B,MAAM,KAAK,CAAC;YACZ,KAAK,GAAG,EAAE,CAAC;QACZ,CAAC;IACF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACtB,KAAuB,EACvB,KAAwC,EACL,EAAE;IACrC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IACtD,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,KAAK,EAAa,CAAC,CAAC;QACxC,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC,CAAC"}

package/lib/data/nil.d.ts

@@ -0,0 +1,92 @@
+import type { ConstructorOf } from "../core.js";
+/**
+ * When you want to normalize away `null` | `undefined`, or deal
+ * with either type through a consistent interface.
+ */
+export type Nil = null | undefined;
+/**
+ * A type that could be either what you want, or `Nil`.
+ * @typeParam T - The type that should be made nillable.
+ */
+export type Maybe<T> = T | Nil;
+/**
+ * Check if something is nil.
+ * Can be used as a typeguard.
+ * @param subject - The subject that could be nil.
+ * @typeParam TSubject - The type of the subject.
+ * @returns `true` if the subject is nil, `false` otherwise.
+ */
+export declare function isNil<TSubject>(subject: Maybe<TSubject>): subject is Nil;
+/**
+ * Check if something is a concrete value of the given type.
+ * Can be used as a typeguard.
+ * @param subject - The subject that could be nil.
+ * @param Prototype - The prototype to check against.
+ * @typeParam TSubject - The type to check against.
+ * @returns `true` if the input element matches the given type,
+ * `false` otherwise.
+ */
+export declare function is<TSubject>(subject: Maybe<TSubject> | unknown, Prototype: ConstructorOf<TSubject>): subject is TSubject;
+/**
+ * Thrown when an unexpected nil value was encountered.
+ */
+export declare class UnexpectedNilError extends Error {
+    /**
+     * Constructs a new {@linkcode UnexpectedNilError}.
+     * @param message - The error message.
+     */
+    constructor(message?: string);
+}
+/**
+ * Ensure that the passed subject is not nil; throw otherwise.
+ * @param subject - A subject that is possibly nil.
+ * @param errorMessage - An optional error message to throw when the subject is nil.
+ * @typeParam TSubject - The type of the subject.
+ * @returns The subject, if it isn't nil.
+ * @throws {@linkcode UnexpectedNilError} When the subject is nil.
+ */
+export declare function mustExist<TSubject>(subject: Maybe<TSubject>, errorMessage?: string): TSubject;
+/**
+ * Ensure that all passed subjects are not nil; throw otherwise.
+ * @param subjects - The subjects that are possibly nil.
+ * @param errorMessage - An optional error message to throw when a subject is nil.
+ * @typeParam TSubject - The type a the subject.
+ * @returns The subjects, if they aren't nil.
+ * @throws {@linkcode UnexpectedNilError} When a subject is nil.
+ */
+export declare function mustExistAll<TSubject>(subjects: Array<Maybe<TSubject>>, errorMessage?: string): Array<TSubject>;
+/**
+ * Ensure that the passed subject is not nil; throw otherwise.
+ * @param subject - A subject that is possibly nil.
+ * @typeParam TSubject - The type of the subject.
+ * @throws {@linkcode UnexpectedNilError} When the subject is nil.
+ */
+export declare function assertExists<TSubject>(subject: Maybe<TSubject>): asserts subject is TSubject;
+/**
+ * Ensure that the passed subjects are not nil; throw otherwise.
+ * @param subjects - Subjects that are possibly nil.
+ * @typeParam TSubject - The type of a subject.
+ * @throws {@linkcode UnexpectedNilError} When a subject is nil.
+ */
+export declare function assertExistsAll<TSubject>(subjects: Array<Maybe<TSubject>>): asserts subjects is Array<TSubject>;
+/**
+ * Convert a nilable into a real value, if it is nil.
+ * @param nilable - The subject to convert to an optional.
+ * @param to - The value to coalese to.
+ * @returns The input value, if it wasn't nil, or the value to coalesce to.
+ */
+export declare function coalesce<T>(nilable: Maybe<T>, to: T): T;
+/**
+ * Drop all nil values from an array, or replaces them with another value.
+ * @param nilables - The subject to convert.
+ * @param to - The value to coalese to.
+ * @returns An array with where all values are not nil.
+ */
+export declare function coalesceArray<T>(nilables: Array<Maybe<T>>, to?: Maybe<T>): Array<T>;
+/**
+ * Convert a nilable into an optional argument.
+ * This means `null` is normalized to `undefined`.
+ * @param nilable - The subject to convert to an optional.
+ * @returns The value, normalized to `undefined`, if it was nil.
+ */
+export declare function toOptional<T>(nilable: Maybe<T>): T | undefined;