@forthtilliath/ts-kit 0.10.0 → 0.11.0

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/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

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

@@ -0,0 +1 @@
+{"version":3,"file":"average.d.ts","sourceRoot":"","sources":["../../src/number/average.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElD"}

package/dist/number/average.js

@@ -0,0 +1,15 @@
+import { sum } from "./sum.js";
+/**
+ * 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 function avg(arr) {
+    return sum(arr) / arr.length;
+}

package/dist/number/formatBytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatBytes.d.ts","sourceRoot":"","sources":["../../src/number/formatBytes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAW/D"}
+{"version":3,"file":"formatBytes.d.ts","sourceRoot":"","sources":["../../src/number/formatBytes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAkB/D"}

package/dist/number/formatBytes.js

@@ -12,8 +12,12 @@ const UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
 export function formatBytes(bytes, decimals = 2) {
     if (bytes === 0)
         return "0 B";
-    const exponent = Math.min(Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024)), UNITS.length - 1);
+    // Clamped at 0 so a fraction of a byte stays in "B" (a negative exponent
+    // has no unit).
+    const exponent = Math.max(0, Math.min(Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024)), UNITS.length - 1));
     const value = bytes / 1024 ** exponent;
-    const formatted = value.toFixed(Math.max(decimals, 0)).replace(/\.?0+$/, "");
+    // Round-tripping through Number drops trailing decimal zeros ("1.50" →
+    // "1.5") without touching the integer part ("100" stays "100").
+    const formatted = String(Number(value.toFixed(Math.max(decimals, 0))));
     return `${formatted} ${UNITS[exponent]}`;
 }

package/dist/number/formatCsvNumber.d.ts

@@ -1,14 +1,3 @@
-/**
- * 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;
+/** @deprecated Import from `@forthtilliath/ts-kit/csv/formatCsvNumber` instead. */
+export { formatCsvNumber } from "../csv/formatCsvNumber.js";
 //# sourceMappingURL=formatCsvNumber.d.ts.map

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

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

package/dist/number/formatCsvNumber.js

@@ -1,15 +1,4 @@
-/**
- * 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(".", ",");
-}
+// CSV helpers now live together in `csv/`. Re-exported so the
+// `@forthtilliath/ts-kit/number/formatCsvNumber` deep import keeps working.
+/** @deprecated Import from `@forthtilliath/ts-kit/csv/formatCsvNumber` instead. */
+export { formatCsvNumber } from "../csv/formatCsvNumber.js";

package/dist/number/index.d.ts

@@ -1,7 +1,9 @@
+export * from "./average.js";
 export * from "./clamp.js";
 export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
 export * from "./padNumber.js";
 export * from "./round.js";
+export * from "./sum.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/number/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/number/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}

package/dist/number/index.js

@@ -1,6 +1,8 @@
+export * from "./average.js";
 export * from "./clamp.js";
 export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
 export * from "./padNumber.js";
 export * from "./round.js";
+export * from "./sum.js";

package/dist/number/sum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ *
+ * @param arr - The numbers to add up.
+ * @returns Their sum, `0` for an empty array.
+ * @example
+ * sum([1, 2, 3]); // => 6
+ */
+export declare function sum(arr: readonly number[]): number;
+//# sourceMappingURL=sum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../src/number/sum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElD"}

package/dist/number/sum.js

@@ -0,0 +1,11 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ *
+ * @param arr - The numbers to add up.
+ * @returns Their sum, `0` for an empty array.
+ * @example
+ * sum([1, 2, 3]); // => 6
+ */
+export function sum(arr) {
+    return arr.reduce((total, n) => total + n, 0);
+}

package/dist/object/deepEqual.d.ts

@@ -1,12 +1,18 @@
 /**
  * Recursively compares two values for structural equality.
  *
+ * Both values must share the same prototype (a plain object never equals an
+ * array or a class instance). `Date`s are compared by timestamp, `RegExp`s by
+ * source and flags, `Map`s by keys (identity) then values (deeply), and
+ * `Set`s by membership (identity, like `Set.prototype.has`).
+ *
  * @param a - The first value.
  * @param b - The second value.
  * @returns `true` if `a` and `b` are deeply equal.
  * @example
  * deepEqual({ a: [1, 2] }, { a: [1, 2] }); // => true
  * deepEqual({ a: 1 }, { a: 2 }); // => false
+ * deepEqual(new Date(0), new Date(0)); // => true
  */
 export declare function deepEqual(a: unknown, b: unknown): boolean;
 //# sourceMappingURL=deepEqual.d.ts.map

package/dist/object/deepEqual.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepEqual.d.ts","sourceRoot":"","sources":["../../src/object/deepEqual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAwBzD"}
+{"version":3,"file":"deepEqual.d.ts","sourceRoot":"","sources":["../../src/object/deepEqual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAwDzD"}