@forthtilliath/ts-kit 0.9.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
@@ -114,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`
 
@@ -148,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,4 +1,5 @@
 export * from "./chunk.js";
+export * from "./createColumnStorage.js";
 export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";

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

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

package/dist/array/index.js

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

package/dist/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.9.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {