@forthtilliath/ts-kit 0.3.0 → 0.5.0

package/README.md

@@ -1,8 +1,8 @@
 # @forthtilliath/ts-kit
 
 Framework-agnostic TypeScript utility functions — arrays, objects, strings,
-async control-flow, dates, numbers, browser file downloads, and a couple of
-`Array` extensions with better type-narrowing.
+async control-flow, dates, numbers, browser file downloads, changelog/version
+parsing, and a couple of `Array` extensions with better type-narrowing.
 
 ## Install
 
@@ -37,6 +37,15 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 
 - `chunk(array, size)` — splits an array into chunks of a given size.
 - `flattenDeep(array)` — recursively flattens nested arrays.
+- `getMostRecentIds(rows, limit?)` — most recently occurring distinct ids
+  (`{ id, occurredAt }[]`), most recent first, deduplicated, limited
+  (default 5).
+- `nextInCycle(ids, currentId)` — next id in a short list (e.g. cycling
+  through recents on tap) — wraps to the first if `currentId` is at the end
+  or no longer in the list.
+- `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
+  `query`: earlier match position first, then shorter name — for a
+  search-as-you-type list.
 
 ### `async`
 
@@ -78,6 +87,9 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `isSameDay(a, b)` — checks whether two dates fall on the same local day.
 - `formatRelativeTime(date, baseDate?, locale?)` — human-readable relative
   time ("3 hours ago"), backed by `Intl.RelativeTimeFormat`.
+- `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.
 
 ### `files`
 
@@ -91,6 +103,14 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `randomId()` — `crypto.randomUUID()` with fallbacks for older/insecure
   contexts.
 
+### `markdown`
+
+- `parseChangelogNotes(notes)` — parses a small subset of Markdown
+  (`### heading`, `- item`, `**bold**`) commonly found in GitHub release
+  notes into a list of typed blocks (`heading` / `item` / `text`, each with
+  `bold`-aware segments), ready for a UI layer to render without a full
+  Markdown dependency.
+
 ### `maths`
 
 - `sum(numbers)` — sum of an array of numbers.
@@ -102,6 +122,8 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `round(value, decimals?)` — rounds to a given number of decimal places.
 - `formatBytes(bytes, decimals?)` — human-readable byte size ("1.5 MB").
 - `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.
 
 ### `object`
 
@@ -122,6 +144,18 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
   hyphenated).
 - `pluralize(count, singular, plural?)` — naive English pluralization, with an
   override for irregular words.
+- `normalizeForSearch(text)` — lowercases, trims, strips accents, and expands
+  œ/æ ligatures (which `normalize("NFD")` alone doesn't decompose) — for
+  accent/case-insensitive search matching.
+- `escapeCsvField(value)` — quotes and escapes a CSV field (RFC 4180) only if
+  it contains a `"`, `;`, or newline.
+- `escapeHtml(text)` — basic HTML entity escaping (`&`, `<`, `>`, `"`) for
+  inserting user text into an HTML template.
+
+### `version`
+
+- `compareVersions(a, b)` — compares two `"x.y.z"` version strings, segment
+  by segment; `-1`/`0`/`1`.
 
 ## Scripts
 

package/dist/array/getMostRecentIds.d.ts

@@ -0,0 +1,21 @@
+export interface RecentIdRow {
+    id: number | null;
+    occurredAt: string;
+}
+/**
+ * Returns the most recently occurring distinct ids, most recent first —
+ * useful for a "recents" picker (a food, a container, or any other dated
+ * entity). Rows with a `null` id (a reference deleted since) are ignored:
+ * there's nothing left to offer for them.
+ *
+ * @param rows - Rows carrying an id (or `null`) and an ISO/parsable date.
+ * @param limit - Max number of ids to return. Defaults to `5`.
+ * @returns Distinct ids, most recent first, limited to `limit`.
+ * @example
+ * getMostRecentIds([
+ *   { id: 1, occurredAt: "2026-01-01T00:00:00.000Z" },
+ *   { id: 2, occurredAt: "2026-01-03T00:00:00.000Z" },
+ * ]); // => [2, 1]
+ */
+export declare function getMostRecentIds(rows: RecentIdRow[], limit?: number): number[];
+//# sourceMappingURL=getMostRecentIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getMostRecentIds.d.ts","sourceRoot":"","sources":["../../src/array/getMostRecentIds.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,SAAgB,GACpB,MAAM,EAAE,CAcV"}

package/dist/array/getMostRecentIds.js

@@ -0,0 +1,30 @@
+const DEFAULT_LIMIT = 5;
+/**
+ * Returns the most recently occurring distinct ids, most recent first —
+ * useful for a "recents" picker (a food, a container, or any other dated
+ * entity). Rows with a `null` id (a reference deleted since) are ignored:
+ * there's nothing left to offer for them.
+ *
+ * @param rows - Rows carrying an id (or `null`) and an ISO/parsable date.
+ * @param limit - Max number of ids to return. Defaults to `5`.
+ * @returns Distinct ids, most recent first, limited to `limit`.
+ * @example
+ * getMostRecentIds([
+ *   { id: 1, occurredAt: "2026-01-01T00:00:00.000Z" },
+ *   { id: 2, occurredAt: "2026-01-03T00:00:00.000Z" },
+ * ]); // => [2, 1]
+ */
+export function getMostRecentIds(rows, limit = DEFAULT_LIMIT) {
+    const sorted = [...rows].sort((a, b) => new Date(b.occurredAt).getTime() - new Date(a.occurredAt).getTime());
+    const seen = new Set();
+    const result = [];
+    for (const row of sorted) {
+        if (row.id == null || seen.has(row.id))
+            continue;
+        seen.add(row.id);
+        result.push(row.id);
+        if (result.length >= limit)
+            break;
+    }
+    return result;
+}

package/dist/array/index.d.ts

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

package/dist/array/index.js

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

package/dist/array/nextInCycle.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns the next element in a short list (e.g. cycling through a few
+ * recent items on tap). Wraps to the first element if the current one is no
+ * longer in the list (deleted, or out of range) or was the last one.
+ *
+ * @param ids - The list to cycle through.
+ * @param currentId - The currently selected id, or `null` for none.
+ * @returns The next id, or `null` if `ids` is empty.
+ * @example
+ * nextInCycle([1, 2, 3], 1); // => 2
+ * nextInCycle([1, 2, 3], 3); // => 1
+ * nextInCycle([1, 2, 3], null); // => 1
+ */
+export declare function nextInCycle(ids: number[], currentId: number | null): number | null;
+//# sourceMappingURL=nextInCycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nextInCycle.d.ts","sourceRoot":"","sources":["../../src/array/nextInCycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EAAE,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM,GAAG,IAAI,CAIf"}

package/dist/array/nextInCycle.js

@@ -0,0 +1,19 @@
+/**
+ * Returns the next element in a short list (e.g. cycling through a few
+ * recent items on tap). Wraps to the first element if the current one is no
+ * longer in the list (deleted, or out of range) or was the last one.
+ *
+ * @param ids - The list to cycle through.
+ * @param currentId - The currently selected id, or `null` for none.
+ * @returns The next id, or `null` if `ids` is empty.
+ * @example
+ * nextInCycle([1, 2, 3], 1); // => 2
+ * nextInCycle([1, 2, 3], 3); // => 1
+ * nextInCycle([1, 2, 3], null); // => 1
+ */
+export function nextInCycle(ids, currentId) {
+    if (ids.length === 0)
+        return null;
+    const currentIndex = currentId == null ? -1 : ids.indexOf(currentId);
+    return ids[(currentIndex + 1) % ids.length] ?? null;
+}

package/dist/array/rankByNameMatch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ranks `items` by relevance to a text search: match position in the name
+ * (earlier is more relevant), then name length. Generic so it can be reused
+ * for any list of items with a displayable name — typically for a
+ * search-as-you-type list.
+ *
+ * @param items - The items to rank.
+ * @param query - The search text.
+ * @param getName - Reads the displayable name off an item.
+ * @returns Only the matching items, ranked most relevant first.
+ * @example
+ * rankByNameMatch(
+ *   [{ label: "Salad with potato" }, { label: "Potato" }],
+ *   "potato",
+ *   (item) => item.label,
+ * ); // => [{ label: "Potato" }, { label: "Salad with potato" }]
+ */
+export declare function rankByNameMatch<T>(items: T[], query: string, getName: (item: T) => string): T[];
+//# sourceMappingURL=rankByNameMatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rankByNameMatch.d.ts","sourceRoot":"","sources":["../../src/array/rankByNameMatch.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC3B,CAAC,EAAE,CAiBL"}

package/dist/array/rankByNameMatch.js

@@ -0,0 +1,45 @@
+import { normalizeForSearch } from "../string/normalizeForSearch.js";
+// Caches each item's normalized name by object reference: useful for fixed
+// lists (module-level constants) searched on every keystroke in a search
+// field, to avoid renormalizing every name on each call.
+const normalizedNameCache = new WeakMap();
+function getNormalizedName(item, getName) {
+    if (typeof item !== "object" || item === null)
+        return normalizeForSearch(getName(item));
+    const cached = normalizedNameCache.get(item);
+    if (cached !== undefined)
+        return cached;
+    const normalized = normalizeForSearch(getName(item));
+    normalizedNameCache.set(item, normalized);
+    return normalized;
+}
+/**
+ * Ranks `items` by relevance to a text search: match position in the name
+ * (earlier is more relevant), then name length. Generic so it can be reused
+ * for any list of items with a displayable name — typically for a
+ * search-as-you-type list.
+ *
+ * @param items - The items to rank.
+ * @param query - The search text.
+ * @param getName - Reads the displayable name off an item.
+ * @returns Only the matching items, ranked most relevant first.
+ * @example
+ * rankByNameMatch(
+ *   [{ label: "Salad with potato" }, { label: "Potato" }],
+ *   "potato",
+ *   (item) => item.label,
+ * ); // => [{ label: "Potato" }, { label: "Salad with potato" }]
+ */
+export function rankByNameMatch(items, query, getName) {
+    const normalizedQuery = normalizeForSearch(query);
+    const matches = [];
+    for (const item of items) {
+        const matchIndex = getNormalizedName(item, getName).indexOf(normalizedQuery);
+        if (matchIndex !== -1) {
+            matches.push({ item, matchIndex });
+        }
+    }
+    matches.sort((a, b) => a.matchIndex - b.matchIndex ||
+        getName(a.item).length - getName(b.item).length);
+    return matches.map((m) => m.item);
+}

package/dist/date/getPeriodStartMs.d.ts

@@ -0,0 +1,16 @@
+export type PeriodFilter = "all" | "today" | "7d" | "30d";
+/**
+ * Returns the timestamp (ms) from which a record is included for a given
+ * period filter, or `null` for `"all"` (no date filter). `"today"` starts at
+ * the current calendar day, not a rolling 24h window.
+ *
+ * @param period - The period filter.
+ * @param now - The reference date. Defaults to `new Date()`.
+ * @returns The period's start timestamp in ms, or `null` for `"all"`.
+ * @example
+ * getPeriodStartMs("today"); // => start of today, local time, in ms
+ * getPeriodStartMs("7d"); // => now minus 7 days, in ms
+ * getPeriodStartMs("all"); // => null
+ */
+export declare function getPeriodStartMs(period: PeriodFilter, now?: Date): number | null;
+//# sourceMappingURL=getPeriodStartMs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getPeriodStartMs.d.ts","sourceRoot":"","sources":["../../src/date/getPeriodStartMs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,GAAG,OAAa,GACf,MAAM,GAAG,IAAI,CASf"}

package/dist/date/getPeriodStartMs.js

@@ -0,0 +1,24 @@
+/**
+ * Returns the timestamp (ms) from which a record is included for a given
+ * period filter, or `null` for `"all"` (no date filter). `"today"` starts at
+ * the current calendar day, not a rolling 24h window.
+ *
+ * @param period - The period filter.
+ * @param now - The reference date. Defaults to `new Date()`.
+ * @returns The period's start timestamp in ms, or `null` for `"all"`.
+ * @example
+ * getPeriodStartMs("today"); // => start of today, local time, in ms
+ * getPeriodStartMs("7d"); // => now minus 7 days, in ms
+ * getPeriodStartMs("all"); // => null
+ */
+export function getPeriodStartMs(period, now = new Date()) {
+    if (period === "all")
+        return null;
+    if (period === "today") {
+        const startOfDay = new Date(now);
+        startOfDay.setHours(0, 0, 0, 0);
+        return startOfDay.getTime();
+    }
+    const days = period === "7d" ? 7 : 30;
+    return now.getTime() - days * 24 * 60 * 60 * 1000;
+}

package/dist/date/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./formatRelativeTime.js";
+export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
 export * from "./startOfDay.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,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/date/index.js

@@ -1,3 +1,4 @@
 export * from "./formatRelativeTime.js";
+export * from "./getPeriodStartMs.js";
 export * from "./isSameDay.js";
 export * from "./startOfDay.js";

package/dist/index.d.ts

@@ -4,8 +4,10 @@ export * from "./classes/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./id/index.js";
+export * from "./markdown/index.js";
 export * from "./maths/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
 export * from "./string/index.js";
+export * from "./version/index.js";
 //# sourceMappingURL=index.d.ts.map

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,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,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,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,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

@@ -9,7 +9,9 @@ export * from "./classes/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";
 export * from "./id/index.js";
+export * from "./markdown/index.js";
 export * from "./maths/index.js";
 export * from "./number/index.js";
 export * from "./object/index.js";
 export * from "./string/index.js";
+export * from "./version/index.js";

package/dist/markdown/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./parseChangelogNotes.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/markdown/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/dist/markdown/index.js

@@ -0,0 +1 @@
+export * from "./parseChangelogNotes.js";

package/dist/markdown/parseChangelogNotes.d.ts

@@ -0,0 +1,16 @@
+export interface ChangelogSegment {
+    text: string;
+    bold: boolean;
+}
+export type ChangelogBlock = {
+    type: "heading";
+    text: string;
+} | {
+    type: "item";
+    segments: ChangelogSegment[];
+} | {
+    type: "text";
+    segments: ChangelogSegment[];
+};
+export declare function parseChangelogNotes(notes: string): ChangelogBlock[];
+//# sourceMappingURL=parseChangelogNotes.d.ts.map

package/dist/markdown/parseChangelogNotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseChangelogNotes.d.ts","sourceRoot":"","sources":["../../src/markdown/parseChangelogNotes.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAsBnD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAiBnE"}

package/dist/markdown/parseChangelogNotes.js

@@ -0,0 +1,43 @@
+// GitHub release notes (and changelogs in general) are usually written in a
+// small subset of Markdown ("### Heading", "- item", "**bold**"). Rendered
+// as-is in a plain UI text node, the raw syntax shows up unstyled — this
+// parser turns it into a small set of typed blocks a UI layer can render
+// (heading / bullet item / plain text), without pulling in a full Markdown
+// dependency for this narrow use case.
+function parseInlineSegments(text) {
+    const segments = [];
+    const boldPattern = /\*\*(.+?)\*\*/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = boldPattern.exec(text)) !== null) {
+        if (match.index > lastIndex) {
+            segments.push({ text: text.slice(lastIndex, match.index), bold: false });
+        }
+        // The capture group is mandatory in the pattern, so it always matches —
+        // the `?? ""` fallback is only here to satisfy `noUncheckedIndexedAccess`.
+        segments.push({ text: match[1] ?? "", bold: true });
+        lastIndex = boldPattern.lastIndex;
+    }
+    if (lastIndex < text.length) {
+        segments.push({ text: text.slice(lastIndex), bold: false });
+    }
+    return segments;
+}
+export function parseChangelogNotes(notes) {
+    return notes
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        if (line.startsWith("### ")) {
+            return { type: "heading", text: line.slice(4).trim() };
+        }
+        if (line.startsWith("- ")) {
+            return {
+                type: "item",
+                segments: parseInlineSegments(line.slice(2).trim()),
+            };
+        }
+        return { type: "text", segments: parseInlineSegments(line) };
+    });
+}

package/dist/number/formatCsvNumber.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export declare function formatCsvNumber(value: number, decimals?: number): string;
+//# sourceMappingURL=formatCsvNumber.d.ts.map

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

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

package/dist/number/formatCsvNumber.js

@@ -0,0 +1,15 @@
+/**
+ * Formats a number as a raw value (no unit suffix) for use in a spreadsheet
+ * (sum, average...), with a comma decimal separator as expected by
+ * French-locale spreadsheets instead of JS's dot.
+ *
+ * @param value - The number to format.
+ * @param decimals - Number of decimal places. Defaults to `1`.
+ * @returns The formatted number, comma as decimal separator.
+ * @example
+ * formatCsvNumber(1.5); // => "1,5"
+ * formatCsvNumber(12.345, 2); // => "12,35"
+ */
+export function formatCsvNumber(value, decimals = 1) {
+    return value.toFixed(decimals).replace(".", ",");
+}

package/dist/number/index.d.ts

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

package/dist/number/index.js

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

package/dist/string/escapeCsvField.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Escapes a CSV field per RFC 4180: wraps it in double quotes and doubles any
+ * internal double quote if the value contains a double quote, a semicolon
+ * (the delimiter), or a newline — returned as-is otherwise.
+ *
+ * @param value - The raw field value.
+ * @returns The value, quoted and escaped only if needed.
+ * @example
+ * escapeCsvField("Apple"); // => "Apple"
+ * escapeCsvField("a;b"); // => '"a;b"'
+ * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ */
+export declare function escapeCsvField(value: string): string;
+//# sourceMappingURL=escapeCsvField.d.ts.map

package/dist/string/escapeCsvField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/string/escapeCsvField.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/string/escapeCsvField.js

@@ -0,0 +1,17 @@
+/**
+ * Escapes a CSV field per RFC 4180: wraps it in double quotes and doubles any
+ * internal double quote if the value contains a double quote, a semicolon
+ * (the delimiter), or a newline — returned as-is otherwise.
+ *
+ * @param value - The raw field value.
+ * @returns The value, quoted and escaped only if needed.
+ * @example
+ * escapeCsvField("Apple"); // => "Apple"
+ * escapeCsvField("a;b"); // => '"a;b"'
+ * escapeCsvField('He said "hi"'); // => '"He said ""hi"""'
+ */
+export function escapeCsvField(value) {
+    if (!/[";\n]/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '""')}"`;
+}

package/dist/string/escapeHtml.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Escapes the HTML entities that matter when inserting arbitrary text into
+ * an HTML template (`&`, `<`, `>`, `"`), without pulling in a templating
+ * dependency.
+ *
+ * @param text - The text to escape.
+ * @returns `text` with `&`, `<`, `>` and `"` replaced by their HTML entities.
+ * @example
+ * escapeHtml("Tom & Jerry <script>"); // => "Tom &amp; Jerry &lt;script&gt;"
+ */
+export declare function escapeHtml(text: string): string;
+//# sourceMappingURL=escapeHtml.d.ts.map

package/dist/string/escapeHtml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escapeHtml.d.ts","sourceRoot":"","sources":["../../src/string/escapeHtml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/string/escapeHtml.js

@@ -0,0 +1,17 @@
+/**
+ * Escapes the HTML entities that matter when inserting arbitrary text into
+ * an HTML template (`&`, `<`, `>`, `"`), without pulling in a templating
+ * dependency.
+ *
+ * @param text - The text to escape.
+ * @returns `text` with `&`, `<`, `>` and `"` replaced by their HTML entities.
+ * @example
+ * escapeHtml("Tom & Jerry <script>"); // => "Tom &amp; Jerry &lt;script&gt;"
+ */
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/string/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./capitalize.js";
+export * from "./escapeCsvField.js";
+export * from "./escapeHtml.js";
+export * from "./normalizeForSearch.js";
 export * from "./pluralize.js";
 export * from "./slugify.js";
 export * from "./truncate.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/dist/string/index.js

@@ -1,4 +1,7 @@
 export * from "./capitalize.js";
+export * from "./escapeCsvField.js";
+export * from "./escapeHtml.js";
+export * from "./normalizeForSearch.js";
 export * from "./pluralize.js";
 export * from "./slugify.js";
 export * from "./truncate.js";

package/dist/string/normalizeForSearch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalizes text for accent/case-insensitive search matching: expands
+ * œ/æ ligatures, strips accents, lower-cases, and trims.
+ *
+ * @param text - The text to normalize.
+ * @returns The normalized text.
+ * @example
+ * normalizeForSearch("Pâtes À La Crème"); // => "pates a la creme"
+ * normalizeForSearch("Œuf"); // => "oeuf"
+ */
+export declare function normalizeForSearch(text: string): string;
+//# sourceMappingURL=normalizeForSearch.d.ts.map

package/dist/string/normalizeForSearch.d.ts.map

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

package/dist/string/normalizeForSearch.js

@@ -0,0 +1,25 @@
+// The œ/æ ligatures do NOT decompose via normalize("NFD") (unlike accented
+// letters): they're standalone Unicode letters, not a base + combining mark.
+// Without this explicit replacement, searching "Œuf" (the real ligature)
+// never matches "Oeuf" in data spelled without the ligature (as most text
+// databases are).
+function expandLigatures(text) {
+    return text.replace(/[œŒ]/g, "oe").replace(/[æÆ]/g, "ae");
+}
+/**
+ * Normalizes text for accent/case-insensitive search matching: expands
+ * œ/æ ligatures, strips accents, lower-cases, and trims.
+ *
+ * @param text - The text to normalize.
+ * @returns The normalized text.
+ * @example
+ * normalizeForSearch("Pâtes À La Crème"); // => "pates a la creme"
+ * normalizeForSearch("Œuf"); // => "oeuf"
+ */
+export function normalizeForSearch(text) {
+    return expandLigatures(text)
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .trim();
+}

package/dist/version/compareVersions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compares two "x.y.z" version strings, segment by segment.
+ *
+ * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+//# sourceMappingURL=compareVersions.d.ts.map

package/dist/version/compareVersions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareVersions.d.ts","sourceRoot":"","sources":["../../src/version/compareVersions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/dist/version/compareVersions.js

@@ -0,0 +1,17 @@
+/**
+ * Compares two "x.y.z" version strings, segment by segment.
+ *
+ * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ */
+export function compareVersions(a, b) {
+    const partsA = a.split(".").map(Number);
+    const partsB = b.split(".").map(Number);
+    const length = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < length; i++) {
+        const numA = partsA[i] ?? 0;
+        const numB = partsB[i] ?? 0;
+        if (numA !== numB)
+            return numA > numB ? 1 : -1;
+    }
+    return 0;
+}

package/dist/version/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./compareVersions.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/version/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/version/index.js

@@ -0,0 +1 @@
+export * from "./compareVersions.js";

package/package.json

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