@forthtilliath/ts-kit 0.2.0 → 0.4.0

package/README.md

@@ -1,11 +1,8 @@
 # @forthtilliath/ts-kit
 
-Framework-agnostic TypeScript utility functions — arrays, maths, browser file
-downloads, and a couple of `Array` extensions with better type-narrowing.
-
-> **Status**: not currently consumed by any other package in this monorepo.
-> Built, linted, tested and type-checked like everything else, but nothing
-> imports it yet.
+Framework-agnostic TypeScript utility functions — arrays, objects, strings,
+async control-flow, dates, numbers, browser file downloads, and a couple of
+`Array` extensions with better type-narrowing.
 
 ## Install
 
@@ -21,31 +18,78 @@ Within the workspace:
 
 ## Usage
 
-Each module is exported individually — import the file you need directly
-rather than a single barrel:
+Import everything you need from the package root — a single barrel re-exports
+every category, so there's no need to remember (or type out) one import line
+per module:
+
+```ts
+import { chunk, clamp, debounce, pick, slugify } from "@forthtilliath/ts-kit";
+```
+
+Subpath imports still work if you'd rather import one module at a time (e.g.
+to keep a bundle's included code obvious at a glance):
 
 ```ts
 import { chunk } from "@forthtilliath/ts-kit/array/chunk";
-import { flattenDeep } from "@forthtilliath/ts-kit/array/flattenDeep";
-import { FArray } from "@forthtilliath/ts-kit/classes/array";
-import {
-  downloadText,
-  downloadTextBlob,
-} from "@forthtilliath/ts-kit/files/downloadText";
-import { avg } from "@forthtilliath/ts-kit/maths/average";
-import { sum } from "@forthtilliath/ts-kit/maths/sum";
 ```
 
 ### `array`
 
 - `chunk(array, size)` — splits an array into chunks of a given size.
 - `flattenDeep(array)` — recursively flattens nested arrays.
+- `getMostRecentIds(rows, limit?)` — most recently occurring distinct ids
+  (`{ id, occurredAt }[]`), most recent first, deduplicated, limited
+  (default 5).
+- `nextInCycle(ids, currentId)` — next id in a short list (e.g. cycling
+  through recents on tap) — wraps to the first if `currentId` is at the end
+  or no longer in the list.
+- `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
+  `query`: earlier match position first, then shorter name — for a
+  search-as-you-type list.
+
+### `async`
+
+- `sleep(ms)` — resolves after a delay.
+- `retry(fn, options)` — retries an async operation with exponential backoff.
+- `debounce(fn, wait)` — delays `fn` until calls stop for `wait` ms; exposes
+  `cancel()` / `flush()`.
+- `throttle(fn, wait)` — runs `fn` at most once per `wait` ms (leading +
+  trailing edge); exposes `cancel()`.
+- `memoize(fn, getKey?)` — caches `fn`'s results per argument tuple; exposes
+  the underlying `cache` map.
+- `withTimeout(promise, ms, message?)` — rejects with a `TimeoutError` if
+  `promise` doesn't settle in time.
 
 ### `classes`
 
-- `FArray` — an `Array` subclass whose `includes()` narrows the type of the
-  searched value when it's found (unlike the native `Array.prototype.includes`,
-  which only narrows the _array's_ element type).
+- `FArray` — an `Array` subclass that fixes a handful of spots where the
+  native `Array` typings are wrong or overly restrictive:
+  - `includes()` narrows the type of the searched value when it's found
+    (the native `Array.prototype.includes` only narrows the _array's_
+    element type).
+  - `indexOf()` / `lastIndexOf()` accept a search value outside of the
+    array's element type instead of rejecting it at compile-time (same
+    root cause as `includes`, fixed the same way).
+  - `filter(Boolean)` strips `null`/`undefined` from the result's type
+    (the native typings don't recognize `Boolean` as a type guard, so the
+    result keeps the nullish types even though they're removed at runtime).
+  - `FArray.from(...)` / `FArray.of(...)` are typed to return an `FArray`
+    instead of a plain array (the native static typings return a plain
+    array even though these methods already construct an instance of the
+    calling class at runtime).
+  - `toArray()` converts an `FArray` back into a plain `Array` instance —
+    rarely needed since `FArray` is already assignable to `T[]` anywhere a
+    plain array is expected, but useful when the runtime type matters too.
+
+### `date`
+
+- `startOfDay(date?)` — returns a new `Date` at local midnight.
+- `isSameDay(a, b)` — checks whether two dates fall on the same local day.
+- `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
+  time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
+- `getPeriodStartMs(period, now?)` — start timestamp (ms) for a
+  `"today" | "7d" | "30d" | "all"` period filter, or `null` for `"all"`.
+  `"today"` is the current calendar day, not a rolling 24h window.
 
 ### `files`
 
@@ -54,11 +98,52 @@ import { sum } from "@forthtilliath/ts-kit/maths/sum";
 - `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
   (better for larger content).
 
+### `id`
+
+- `randomId()` — `crypto.randomUUID()` with fallbacks for older/insecure
+  contexts.
+
 ### `maths`
 
 - `sum(numbers)` — sum of an array of numbers.
 - `avg(numbers)` — average of an array of numbers.
 
+### `number`
+
+- `clamp(value, min, max)` — clamps a number between two bounds.
+- `round(value, decimals?)` — rounds to a given number of decimal places.
+- `formatBytes(bytes, decimals?)` — human-readable byte size ("1.5 MB").
+- `formatDuration(ms)` — human-readable duration ("1d 1h 1m 1s").
+- `formatCsvNumber(value, decimals?)` — formats a number with a comma
+  decimal separator (French-locale spreadsheets) instead of JS's dot.
+
+### `object`
+
+- `pick(obj, keys)` / `omit(obj, keys)` — keep or drop a set of keys.
+- `groupBy(array, getKey)` — groups elements by a computed key.
+- `uniqueBy(array, getKey)` — deduplicates elements by a computed key.
+- `deepClone(value)` — deep clone (via `structuredClone`, with a JSON
+  fallback).
+- `deepEqual(a, b)` — recursive structural equality check.
+- `mapValues(obj, fn)` — maps every value of an object through `fn`.
+
+### `string`
+
+- `capitalize(str)` — uppercases the first letter, lowercases the rest.
+- `truncate(str, maxLength, suffix?)` — truncates with an ellipsis (or custom
+  suffix).
+- `slugify(str)` — URL-friendly slug (accents stripped, lower-cased,
+  hyphenated).
+- `pluralize(count, singular, plural?)` — naive English pluralization, with an
+  override for irregular words.
+- `normalizeForSearch(text)` — lowercases, trims, strips accents, and expands
+  œ/æ ligatures (which `normalize("NFD")` alone doesn't decompose) — for
+  accent/case-insensitive search matching.
+- `escapeCsvField(value)` — quotes and escapes a CSV field (RFC 4180) only if
+  it contains a `"`, `;`, or newline.
+- `escapeHtml(text)` — basic HTML entity escaping (`&`, `<`, `>`, `"`) for
+  inserting user text into an HTML template.
+
 ## Scripts
 
 ```bash

package/dist/array/getMostRecentIds.d.ts

@@ -0,0 +1,21 @@
+export interface RecentIdRow {
+    id: number | null;
+    occurredAt: string;
+}
+/**
+ * Returns the most recently occurring distinct ids, most recent first —
+ * useful for a "recents" picker (a food, a container, or any other dated
+ * entity). Rows with a `null` id (a reference deleted since) are ignored:
+ * there's nothing left to offer for them.
+ *
+ * @param rows - Rows carrying an id (or `null`) and an ISO/parsable date.
+ * @param limit - Max number of ids to return. Defaults to `5`.
+ * @returns Distinct ids, most recent first, limited to `limit`.
+ * @example
+ * getMostRecentIds([
+ *   { id: 1, occurredAt: "2026-01-01T00:00:00.000Z" },
+ *   { id: 2, occurredAt: "2026-01-03T00:00:00.000Z" },
+ * ]); // => [2, 1]
+ */
+export declare function getMostRecentIds(rows: RecentIdRow[], limit?: number): number[];
+//# sourceMappingURL=getMostRecentIds.d.ts.map

package/dist/array/getMostRecentIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMostRecentIds.d.ts","sourceRoot":"","sources":["../../src/array/getMostRecentIds.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,SAAgB,GACpB,MAAM,EAAE,CAcV"}

package/dist/array/getMostRecentIds.js

@@ -0,0 +1,30 @@
+const DEFAULT_LIMIT = 5;
+/**
+ * Returns the most recently occurring distinct ids, most recent first —
+ * useful for a "recents" picker (a food, a container, or any other dated
+ * entity). Rows with a `null` id (a reference deleted since) are ignored:
+ * there's nothing left to offer for them.
+ *
+ * @param rows - Rows carrying an id (or `null`) and an ISO/parsable date.
+ * @param limit - Max number of ids to return. Defaults to `5`.
+ * @returns Distinct ids, most recent first, limited to `limit`.
+ * @example
+ * getMostRecentIds([
+ *   { id: 1, occurredAt: "2026-01-01T00:00:00.000Z" },
+ *   { id: 2, occurredAt: "2026-01-03T00:00:00.000Z" },
+ * ]); // => [2, 1]
+ */
+export function getMostRecentIds(rows, limit = DEFAULT_LIMIT) {
+    const sorted = [...rows].sort((a, b) => new Date(b.occurredAt).getTime() - new Date(a.occurredAt).getTime());
+    const seen = new Set();
+    const result = [];
+    for (const row of sorted) {
+        if (row.id == null || seen.has(row.id))
+            continue;
+        seen.add(row.id);
+        result.push(row.id);
+        if (result.length >= limit)
+            break;
+    }
+    return result;
+}

package/dist/array/index.d.ts

@@ -1,3 +1,6 @@
 export * from "./chunk.js";
 export * from "./flattenDeep.js";
+export * from "./getMostRecentIds.js";
+export * from "./nextInCycle.js";
+export * from "./rankByNameMatch.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC"}

package/dist/array/index.js

@@ -1,2 +1,5 @@
 export * from "./chunk.js";
 export * from "./flattenDeep.js";
+export * from "./getMostRecentIds.js";
+export * from "./nextInCycle.js";
+export * from "./rankByNameMatch.js";

package/dist/array/nextInCycle.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns the next element in a short list (e.g. cycling through a few
+ * recent items on tap). Wraps to the first element if the current one is no
+ * longer in the list (deleted, or out of range) or was the last one.
+ *
+ * @param ids - The list to cycle through.
+ * @param currentId - The currently selected id, or `null` for none.
+ * @returns The next id, or `null` if `ids` is empty.
+ * @example
+ * nextInCycle([1, 2, 3], 1); // => 2
+ * nextInCycle([1, 2, 3], 3); // => 1
+ * nextInCycle([1, 2, 3], null); // => 1
+ */
+export declare function nextInCycle(ids: number[], currentId: number | null): number | null;
+//# sourceMappingURL=nextInCycle.d.ts.map

package/dist/array/nextInCycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextInCycle.d.ts","sourceRoot":"","sources":["../../src/array/nextInCycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EAAE,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM,GAAG,IAAI,CAIf"}

package/dist/array/nextInCycle.js

@@ -0,0 +1,19 @@
+/**
+ * Returns the next element in a short list (e.g. cycling through a few
+ * recent items on tap). Wraps to the first element if the current one is no
+ * longer in the list (deleted, or out of range) or was the last one.
+ *
+ * @param ids - The list to cycle through.
+ * @param currentId - The currently selected id, or `null` for none.
+ * @returns The next id, or `null` if `ids` is empty.
+ * @example
+ * nextInCycle([1, 2, 3], 1); // => 2
+ * nextInCycle([1, 2, 3], 3); // => 1
+ * nextInCycle([1, 2, 3], null); // => 1
+ */
+export function nextInCycle(ids, currentId) {
+    if (ids.length === 0)
+        return null;
+    const currentIndex = currentId == null ? -1 : ids.indexOf(currentId);
+    return ids[(currentIndex + 1) % ids.length] ?? null;
+}

package/dist/array/rankByNameMatch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ranks `items` by relevance to a text search: match position in the name
+ * (earlier is more relevant), then name length. Generic so it can be reused
+ * for any list of items with a displayable name — typically for a
+ * search-as-you-type list.
+ *
+ * @param items - The items to rank.
+ * @param query - The search text.
+ * @param getName - Reads the displayable name off an item.
+ * @returns Only the matching items, ranked most relevant first.
+ * @example
+ * rankByNameMatch(
+ *   [{ label: "Salad with potato" }, { label: "Potato" }],
+ *   "potato",
+ *   (item) => item.label,
+ * ); // => [{ label: "Potato" }, { label: "Salad with potato" }]
+ */
+export declare function rankByNameMatch<T>(items: T[], query: string, getName: (item: T) => string): T[];
+//# sourceMappingURL=rankByNameMatch.d.ts.map

package/dist/array/rankByNameMatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rankByNameMatch.d.ts","sourceRoot":"","sources":["../../src/array/rankByNameMatch.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC3B,CAAC,EAAE,CAiBL"}

package/dist/array/rankByNameMatch.js

@@ -0,0 +1,45 @@
+import { normalizeForSearch } from "../string/normalizeForSearch.js";
+// Caches each item's normalized name by object reference: useful for fixed
+// lists (module-level constants) searched on every keystroke in a search
+// field, to avoid renormalizing every name on each call.
+const normalizedNameCache = new WeakMap();
+function getNormalizedName(item, getName) {
+    if (typeof item !== "object" || item === null)
+        return normalizeForSearch(getName(item));
+    const cached = normalizedNameCache.get(item);
+    if (cached !== undefined)
+        return cached;
+    const normalized = normalizeForSearch(getName(item));
+    normalizedNameCache.set(item, normalized);
+    return normalized;
+}
+/**
+ * Ranks `items` by relevance to a text search: match position in the name
+ * (earlier is more relevant), then name length. Generic so it can be reused
+ * for any list of items with a displayable name — typically for a
+ * search-as-you-type list.
+ *
+ * @param items - The items to rank.
+ * @param query - The search text.
+ * @param getName - Reads the displayable name off an item.
+ * @returns Only the matching items, ranked most relevant first.
+ * @example
+ * rankByNameMatch(
+ *   [{ label: "Salad with potato" }, { label: "Potato" }],
+ *   "potato",
+ *   (item) => item.label,
+ * ); // => [{ label: "Potato" }, { label: "Salad with potato" }]
+ */
+export function rankByNameMatch(items, query, getName) {
+    const normalizedQuery = normalizeForSearch(query);
+    const matches = [];
+    for (const item of items) {
+        const matchIndex = getNormalizedName(item, getName).indexOf(normalizedQuery);
+        if (matchIndex !== -1) {
+            matches.push({ item, matchIndex });
+        }
+    }
+    matches.sort((a, b) => a.matchIndex - b.matchIndex ||
+        getName(a.item).length - getName(b.item).length);
+    return matches.map((m) => m.item);
+}

package/dist/async/debounce.d.ts

@@ -0,0 +1,20 @@
+export interface DebouncedFunction<Args extends unknown[]> {
+    (...args: Args): void;
+    /** Cancels a pending invocation, if any. */
+    cancel: () => void;
+    /** Immediately invokes a pending call, if any. */
+    flush: () => void;
+}
+/**
+ * Returns a debounced version of `fn` that only runs after `wait`
+ * milliseconds have elapsed without another call.
+ *
+ * @param fn - The function to debounce.
+ * @param wait - The delay in milliseconds.
+ * @returns The debounced function, with `cancel()` and `flush()` helpers.
+ * @example
+ * const onResize = debounce(() => recompute(), 200);
+ * window.addEventListener("resize", onResize);
+ */
+export declare function debounce<Args extends unknown[]>(fn: (...args: Args) => void, wait: number): DebouncedFunction<Args>;
+//# sourceMappingURL=debounce.d.ts.map

package/dist/async/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/async/debounce.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,OAAO,EAAE;IACvD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,EAC7C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,IAAI,CAAC,CA+BzB"}

package/dist/async/debounce.js

@@ -0,0 +1,44 @@
+/**
+ * Returns a debounced version of `fn` that only runs after `wait`
+ * milliseconds have elapsed without another call.
+ *
+ * @param fn - The function to debounce.
+ * @param wait - The delay in milliseconds.
+ * @returns The debounced function, with `cancel()` and `flush()` helpers.
+ * @example
+ * const onResize = debounce(() => recompute(), 200);
+ * window.addEventListener("resize", onResize);
+ */
+export function debounce(fn, wait) {
+    let timer;
+    let pendingArgs;
+    const debounced = ((...args) => {
+        pendingArgs = args;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            const callArgs = pendingArgs;
+            pendingArgs = undefined;
+            if (callArgs)
+                fn(...callArgs);
+        }, wait);
+    });
+    debounced.cancel = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        pendingArgs = undefined;
+    };
+    debounced.flush = () => {
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        timer = undefined;
+        const callArgs = pendingArgs;
+        pendingArgs = undefined;
+        if (callArgs)
+            fn(...callArgs);
+    };
+    return debounced;
+}

package/dist/async/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./debounce.js";
+export * from "./memoize.js";
+export * from "./retry.js";
+export * from "./sleep.js";
+export * from "./throttle.js";
+export * from "./withTimeout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC"}

package/dist/async/index.js

@@ -0,0 +1,6 @@
+export * from "./debounce.js";
+export * from "./memoize.js";
+export * from "./retry.js";
+export * from "./sleep.js";
+export * from "./throttle.js";
+export * from "./withTimeout.js";

package/dist/async/memoize.d.ts

@@ -0,0 +1,19 @@
+export interface MemoizedFunction<Args extends unknown[], R> {
+    (...args: Args): R;
+    /** The underlying cache, exposed for inspection or manual clearing. */
+    cache: Map<string, R>;
+}
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * @param fn - The function to memoize.
+ * @param getKey - Computes the cache key for a set of arguments (defaults to `JSON.stringify`).
+ * @returns A memoized version of `fn`, with a `cache` map exposed.
+ * @example
+ * const square = memoize((n: number) => expensiveSquare(n));
+ * square(4); // computed
+ * square(4); // cached
+ */
+export declare function memoize<Args extends unknown[], R>(fn: (...args: Args) => R, getKey?: (...args: Args) => string): MemoizedFunction<Args, R>;
+//# sourceMappingURL=memoize.d.ts.map

package/dist/async/memoize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/async/memoize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC;IACzD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC;IACnB,uEAAuE;IACvE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EAC/C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,EACxB,MAAM,GAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAA0C,GACpE,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,CAa3B"}

package/dist/async/memoize.js

@@ -0,0 +1,25 @@
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * @param fn - The function to memoize.
+ * @param getKey - Computes the cache key for a set of arguments (defaults to `JSON.stringify`).
+ * @returns A memoized version of `fn`, with a `cache` map exposed.
+ * @example
+ * const square = memoize((n: number) => expensiveSquare(n));
+ * square(4); // computed
+ * square(4); // cached
+ */
+export function memoize(fn, getKey = (...args) => JSON.stringify(args)) {
+    const cache = new Map();
+    const memoized = ((...args) => {
+        const key = getKey(...args);
+        if (cache.has(key))
+            return cache.get(key);
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    });
+    memoized.cache = cache;
+    return memoized;
+}

package/dist/async/retry.d.ts

@@ -0,0 +1,25 @@
+export interface RetryOptions {
+    /** Maximum number of attempts, including the first one (default: 3). */
+    attempts?: number;
+    /** Base delay in milliseconds before retrying (default: 200). */
+    delayMs?: number;
+    /** Backoff multiplier applied to `delayMs` after each failed attempt (default: 2). */
+    backoffFactor?: number;
+    /** Called with the error and the 1-based attempt number after each failure. */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * Retries an async operation with exponential backoff.
+ *
+ * @param fn - The operation to retry. Receives the 1-based attempt number.
+ * @param options - Retry configuration.
+ * @returns The result of the first successful attempt.
+ * @throws The last error, if every attempt failed.
+ * @example
+ * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ *   attempts: 5,
+ *   delayMs: 300,
+ * });
+ */
+export declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/async/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/async/retry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAoBZ"}

package/dist/async/retry.js

@@ -0,0 +1,33 @@
+import { sleep } from "./sleep.js";
+/**
+ * Retries an async operation with exponential backoff.
+ *
+ * @param fn - The operation to retry. Receives the 1-based attempt number.
+ * @param options - Retry configuration.
+ * @returns The result of the first successful attempt.
+ * @throws The last error, if every attempt failed.
+ * @example
+ * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ *   attempts: 5,
+ *   delayMs: 300,
+ * });
+ */
+export async function retry(fn, options = {}) {
+    const { attempts = 3, delayMs = 200, backoffFactor = 2, onRetry } = options;
+    let lastError;
+    let currentDelay = delayMs;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (error) {
+            lastError = error;
+            onRetry?.(error, attempt);
+            if (attempt < attempts) {
+                await sleep(currentDelay);
+                currentDelay *= backoffFactor;
+            }
+        }
+    }
+    throw lastError;
+}

package/dist/async/sleep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves after the given number of milliseconds.
+ *
+ * @param ms - The delay in milliseconds.
+ * @example
+ * await sleep(1000); // waits 1 second
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/async/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/async/sleep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/async/sleep.js

@@ -0,0 +1,10 @@
+/**
+ * Resolves after the given number of milliseconds.
+ *
+ * @param ms - The delay in milliseconds.
+ * @example
+ * await sleep(1000); // waits 1 second
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/async/throttle.d.ts

@@ -0,0 +1,20 @@
+export interface ThrottledFunction<Args extends unknown[]> {
+    (...args: Args): void;
+    /** Cancels any pending trailing invocation. */
+    cancel: () => void;
+}
+/**
+ * Returns a throttled version of `fn` that runs at most once every `wait`
+ * milliseconds: immediately on the first call (leading edge), then once more
+ * at the end of the window if further calls came in during it (trailing
+ * edge).
+ *
+ * @param fn - The function to throttle.
+ * @param wait - The minimum delay in milliseconds between calls.
+ * @returns The throttled function, with a `cancel()` helper.
+ * @example
+ * const onScroll = throttle(() => updatePosition(), 100);
+ * window.addEventListener("scroll", onScroll);
+ */
+export declare function throttle<Args extends unknown[]>(fn: (...args: Args) => void, wait: number): ThrottledFunction<Args>;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/async/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/async/throttle.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,OAAO,EAAE;IACvD,CAAC,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAS,OAAO,EAAE,EAC7C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,EAC3B,IAAI,EAAE,MAAM,GACX,iBAAiB,CAAC,IAAI,CAAC,CAkCzB"}

package/dist/async/throttle.js

@@ -0,0 +1,43 @@
+/**
+ * Returns a throttled version of `fn` that runs at most once every `wait`
+ * milliseconds: immediately on the first call (leading edge), then once more
+ * at the end of the window if further calls came in during it (trailing
+ * edge).
+ *
+ * @param fn - The function to throttle.
+ * @param wait - The minimum delay in milliseconds between calls.
+ * @returns The throttled function, with a `cancel()` helper.
+ * @example
+ * const onScroll = throttle(() => updatePosition(), 100);
+ * window.addEventListener("scroll", onScroll);
+ */
+export function throttle(fn, wait) {
+    let lastCallTime;
+    let timer;
+    let pendingArgs;
+    const throttled = ((...args) => {
+        const now = Date.now();
+        if (lastCallTime === undefined || now - lastCallTime >= wait) {
+            lastCallTime = now;
+            fn(...args);
+            return;
+        }
+        pendingArgs = args;
+        timer ??= setTimeout(() => {
+            lastCallTime = Date.now();
+            timer = undefined;
+            const callArgs = pendingArgs;
+            pendingArgs = undefined;
+            if (callArgs)
+                fn(...callArgs);
+        }, wait - (now - lastCallTime));
+    });
+    throttled.cancel = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        pendingArgs = undefined;
+        lastCallTime = undefined;
+    };
+    return throttled;
+}