@fuzdev/fuz_util 0.42.0

package/dist/string.js

@@ -0,0 +1,92 @@
+import { count_iterator } from './iterator.js';
+/**
+ * Truncates a string to a maximum length, adding a suffix if needed that defaults to `...`.
+ */
+export const truncate = (str, maxLength, suffix = '...') => {
+    if (maxLength < suffix.length)
+        return '';
+    if (str.length > maxLength) {
+        return str.substring(0, maxLength - suffix.length) + suffix;
+    }
+    return str;
+};
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_start = (source, stripped) => {
+    if (!stripped || !source.startsWith(stripped))
+        return source;
+    return source.substring(stripped.length);
+};
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_end = (source, stripped) => {
+    if (!stripped || !source.endsWith(stripped))
+        return source;
+    return source.substring(0, source.length - stripped.length);
+};
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_after = (source, stripped) => {
+    if (!stripped)
+        return source;
+    const idx = source.indexOf(stripped);
+    if (idx === -1)
+        return source;
+    return source.substring(0, idx);
+};
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export const strip_before = (source, stripped) => {
+    if (!stripped)
+        return source;
+    const idx = source.indexOf(stripped);
+    if (idx === -1)
+        return source;
+    return source.substring(idx + stripped.length);
+};
+/**
+ * Adds the substring `ensured` to the start of the `source` string if it's not already present.
+ */
+export const ensure_start = (source, ensured) => {
+    if (source.startsWith(ensured))
+        return source;
+    return ensured + source;
+};
+/**
+ * Adds the substring `ensured` to the end of the `source` string if it's not already present.
+ */
+export const ensure_end = (source, ensured) => {
+    if (source.endsWith(ensured))
+        return source;
+    return source + ensured;
+};
+/**
+ * Removes leading and trailing spaces from each line of a string.
+ */
+export const deindent = (str) => str
+    .split('\n')
+    .filter(Boolean)
+    .map((s) => s.trim())
+    .join('\n');
+/**
+ * Returns a plural suffix based on a count.
+ */
+export const plural = (count, suffix = 's') => count === 1 ? '' : suffix;
+/**
+ * Returns the count of graphemes in a string, the individually rendered characters.
+ */
+export const count_graphemes = (str) => count_iterator(new Intl.Segmenter().segment(str));
+/**
+ * Strips ANSI escape sequences from a string
+ */
+export const strip_ansi = (str) => str.replaceAll(/\x1B\[[0-9;]*[a-zA-Z]/g, ''); // eslint-disable-line no-control-regex
+/**
+ * Stringifies a value like `JSON.stringify` but with some corner cases handled better.
+ *
+ * @source https://2ality.com/2025/04/stringification-javascript.html
+ */
+export const stringify = (value) => typeof value === 'bigint' ? value + 'n' : (JSON.stringify(value) ?? String(value)); // eslint-disable-line @typescript-eslint/no-unnecessary-condition

package/dist/throttle.d.ts

@@ -0,0 +1,26 @@
+export interface ThrottleOptions {
+    /**
+     * Enforced milliseconds between calls. For `when='trailing'` this is the debounce delay.
+     */
+    delay?: number;
+    /**
+     * When to call the throttled function. Defaults to `both`.
+     */
+    when?: 'both' | 'leading' | 'trailing';
+}
+/**
+ * Throttles calls to a callback that returns a void promise.
+ * Immediately invokes the callback on the first call unless `leading=false`.
+ * If the throttled function is called while the promise is already pending,
+ * the call is queued to run after the pending promise completes plus `delay`,
+ * and only the last call is invoked.
+ * In other words, all calls and their args are discarded
+ * during the pending window except for the most recent.
+ * Unlike debouncing, this calls the throttled callback
+ * both on the leading and trailing edges of the delay window by default,
+ * and this can be customized by setting `leading` or `trailing.
+ * It also differs from a queue where every call to the throttled callback eventually runs.
+ * @returns same as `cb`
+ */
+export declare const throttle: <T extends (...args: Array<any>) => Promise<void>>(cb: T, { delay, when }?: ThrottleOptions) => T;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/throttle.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACxE,IAAI,CAAC,EACL,kBAA4B,eAA8B,KACxD,CAsCF,CAAC"}

package/dist/throttle.js

@@ -0,0 +1,53 @@
+import { create_deferred } from './async.js';
+import { EMPTY_OBJECT } from './object.js';
+/**
+ * Throttles calls to a callback that returns a void promise.
+ * Immediately invokes the callback on the first call unless `leading=false`.
+ * If the throttled function is called while the promise is already pending,
+ * the call is queued to run after the pending promise completes plus `delay`,
+ * and only the last call is invoked.
+ * In other words, all calls and their args are discarded
+ * during the pending window except for the most recent.
+ * Unlike debouncing, this calls the throttled callback
+ * both on the leading and trailing edges of the delay window by default,
+ * and this can be customized by setting `leading` or `trailing.
+ * It also differs from a queue where every call to the throttled callback eventually runs.
+ * @returns same as `cb`
+ */
+export const throttle = (cb, { delay = 0, when = 'both' } = EMPTY_OBJECT) => {
+    let pending_promise = null;
+    let next_args = null;
+    let next_deferred = null;
+    const defer = (args) => {
+        next_args = args;
+        if (!next_deferred) {
+            next_deferred = create_deferred();
+            setTimeout(flush, delay);
+        }
+        return next_deferred.promise;
+    };
+    const flush = async () => {
+        if (!next_deferred)
+            return;
+        const result = await call(next_args);
+        next_args = null;
+        const { resolve } = next_deferred;
+        next_deferred = null;
+        resolve(result); // resolve last to prevent synchronous call issues
+    };
+    const call = (args) => {
+        pending_promise = cb(...args);
+        void pending_promise.finally(() => {
+            pending_promise = null;
+        });
+        return pending_promise;
+    };
+    return ((...args) => {
+        if (pending_promise || when === 'trailing') {
+            return when === 'leading' ? pending_promise : defer(args); // discarded when pending and not trailing
+        }
+        else {
+            return call(args);
+        }
+    });
+};

package/dist/timings.d.ts

@@ -0,0 +1,33 @@
+export type Stopwatch = (reset?: boolean) => number;
+/**
+ * Tracks elapsed time in milliseconds.
+ */
+export declare const create_stopwatch: (decimals?: number) => Stopwatch;
+export type TimingsKey = string | number;
+/**
+ * Tracks and manages multiple timing operations.
+ * Allows starting, stopping, and retrieving timings with optional precision.
+ */
+export declare class Timings {
+    readonly decimals: number | undefined;
+    private readonly timings;
+    private readonly stopwatches;
+    constructor(decimals?: number);
+    /**
+     * Starts a timing operation for the given key.
+     */
+    start(key: TimingsKey, decimals?: number | undefined): () => number;
+    private next_key;
+    /**
+     * Stops a timing operation and records the elapsed time.
+     */
+    private stop;
+    get(key: TimingsKey): number;
+    entries(): IterableIterator<[TimingsKey, number | undefined]>;
+    /**
+     * Merges other timings into this one,
+     * adding together values with identical keys.
+     */
+    merge(timings: Timings): void;
+}
+//# sourceMappingURL=timings.d.ts.map

package/dist/timings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timings.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/timings.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,iBAAY,KAAG,SAQ/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,qBAAa,OAAO;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;gBAEzD,QAAQ,CAAC,EAAE,MAAM;IAI7B;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,qBAAgB,GAAG,MAAM,MAAM;IAO9D,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,OAAO,CAAC,IAAI;IASZ,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM;IAM5B,OAAO,IAAI,gBAAgB,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAI7D;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAc7B"}

package/dist/timings.js

@@ -0,0 +1,75 @@
+import { round } from './maths.js';
+/**
+ * Tracks elapsed time in milliseconds.
+ */
+export const create_stopwatch = (decimals = 2) => {
+    let start = performance.now();
+    return (reset = false) => {
+        const end = performance.now();
+        const elapsed = round(Number(end - start), decimals); // eslint-disable-line @typescript-eslint/no-unnecessary-type-conversion
+        if (reset)
+            start = end;
+        return elapsed;
+    };
+};
+/**
+ * Tracks and manages multiple timing operations.
+ * Allows starting, stopping, and retrieving timings with optional precision.
+ */
+export class Timings {
+    decimals;
+    timings = new Map();
+    stopwatches = new Map();
+    constructor(decimals) {
+        this.decimals = decimals;
+    }
+    /**
+     * Starts a timing operation for the given key.
+     */
+    start(key, decimals = this.decimals) {
+        const final_key = this.next_key(key);
+        this.stopwatches.set(final_key, create_stopwatch(decimals));
+        this.timings.set(final_key, undefined); // initializing to preserve order
+        return () => this.stop(final_key);
+    }
+    next_key(key) {
+        if (!this.stopwatches.has(key))
+            return key;
+        let i = 2;
+        while (true) {
+            const next = key + '_' + i++;
+            if (!this.stopwatches.has(next))
+                return next;
+        }
+    }
+    /**
+     * Stops a timing operation and records the elapsed time.
+     */
+    stop(key) {
+        const stopwatch = this.stopwatches.get(key);
+        if (!stopwatch)
+            return 0; // TODO maybe warn?
+        this.stopwatches.delete(key);
+        const timing = stopwatch();
+        this.timings.set(key, timing);
+        return timing;
+    }
+    get(key) {
+        const timing = this.timings.get(key);
+        if (timing === undefined)
+            return 0; // TODO maybe warn?
+        return timing;
+    }
+    entries() {
+        return this.timings.entries();
+    }
+    /**
+     * Merges other timings into this one,
+     * adding together values with identical keys.
+     */
+    merge(timings) {
+        for (const [key, timing] of timings.entries()) {
+            this.timings.set(key, timing === undefined ? undefined : (this.timings.get(key) ?? 0) + timing);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type ClassConstructor<TInstance, TArgs extends Array<any> = Array<any>> = new (...args: TArgs) => TInstance;
+export type OmitStrict<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+/**
+ * Like `Pick` but works for type unions.
+ *
+ * @see https://stackoverflow.com/questions/75271774/creating-a-type-using-pick-with-a-type-that-is-defined-as-a-union-of-types
+ * @see https://stackoverflow.com/users/5770132/oblosys
+ */
+export type PickUnion<T, K extends KeyofUnion<T>> = T extends unknown ? K & keyof T extends never ? never : Pick<T, K & keyof T> : never;
+/**
+ * Like `keyof` but works for type unions.
+ *
+ * @see https://stackoverflow.com/questions/75271774/creating-a-type-using-pick-with-a-type-that-is-defined-as-a-union-of-types
+ * @see https://stackoverflow.com/users/5770132/oblosys
+ */
+export type KeyofUnion<T> = T extends unknown ? keyof T : never;
+export type PartialExcept<T, K extends keyof T> = {
+    [P in K]: T[P];
+} & {
+    [P in Exclude<keyof T, K>]?: T[P];
+};
+export type PartialOnly<T, K extends keyof T> = {
+    [P in K]?: T[P];
+} & {
+    [P in Exclude<keyof T, K>]: T[P];
+};
+export type PartialValues<T> = {
+    [P in keyof T]: Partial<T[P]>;
+};
+export type Assignable<T, K extends keyof T = keyof T> = {
+    -readonly [P in K]: T[P];
+};
+export type Defined<T> = T extends undefined ? never : T;
+export type NotNull<T> = T extends null ? never : T;
+export type ArrayElement<T> = T extends ReadonlyArray<infer U> ? U : never;
+/**
+ * The `Flavored` and `Branded` type helpers add varying degrees of nominal typing to other types.
+ * This is especially useful with primitives like strings and numbers.
+ *
+ * @see https://spin.atomicobject.com/typescript-flexible-nominal-typing/
+ *
+ * `Flavored` is a looser form of `Branded` that trades
+ * explicitness and a little safety in some cases for ergonomics.
+ * With `Flavored` you don't need to cast unflavored types:
+ *
+ * ```ts
+ * type Email = Flavored<string, 'Email'>;
+ * const email1: Email = 'foo'; // ok
+ * type Address = Flavored<string, 'Address'>;
+ * const email2: Email = 'foo' as Address; // error!
+ * ```
+ *
+ * `Branded` requires casting:
+ *
+ * ```ts
+ * type PhoneNumber = Branded<string, 'PhoneNumber'>;
+ * const phone1: PhoneNumber = 'foo'; // error!
+ * const phone2: PhoneNumber = 'foo' as PhoneNumber; // ok
+ * ```
+ *
+ * See also Zod's `.brand` schema helper:
+ *
+ * @see https://github.com/colinhacks/zod#brand
+ *
+ */
+export type Flavored<TValue, TName> = TValue & Flavor<TName>;
+declare const FlavoredSymbol: unique symbol;
+export interface Flavor<T> {
+    readonly [FlavoredSymbol]?: T;
+}
+export type Branded<TValue, TName> = TValue & Brand<TName>;
+declare const BrandedSymbol: unique symbol;
+export interface Brand<T> {
+    readonly [BrandedSymbol]: T;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/types.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,KAChF,GAAG,IAAI,EAAE,KAAK,KACV,SAAS,CAAC;AAEf,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,GAClE,CAAC,GAAG,MAAM,CAAC,SAAS,KAAK,GACxB,KAAK,GACL,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,GACrB,KAAK,CAAC;AAET;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC;AAKhE,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAC,GAAG;KACnE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AACF,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAAC,GAAG;KAClE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI;IACxD,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC;AACzD,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;AAEpD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7D,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAC5C,MAAM,WAAW,MAAM,CAAC,CAAC;IACxB,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;CAC9B;AACD,MAAM,MAAM,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3D,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAC3C,MAAM,WAAW,KAAK,CAAC,CAAC;IACvB,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;CAC5B"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/*
+
+These are convenient global types that can be used in both Felt and user code.
+It probably makes more sense to give this file a `.d.ts` extension,
+but that complicates the build because TypeScript does not output them.
+
+TODO probably make this `.d.ts` when we make a proper build process
+
+*/
+export {};

package/dist/url.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { Flavored } from './types.js';
+/**
+ * Formats a URL by removing 'https://', 'www.', and trailing slashes.
+ * Notably it does not remove 'http://', so the user can see that it's insecure.
+ */
+export declare const format_url: (url: string) => string;
+export declare const Url: z.ZodURL;
+export type Url = Flavored<z.infer<typeof Url>, 'Url'>;
+//# sourceMappingURL=url.d.ts.map

package/dist/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MACyB,CAAC;AAEnE,eAAO,MAAM,GAAG,UAAU,CAAC;AAC3B,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC"}

package/dist/url.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { strip_end, strip_start } from './string.js';
+/**
+ * Formats a URL by removing 'https://', 'www.', and trailing slashes.
+ * Notably it does not remove 'http://', so the user can see that it's insecure.
+ */
+export const format_url = (url) => strip_end(strip_start(strip_start(url, 'https://'), 'www.'), '/');
+export const Url = z.url();

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@fuzdev/fuz_util",
+  "version": "0.42.0",
+  "description": "utility belt for JS",
+  "glyph": "🦕",
+  "logo": "logo.svg",
+  "logo_alt": "a green sauropod wearing a brown utility belt",
+  "motto": "ancient not extinct",
+  "public": true,
+  "license": "MIT",
+  "homepage": "https://belt.ryanatkn.com/",
+  "author": {
+    "name": "Ryan Atkinson",
+    "email": "mail@ryanatkn.com",
+    "url": "https://www.ryanatkn.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanatkn/belt.git"
+  },
+  "bugs": "https://github.com/ryanatkn/belt/issues",
+  "funding": "https://www.ryanatkn.com/funding",
+  "scripts": {
+    "start": "gro dev",
+    "dev": "gro dev",
+    "build": "gro build",
+    "check": "gro check",
+    "test": "gro test",
+    "preview": "vite preview",
+    "deploy": "gro deploy",
+    "benchmark": "gro run src/benchmarks/slugify_benchmark.ts",
+    "benchmark-deep-equal": "node --max-old-space-size=8192 --expose-gc --import @ryanatkn/gro/register.js src/lib/deep_equal.bench_comparison.ts",
+    "benchmark-deep-equal-deno": "deno run --allow-read --allow-env --v8-flags=--expose-gc src/lib/deep_equal.bench_comparison.ts"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.15"
+  },
+  "keywords": [
+    "js",
+    "typescript",
+    "utilities",
+    "web"
+  ],
+  "peerDependencies": {
+    "@types/node": "^24",
+    "esm-env": "^1.2.2",
+    "zod": "^4.0.14"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    },
+    "esm-env": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/changelog-git": "^0.2.1",
+    "@ryanatkn/eslint-config": "^0.9.0",
+    "@ryanatkn/fuz": "^0.167.0",
+    "@ryanatkn/fuz_code": "^0.36.0",
+    "@ryanatkn/gro": "^0.179.0",
+    "@ryanatkn/moss": "^0.39.0",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.49.0",
+    "@sveltejs/package": "^2.5.6",
+    "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@types/node": "^24.10.1",
+    "dequal": "^2.0.3",
+    "eslint": "^9.39.1",
+    "eslint-plugin-svelte": "^3.13.0",
+    "esm-env": "^1.2.2",
+    "prettier": "^3.6.2",
+    "prettier-plugin-svelte": "^3.4.0",
+    "svelte": "^5.44.1",
+    "svelte-check": "^4.3.4",
+    "tinybench": "^5.1.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.0.14",
+    "zod": "^4.1.13"
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-svelte"
+    ],
+    "useTabs": true,
+    "printWidth": 100,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "overrides": [
+      {
+        "files": "package.json",
+        "options": {
+          "useTabs": false
+        }
+      }
+    ]
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src/lib/**/*.ts",
+    "!src/lib/**/*.test.*",
+    "!dist/**/*.test.*"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  }
+}

package/src/lib/array.ts

@@ -0,0 +1,30 @@
+import type {ArrayElement} from './types.js';
+
+// TODO try to cange to readonly again, see if upstream errors are tolerably fixed
+export const EMPTY_ARRAY: Array<any> = Object.freeze([]) as any;
+
+/** Converts `value` to an array if it's not already. */
+export const to_array = <T>(value: T): T extends ReadonlyArray<any> ? T : Array<T> =>
+	Array.isArray(value) ? (value as any) : ([value] as any);
+
+/**
+ * Removes an element from `array` at `index` in an unordered manner.
+ * @mutates array swaps element at index with last element, then removes last element
+ */
+export const remove_unordered = (array: Array<any>, index: number): void => {
+	array[index] = array[array.length - 1];
+	array.pop();
+};
+
+/**
+ * Returns a function that returns the next item in the `array`
+ * in a linear sequence, looping back to index 0 when it reaches the end.
+ */
+export const to_next = <T extends ReadonlyArray<any>>(array: T): (() => ArrayElement<T>) => {
+	let i = -1;
+	return () => {
+		i++;
+		if (i >= array.length) i = 0;
+		return array[i];
+	};
+};