@forthtilliath/ts-kit 0.11.0 → 0.12.0

package/README.md

@@ -63,6 +63,8 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
   `query`: earlier match position first, then shorter name — for a
   search-as-you-type list.
+- `shuffle(array, random?)` — shuffled copy (Fisher–Yates); `random`
+  (default `Math.random`) can be swapped for a seeded generator in tests.
 - `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
@@ -134,8 +136,18 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 
 - `startOfDay(date?)` — returns a new `Date` at local midnight.
 - `isSameDay(a, b)` — checks whether two dates fall on the same local day.
+- `parseIsoDate(iso)` — a `YYYY-MM-DD` calendar date as **local** midnight
+  (`new Date("2026-03-14")` is UTC midnight, the previous day in the Americas).
+- `parseSqliteDate(value)` — reads a SQLite `current_timestamp` value
+  (`"2026-10-09 19:46:00"`, UTC without a zone marker) as **UTC** instead of
+  local time; full ISO strings are read as they are.
+- `mondayFirstWeekday(date)` — weekday index with Monday = `0` … Sunday = `6`,
+  from a `Date` or a `YYYY-MM-DD` string; offsets a Monday-first month grid.
 - `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
   time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
+- `formatRecentDate(date, { now?, locale? })` — a past moment as a "last
+  saved…" line reads best: `"aujourd'hui à 21:42"`, `"hier à 08:05"`, then
+  `"le 11 octobre 2026"` (`locale: "en"`: `"today at…"`, `"on October 11, 2026"`).
 - `getPeriodStartMs(period, now?)` — start timestamp (ms) for a
   `"today" | "7d" | "30d" | "all"` period filter, or `null` for `"all"`.
   `"today"` is the current calendar day, not a rolling 24h window.
@@ -156,6 +168,9 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `downloadTextBlob(filename, text)` — same, but via a `Blob` + object URL
   (better for larger content). The object URL is revoked 40 s later, not
   right after the click (which can cancel the download in Firefox/Safari).
+- `formatFileTimestamp(date?, { seconds?, separator? })` — compact **local**
+  timestamp for file names, `"20261008-0902"` by default (`toISOString()` is
+  UTC and its `:` is rejected by Windows); names sort chronologically.
 
 ### `function`
 
@@ -167,6 +182,19 @@ Importing them is harmless anywhere: the DOM is only touched when called.
 - `sanitizeFileName(name)` — replaces characters forbidden in file names
   (`\ / : * ? " < > |`) with hyphens, collapses whitespace and trims.
 
+### `ics`
+
+Building blocks for writing an iCalendar (`.ics`, RFC 5545) file.
+
+- `escapeIcsText(text)` — escapes a TEXT value (`SUMMARY`, `DESCRIPTION`…):
+  `\`, `;`, `,` and line breaks.
+- `foldIcsLine(line, maxOctets?)` — folds a content line past 75 **octets**
+  (UTF-8 bytes, not characters) without splitting a character.
+- `toIcsDate(isoDate)` — `"2026-07-14"` → `"20260714"`, for all-day events.
+- `toIcsDateTime(isoDate, "HH:MM")` — floating local date-time,
+  `"20260714T063000"`.
+- `icsTimestamp(date?)` — UTC date-time for `DTSTAMP`, `"20260714T080509Z"`.
+
 ### `id`
 
 - `randomId()` — `crypto.randomUUID()` with fallbacks for older/insecure

package/dist/array/index.d.ts

@@ -4,6 +4,7 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./shuffle.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,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"}
+{"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,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -4,5 +4,6 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./shuffle.js";
 export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.js";

package/dist/array/shuffle.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns a shuffled copy of an array (Fisher–Yates), leaving the original
+ * untouched.
+ *
+ * @param array - The array to shuffle.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns A new array holding the same elements in random order.
+ * @example
+ * shuffle([1, 2, 3, 4]); // => e.g. [3, 1, 4, 2]
+ * shuffle(["a", "b", "c"], () => 0); // => ["b", "c", "a"]
+ */
+export declare function shuffle<T>(array: readonly T[], random?: () => number): T[];
+//# sourceMappingURL=shuffle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shuffle.d.ts","sourceRoot":"","sources":["../../src/array/shuffle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,GAAE,MAAM,MAAoB,GACjC,CAAC,EAAE,CAOL"}

package/dist/array/shuffle.js

@@ -0,0 +1,20 @@
+/**
+ * Returns a shuffled copy of an array (Fisher–Yates), leaving the original
+ * untouched.
+ *
+ * @param array - The array to shuffle.
+ * @param random - Returns a number in `[0, 1)`. Defaults to `Math.random`;
+ * pass a seeded generator for deterministic tests.
+ * @returns A new array holding the same elements in random order.
+ * @example
+ * shuffle([1, 2, 3, 4]); // => e.g. [3, 1, 4, 2]
+ * shuffle(["a", "b", "c"], () => 0); // => ["b", "c", "a"]
+ */
+export function shuffle(array, random = Math.random) {
+    const result = [...array];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}

package/dist/date/formatRecentDate.d.ts

@@ -0,0 +1,22 @@
+/** Languages {@link formatRecentDate} has wording for. */
+export type RecentDateLocale = "fr" | "en";
+export interface FormatRecentDateOptions {
+    /** Reference "now" (defaults to the current time). */
+    now?: Date;
+    /** Wording and `Intl` formats. @defaultValue "fr" */
+    locale?: RecentDateLocale;
+}
+/**
+ * Describes a past moment the way a "last saved…" line reads best: with the
+ * time when it's today or yesterday, as a plain day otherwise. A date in the
+ * future (clock change between devices) reads as today.
+ *
+ * @param date - The moment to describe.
+ * @param options - See {@link FormatRecentDateOptions}.
+ * @returns E.g. `"aujourd'hui à 21:42"`, `"hier à 08:05"`, `"le 11 octobre 2026"`.
+ * @example
+ * formatRecentDate(lastBackupAt); // => "hier à 21:42"
+ * formatRecentDate(lastBackupAt, { locale: "en" }); // => "yesterday at 9:42 PM"
+ */
+export declare function formatRecentDate(date: Date, { now, locale }?: FormatRecentDateOptions): string;
+//# sourceMappingURL=formatRecentDate.d.ts.map

package/dist/date/formatRecentDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatRecentDate.d.ts","sourceRoot":"","sources":["../../src/date/formatRecentDate.ts"],"names":[],"mappings":"AAEA,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,qDAAqD;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AA2BD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,EAAE,GAAgB,EAAE,MAAa,EAAE,GAAE,uBAA4B,GAChE,MAAM,CAmBR"}

package/dist/date/formatRecentDate.js

@@ -0,0 +1,46 @@
+import { startOfDay } from "./startOfDay.js";
+const WORDING = {
+    fr: {
+        tag: "fr-FR",
+        today: (time) => `aujourd'hui à ${time}`,
+        yesterday: (time) => `hier à ${time}`,
+        older: (day) => `le ${day}`,
+    },
+    en: {
+        tag: "en-US",
+        today: (time) => `today at ${time}`,
+        yesterday: (time) => `yesterday at ${time}`,
+        older: (day) => `on ${day}`,
+    },
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Describes a past moment the way a "last saved…" line reads best: with the
+ * time when it's today or yesterday, as a plain day otherwise. A date in the
+ * future (clock change between devices) reads as today.
+ *
+ * @param date - The moment to describe.
+ * @param options - See {@link FormatRecentDateOptions}.
+ * @returns E.g. `"aujourd'hui à 21:42"`, `"hier à 08:05"`, `"le 11 octobre 2026"`.
+ * @example
+ * formatRecentDate(lastBackupAt); // => "hier à 21:42"
+ * formatRecentDate(lastBackupAt, { locale: "en" }); // => "yesterday at 9:42 PM"
+ */
+export function formatRecentDate(date, { now = new Date(), locale = "fr" } = {}) {
+    const wording = WORDING[locale];
+    // Rounded: a day that has a DST change lasts 23 or 25 hours.
+    const dayDiff = Math.round((startOfDay(now).getTime() - startOfDay(date).getTime()) / DAY_MS);
+    if (dayDiff <= 1) {
+        const time = new Intl.DateTimeFormat(wording.tag, {
+            hour: "2-digit",
+            minute: "2-digit",
+        }).format(date);
+        return dayDiff === 1 ? wording.yesterday(time) : wording.today(time);
+    }
+    const day = new Intl.DateTimeFormat(wording.tag, {
+        day: "numeric",
+        month: "long",
+        year: "numeric",
+    }).format(date);
+    return wording.older(day);
+}

package/dist/date/index.d.ts

@@ -1,8 +1,12 @@
 export * from "./dateInTimeZone.js";
 export * from "./daysUntil.js";
+export * from "./formatRecentDate.js";
 export * from "./formatRelativeTime.js";
 export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
+export * from "./mondayFirstWeekday.js";
+export * from "./parseIsoDate.js";
+export * from "./parseSqliteDate.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,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"}
+{"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,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/date/index.js

@@ -1,7 +1,11 @@
 export * from "./dateInTimeZone.js";
 export * from "./daysUntil.js";
+export * from "./formatRecentDate.js";
 export * from "./formatRelativeTime.js";
 export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
+export * from "./mondayFirstWeekday.js";
+export * from "./parseIsoDate.js";
+export * from "./parseSqliteDate.js";
 export * from "./startOfDay.js";
 export * from "./todayInTimeZone.js";

package/dist/date/mondayFirstWeekday.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Day of the week with Monday as the first day: `0` for Monday … `6` for
+ * Sunday (instead of JavaScript's Sunday = `0`). Handy to offset the first
+ * day of a month in a Monday-first calendar grid.
+ *
+ * @param date - A `Date`, or a `YYYY-MM-DD` calendar date read as local midnight.
+ * @returns The weekday index, Monday = `0`.
+ * @example
+ * mondayFirstWeekday("2026-10-01"); // => 3 (a Thursday)
+ */
+export declare function mondayFirstWeekday(date: Date | string): number;
+//# sourceMappingURL=mondayFirstWeekday.d.ts.map

package/dist/date/mondayFirstWeekday.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mondayFirstWeekday.d.ts","sourceRoot":"","sources":["../../src/date/mondayFirstWeekday.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAG9D"}

package/dist/date/mondayFirstWeekday.js

@@ -0,0 +1,15 @@
+import { parseIsoDate } from "./parseIsoDate.js";
+/**
+ * Day of the week with Monday as the first day: `0` for Monday … `6` for
+ * Sunday (instead of JavaScript's Sunday = `0`). Handy to offset the first
+ * day of a month in a Monday-first calendar grid.
+ *
+ * @param date - A `Date`, or a `YYYY-MM-DD` calendar date read as local midnight.
+ * @returns The weekday index, Monday = `0`.
+ * @example
+ * mondayFirstWeekday("2026-10-01"); // => 3 (a Thursday)
+ */
+export function mondayFirstWeekday(date) {
+    const day = (typeof date === "string" ? parseIsoDate(date) : date).getDay();
+    return (day + 6) % 7;
+}

package/dist/date/parseIsoDate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses a `YYYY-MM-DD` calendar date as **local** midnight — unlike
+ * `new Date("2026-03-14")`, which the spec reads as UTC midnight and which
+ * therefore lands on the previous day west of Greenwich.
+ *
+ * @param iso - A calendar date, `YYYY-MM-DD`.
+ * @returns A `Date` at local midnight on that day.
+ * @example
+ * parseIsoDate("2026-03-14").getDate(); // => 14, whatever the time zone
+ */
+export declare function parseIsoDate(iso: string): Date;
+//# sourceMappingURL=parseIsoDate.d.ts.map

package/dist/date/parseIsoDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseIsoDate.d.ts","sourceRoot":"","sources":["../../src/date/parseIsoDate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C"}

package/dist/date/parseIsoDate.js

@@ -0,0 +1,13 @@
+/**
+ * Parses a `YYYY-MM-DD` calendar date as **local** midnight — unlike
+ * `new Date("2026-03-14")`, which the spec reads as UTC midnight and which
+ * therefore lands on the previous day west of Greenwich.
+ *
+ * @param iso - A calendar date, `YYYY-MM-DD`.
+ * @returns A `Date` at local midnight on that day.
+ * @example
+ * parseIsoDate("2026-03-14").getDate(); // => 14, whatever the time zone
+ */
+export function parseIsoDate(iso) {
+    return new Date(`${iso}T00:00:00`);
+}

package/dist/date/parseSqliteDate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parses a date read from SQLite. A `current_timestamp` value
+ * (`"2026-10-09 19:46:00"`, UTC without a zone marker) is read as **UTC** —
+ * `new Date()` would take it for local time and shift it by the time zone
+ * offset. Full ISO strings (with `Z` or an offset) are read as they are.
+ *
+ * @param value - A SQLite datetime or a full ISO string.
+ * @returns The corresponding `Date`.
+ * @example
+ * parseSqliteDate("2026-10-09 19:46:00").toISOString(); // => "2026-10-09T19:46:00.000Z"
+ */
+export declare function parseSqliteDate(value: string): Date;
+//# sourceMappingURL=parseSqliteDate.d.ts.map

package/dist/date/parseSqliteDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseSqliteDate.d.ts","sourceRoot":"","sources":["../../src/date/parseSqliteDate.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAInD"}

package/dist/date/parseSqliteDate.js

@@ -0,0 +1,17 @@
+// SQLite's `current_timestamp` stores UTC as "YYYY-MM-DD HH:MM:SS", with no
+// zone marker: `new Date()` would read it as local time.
+const SQLITE_DATETIME = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?$/;
+/**
+ * Parses a date read from SQLite. A `current_timestamp` value
+ * (`"2026-10-09 19:46:00"`, UTC without a zone marker) is read as **UTC** —
+ * `new Date()` would take it for local time and shift it by the time zone
+ * offset. Full ISO strings (with `Z` or an offset) are read as they are.
+ *
+ * @param value - A SQLite datetime or a full ISO string.
+ * @returns The corresponding `Date`.
+ * @example
+ * parseSqliteDate("2026-10-09 19:46:00").toISOString(); // => "2026-10-09T19:46:00.000Z"
+ */
+export function parseSqliteDate(value) {
+    return new Date(SQLITE_DATETIME.test(value) ? `${value.replace(" ", "T")}Z` : value);
+}

package/dist/files/formatFileTimestamp.d.ts

@@ -0,0 +1,22 @@
+export interface FormatFileTimestampOptions {
+    /** Append the seconds (`HHMMSS` instead of `HHMM`). Default: `false`. */
+    seconds?: boolean;
+    /** Put between the date and the time. Default: `"-"`. */
+    separator?: string;
+}
+/**
+ * Compact, file-name-safe timestamp in **local** time, `YYYYMMDD-HHMM` by
+ * default: unlike `toISOString()` (UTC, with `:` that Windows rejects), an
+ * export made at 00:30 carries the day it was made on, and names built with it
+ * sort chronologically in a file explorer.
+ *
+ * @param date - The instant to format. Default: now.
+ * @param options - `seconds`, `separator` between date and time.
+ * @returns The formatted timestamp.
+ * @example
+ * formatFileTimestamp(new Date(2026, 9, 8, 9, 2)); // => "20261008-0902"
+ * formatFileTimestamp(new Date(2026, 9, 8, 9, 2, 5), { seconds: true, separator: "" });
+ * // => "20261008090205"
+ */
+export declare function formatFileTimestamp(date?: Date, { seconds, separator }?: FormatFileTimestampOptions): string;
+//# sourceMappingURL=formatFileTimestamp.d.ts.map

package/dist/files/formatFileTimestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatFileTimestamp.d.ts","sourceRoot":"","sources":["../../src/files/formatFileTimestamp.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,IAAiB,EACvB,EAAE,OAAe,EAAE,SAAe,EAAE,GAAE,0BAA+B,GACpE,MAAM,CAIR"}

package/dist/files/formatFileTimestamp.js

@@ -0,0 +1,20 @@
+const pad2 = (value) => String(value).padStart(2, "0");
+/**
+ * Compact, file-name-safe timestamp in **local** time, `YYYYMMDD-HHMM` by
+ * default: unlike `toISOString()` (UTC, with `:` that Windows rejects), an
+ * export made at 00:30 carries the day it was made on, and names built with it
+ * sort chronologically in a file explorer.
+ *
+ * @param date - The instant to format. Default: now.
+ * @param options - `seconds`, `separator` between date and time.
+ * @returns The formatted timestamp.
+ * @example
+ * formatFileTimestamp(new Date(2026, 9, 8, 9, 2)); // => "20261008-0902"
+ * formatFileTimestamp(new Date(2026, 9, 8, 9, 2, 5), { seconds: true, separator: "" });
+ * // => "20261008090205"
+ */
+export function formatFileTimestamp(date = new Date(), { seconds = false, separator = "-" } = {}) {
+    const day = `${date.getFullYear()}${pad2(date.getMonth() + 1)}${pad2(date.getDate())}`;
+    const time = `${pad2(date.getHours())}${pad2(date.getMinutes())}${seconds ? pad2(date.getSeconds()) : ""}`;
+    return `${day}${separator}${time}`;
+}

package/dist/files/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./downloadText.js";
+export * from "./formatFileTimestamp.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;AAClC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC"}

package/dist/files/index.js

@@ -1,2 +1,3 @@
 export * from "./downloadText.js";
+export * from "./formatFileTimestamp.js";
 export * from "./sanitizeFileName.js";

package/dist/ics/escapeIcsText.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Escapes a value for an iCalendar (RFC 5545) TEXT property — `SUMMARY`,
+ * `DESCRIPTION`, `LOCATION`…: backslashes, semicolons and commas get a
+ * backslash, line breaks become a literal `\n`.
+ *
+ * @param text - The raw text.
+ * @returns The text, safe to put after `SUMMARY:` and the like.
+ * @example
+ * escapeIcsText("Matin; puis soir, à 20h"); // => "Matin\\; puis soir\\, à 20h"
+ */
+export declare function escapeIcsText(text: string): string;
+//# sourceMappingURL=escapeIcsText.d.ts.map

package/dist/ics/escapeIcsText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeIcsText.d.ts","sourceRoot":"","sources":["../../src/ics/escapeIcsText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD"}

package/dist/ics/escapeIcsText.js

@@ -0,0 +1,17 @@
+/**
+ * Escapes a value for an iCalendar (RFC 5545) TEXT property — `SUMMARY`,
+ * `DESCRIPTION`, `LOCATION`…: backslashes, semicolons and commas get a
+ * backslash, line breaks become a literal `\n`.
+ *
+ * @param text - The raw text.
+ * @returns The text, safe to put after `SUMMARY:` and the like.
+ * @example
+ * escapeIcsText("Matin; puis soir, à 20h"); // => "Matin\\; puis soir\\, à 20h"
+ */
+export function escapeIcsText(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/;/g, "\\;")
+        .replace(/,/g, "\\,")
+        .replace(/\r?\n/g, "\\n");
+}

package/dist/ics/foldIcsLine.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Folds an iCalendar (RFC 5545) content line longer than 75 **octets**: the
+ * rest goes on continuation lines (CRLF + one space), each 75 octets at most
+ * including that space. Counts UTF-8 bytes, not characters — an accented
+ * line folded at 75 characters would overflow — and never splits a
+ * multi-byte character.
+ *
+ * @param line - One unfolded content line, without its line break.
+ * @param maxOctets - Octets per line. @defaultValue 75
+ * @returns The line, folded with `\r\n ` where needed.
+ * @example
+ * foldIcsLine(`DESCRIPTION:${"é".repeat(40)}`); // => 2 lines
+ */
+export declare function foldIcsLine(line: string, maxOctets?: number): string;
+//# sourceMappingURL=foldIcsLine.d.ts.map

package/dist/ics/foldIcsLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldIcsLine.d.ts","sourceRoot":"","sources":["../../src/ics/foldIcsLine.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAgBhE"}

package/dist/ics/foldIcsLine.js

@@ -0,0 +1,40 @@
+/** Octets taken by one code point in UTF-8. */
+function utf8Length(codePoint) {
+    if (codePoint < 0x80)
+        return 1;
+    if (codePoint < 0x800)
+        return 2;
+    if (codePoint < 0x10000)
+        return 3;
+    return 4;
+}
+/**
+ * Folds an iCalendar (RFC 5545) content line longer than 75 **octets**: the
+ * rest goes on continuation lines (CRLF + one space), each 75 octets at most
+ * including that space. Counts UTF-8 bytes, not characters — an accented
+ * line folded at 75 characters would overflow — and never splits a
+ * multi-byte character.
+ *
+ * @param line - One unfolded content line, without its line break.
+ * @param maxOctets - Octets per line. @defaultValue 75
+ * @returns The line, folded with `\r\n ` where needed.
+ * @example
+ * foldIcsLine(`DESCRIPTION:${"é".repeat(40)}`); // => 2 lines
+ */
+export function foldIcsLine(line, maxOctets = 75) {
+    const parts = [];
+    let current = "";
+    let size = 0;
+    for (const char of line) {
+        const bytes = utf8Length(char.codePointAt(0) ?? 0);
+        if (size + bytes > maxOctets) {
+            parts.push(current);
+            current = " ";
+            size = 1;
+        }
+        current += char;
+        size += bytes;
+    }
+    parts.push(current);
+    return parts.join("\r\n");
+}

package/dist/ics/icsTimestamp.d.ts

@@ -0,0 +1,10 @@
+/**
+ * An iCalendar UTC `DATE-TIME` (`YYYYMMDDTHHMMSSZ`), as `DTSTAMP` expects.
+ *
+ * @param date - The instant. @defaultValue now
+ * @returns The instant in UTC, as `YYYYMMDDTHHMMSSZ`.
+ * @example
+ * icsTimestamp(new Date("2026-07-14T08:05:09.123Z")); // => "20260714T080509Z"
+ */
+export declare function icsTimestamp(date?: Date): string;
+//# sourceMappingURL=icsTimestamp.d.ts.map

package/dist/ics/icsTimestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icsTimestamp.d.ts","sourceRoot":"","sources":["../../src/ics/icsTimestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAE5D"}

package/dist/ics/icsTimestamp.js

@@ -0,0 +1,11 @@
+/**
+ * An iCalendar UTC `DATE-TIME` (`YYYYMMDDTHHMMSSZ`), as `DTSTAMP` expects.
+ *
+ * @param date - The instant. @defaultValue now
+ * @returns The instant in UTC, as `YYYYMMDDTHHMMSSZ`.
+ * @example
+ * icsTimestamp(new Date("2026-07-14T08:05:09.123Z")); // => "20260714T080509Z"
+ */
+export function icsTimestamp(date = new Date()) {
+    return `${date.toISOString().replace(/[-:]/g, "").slice(0, 15)}Z`;
+}

package/dist/ics/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./escapeIcsText.js";
+export * from "./foldIcsLine.js";
+export * from "./icsTimestamp.js";
+export * from "./toIcsDate.js";
+export * from "./toIcsDateTime.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ics/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/ics/index.js

@@ -0,0 +1,5 @@
+export * from "./escapeIcsText.js";
+export * from "./foldIcsLine.js";
+export * from "./icsTimestamp.js";
+export * from "./toIcsDate.js";
+export * from "./toIcsDateTime.js";

package/dist/ics/toIcsDate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An iCalendar `DATE` value (`YYYYMMDD`) from a `YYYY-MM-DD` calendar date,
+ * for all-day events (`DTSTART;VALUE=DATE:…`).
+ *
+ * @param isoDate - A calendar date, `YYYY-MM-DD`.
+ * @returns The date as `YYYYMMDD`.
+ * @example
+ * toIcsDate("2026-07-14"); // => "20260714"
+ */
+export declare function toIcsDate(isoDate: string): string;
+//# sourceMappingURL=toIcsDate.d.ts.map

package/dist/ics/toIcsDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toIcsDate.d.ts","sourceRoot":"","sources":["../../src/ics/toIcsDate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/ics/toIcsDate.js

@@ -0,0 +1,12 @@
+/**
+ * An iCalendar `DATE` value (`YYYYMMDD`) from a `YYYY-MM-DD` calendar date,
+ * for all-day events (`DTSTART;VALUE=DATE:…`).
+ *
+ * @param isoDate - A calendar date, `YYYY-MM-DD`.
+ * @returns The date as `YYYYMMDD`.
+ * @example
+ * toIcsDate("2026-07-14"); // => "20260714"
+ */
+export function toIcsDate(isoDate) {
+    return isoDate.replace(/-/g, "");
+}

package/dist/ics/toIcsDateTime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * An iCalendar floating local `DATE-TIME` value (`YYYYMMDDTHHMMSS`, no `Z`)
+ * from a calendar date and a wall-clock time — the calendar app shows it at
+ * that time in its own time zone.
+ *
+ * @param isoDate - A calendar date, `YYYY-MM-DD`.
+ * @param time - A time, `H:MM` or `HH:MM`.
+ * @returns The date-time as `YYYYMMDDTHHMMSS`.
+ * @example
+ * toIcsDateTime("2026-07-14", "6:30"); // => "20260714T063000"
+ */
+export declare function toIcsDateTime(isoDate: string, time: string): string;
+//# sourceMappingURL=toIcsDateTime.d.ts.map

package/dist/ics/toIcsDateTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toIcsDateTime.d.ts","sourceRoot":"","sources":["../../src/ics/toIcsDateTime.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnE"}

package/dist/ics/toIcsDateTime.js

@@ -0,0 +1,16 @@
+import { toIcsDate } from "./toIcsDate.js";
+/**
+ * An iCalendar floating local `DATE-TIME` value (`YYYYMMDDTHHMMSS`, no `Z`)
+ * from a calendar date and a wall-clock time — the calendar app shows it at
+ * that time in its own time zone.
+ *
+ * @param isoDate - A calendar date, `YYYY-MM-DD`.
+ * @param time - A time, `H:MM` or `HH:MM`.
+ * @returns The date-time as `YYYYMMDDTHHMMSS`.
+ * @example
+ * toIcsDateTime("2026-07-14", "6:30"); // => "20260714T063000"
+ */
+export function toIcsDateTime(isoDate, time) {
+    const [hours = "0", minutes = "0"] = time.split(":");
+    return `${toIcsDate(isoDate)}T${hours.padStart(2, "0")}${minutes.padStart(2, "0")}00`;
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./function/index.js";
+export * from "./ics/index.js";
 export * from "./id/index.js";
 export * from "./image/index.js";
 export * from "./markdown/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,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"}
+{"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,gBAAgB,CAAC;AAC/B,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

@@ -10,6 +10,7 @@ export * from "./csv/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./function/index.js";
+export * from "./ics/index.js";
 export * from "./id/index.js";
 export * from "./image/index.js";
 export * from "./markdown/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -27,7 +27,7 @@
     "jsdom": "^30.1.1",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2",
-    "@forthtilliath/eslint-config": "0.8.0",
+    "@forthtilliath/eslint-config": "0.9.0",
     "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {