@forthtilliath/ts-kit 0.9.0 → 0.11.0

package/README.md

@@ -33,10 +33,27 @@ to keep a bundle's included code obvious at a glance):
 import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 ```
 
+### Browser-only functions
+
+Everything runs in any JavaScript runtime (browser, Node, React Native,
+Angular SSR…) **except** these, which need a DOM (`document`, `Image`,
+`URL.createObjectURL`) and throw elsewhere — only call them client-side:
+
+- `csv/downloadCsv`
+- `files/downloadText`, `files/downloadTextBlob`
+- `image/compressImage`
+
+Importing them is harmless anywhere: the DOM is only touched when called.
+
 ### `array`
 
 - `chunk(array, size)` — splits an array into chunks of a given size.
-- `flattenDeep(array)` — recursively flattens nested arrays.
+- `createColumnStorage(defaults)` — `{ serialize, deserialize }` pair to
+  persist a user-customized column list (order + visibility, e.g. in
+  `localStorage`). Only `key`/`visible` are stored; on read, unknown keys are
+  dropped, new columns appended, and invalid input falls back to `defaults`.
+- `flattenDeep(array)` — recursively flattens nested arrays, typed as the
+  innermost element type (`number[][][]` → `number[]`).
 - `getMostRecentIds(rows, limit?)` — most recently occurring distinct ids
   (`{ id, occurredAt }[]`), most recent first, deduplicated, limited
   (default 5).
@@ -56,16 +73,23 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 
 ### `async`
 
-- `sleep(ms)` — resolves after a delay.
+- `sleep(ms, signal?)` — resolves after a delay; rejects early if `signal`
+  aborts.
 - `retry(fn, options)` — retries an async operation with exponential backoff.
+  Options: `attempts` (3), `delayMs` (200), `backoffFactor` (2),
+  `maxDelayMs`, `shouldRetry(error, attempt)` (return `false` to rethrow at
+  once, e.g. on a 4xx), `onRetry(error, attempt)` (called before each actual
+  retry), `signal`.
 - `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.
+- `withTimeout(operation, ms, message?)` — rejects with a `TimeoutError` if
+  `operation` doesn't settle in time. Pass a function `(signal) => promise`
+  instead of a promise to also **cancel** the operation on timeout (e.g.
+  `withTimeout((signal) => fetch(url, { signal }), 5000)`).
+- `memoize` — moved to [`function`](#function); still importable from
+  `async/memoize` (deprecated).
 
 ### `classes`
 
@@ -93,11 +117,19 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `parseCsvLine(line, delimiter?)` — splits one CSV line into trimmed cells;
   quoted cells may contain the delimiter, `""` stands for a literal quote.
   Delimiter defaults to `","`.
-- `toCsv(rows, delimiter?)` — serializes rows to CSV, every cell quoted and
-  escaped, rows joined with `\n`.
+- `toCsv(rows, delimiter?)` — serializes whole rows to CSV, every cell quoted
+  and escaped, rows joined with `\n`. Delimiter defaults to `","`.
+- `escapeCsvField(value, delimiter?)` — escapes a single field (RFC 4180),
+  quoting it only if it contains a `"`, the delimiter or a line break — to
+  build rows cell by cell. Delimiter defaults to `";"` (French-locale Excel).
+- `formatCsvNumber(value, decimals?)` — formats a number with a comma decimal
+  separator (French-locale spreadsheets) instead of JS's dot.
 - `downloadCsv(filename, content)` — browser download as `text/csv`, with a
   UTF-8 BOM so Excel reads accented characters.
 
+`escapeCsvField` and `formatCsvNumber` used to live in `string/` and
+`number/`; those deep imports still work (deprecated).
+
 ### `date`
 
 - `startOfDay(date?)` — returns a new `Date` at local midnight.
@@ -107,13 +139,33 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `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.
+- `dateInTimeZone(date, timeZone)` — the calendar date of an instant in an
+  IANA time zone, `{ year, month, day, iso }` (`month` from 1 to 12), whatever
+  the machine's own time zone.
+- `todayInTimeZone(timeZone, now?)` — today's date in that time zone: on a
+  server running in UTC, `new Date()` is still "yesterday" in Paris just
+  after midnight.
+- `daysUntil(date, timeZone, now?)` — calendar days between today and a date,
+  both taken in that time zone (`0` today, `1` tomorrow, `-1` yesterday);
+  unaffected by the time of day or daylight saving time.
 
 ### `files`
 
 - `downloadText(filename, text)` — triggers a browser download of a text file
   via a `data:` URI.
 - `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
-  (better for larger content).
+  (better for larger content). The object URL is revoked 40 s later, not
+  right after the click (which can cancel the download in Firefox/Safari).
+
+### `function`
+
+- `memoize(fn, getKeyOrOptions?)` — caches `fn`'s results per argument tuple
+  (JSON-stringified by default); exposes the underlying `cache` map. Pass a
+  key function, or `{ getKey, maxSize }` to evict the least recently used
+  result beyond `maxSize`. A returned promise that rejects is evicted, so the
+  next call retries instead of failing forever.
+- `sanitizeFileName(name)` — replaces characters forbidden in file names
+  (`\ / : * ? " < > |`) with hyphens, collapses whitespace and trims.
 
 ### `id`
 
@@ -135,19 +187,20 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
   `bold`-aware segments), ready for a UI layer to render without a full
   Markdown dependency.
 
-### `maths`
-
-- `sum(numbers)` — sum of an array of numbers.
-- `avg(numbers)` — average of an array of numbers.
-
 ### `number`
 
+- `sum(numbers)` — sum of an array of numbers (`0` if empty).
+- `avg(numbers)` — average of an array of numbers; `NaN` if empty (no
+  meaningful average of nothing, like lodash's `mean`).
 - `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.
+- `padNumber(n, total, minWidth?)` — zero-pads `n` to the width of `total`
+  (at least `minWidth`, default 2) so numbered file names sort correctly.
+
+`sum` and `avg` used to live in `maths/`; those deep imports still work
+(deprecated).
 
 ### `object`
 
@@ -166,15 +219,20 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
   suffix).
 - `slugify(str)` — URL-friendly slug (accents stripped, lower-cased,
   hyphenated).
-- `pluralize(count, singular, plural?)` — naive English pluralization, with an
-  override for irregular words.
+- `pluralize(count, singular, plural? | { plural?, locale? })` — picks the
+  singular or the plural form. Which counts take the singular follows the
+  locale's rules (`Intl.PluralRules`, `"en"` by default): only ±1 in
+  English, 0 and 1.5 too in French. Without an explicit plural form, a naive
+  suffix: English `s`/`es`/`ies`, French `s` (nothing after `s`/`x`/`z`),
+  `s` elsewhere.
+- `createPluralize(locale)` — `pluralize` bound to a locale, declared once per
+  app: `const plural = createPluralize("fr"); plural(n, "est", "sont")`.
 - `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.
+- `escapeHtml(text)` — HTML entity escaping (`&`, `<`, `>`, `"`, `'`) for
+  inserting user text into an HTML template, in text content or in an
+  attribute quoted with `"` or `'`.
 
 ### `version`
 

package/dist/array/createColumnStorage.d.ts

@@ -0,0 +1,30 @@
+/** Minimal shape of a toggleable, reorderable column. */
+export interface StorableColumn {
+    key: string;
+    visible: boolean;
+}
+export interface ColumnStorage<T extends StorableColumn> {
+    serialize: (columns: readonly T[]) => string;
+    deserialize: (raw: string) => T[];
+}
+/**
+ * Creates a (de)serializer for a user-customized list of columns (order and
+ * visibility), e.g. to persist a table layout in `localStorage`. Only `key`
+ * and `visible` are stored; other properties (labels…) always come from
+ * `defaults`. On read, unknown keys are dropped, columns missing from the
+ * stored value are appended in their default order, and invalid JSON falls
+ * back to `defaults`.
+ *
+ * @param defaults - The default columns, in their default order.
+ * @returns A `{ serialize, deserialize }` pair.
+ * @example
+ * const storage = createColumnStorage([
+ *   { key: "name", label: "Name", visible: true },
+ *   { key: "email", label: "Email", visible: true },
+ * ]);
+ * storage.deserialize('[{"key":"email","visible":false}]');
+ * // => [{ key: "email", label: "Email", visible: false },
+ * //     { key: "name", label: "Name", visible: true }]
+ */
+export declare function createColumnStorage<T extends StorableColumn>(defaults: readonly T[]): ColumnStorage<T>;
+//# sourceMappingURL=createColumnStorage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createColumnStorage.d.ts","sourceRoot":"","sources":["../../src/array/createColumnStorage.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc;IACrD,SAAS,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,KAAK,MAAM,CAAC;IAC7C,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAC1D,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,aAAa,CAAC,CAAC,CAAC,CAgClB"}

package/dist/array/createColumnStorage.js

@@ -0,0 +1,51 @@
+/**
+ * Creates a (de)serializer for a user-customized list of columns (order and
+ * visibility), e.g. to persist a table layout in `localStorage`. Only `key`
+ * and `visible` are stored; other properties (labels…) always come from
+ * `defaults`. On read, unknown keys are dropped, columns missing from the
+ * stored value are appended in their default order, and invalid JSON falls
+ * back to `defaults`.
+ *
+ * @param defaults - The default columns, in their default order.
+ * @returns A `{ serialize, deserialize }` pair.
+ * @example
+ * const storage = createColumnStorage([
+ *   { key: "name", label: "Name", visible: true },
+ *   { key: "email", label: "Email", visible: true },
+ * ]);
+ * storage.deserialize('[{"key":"email","visible":false}]');
+ * // => [{ key: "email", label: "Email", visible: false },
+ * //     { key: "name", label: "Name", visible: true }]
+ */
+export function createColumnStorage(defaults) {
+    function serialize(columns) {
+        return JSON.stringify(columns.map(({ key, visible }) => ({ key, visible })));
+    }
+    function deserialize(raw) {
+        try {
+            const stored = JSON.parse(raw);
+            if (!Array.isArray(stored))
+                return [...defaults];
+            const result = [];
+            for (const entry of stored) {
+                const { key, visible } = (entry ?? {});
+                const column = defaults.find((c) => c.key === key);
+                if (!column || result.some((c) => c.key === column.key))
+                    continue;
+                result.push({
+                    ...column,
+                    visible: typeof visible === "boolean" ? visible : column.visible,
+                });
+            }
+            for (const column of defaults) {
+                if (!result.some((c) => c.key === column.key))
+                    result.push(column);
+            }
+            return result;
+        }
+        catch {
+            return [...defaults];
+        }
+    }
+    return { serialize, deserialize };
+}

package/dist/array/flattenDeep.d.ts

@@ -1,9 +1,11 @@
 /**
- * Recursively flattens a nested array.
+ * Recursively flattens a nested array, at any depth.
  *
- * @template T - The type of elements in the array.
- * @param {T[]} array - The array to flatten.
- * @return {T[]} The flattened array.
+ * @param array - The array to flatten (left untouched).
+ * @returns A new array with every nested element at the top level, typed as
+ *   the innermost element type (`number[][][]` → `number[]`).
+ * @example
+ * flattenDeep([1, [2, [3, [4]]]]); // => [1, 2, 3, 4]
  */
-export declare function flattenDeep<T>(array: T[]): T[];
+export declare function flattenDeep<T extends readonly unknown[]>(array: T): FlatArray<T, 20>[];
 //# sourceMappingURL=flattenDeep.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flattenDeep.d.ts","sourceRoot":"","sources":["../../src/array/flattenDeep.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAM9C"}
+{"version":3,"file":"flattenDeep.d.ts","sourceRoot":"","sources":["../../src/array/flattenDeep.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EACtD,KAAK,EAAE,CAAC,GACP,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAGpB"}

package/dist/array/flattenDeep.js

@@ -1,10 +1,13 @@
 /**
- * Recursively flattens a nested array.
+ * Recursively flattens a nested array, at any depth.
  *
- * @template T - The type of elements in the array.
- * @param {T[]} array - The array to flatten.
- * @return {T[]} The flattened array.
+ * @param array - The array to flatten (left untouched).
+ * @returns A new array with every nested element at the top level, typed as
+ *   the innermost element type (`number[][][]` → `number[]`).
+ * @example
+ * flattenDeep([1, [2, [3, [4]]]]); // => [1, 2, 3, 4]
  */
 export function flattenDeep(array) {
-    return array.reduce((acc, val) => Array.isArray(val) ? acc.concat(flattenDeep(val)) : acc.concat(val), []);
+    // 20 is the deepest level the built-in `FlatArray` type can unwind.
+    return array.flat(Infinity);
 }

package/dist/array/index.d.ts

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

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;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

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

package/dist/async/abortReason.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The error to reject with once `signal` is aborted: its `reason` (what was
+ * passed to `abort()`), or a standard `AbortError` when the runtime doesn't
+ * provide one (some React Native polyfills).
+ *
+ * Internal helper — not part of the package's public barrel.
+ */
+export declare function abortReason(signal: AbortSignal): unknown;
+//# sourceMappingURL=abortReason.d.ts.map

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

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

package/dist/async/abortReason.js

@@ -0,0 +1,11 @@
+/**
+ * The error to reject with once `signal` is aborted: its `reason` (what was
+ * passed to `abort()`), or a standard `AbortError` when the runtime doesn't
+ * provide one (some React Native polyfills).
+ *
+ * Internal helper — not part of the package's public barrel.
+ */
+export function abortReason(signal) {
+    return (signal.reason ??
+        new DOMException("This operation was aborted", "AbortError"));
+}

package/dist/async/memoize.d.ts

@@ -1,19 +1,3 @@
-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>;
+/** @deprecated Import from `@forthtilliath/ts-kit/function/memoize` instead. */
+export { memoize, type MemoizedFunction, type MemoizeOptions, } from "../function/memoize.js";
 //# sourceMappingURL=memoize.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/async/memoize.ts"],"names":[],"mappings":"AAGA,gFAAgF;AAChF,OAAO,EACL,OAAO,EACP,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC"}

package/dist/async/memoize.js

@@ -1,25 +1,4 @@
-/**
- * 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;
-}
+// `memoize` isn't async-specific: it moved to `function/`. Re-exported here so
+// the `@forthtilliath/ts-kit/async/memoize` deep import keeps working.
+/** @deprecated Import from `@forthtilliath/ts-kit/function/memoize` instead. */
+export { memoize, } from "../function/memoize.js";

package/dist/async/retry.d.ts

@@ -5,8 +5,18 @@ export interface RetryOptions {
     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. */
+    /** Upper bound for a single delay between two attempts (default: none). */
+    maxDelayMs?: number;
+    /**
+     * Decides whether a failure is worth retrying — return `false` to rethrow
+     * it right away (e.g. a 4xx response that won't fix itself). Retries every
+     * error by default.
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Called with the error and the 1-based attempt number before each retry. */
     onRetry?: (error: unknown, attempt: number) => void;
+    /** Stops retrying (rejecting with the abort reason) once aborted. */
+    signal?: AbortSignal;
 }
 /**
  * Retries an async operation with exponential backoff.
@@ -14,11 +24,13 @@ export interface RetryOptions {
  * @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.
+ * @throws The last error once attempts are exhausted, the first error
+ *   `shouldRetry` declines, or the abort reason once `signal` is aborted.
  * @example
- * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ * const data = await retry(() => fetchJson("/api"), {
  *   attempts: 5,
  *   delayMs: 300,
+ *   shouldRetry: (error) => !(error instanceof HttpError && error.status < 500),
  * });
  */
 export declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;

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

@@ -1 +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"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/async/retry.ts"],"names":[],"mappings":"AAGA,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,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3D,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,qEAAqE;IACrE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;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,CA0BZ"}

package/dist/async/retry.js

@@ -1,3 +1,4 @@
+import { abortReason } from "./abortReason.js";
 import { sleep } from "./sleep.js";
 /**
  * Retries an async operation with exponential backoff.
@@ -5,29 +6,32 @@ import { sleep } from "./sleep.js";
  * @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.
+ * @throws The last error once attempts are exhausted, the first error
+ *   `shouldRetry` declines, or the abort reason once `signal` is aborted.
  * @example
- * const data = await retry(() => fetch("/api").then((r) => r.json()), {
+ * const data = await retry(() => fetchJson("/api"), {
  *   attempts: 5,
  *   delayMs: 300,
+ *   shouldRetry: (error) => !(error instanceof HttpError && error.status < 500),
  * });
  */
 export async function retry(fn, options = {}) {
-    const { attempts = 3, delayMs = 200, backoffFactor = 2, onRetry } = options;
-    let lastError;
+    const { attempts = 3, delayMs = 200, backoffFactor = 2, maxDelayMs = Infinity, shouldRetry, onRetry, signal, } = options;
+    const maxAttempts = Math.max(1, attempts);
     let currentDelay = delayMs;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
+    for (let attempt = 1;; attempt++) {
+        if (signal?.aborted)
+            throw abortReason(signal);
         try {
             return await fn(attempt);
         }
         catch (error) {
-            lastError = error;
+            const canRetry = attempt < maxAttempts && (shouldRetry?.(error, attempt) ?? true);
+            if (!canRetry)
+                throw error;
             onRetry?.(error, attempt);
-            if (attempt < attempts) {
-                await sleep(currentDelay);
-                currentDelay *= backoffFactor;
-            }
+            await sleep(Math.min(currentDelay, maxDelayMs), signal);
+            currentDelay *= backoffFactor;
         }
     }
-    throw lastError;
 }

package/dist/async/sleep.d.ts

@@ -2,8 +2,9 @@
  * Resolves after the given number of milliseconds.
  *
  * @param ms - The delay in milliseconds.
+ * @param signal - Rejects early (with the abort reason) when aborted.
  * @example
  * await sleep(1000); // waits 1 second
  */
-export declare function sleep(ms: number): Promise<void>;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 //# sourceMappingURL=sleep.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/async/sleep.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAIH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBrE"}

package/dist/async/sleep.js

@@ -1,10 +1,31 @@
+import { abortReason } from "./abortReason.js";
 /**
  * Resolves after the given number of milliseconds.
  *
  * @param ms - The delay in milliseconds.
+ * @param signal - Rejects early (with the abort reason) when aborted.
  * @example
  * await sleep(1000); // waits 1 second
  */
-export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+// Rejects with the caller's own abort reason, whatever its type — like
+// `fetch` does.
+/* eslint-disable @typescript-eslint/prefer-promise-reject-errors */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            if (signal)
+                reject(abortReason(signal));
+        };
+        /* eslint-enable @typescript-eslint/prefer-promise-reject-errors */
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }

package/dist/async/withTimeout.d.ts

@@ -6,14 +6,21 @@ export declare class TimeoutError extends Error {
     constructor(message?: string);
 }
 /**
- * Rejects with a {@link TimeoutError} if `promise` has not settled within
+ * Rejects with a {@link TimeoutError} if `operation` has not settled within
  * `ms` milliseconds.
  *
- * @param promise - The promise to race against the timeout.
+ * Pass a function rather than a promise to also **cancel** the operation on
+ * timeout: it receives an `AbortSignal`, aborted (with the `TimeoutError`)
+ * when time runs out — hand it to `fetch` or any abortable API. A plain
+ * promise can only be given up on, not stopped.
+ *
+ * @param operation - The promise to race against the timeout, or a function
+ *   starting the operation with the given `AbortSignal`.
  * @param ms - The timeout in milliseconds.
  * @param message - Optional error message (defaults to a generic one).
  * @example
- * await withTimeout(fetch("/api"), 5000);
+ * await withTimeout((signal) => fetch("/api", { signal }), 5000); // aborted on timeout
+ * await withTimeout(somePromise, 5000); // only stops waiting
  */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+export declare function withTimeout<T>(operation: Promise<T> | ((signal: AbortSignal) => Promise<T>), ms: number, message?: string): Promise<T>;
 //# sourceMappingURL=withTimeout.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"withTimeout.d.ts","sourceRoot":"","sources":["../../src/async/withTimeout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,SAAwB;CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAgBZ"}
+{"version":3,"file":"withTimeout.d.ts","sourceRoot":"","sources":["../../src/async/withTimeout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,SAAwB;CAI5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAC7D,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CA2BZ"}