@fuzdev/fuz_util 0.42.0

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/process.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAIxC,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,OAAO;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAID,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,UAAU,CAAC,OAAO,aAAa,CAAC,KAAG,OAAO,CAAC,WAAW,CACvD,CAAC;AAE/B,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,SAAS,MAAM,EACf,OAAM,aAAa,CAAC,MAAM,CAAM,EAChC,UAAU,YAAY,KACpB,OAAO,CAAC,UAAU,CAYpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,MAAM,EACf,OAAM,aAAa,CAAC,MAAM,CAAM,EAChC,UAAU,YAAY,KACpB,cAUF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,OAAO,YAAY,KAAG,MACwC,CAAC;AAEnG;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,GAAG,CAAC,YAAY,CAAa,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,YAAY,KAAG,CAAC,MAAM,IAAI,CAWtE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,YAAY,KAAG,OAAO,CAAC,WAAW,CAShE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAO,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CACQ,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GACzC,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,uBAAuB,KAAK,MAAM,GAAG,IAAI,EACtF,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,uBAAuB,KAAK,MAAM,GAAG,IAAI,EACtF,eAAc,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,uBAAuB,KAAK,IACtD,KACd,IAYF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,WAAW,KAAG,MAKxD,CAAC;AAGF,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,MAAM,EACf,OAAM,aAAa,CAAC,MAAM,CAAM,EAChC,UAAU,YAAY,KACpB,kBAuBF,CAAC"}

package/dist/process.js

@@ -0,0 +1,148 @@
+import { spawn as spawn_child_process, } from 'node:child_process';
+import { styleText as st } from 'node:util';
+import { Logger } from './log.js';
+import { print_error, print_key_value } from './print.js';
+const log = new Logger('process');
+/**
+ * A convenient promise wrapper around `spawn_process`
+ * intended for commands that have an end, not long running-processes like watchers.
+ * Any more advanced usage should use `spawn_process` directly for access to the `child` process.
+ */
+export const spawn = (...args) => spawn_process(...args).closed;
+/**
+ * Similar to `spawn` but buffers and returns `stdout` and `stderr` as strings.
+ */
+export const spawn_out = async (command, args = [], options) => {
+    const { child, closed } = spawn_process(command, args, { ...options, stdio: 'pipe' });
+    let stdout = null;
+    child.stdout.on('data', (data) => {
+        stdout = (stdout ?? '') + data.toString();
+    });
+    let stderr = null;
+    child.stderr.on('data', (data) => {
+        stderr = (stderr ?? '') + data.toString();
+    });
+    const result = await closed;
+    return { result, stdout, stderr };
+};
+/**
+ * Wraps the normal Node `childProcess.spawn` with graceful child shutdown behavior.
+ * Also returns a convenient `closed` promise.
+ * If you only need `closed`, prefer the shorthand function `spawn`.
+ * @mutates global_spawn calls `register_global_spawn()` which adds to the module-level Set
+ */
+export const spawn_process = (command, args = [], options) => {
+    let resolve;
+    const closed = new Promise((r) => (resolve = r));
+    const child = spawn_child_process(command, args, { stdio: 'inherit', ...options });
+    const unregister = register_global_spawn(child);
+    child.once('close', (code, signal) => {
+        unregister();
+        resolve(code ? { ok: false, child, code, signal } : { ok: true, child, code, signal });
+    });
+    return { closed, child };
+};
+export const print_child_process = (child) => `${st('gray', 'pid(')}${child.pid}${st('gray', ')')} ← ${st('green', child.spawnargs.join(' '))}`;
+/**
+ * We register spawned processes gloabally so we can gracefully exit child processes.
+ * Otherwise, errors can cause zombie processes, sometimes blocking ports even!
+ */
+export const global_spawn = new Set();
+/**
+ * Returns a function that unregisters the `child`.
+ * @param child the child process to register
+ * @returns cleanup function that removes the child from `global_spawn`
+ * @mutates global_spawn adds child to the module-level Set, and the returned function removes it
+ */
+export const register_global_spawn = (child) => {
+    if (global_spawn.has(child)) {
+        log.error(st('red', 'already registered global spawn:'), print_child_process(child));
+    }
+    global_spawn.add(child);
+    return () => {
+        if (!global_spawn.has(child)) {
+            log.error(st('red', 'spawn not registered:'), print_child_process(child));
+        }
+        global_spawn.delete(child);
+    };
+};
+/**
+ * Kills a child process and returns a `SpawnResult`.
+ */
+export const despawn = (child) => {
+    let resolve;
+    const closed = new Promise((r) => (resolve = r));
+    log.debug('despawning', print_child_process(child));
+    child.once('close', (code, signal) => {
+        resolve(code ? { ok: false, child, code, signal } : { ok: true, child, code, signal });
+    });
+    child.kill();
+    return closed;
+};
+/**
+ * Kills all globally registered child processes.
+ * @mutates global_spawn indirectly removes processes through `despawn()` calls
+ */
+export const despawn_all = () => Promise.all(Array.from(global_spawn, (child) => despawn(child)));
+/**
+ * Attaches the `'uncoughtException'` event to despawn all processes,
+ * and enables custom error logging with `to_error_label`.
+ * @param to_error_label - Customize the error label or return `null` for the default `origin`.
+ * @param map_error_text - Customize the error text. Return `''` to silence, or `null` for the default `print_error(err)`.
+ */
+export const attach_process_error_handlers = (to_error_label, map_error_text, handle_error = () => process.exit(1)) => {
+    process.on('uncaughtException', async (err, origin) => {
+        const label = to_error_label?.(err, origin) ?? origin;
+        if (label) {
+            const error_text = map_error_text?.(err, origin) ?? print_error(err);
+            if (error_text) {
+                new Logger(label).error(error_text);
+            }
+        }
+        await despawn_all();
+        handle_error(err, origin);
+    });
+};
+/**
+ * Formats a `SpawnResult` for printing.
+ */
+export const print_spawn_result = (result) => {
+    if (result.ok)
+        return 'ok';
+    let text = result.code === null ? '' : print_key_value('code', result.code);
+    if (result.signal !== null)
+        text += (text ? ' ' : '') + print_key_value('signal', result.signal);
+    return text;
+};
+/**
+ * Like `spawn_process` but with `restart` and `kill`,
+ * handling many concurrent `restart` calls gracefully.
+ */
+export const spawn_restartable_process = (command, args = [], options) => {
+    let spawned = null;
+    let restarting = null;
+    const close = async () => {
+        if (!spawned)
+            return;
+        restarting = spawned.closed;
+        spawned.child.kill();
+        spawned = null;
+        await restarting;
+        restarting = null;
+    };
+    const restart = async () => {
+        if (restarting)
+            return restarting;
+        if (spawned)
+            await close();
+        spawned = spawn_process(command, args, { stdio: 'inherit', ...options });
+    };
+    const kill = async () => {
+        if (restarting)
+            await restarting;
+        await close();
+    };
+    // Start immediately -- it sychronously starts the process so there's no need to await.
+    void restart();
+    return { restart, kill };
+};

package/dist/random.d.ts

@@ -0,0 +1,25 @@
+import type { ArrayElement } from './types.js';
+/**
+ * Generates a random `number` between `min` and `max`.
+ */
+export declare const random_float: (min: number, max: number, random?: () => number) => number;
+/**
+ * Returns a random integer between `min` and `max` inclusive.
+ * Node's `randomInt` is similar but exclusive of the max value, and makes `min` optional -
+ * https://nodejs.org/docs/latest-v20.x/api/crypto.html#cryptorandomintmin-max-callback
+ */
+export declare const random_int: (min: number, max: number, random?: () => number) => number;
+/**
+ * Generates a random `boolean`.
+ */
+export declare const random_boolean: (random?: () => number) => boolean;
+/**
+ * Selects a random item from an array.
+ */
+export declare const random_item: <T extends ReadonlyArray<any>>(arr: T, random?: () => number) => ArrayElement<T>;
+/**
+ * Mutates `array` with random ordering.
+ * @mutates array randomly reorders elements in place using Fisher-Yates shuffle
+ */
+export declare const shuffle: <T extends Array<any>>(array: T, random?: typeof random_int) => T;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/random.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,qBAAoB,KAAG,MACjD,CAAC;AAE9B;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,qBAAoB,KAAG,MAC/B,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,qBAAoB,KAAG,OAAyB,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,EACvD,KAAK,CAAC,EACN,qBAAoB,KAClB,YAAY,CAAC,CAAC,CAA+C,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,UAAU,KAAK,CAcrF,CAAC"}

package/dist/random.js

@@ -0,0 +1,35 @@
+/**
+ * Generates a random `number` between `min` and `max`.
+ */
+export const random_float = (min, max, random = Math.random) => random() * (max - min) + min;
+/**
+ * Returns a random integer between `min` and `max` inclusive.
+ * Node's `randomInt` is similar but exclusive of the max value, and makes `min` optional -
+ * https://nodejs.org/docs/latest-v20.x/api/crypto.html#cryptorandomintmin-max-callback
+ */
+export const random_int = (min, max, random = Math.random) => Math.floor(random() * (max - min + 1)) + min;
+/**
+ * Generates a random `boolean`.
+ */
+export const random_boolean = (random = Math.random) => random() > 0.5;
+/**
+ * Selects a random item from an array.
+ */
+export const random_item = (arr, random = Math.random) => arr[random_int(0, arr.length - 1, random)];
+/**
+ * Mutates `array` with random ordering.
+ * @mutates array randomly reorders elements in place using Fisher-Yates shuffle
+ */
+export const shuffle = (array, random = random_int) => {
+    const { length } = array;
+    const max = length - 1;
+    for (let i = 0; i < length; i++) {
+        const index = random(0, max);
+        if (i === index)
+            continue;
+        const item = array[index];
+        array[index] = array[i];
+        array[i] = item;
+    }
+    return array;
+};

package/dist/random_alea.d.ts

@@ -0,0 +1,23 @@
+export interface Alea {
+    (): number;
+    uint32: () => number;
+    fract53: () => number;
+    version: string;
+    seeds: Array<unknown>;
+}
+/**
+ * Seeded pseudo-random number generator.
+ * DO NOT USE when security matters, use webcrypto APIs instead.
+ *
+ * @see http://baagoe.com/en/RandomMusings/javascript/
+ * @see https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
+ */
+export declare const create_random_alea: (...seed: Array<unknown>) => Alea;
+type Mash = (data: any) => number;
+/**
+ * @source http://baagoe.com/en/RandomMusings/javascript/
+ * @copyright Johannes Baagøe <baagoe@baagoe.com>, 2010
+ */
+export declare const masher: () => Mash;
+export {};
+//# sourceMappingURL=random_alea.d.ts.map

package/dist/random_alea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random_alea.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/random_alea.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,IAAI;IACpB,IAAI,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,KAAG,IAqC5D,CAAC;AAEF,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,KAAK,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,MAAM,QAAO,IAgBzB,CAAC"}

package/dist/random_alea.js

@@ -0,0 +1,95 @@
+/*
+
+DO NOT USE when security matters, use webcrypto APIs instead.
+This is the Alea pseudo-random number generator by Johannes Baagøe.
+
+From http://baagoe.com/en/RandomMusings/javascript/
+via https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
+
+Copyright (C) 2010 by Johannes Baagøe <baagoe@baagoe.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+*/
+/**
+ * Seeded pseudo-random number generator.
+ * DO NOT USE when security matters, use webcrypto APIs instead.
+ *
+ * @see http://baagoe.com/en/RandomMusings/javascript/
+ * @see https://github.com/nquinlan/better-random-numbers-for-javascript-mirror
+ */
+export const create_random_alea = (...seed) => {
+    let s0 = 0;
+    let s1 = 0;
+    let s2 = 0;
+    let c = 1;
+    const seeds = seed.length ? seed : [Date.now()];
+    let mash = masher();
+    s0 = mash(' ');
+    s1 = mash(' ');
+    s2 = mash(' ');
+    for (const s of seeds) {
+        s0 -= mash(s);
+        if (s0 < 0)
+            s0 += 1;
+        s1 -= mash(s);
+        if (s1 < 0)
+            s1 += 1;
+        s2 -= mash(s);
+        if (s2 < 0)
+            s2 += 1;
+    }
+    mash = null;
+    const random = () => {
+        const t = 2091639 * s0 + c * 2.3283064365386963e-10; // 2^-32
+        s0 = s1;
+        s1 = s2;
+        return (s2 = t - (c = t | 0));
+    };
+    random.uint32 = () => {
+        return random() * 0x100000000; // 2^32
+    };
+    random.fract53 = () => {
+        return random() + ((random() * 0x200000) | 0) * 1.1102230246251565e-16; // 2^-53
+    };
+    random.version = 'Alea 0.9';
+    random.seeds = seeds;
+    return random;
+};
+/**
+ * @source http://baagoe.com/en/RandomMusings/javascript/
+ * @copyright Johannes Baagøe <baagoe@baagoe.com>, 2010
+ */
+export const masher = () => {
+    let n = 0xefc8249d;
+    return (data) => {
+        const d = data + '';
+        for (let i = 0; i < d.length; i++) {
+            n += d.charCodeAt(i);
+            let h = 0.02519603282416938 * n;
+            n = h >>> 0;
+            h -= n;
+            h *= n;
+            n = h >>> 0;
+            h -= n;
+            n += h * 0x100000000; // 2^32
+        }
+        return (n >>> 0) * 2.3283064365386963e-10; // 2^-32
+    };
+};

package/dist/regexp.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Escapes a string for literal matching in a RegExp.
+ * @source https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/RegularExpressions
+ */
+export declare const escape_regexp: (str: string) => string;
+/**
+ * Reset a RegExp's lastIndex to 0 for global and sticky patterns.
+ * Ensures consistent behavior by clearing state that affects subsequent matches.
+ * @mutates regexp sets lastIndex to 0 if regexp is global or sticky
+ */
+export declare const reset_regexp: <T extends RegExp>(regexp: T) => T;
+//# sourceMappingURL=regexp.d.ts.map

package/dist/regexp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regexp.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/regexp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,MAAoD,CAAC;AAEjG;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,CAK1D,CAAC"}

package/dist/regexp.js

@@ -0,0 +1,16 @@
+/**
+ * Escapes a string for literal matching in a RegExp.
+ * @source https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/RegularExpressions
+ */
+export const escape_regexp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Reset a RegExp's lastIndex to 0 for global and sticky patterns.
+ * Ensures consistent behavior by clearing state that affects subsequent matches.
+ * @mutates regexp sets lastIndex to 0 if regexp is global or sticky
+ */
+export const reset_regexp = (regexp) => {
+    if (regexp.global || regexp.sticky) {
+        regexp.lastIndex = 0;
+    }
+    return regexp;
+};

package/dist/result.d.ts

@@ -0,0 +1,64 @@
+/**
+ * An alternative pattern to throwing and catching errors.
+ * Uses the type system to strongly type error return values when desired.
+ * Catching errors is then reserved for unexpected situations.
+ */
+export type Result<TValue = object, TError = object> = ({
+    ok: true;
+} & TValue) | ({
+    ok: false;
+} & TError);
+/**
+ * Frozen object representing a successful result.
+ */
+export declare const OK: Readonly<{
+    readonly ok: true;
+}>;
+/**
+ * Frozen object representing a failed result.
+ */
+export declare const NOT_OK: Readonly<{
+    readonly ok: false;
+}>;
+/**
+ * A helper that says,
+ * "hey I know this is wrapped in a `Result`, but I expect it to be `ok`,
+ * so if it's not, I understand it will throw an error that wraps the result".
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The wrapped value.
+ */
+export declare const unwrap: <TValue extends {
+    value?: unknown;
+}, TError extends {
+    message?: string;
+}>(result: Result<TValue, TError>, message?: string) => TValue["value"];
+/**
+ * A custom error class that's thrown by `unwrap`.
+ * Wraps a failed `Result` with an optional message,
+ * and also accepts an optional message that overrides the result's.
+ * Useful for generic handling of unwrapped results
+ * to forward custom messages and other failed result data.
+ */
+export declare class ResultError extends Error {
+    static DEFAULT_MESSAGE: string;
+    readonly result: {
+        ok: false;
+        message?: string;
+    };
+    constructor(result: {
+        ok: false;
+        message?: string;
+    }, message?: string, options?: ErrorOptions);
+}
+/**
+ * A helper that does the opposite of `unwrap`, throwing if the `Result` is ok.
+ * Note that while `unwrap` returns the wrapped `value`, `unwrap_error` returns the entire result.
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The type-narrowed result.
+ */
+export declare const unwrap_error: <TError extends object>(result: Result<object, TError>, message?: string) => {
+    ok: false;
+} & TError;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,IAChD,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAC,GAAG,MAAM,CAAC,GACrB,CAAC;IAAC,EAAE,EAAE,KAAK,CAAA;CAAC,GAAG,MAAM,CAAC,CAAC;AAE1B;;GAEG;AACH,eAAO,MAAM,EAAE;;EAAqC,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,MAAM;;EAAsC,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,SAAS;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAC,EAAE,MAAM,SAAS;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,EACzF,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,UAAU,MAAM,KACd,MAAM,CAAC,OAAO,CAGhB,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACrC,MAAM,CAAC,eAAe,SAAmB;IAEzC,QAAQ,CAAC,MAAM,EAAE;QAAC,EAAE,EAAE,KAAK,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;gBAEnC,MAAM,EAAE;QAAC,EAAE,EAAE,KAAK,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI3F;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EACjD,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,gBAAyC,KACvC;IAAC,EAAE,EAAE,KAAK,CAAA;CAAC,GAAG,MAGhB,CAAC"}

package/dist/result.js

@@ -0,0 +1,48 @@
+/**
+ * Frozen object representing a successful result.
+ */
+export const OK = Object.freeze({ ok: true });
+/**
+ * Frozen object representing a failed result.
+ */
+export const NOT_OK = Object.freeze({ ok: false });
+/**
+ * A helper that says,
+ * "hey I know this is wrapped in a `Result`, but I expect it to be `ok`,
+ * so if it's not, I understand it will throw an error that wraps the result".
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The wrapped value.
+ */
+export const unwrap = (result, message) => {
+    if (!result.ok)
+        throw new ResultError(result, message);
+    return result.value;
+};
+/**
+ * A custom error class that's thrown by `unwrap`.
+ * Wraps a failed `Result` with an optional message,
+ * and also accepts an optional message that overrides the result's.
+ * Useful for generic handling of unwrapped results
+ * to forward custom messages and other failed result data.
+ */
+export class ResultError extends Error {
+    static DEFAULT_MESSAGE = 'unknown error';
+    result;
+    constructor(result, message, options) {
+        super(message ?? result.message ?? ResultError.DEFAULT_MESSAGE, options);
+        this.result = result;
+    }
+}
+/**
+ * A helper that does the opposite of `unwrap`, throwing if the `Result` is ok.
+ * Note that while `unwrap` returns the wrapped `value`, `unwrap_error` returns the entire result.
+ * @param result Some `Result` object.
+ * @param message Optional custom error message.
+ * @returns The type-narrowed result.
+ */
+export const unwrap_error = (result, message = 'Failed to unwrap result error') => {
+    if (result.ok)
+        throw Error(message);
+    return result;
+};