@forthtilliath/ts-kit 0.7.0 → 0.9.0

package/README.md

@@ -46,6 +46,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.
@@ -84,6 +88,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,5 +3,6 @@ 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,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

@@ -3,4 +3,5 @@ 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/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.7.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -26,8 +26,8 @@
     "jsdom": "^29.1.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@forthtilliath/typescript-config": "0.1.1",
-    "@forthtilliath/eslint-config": "0.7.0"
+    "@forthtilliath/eslint-config": "0.7.0",
+    "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
     "dev": "tsc --watch -p tsconfig.build.json",