@forthtilliath/ts-kit 0.10.0 → 0.12.0

package/README.md

@@ -33,6 +33,18 @@ 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.
@@ -40,7 +52,8 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
   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.
+- `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).
@@ -50,6 +63,8 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
   `query`: earlier match position first, then shorter name — for a
   search-as-you-type list.
+- `shuffle(array, random?)` — shuffled copy (Fisher–Yates); `random`
+  (default `Math.random`) can be swapped for a seeded generator in tests.
 - `sortUpcomingFirst(items, getDates, { now? })` — upcoming items first
   (nearest first), then past ones (most recent first), undated last — for a
   list of events. An item may carry several dates: it stays upcoming while
@@ -60,16 +75,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`
 
@@ -97,30 +119,82 @@ 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.
 - `isSameDay(a, b)` — checks whether two dates fall on the same local day.
+- `parseIsoDate(iso)` — a `YYYY-MM-DD` calendar date as **local** midnight
+  (`new Date("2026-03-14")` is UTC midnight, the previous day in the Americas).
+- `parseSqliteDate(value)` — reads a SQLite `current_timestamp` value
+  (`"2026-10-09 19:46:00"`, UTC without a zone marker) as **UTC** instead of
+  local time; full ISO strings are read as they are.
+- `mondayFirstWeekday(date)` — weekday index with Monday = `0` … Sunday = `6`,
+  from a `Date` or a `YYYY-MM-DD` string; offsets a Monday-first month grid.
 - `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
   time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
+- `formatRecentDate(date, { now?, locale? })` — a past moment as a "last
+  saved…" line reads best: `"aujourd'hui à 21:42"`, `"hier à 08:05"`, then
+  `"le 11 octobre 2026"` (`locale: "en"`: `"today at…"`, `"on October 11, 2026"`).
 - `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).
+- `formatFileTimestamp(date?, { seconds?, separator? })` — compact **local**
+  timestamp for file names, `"20261008-0902"` by default (`toISOString()` is
+  UTC and its `:` is rejected by Windows); names sort chronologically.
+
+### `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.
 
+### `ics`
+
+Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
+
+- `escapeIcsText(text)` — escapes a TEXT value (`SUMMARY`, `DESCRIPTION`…):
+  `\`, `;`, `,` and line breaks.
+- `foldIcsLine(line, maxOctets?)` — folds a content line past 75 **octets**
+  (UTF-8 bytes, not characters) without splitting a character.
+- `toIcsDate(isoDate)` — `"2026-07-14"` → `"20260714"`, for all-day events.
+- `toIcsDateTime(isoDate, "HH:MM")` — floating local date-time,
+  `"20260714T063000"`.
+- `icsTimestamp(date?)` — UTC date-time for `DTSTAMP`, `"20260714T080509Z"`.
+
 ### `id`
 
 - `randomId()` — `crypto.randomUUID()` with fallbacks for older/insecure
@@ -141,22 +215,21 @@ 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`
 
 - `pick(obj, keys)` / `omit(obj, keys)` — keep or drop a set of keys.
@@ -174,15 +247,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/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

@@ -4,6 +4,7 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.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,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"}
+{"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,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -4,5 +4,6 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.js";

package/dist/array/shuffle.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns a shuffled copy of an array (Fisher–Yates), leaving the original
+ * untouched.
+ *
+ * @param array - The array to shuffle.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns A new array holding the same elements in random order.
+ * @example
+ * shuffle([1, 2, 3, 4]); // => e.g. [3, 1, 4, 2]
+ * shuffle(["a", "b", "c"], () => 0); // => ["b", "c", "a"]
+ */
+export declare function shuffle<T>(array: readonly T[], random?: () => number): T[];
+//# sourceMappingURL=shuffle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shuffle.d.ts","sourceRoot":"","sources":["../../src/array/shuffle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,GAAE,MAAM,MAAoB,GACjC,CAAC,EAAE,CAOL"}

package/dist/array/shuffle.js

@@ -0,0 +1,20 @@
+/**
+ * Returns a shuffled copy of an array (Fisher–Yates), leaving the original
+ * untouched.
+ *
+ * @param array - The array to shuffle.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns A new array holding the same elements in random order.
+ * @example
+ * shuffle([1, 2, 3, 4]); // => e.g. [3, 1, 4, 2]
+ * shuffle(["a", "b", "c"], () => 0); // => ["b", "c", "a"]
+ */
+export function shuffle(array, random = Math.random) {
+    const result = [...array];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}

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"}

package/dist/async/withTimeout.js

@@ -9,26 +9,48 @@ export class TimeoutError extends Error {
     }
 }
 /**
- * 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 function withTimeout(promise, ms, message) {
+export function withTimeout(operation, ms, message) {
+    const controller = new AbortController();
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
-            reject(new TimeoutError(message));
+            const error = new TimeoutError(message);
+            controller.abort(error);
+            reject(error);
         }, ms);
+        const fail = (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        let promise;
+        try {
+            promise =
+                typeof operation === "function"
+                    ? operation(controller.signal)
+                    : operation;
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
         promise.then((value) => {
             clearTimeout(timer);
             resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
+        }, fail);
     });
 }