@forthtilliath/ts-kit 0.8.0 → 0.10.0

package/README.md

@@ -36,6 +36,10 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 ### `array`
 
 - `chunk(array, size)` — splits an array into chunks of a given size.
+- `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.
 - `getMostRecentIds(rows, limit?)` — most recently occurring distinct ids
   (`{ id, occurredAt }[]`), most recent first, deduplicated, limited
@@ -46,6 +50,10 @@ 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.
+- `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
+  one is ahead (ranked by its next date), then is ranked by its latest date.
 - `swapItems(items, i, j)` — copy of `items` with the elements at `i` and `j`
   swapped (e.g. moving an item up/down) — a plain copy if either position is
   out of bounds.
@@ -110,6 +118,8 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
   via a `data:` URI.
 - `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
   (better for larger content).
+- `sanitizeFileName(name)` — replaces characters forbidden in file names
+  (`\ / : * ? " < > |`) with hyphens, collapses whitespace and trims.
 
 ### `id`
 
@@ -144,6 +154,8 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `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.
 
 ### `object`
 

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/index.d.ts

@@ -1,7 +1,9 @@
 export * from "./chunk.js";
+export * from "./createColumnStorage.js";
 export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.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,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,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,6 +1,8 @@
 export * from "./chunk.js";
+export * from "./createColumnStorage.js";
 export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.js";

package/dist/array/sortUpcomingFirst.d.ts

@@ -0,0 +1,30 @@
+export type DateInput = Date | string | number;
+export interface SortUpcomingFirstOptions {
+    /** Instant separating upcoming from past items. Defaults to now. */
+    now?: DateInput;
+}
+/**
+ * Sorts items around a reference instant: upcoming items first, nearest
+ * first, then past items, most recent first — the usual order for a list of
+ * events (concerts, meetings, bookings…). Items without a valid date go last.
+ * Ties keep their original order.
+ *
+ * An item may carry several dates (e.g. an event with several sessions): it
+ * stays upcoming as long as one of its dates is still ahead and is ranked by
+ * its next date; once all are past, it is ranked by its latest date.
+ *
+ * @param items - The items to sort (left untouched).
+ * @param getDates - Reads the date(s) off an item (`Date`, ISO string or
+ *   timestamp); `null`/`undefined` or invalid dates are ignored.
+ * @param options - `now`: the reference instant (a date equal to it counts as
+ *   upcoming). Defaults to now.
+ * @returns A sorted copy of `items`.
+ * @example
+ * sortUpcomingFirst(
+ *   [{ d: "2026-01-01" }, { d: "2026-12-01" }, { d: "2026-03-01" }, { d: "2026-10-01" }],
+ *   (item) => item.d,
+ *   { now: "2026-06-01" },
+ * ); // => 2026-10-01, 2026-12-01, 2026-03-01, 2026-01-01
+ */
+export declare function sortUpcomingFirst<T>(items: readonly T[], getDates: (item: T) => DateInput | readonly DateInput[] | null | undefined, { now }?: SortUpcomingFirstOptions): T[];
+//# sourceMappingURL=sortUpcomingFirst.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sortUpcomingFirst.d.ts","sourceRoot":"","sources":["../../src/array/sortUpcomingFirst.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,GAAG,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,EAC1E,EAAE,GAAgB,EAAE,GAAE,wBAA6B,GAClD,CAAC,EAAE,CAaL"}

package/dist/array/sortUpcomingFirst.js

@@ -0,0 +1,51 @@
+// Upcoming items first, then past items, then items without a usable date.
+const UPCOMING = 0;
+const PAST = 1;
+const UNDATED = 2;
+function toTimes(dates) {
+    if (dates == null)
+        return [];
+    const list = Array.isArray(dates)
+        ? dates
+        : [dates];
+    return list
+        .map((date) => new Date(date).getTime())
+        .filter((time) => !Number.isNaN(time));
+}
+/**
+ * Sorts items around a reference instant: upcoming items first, nearest
+ * first, then past items, most recent first — the usual order for a list of
+ * events (concerts, meetings, bookings…). Items without a valid date go last.
+ * Ties keep their original order.
+ *
+ * An item may carry several dates (e.g. an event with several sessions): it
+ * stays upcoming as long as one of its dates is still ahead and is ranked by
+ * its next date; once all are past, it is ranked by its latest date.
+ *
+ * @param items - The items to sort (left untouched).
+ * @param getDates - Reads the date(s) off an item (`Date`, ISO string or
+ *   timestamp); `null`/`undefined` or invalid dates are ignored.
+ * @param options - `now`: the reference instant (a date equal to it counts as
+ *   upcoming). Defaults to now.
+ * @returns A sorted copy of `items`.
+ * @example
+ * sortUpcomingFirst(
+ *   [{ d: "2026-01-01" }, { d: "2026-12-01" }, { d: "2026-03-01" }, { d: "2026-10-01" }],
+ *   (item) => item.d,
+ *   { now: "2026-06-01" },
+ * ); // => 2026-10-01, 2026-12-01, 2026-03-01, 2026-01-01
+ */
+export function sortUpcomingFirst(items, getDates, { now = Date.now() } = {}) {
+    const nowTime = new Date(now).getTime();
+    const keyed = items.map((item) => {
+        const times = toTimes(getDates(item));
+        const upcoming = times.filter((time) => time >= nowTime);
+        if (upcoming.length > 0)
+            return { item, group: UPCOMING, key: Math.min(...upcoming) };
+        if (times.length > 0)
+            return { item, group: PAST, key: -Math.max(...times) };
+        return { item, group: UNDATED, key: 0 };
+    });
+    keyed.sort((a, b) => a.group - b.group || a.key - b.key);
+    return keyed.map((k) => k.item);
+}

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/number/index.d.ts

@@ -2,5 +2,6 @@ export * from "./clamp.js";
 export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
+export * from "./padNumber.js";
 export * from "./round.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,YAAY,CAAC"}
+{"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"}

package/dist/number/index.js

@@ -2,4 +2,5 @@ export * from "./clamp.js";
 export * from "./formatBytes.js";
 export * from "./formatCsvNumber.js";
 export * from "./formatDuration.js";
+export * from "./padNumber.js";
 export * from "./round.js";

package/dist/number/padNumber.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Left-pads a number with zeros so that file names sort correctly in a file
+ * explorer (`"01"`, `"02"`, …, `"10"`). The width adapts to `total` (3 digits
+ * from 100 items on) and never goes below `minWidth`.
+ *
+ * @param n - The number to pad.
+ * @param total - The total count, used to compute the width.
+ * @param minWidth - The minimum width (default: 2).
+ * @returns The zero-padded number.
+ * @example
+ * padNumber(1, 12); // => "01"
+ * padNumber(7, 120); // => "007"
+ */
+export declare function padNumber(n: number, total: number, minWidth?: number): string;
+//# sourceMappingURL=padNumber.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"padNumber.d.ts","sourceRoot":"","sources":["../../src/number/padNumber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAExE"}

package/dist/number/padNumber.js

@@ -0,0 +1,16 @@
+/**
+ * Left-pads a number with zeros so that file names sort correctly in a file
+ * explorer (`"01"`, `"02"`, …, `"10"`). The width adapts to `total` (3 digits
+ * from 100 items on) and never goes below `minWidth`.
+ *
+ * @param n - The number to pad.
+ * @param total - The total count, used to compute the width.
+ * @param minWidth - The minimum width (default: 2).
+ * @returns The zero-padded number.
+ * @example
+ * padNumber(1, 12); // => "01"
+ * padNumber(7, 120); // => "007"
+ */
+export function padNumber(n, total, minWidth = 2) {
+    return String(n).padStart(Math.max(minWidth, String(total).length), "0");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {