@forthtilliath/ts-kit 0.6.0 → 0.8.0

package/README.md

@@ -46,6 +46,9 @@ 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.
+- `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.
 
 ### `async`
 
@@ -81,6 +84,16 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
     rarely needed since `FArray` is already assignable to `T[]` anywhere a
     plain array is expected, but useful when the runtime type matters too.
 
+### `csv`
+
+- `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`.
+- `downloadCsv(filename, content)` — browser download as `text/csv`, with a
+  UTF-8 BOM so Excel reads accented characters.
+
 ### `date`
 
 - `startOfDay(date?)` — returns a new `Date` at local midnight.

package/dist/array/index.d.ts

@@ -3,4 +3,5 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.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"}
+{"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"}

package/dist/array/index.js

@@ -3,3 +3,4 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./swapItems.js";

package/dist/array/swapItems.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns a copy of `items` with the elements at positions `i` and `j`
+ * swapped (e.g. moving an item up or down in a reorderable list). Never
+ * mutates `items`, and stays sound under `noUncheckedIndexedAccess`.
+ *
+ * @param items - The array to copy.
+ * @param i - The position of the first element.
+ * @param j - The position of the second element.
+ * @returns A new array with both elements swapped, or a plain copy if either
+ * position is out of bounds.
+ * @example
+ * swapItems(["a", "b", "c"], 0, 2); // => ["c", "b", "a"]
+ * swapItems(["a", "b", "c"], 0, 5); // => ["a", "b", "c"]
+ */
+export declare function swapItems<T>(items: readonly T[], i: number, j: number): T[];
+//# sourceMappingURL=swapItems.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swapItems.d.ts","sourceRoot":"","sources":["../../src/array/swapItems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAQ3E"}

package/dist/array/swapItems.js

@@ -0,0 +1,24 @@
+/**
+ * Returns a copy of `items` with the elements at positions `i` and `j`
+ * swapped (e.g. moving an item up or down in a reorderable list). Never
+ * mutates `items`, and stays sound under `noUncheckedIndexedAccess`.
+ *
+ * @param items - The array to copy.
+ * @param i - The position of the first element.
+ * @param j - The position of the second element.
+ * @returns A new array with both elements swapped, or a plain copy if either
+ * position is out of bounds.
+ * @example
+ * swapItems(["a", "b", "c"], 0, 2); // => ["c", "b", "a"]
+ * swapItems(["a", "b", "c"], 0, 5); // => ["a", "b", "c"]
+ */
+export function swapItems(items, i, j) {
+    const next = [...items];
+    const a = next[i];
+    const b = next[j];
+    if (a === undefined || b === undefined)
+        return next;
+    next[i] = b;
+    next[j] = a;
+    return next;
+}

package/dist/csv/downloadCsv.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Downloads CSV content as a file. Prepends a UTF-8 byte order mark so Excel
+ * reads accented characters correctly instead of guessing a legacy encoding.
+ *
+ * @param filename - The filename to save to.
+ * @param content - The CSV content (see `toCsv`).
+ * @example
+ * downloadCsv("members.csv", toCsv([["name"], ["Zoé"]]));
+ */
+export declare function downloadCsv(filename: string, content: string): void;
+//# sourceMappingURL=downloadCsv.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"downloadCsv.d.ts","sourceRoot":"","sources":["../../src/csv/downloadCsv.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnE"}

package/dist/csv/downloadCsv.js

@@ -0,0 +1,13 @@
+import { downloadTextBlob } from "../files/downloadText.js";
+/**
+ * Downloads CSV content as a file. Prepends a UTF-8 byte order mark so Excel
+ * reads accented characters correctly instead of guessing a legacy encoding.
+ *
+ * @param filename - The filename to save to.
+ * @param content - The CSV content (see `toCsv`).
+ * @example
+ * downloadCsv("members.csv", toCsv([["name"], ["Zoé"]]));
+ */
+export function downloadCsv(filename, content) {
+    downloadTextBlob(filename, "" + content, "text/csv");
+}

package/dist/csv/index.d.ts

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

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

@@ -0,0 +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"}

package/dist/csv/index.js

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

package/dist/csv/parseCsvLine.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Splits a single CSV line into its cells. A cell wrapped in double quotes may
+ * contain the delimiter, and a doubled double quote (`""`) inside it stands for
+ * a literal one. Every cell is trimmed.
+ *
+ * @param line - One line of CSV (no line break).
+ * @param delimiter - The cell separator. Defaults to `","`.
+ * @returns The cells of the line, unquoted and trimmed.
+ * @example
+ * parseCsvLine('a, "b, c" ,d'); // => ["a", "b, c", "d"]
+ * parseCsvLine('"He said ""hi"""'); // => ['He said "hi"']
+ * parseCsvLine("a;b", ";"); // => ["a", "b"]
+ */
+export declare function parseCsvLine(line: string, delimiter?: string): string[];
+//# sourceMappingURL=parseCsvLine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parseCsvLine.d.ts","sourceRoot":"","sources":["../../src/csv/parseCsvLine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,MAAM,EAAE,CAoBpE"}

package/dist/csv/parseCsvLine.js

@@ -0,0 +1,38 @@
+/**
+ * Splits a single CSV line into its cells. A cell wrapped in double quotes may
+ * contain the delimiter, and a doubled double quote (`""`) inside it stands for
+ * a literal one. Every cell is trimmed.
+ *
+ * @param line - One line of CSV (no line break).
+ * @param delimiter - The cell separator. Defaults to `","`.
+ * @returns The cells of the line, unquoted and trimmed.
+ * @example
+ * parseCsvLine('a, "b, c" ,d'); // => ["a", "b, c", "d"]
+ * parseCsvLine('"He said ""hi"""'); // => ['He said "hi"']
+ * parseCsvLine("a;b", ";"); // => ["a", "b"]
+ */
+export function parseCsvLine(line, delimiter = ",") {
+    const cells = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line.charAt(i);
+        if (ch === '"') {
+            if (inQuotes && line.charAt(i + 1) === '"') {
+                current += '"';
+                i++;
+            }
+            else
+                inQuotes = !inQuotes;
+        }
+        else if (ch === delimiter && !inQuotes) {
+            cells.push(current.trim());
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    cells.push(current.trim());
+    return cells;
+}

package/dist/csv/toCsv.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Serializes rows to CSV. Every cell is wrapped in double quotes (any internal
+ * double quote doubled), so delimiters and line breaks inside a cell are safe.
+ * Rows are joined with `\n`.
+ *
+ * @param rows - The rows to serialize, header row included if any.
+ * @param delimiter - The cell separator. Defaults to `","`.
+ * @returns The CSV content.
+ * @example
+ * toCsv([["name", "age"], ["Ann", 32]]); // => '"name","age"\n"Ann","32"'
+ * toCsv([['say "hi"']]); // => '"say ""hi"""'
+ */
+export declare function toCsv(rows: readonly (readonly (string | number)[])[], delimiter?: string): string;
+//# sourceMappingURL=toCsv.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toCsv.d.ts","sourceRoot":"","sources":["../../src/csv/toCsv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,EAAE,EAC/C,SAAS,SAAM,GACd,MAAM,CAQR"}

package/dist/csv/toCsv.js

@@ -0,0 +1,19 @@
+/**
+ * Serializes rows to CSV. Every cell is wrapped in double quotes (any internal
+ * double quote doubled), so delimiters and line breaks inside a cell are safe.
+ * Rows are joined with `\n`.
+ *
+ * @param rows - The rows to serialize, header row included if any.
+ * @param delimiter - The cell separator. Defaults to `","`.
+ * @returns The CSV content.
+ * @example
+ * toCsv([["name", "age"], ["Ann", 32]]); // => '"name","age"\n"Ann","32"'
+ * toCsv([['say "hi"']]); // => '"say ""hi"""'
+ */
+export function toCsv(rows, delimiter = ",") {
+    return rows
+        .map((row) => row
+        .map((cell) => `"${String(cell).replace(/"/g, '""')}"`)
+        .join(delimiter))
+        .join("\n");
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./array/index.js";
 export * from "./async/index.js";
 export * from "./classes/index.js";
+export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./id/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,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,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"}

package/dist/index.js

@@ -6,6 +6,7 @@
 export * from "./array/index.js";
 export * from "./async/index.js";
 export * from "./classes/index.js";
+export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./id/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -26,8 +26,8 @@
     "jsdom": "^29.1.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@forthtilliath/eslint-config": "0.5.0",
-    "@forthtilliath/typescript-config": "0.0.0"
+    "@forthtilliath/eslint-config": "0.7.0",
+    "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
     "dev": "tsc --watch -p tsconfig.build.json",