@forthtilliath/ts-kit 0.9.0 → 0.11.0

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);
     });
 }

package/dist/csv/escapeCsvField.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Escapes a single CSV field per RFC 4180, quoting it only when needed: if it
+ * contains a double quote, the delimiter or a line break, it's wrapped in
+ * double quotes with any internal double quote doubled; otherwise it's
+ * returned as-is.
+ *
+ * Builds rows cell by cell. To serialize whole rows at once, see `toCsv`
+ * (which always quotes, and defaults to `,`).
+ *
+ * @param value - The raw field value.
+ * @param delimiter - The cell separator the field will be joined with.
+ *   Defaults to `";"`, what French-locale Excel expects.
+ * @returns The value, quoted and escaped only if needed.
+ * @example
+ * escapeCsvField("Apple"); // => "Apple"
+ * escapeCsvField("a;b"); // => '"a;b"'
+ * escapeCsvField("a,b", ","); // => '"a,b"'
+ * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ */
+export declare function escapeCsvField(value: string, delimiter?: string): string;
+//# sourceMappingURL=escapeCsvField.d.ts.map

package/dist/csv/escapeCsvField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/csv/escapeCsvField.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAQrE"}

package/dist/csv/escapeCsvField.js

@@ -0,0 +1,28 @@
+/**
+ * Escapes a single CSV field per RFC 4180, quoting it only when needed: if it
+ * contains a double quote, the delimiter or a line break, it's wrapped in
+ * double quotes with any internal double quote doubled; otherwise it's
+ * returned as-is.
+ *
+ * Builds rows cell by cell. To serialize whole rows at once, see `toCsv`
+ * (which always quotes, and defaults to `,`).
+ *
+ * @param value - The raw field value.
+ * @param delimiter - The cell separator the field will be joined with.
+ *   Defaults to `";"`, what French-locale Excel expects.
+ * @returns The value, quoted and escaped only if needed.
+ * @example
+ * escapeCsvField("Apple"); // => "Apple"
+ * escapeCsvField("a;b"); // => '"a;b"'
+ * escapeCsvField("a,b", ","); // => '"a,b"'
+ * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ */
+export function escapeCsvField(value, delimiter = ";") {
+    const needsQuoting = value.includes('"') ||
+        value.includes(delimiter) ||
+        value.includes("\n") ||
+        value.includes("\r");
+    if (!needsQuoting)
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+}

package/dist/csv/formatCsvNumber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export declare function formatCsvNumber(value: number, decimals?: number): string;
+//# sourceMappingURL=formatCsvNumber.d.ts.map

package/dist/csv/formatCsvNumber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatCsvNumber.d.ts","sourceRoot":"","sources":["../../src/csv/formatCsvNumber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAEnE"}

package/dist/csv/formatCsvNumber.js

@@ -0,0 +1,15 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export function formatCsvNumber(value, decimals = 1) {
+    return value.toFixed(decimals).replace(".", ",");
+}

package/dist/csv/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./downloadCsv.js";
+export * from "./escapeCsvField.js";
+export * from "./formatCsvNumber.js";
 export * from "./parseCsvLine.js";
 export * from "./toCsv.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/csv/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/csv/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/csv/index.js

@@ -1,3 +1,5 @@
 export * from "./downloadCsv.js";
+export * from "./escapeCsvField.js";
+export * from "./formatCsvNumber.js";
 export * from "./parseCsvLine.js";
 export * from "./toCsv.js";

package/dist/date/dateInTimeZone.d.ts

@@ -0,0 +1,22 @@
+export interface CalendarDate {
+    year: number;
+    /** 1–12. */
+    month: number;
+    day: number;
+    /** `YYYY-MM-DD`. */
+    iso: string;
+}
+/**
+ * Returns the calendar date of an instant in a given time zone, whatever the
+ * machine's own time zone (e.g. a server running in UTC).
+ *
+ * @param date - The instant (a `Date`, a timestamp in ms or a parsable string).
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @returns `{ year, month, day, iso }`, `month` from 1 to 12.
+ * @throws {RangeError} If the time zone or the date is invalid.
+ * @example
+ * dateInTimeZone("2026-03-14T23:30:00Z", "Europe/Paris");
+ * // => { year: 2026, month: 3, day: 15, iso: "2026-03-15" }
+ */
+export declare function dateInTimeZone(date: Date | number | string, timeZone: string): CalendarDate;
+//# sourceMappingURL=dateInTimeZone.d.ts.map

package/dist/date/dateInTimeZone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateInTimeZone.d.ts","sourceRoot":"","sources":["../../src/date/dateInTimeZone.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC5B,QAAQ,EAAE,MAAM,GACf,YAAY,CASd"}

package/dist/date/dateInTimeZone.js

@@ -0,0 +1,35 @@
+const formatters = new Map();
+function formatter(timeZone) {
+    let result = formatters.get(timeZone);
+    if (!result) {
+        result = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            year: "numeric",
+            month: "numeric",
+            day: "numeric",
+        });
+        formatters.set(timeZone, result);
+    }
+    return result;
+}
+/**
+ * Returns the calendar date of an instant in a given time zone, whatever the
+ * machine's own time zone (e.g. a server running in UTC).
+ *
+ * @param date - The instant (a `Date`, a timestamp in ms or a parsable string).
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @returns `{ year, month, day, iso }`, `month` from 1 to 12.
+ * @throws {RangeError} If the time zone or the date is invalid.
+ * @example
+ * dateInTimeZone("2026-03-14T23:30:00Z", "Europe/Paris");
+ * // => { year: 2026, month: 3, day: 15, iso: "2026-03-15" }
+ */
+export function dateInTimeZone(date, timeZone) {
+    const parts = formatter(timeZone).formatToParts(new Date(date));
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    const year = get("year");
+    const month = get("month");
+    const day = get("day");
+    const iso = `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+    return { year, month, day, iso };
+}

package/dist/date/daysUntil.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Counts the calendar days between today and a date, both taken in a given
+ * time zone: the time of day doesn't matter, only the date on the calendar.
+ *
+ * @param date - The target instant (a `Date`, a timestamp in ms or a parsable string).
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @param now - The reference instant (defaults to now).
+ * @returns `0` today, `1` tomorrow, `-1` yesterday…
+ * @throws {RangeError} If the time zone or the date is invalid.
+ * @example
+ * // It's 2026-03-14 23:00 in Paris
+ * daysUntil("2026-03-15T08:00:00+01:00", "Europe/Paris"); // => 1
+ */
+export declare function daysUntil(date: Date | number | string, timeZone: string, now?: Date): number;
+//# sourceMappingURL=daysUntil.d.ts.map

package/dist/date/daysUntil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daysUntil.d.ts","sourceRoot":"","sources":["../../src/date/daysUntil.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC5B,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACrB,MAAM,CAER"}

package/dist/date/daysUntil.js

@@ -0,0 +1,22 @@
+import { dateInTimeZone } from "./dateInTimeZone.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+function dayNumber(date, timeZone) {
+    const { year, month, day } = dateInTimeZone(date, timeZone);
+    return Date.UTC(year, month - 1, day) / DAY_MS;
+}
+/**
+ * Counts the calendar days between today and a date, both taken in a given
+ * time zone: the time of day doesn't matter, only the date on the calendar.
+ *
+ * @param date - The target instant (a `Date`, a timestamp in ms or a parsable string).
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @param now - The reference instant (defaults to now).
+ * @returns `0` today, `1` tomorrow, `-1` yesterday…
+ * @throws {RangeError} If the time zone or the date is invalid.
+ * @example
+ * // It's 2026-03-14 23:00 in Paris
+ * daysUntil("2026-03-15T08:00:00+01:00", "Europe/Paris"); // => 1
+ */
+export function daysUntil(date, timeZone, now = new Date()) {
+    return dayNumber(date, timeZone) - dayNumber(now, timeZone);
+}

package/dist/date/index.d.ts

@@ -1,5 +1,8 @@
+export * from "./dateInTimeZone.js";
+export * from "./daysUntil.js";
 export * from "./formatRelativeTime.js";
 export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
 export * from "./startOfDay.js";
+export * from "./todayInTimeZone.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/date/index.js

@@ -1,4 +1,7 @@
+export * from "./dateInTimeZone.js";
+export * from "./daysUntil.js";
 export * from "./formatRelativeTime.js";
 export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
 export * from "./startOfDay.js";
+export * from "./todayInTimeZone.js";

package/dist/date/todayInTimeZone.d.ts

@@ -0,0 +1,14 @@
+import type { CalendarDate } from "./dateInTimeZone.js";
+/**
+ * Returns today's calendar date in a given time zone — on a server running in
+ * UTC, `new Date()` is still "yesterday" in Paris between midnight and 1–2 am.
+ *
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @param now - The reference instant (defaults to now).
+ * @returns `{ year, month, day, iso }`, `month` from 1 to 12.
+ * @throws {RangeError} If the time zone is invalid.
+ * @example
+ * todayInTimeZone("Europe/Paris").iso; // => "2026-09-30"
+ */
+export declare function todayInTimeZone(timeZone: string, now?: Date): CalendarDate;
+//# sourceMappingURL=todayInTimeZone.d.ts.map

package/dist/date/todayInTimeZone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todayInTimeZone.d.ts","sourceRoot":"","sources":["../../src/date/todayInTimeZone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACrB,YAAY,CAEd"}

package/dist/date/todayInTimeZone.js

@@ -0,0 +1,15 @@
+import { dateInTimeZone } from "./dateInTimeZone.js";
+/**
+ * Returns today's calendar date in a given time zone — on a server running in
+ * UTC, `new Date()` is still "yesterday" in Paris between midnight and 1–2 am.
+ *
+ * @param timeZone - An IANA time zone, e.g. `"Europe/Paris"`.
+ * @param now - The reference instant (defaults to now).
+ * @returns `{ year, month, day, iso }`, `month` from 1 to 12.
+ * @throws {RangeError} If the time zone is invalid.
+ * @example
+ * todayInTimeZone("Europe/Paris").iso; // => "2026-09-30"
+ */
+export function todayInTimeZone(timeZone, now = new Date()) {
+    return dateInTimeZone(now, timeZone);
+}

package/dist/files/downloadText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"downloadText.d.ts","sourceRoot":"","sources":["../../src/files/downloadText.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAcjE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,SAAe,GACtB,IAAI,CAcN"}
+{"version":3,"file":"downloadText.d.ts","sourceRoot":"","sources":["../../src/files/downloadText.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAcjE;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,SAAe,GACtB,IAAI,CAgBN"}

package/dist/files/downloadText.js

@@ -12,6 +12,12 @@ export function downloadText(filename, text) {
     element.click();
     document.body.removeChild(element);
 }
+/**
+ * How long the object URL stays valid after the click. Revoking it right
+ * away can cancel the download in Firefox and Safari, which start it
+ * asynchronously; FileSaver.js uses the same 40 s delay.
+ */
+const REVOKE_DELAY_MS = 40_000;
 /**
  * Downloads a text blob as a file.
  * @param filename The filename to save to.
@@ -26,6 +32,8 @@ export function downloadTextBlob(filename, text, mimeType = "text/plain") {
     a.style.setProperty("display", "none");
     document.body.appendChild(a);
     a.click();
-    URL.revokeObjectURL(url);
     document.body.removeChild(a);
+    setTimeout(() => {
+        URL.revokeObjectURL(url);
+    }, REVOKE_DELAY_MS);
 }

package/dist/files/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./downloadText.js";
+export * from "./sanitizeFileName.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC"}

package/dist/files/index.js

@@ -1 +1,2 @@
 export * from "./downloadText.js";
+export * from "./sanitizeFileName.js";

package/dist/files/sanitizeFileName.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Makes a string safe to use as a file name: characters forbidden on Windows
+ * (`\ / : * ? " < > |`) become hyphens, whitespace runs collapse into a single
+ * space and the result is trimmed. Also prevents a `/` from creating a
+ * sub-folder inside a ZIP archive.
+ *
+ * @param name - The raw file name.
+ * @returns The sanitized file name.
+ * @example
+ * sanitizeFileName("AC/DC: Live?"); // => "AC-DC- Live-"
+ * sanitizeFileName("  My   file "); // => "My file"
+ */
+export declare function sanitizeFileName(name: string): string;
+//# sourceMappingURL=sanitizeFileName.d.ts.map

package/dist/files/sanitizeFileName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeFileName.d.ts","sourceRoot":"","sources":["../../src/files/sanitizeFileName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD"}

package/dist/files/sanitizeFileName.js

@@ -0,0 +1,18 @@
+/**
+ * Makes a string safe to use as a file name: characters forbidden on Windows
+ * (`\ / : * ? " < > |`) become hyphens, whitespace runs collapse into a single
+ * space and the result is trimmed. Also prevents a `/` from creating a
+ * sub-folder inside a ZIP archive.
+ *
+ * @param name - The raw file name.
+ * @returns The sanitized file name.
+ * @example
+ * sanitizeFileName("AC/DC: Live?"); // => "AC-DC- Live-"
+ * sanitizeFileName("  My   file "); // => "My file"
+ */
+export function sanitizeFileName(name) {
+    return name
+        .replace(/[\\/:*?"<>|]/g, "-")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/function/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./memoize.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/function/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/function/index.js

@@ -0,0 +1 @@
+export * from "./memoize.js";

package/dist/function/memoize.d.ts

@@ -0,0 +1,34 @@
+export interface MemoizedFunction<Args extends unknown[], R> {
+    (...args: Args): R;
+    /** The underlying cache, exposed for inspection or manual clearing. */
+    cache: Map<string, R>;
+}
+export interface MemoizeOptions<Args extends unknown[]> {
+    /** Computes the cache key for a set of arguments (defaults to `JSON.stringify`). */
+    getKey?: (...args: Args) => string;
+    /**
+     * Max number of cached results; beyond it, the least recently used one is
+     * evicted. Unbounded by default — set it for a long-lived function called
+     * with many distinct arguments.
+     */
+    maxSize?: number;
+}
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * A returned promise that rejects is evicted from the cache, so a failed
+ * async call is retried on the next invocation instead of failing forever.
+ *
+ * @param fn - The function to memoize.
+ * @param getKeyOrOptions - A key function, or `{ getKey, maxSize }`.
+ * @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
+ *
+ * const getUser = memoize(fetchUser, { maxSize: 100 });
+ */
+export declare function memoize<Args extends unknown[], R>(fn: (...args: Args) => R, getKeyOrOptions?: ((...args: Args) => string) | MemoizeOptions<Args>): MemoizedFunction<Args, R>;
+//# sourceMappingURL=memoize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/function/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,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,OAAO,EAAE;IACpD,oFAAoF;IACpF,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EAC/C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,EACxB,eAAe,GAAE,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAM,GACvE,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,CAqC3B"}

package/dist/function/memoize.js

@@ -0,0 +1,50 @@
+/**
+ * Caches the result of `fn` per argument tuple (JSON-stringified by
+ * default).
+ *
+ * A returned promise that rejects is evicted from the cache, so a failed
+ * async call is retried on the next invocation instead of failing forever.
+ *
+ * @param fn - The function to memoize.
+ * @param getKeyOrOptions - A key function, or `{ getKey, maxSize }`.
+ * @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
+ *
+ * const getUser = memoize(fetchUser, { maxSize: 100 });
+ */
+export function memoize(fn, getKeyOrOptions = {}) {
+    const { getKey = (...args) => JSON.stringify(args), maxSize = Infinity, } = typeof getKeyOrOptions === "function"
+        ? { getKey: getKeyOrOptions }
+        : getKeyOrOptions;
+    const cache = new Map();
+    const memoized = ((...args) => {
+        const key = getKey(...args);
+        if (cache.has(key)) {
+            const cached = cache.get(key);
+            // Re-insert to mark it as the most recently used.
+            cache.delete(key);
+            cache.set(key, cached);
+            return cached;
+        }
+        const result = fn(...args);
+        cache.set(key, result);
+        if (cache.size > maxSize) {
+            const oldestKey = cache.keys().next().value;
+            if (oldestKey !== undefined)
+                cache.delete(oldestKey);
+        }
+        if (result instanceof Promise) {
+            result.catch(() => {
+                // Only if it's still this call's promise (not a newer one).
+                if (cache.get(key) === result)
+                    cache.delete(key);
+            });
+        }
+        return result;
+    });
+    memoized.cache = cache;
+    return memoized;
+}

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export * from "./classes/index.js";
 export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
+export * from "./function/index.js";
 export * from "./id/index.js";
 export * from "./image/index.js";
 export * from "./markdown/index.js";
-export * from "./maths/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
 export * from "./string/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -9,10 +9,10 @@ export * from "./classes/index.js";
 export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
+export * from "./function/index.js";
 export * from "./id/index.js";
 export * from "./image/index.js";
 export * from "./markdown/index.js";
-export * from "./maths/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
 export * from "./string/index.js";

package/dist/maths/average.d.ts

@@ -1,8 +1,3 @@
-/**
- * Calculates the average of all numbers in an array.
- *
- * @param {number[]} arr - The array of numbers to average.
- * @return {number} The average of all numbers in the array.
- */
-export declare function avg(arr: number[]): number;
+/** @deprecated Import from `@forthtilliath/ts-kit/number/average` instead. */
+export { avg } from "../number/average.js";
 //# sourceMappingURL=average.d.ts.map

package/dist/maths/average.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"average.d.ts","sourceRoot":"","sources":["../../src/maths/average.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzC"}
+{"version":3,"file":"average.d.ts","sourceRoot":"","sources":["../../src/maths/average.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/maths/average.js

@@ -1,10 +1,4 @@
-import { sum } from "./sum.js";
-/**
- * Calculates the average of all numbers in an array.
- *
- * @param {number[]} arr - The array of numbers to average.
- * @return {number} The average of all numbers in the array.
- */
-export function avg(arr) {
-    return sum(arr) / arr.length;
-}
+// `maths/` duplicated `number/`: `avg` moved there. Re-exported so the
+// `@forthtilliath/ts-kit/maths/average` deep import keeps working.
+/** @deprecated Import from `@forthtilliath/ts-kit/number/average` instead. */
+export { avg } from "../number/average.js";

package/dist/maths/sum.d.ts

@@ -1,8 +1,3 @@
-/**
- * Calculates the sum of all numbers in an array.
- *
- * @param {number[]} arr - The array of numbers to sum.
- * @return {number} The sum of all numbers in the array.
- */
-export declare function sum(arr: number[]): number;
+/** @deprecated Import from `@forthtilliath/ts-kit/number/sum` instead. */
+export { sum } from "../number/sum.js";
 //# sourceMappingURL=sum.d.ts.map

package/dist/maths/sum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../src/maths/sum.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzC"}
+{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../src/maths/sum.ts"],"names":[],"mappings":"AAGA,0EAA0E;AAC1E,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/maths/sum.js

@@ -1,9 +1,4 @@
-/**
- * Calculates the sum of all numbers in an array.
- *
- * @param {number[]} arr - The array of numbers to sum.
- * @return {number} The sum of all numbers in the array.
- */
-export function sum(arr) {
-    return arr.reduce((total, n) => total + n, 0);
-}
+// `maths/` duplicated `number/`: `sum` moved there. Re-exported so the
+// `@forthtilliath/ts-kit/maths/sum` deep import keeps working.
+/** @deprecated Import from `@forthtilliath/ts-kit/number/sum` instead. */
+export { sum } from "../number/sum.js";

package/dist/number/average.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calculates the average (arithmetic mean) of all numbers in an array.
+ *
+ * @param arr - The numbers to average.
+ * @returns The average, or `NaN` for an empty array — there's no meaningful
+ *   average of nothing, and `0` would be indistinguishable from a real one
+ *   (same as lodash's `mean`). Check `arr.length` first if you need a fallback.
+ * @example
+ * avg([1, 2, 3]); // => 2
+ * avg([]); // => NaN
+ */
+export declare function avg(arr: readonly number[]): number;
+//# sourceMappingURL=average.d.ts.map