@forthtilliath/ts-kit 0.10.0 → 0.11.0

package/dist/object/deepEqual.js

@@ -1,31 +1,65 @@
 /**
  * Recursively compares two values for structural equality.
  *
+ * Both values must share the same prototype (a plain object never equals an
+ * array or a class instance). `Date`s are compared by timestamp, `RegExp`s by
+ * source and flags, `Map`s by keys (identity) then values (deeply), and
+ * `Set`s by membership (identity, like `Set.prototype.has`).
+ *
  * @param a - The first value.
  * @param b - The second value.
  * @returns `true` if `a` and `b` are deeply equal.
  * @example
  * deepEqual({ a: [1, 2] }, { a: [1, 2] }); // => true
  * deepEqual({ a: 1 }, { a: 2 }); // => false
+ * deepEqual(new Date(0), new Date(0)); // => true
  */
 export function deepEqual(a, b) {
     if (Object.is(a, b))
         return true;
-    if (typeof a !== typeof b || a === null || b === null)
+    if (typeof a !== "object" ||
+        typeof b !== "object" ||
+        a === null ||
+        b === null ||
+        Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
         return false;
-    if (Array.isArray(a) || Array.isArray(b)) {
-        if (!Array.isArray(a) || !Array.isArray(b))
+    }
+    if (a instanceof Date) {
+        return Object.is(a.getTime(), b.getTime());
+    }
+    if (a instanceof RegExp) {
+        const other = b;
+        return a.source === other.source && a.flags === other.flags;
+    }
+    if (a instanceof Map) {
+        const other = b;
+        if (a.size !== other.size)
             return false;
-        if (a.length !== b.length)
+        for (const [key, value] of a) {
+            if (!other.has(key) || !deepEqual(value, other.get(key)))
+                return false;
+        }
+        return true;
+    }
+    if (a instanceof Set) {
+        const other = b;
+        if (a.size !== other.size)
             return false;
-        return a.every((item, index) => deepEqual(item, b[index]));
+        for (const value of a) {
+            if (!other.has(value))
+                return false;
+        }
+        return true;
     }
-    if (typeof a === "object" && typeof b === "object") {
-        const aKeys = Object.keys(a);
-        const bKeys = Object.keys(b);
-        if (aKeys.length !== bKeys.length)
+    if (Array.isArray(a)) {
+        const other = b;
+        if (a.length !== other.length)
             return false;
-        return aKeys.every((key) => deepEqual(a[key], b[key]));
+        return a.every((item, index) => deepEqual(item, other[index]));
     }
-    return false;
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) &&
+        deepEqual(a[key], b[key]));
 }

package/dist/string/escapeCsvField.d.ts

@@ -1,14 +1,3 @@
-/**
- * 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;
+/** @deprecated Import from `@forthtilliath/ts-kit/csv/escapeCsvField` instead. */
+export { escapeCsvField } from "../csv/escapeCsvField.js";
 //# sourceMappingURL=escapeCsvField.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"escapeCsvField.d.ts","sourceRoot":"","sources":["../../src/string/escapeCsvField.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/string/escapeCsvField.js

@@ -1,17 +1,4 @@
-/**
- * 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, '""')}"`;
-}
+// CSV helpers now live together in `csv/`. Re-exported so the
+// `@forthtilliath/ts-kit/string/escapeCsvField` deep import keeps working.
+/** @deprecated Import from `@forthtilliath/ts-kit/csv/escapeCsvField` instead. */
+export { escapeCsvField } from "../csv/escapeCsvField.js";

package/dist/string/escapeHtml.d.ts

@@ -1,12 +1,14 @@
 /**
- * Escapes the HTML entities that matter when inserting arbitrary text into
- * an HTML template (`&`, `<`, `>`, `"`), without pulling in a templating
- * dependency.
+ * Escapes the HTML special characters (`&`, `<`, `>`, `"`, `'`) when
+ * inserting arbitrary text into an HTML template, without pulling in a
+ * templating dependency. Safe in text content and in attribute values,
+ * whether they're quoted with `"` or `'`.
  *
  * @param text - The text to escape.
- * @returns `text` with `&`, `<`, `>` and `"` replaced by their HTML entities.
+ * @returns `text` with `&`, `<`, `>`, `"` and `'` replaced by HTML entities.
  * @example
  * escapeHtml("Tom & Jerry <script>"); // => "Tom &amp; Jerry &lt;script&gt;"
+ * escapeHtml("it's"); // => "it&#39;s"
  */
 export declare function escapeHtml(text: string): string;
 //# sourceMappingURL=escapeHtml.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"escapeHtml.d.ts","sourceRoot":"","sources":["../../src/string/escapeHtml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/C"}

package/dist/string/escapeHtml.js

@@ -1,17 +1,20 @@
 /**
- * Escapes the HTML entities that matter when inserting arbitrary text into
- * an HTML template (`&`, `<`, `>`, `"`), without pulling in a templating
- * dependency.
+ * Escapes the HTML special characters (`&`, `<`, `>`, `"`, `'`) when
+ * inserting arbitrary text into an HTML template, without pulling in a
+ * templating dependency. Safe in text content and in attribute values,
+ * whether they're quoted with `"` or `'`.
  *
  * @param text - The text to escape.
- * @returns `text` with `&`, `<`, `>` and `"` replaced by their HTML entities.
+ * @returns `text` with `&`, `<`, `>`, `"` and `'` replaced by HTML entities.
  * @example
  * escapeHtml("Tom & Jerry <script>"); // => "Tom &amp; Jerry &lt;script&gt;"
+ * escapeHtml("it's"); // => "it&#39;s"
  */
 export function escapeHtml(text) {
     return text
         .replace(/&/g, "&amp;")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;");
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
 }

package/dist/string/pluralize.d.ts

@@ -1,17 +1,40 @@
+export interface PluralizeOptions {
+    /** An explicit plural form (overrides the default suffix rules). */
+    plural?: string;
+    /**
+     * The locale deciding which counts take the singular (defaults to `"en"`):
+     * only ±1 in English, but also 0 and 1.5 in French.
+     */
+    locale?: string;
+}
 /**
- * Pluralizes a word based on a count, with a naive English default (`s`
- * suffix, `y` → `ies`, `es` after `s`/`x`/`z`/`sh`/`ch`) or an explicit
- * plural form for irregular words.
+ * Pluralizes a word based on a count. Which counts take the singular follows
+ * the locale's plural rules (`Intl.PluralRules`). Without an explicit plural
+ * form, the default suffix is naive: in English `s`, `y` → `ies`, `es` after
+ * `s`/`x`/`z`/`sh`/`ch`; in French `s`, nothing after `s`/`x`/`z`; `s` in
+ * any other language.
  *
  * @param count - The count driving singular vs. plural.
  * @param singular - The singular form.
- * @param plural - An explicit plural form (overrides the naive default).
- * @returns `singular` when `count` is 1 or -1, otherwise the plural form.
+ * @param options - An explicit plural form, or `{ plural?, locale? }`.
+ * @returns The singular or plural form.
  * @example
  * pluralize(1, "item"); // => "item"
- * pluralize(3, "item"); // => "items"
  * pluralize(3, "city"); // => "cities"
  * pluralize(2, "child", "children"); // => "children"
+ * pluralize(0, "chant", { locale: "fr" }); // => "chant"
+ * pluralize(2, "journal", { plural: "journaux", locale: "fr" }); // => "journaux"
  */
-export declare function pluralize(count: number, singular: string, plural?: string): string;
+export declare function pluralize(count: number, singular: string, options?: string | PluralizeOptions): string;
+/**
+ * Returns `pluralize` bound to a locale, to declare once per app.
+ *
+ * @param locale - The locale of every call.
+ * @returns `(count, singular, plural?) => string`.
+ * @example
+ * const plural = createPluralize("fr");
+ * plural(0, "chant"); // => "chant"
+ * plural(2, "est", "sont"); // => "sont"
+ */
+export declare function createPluralize(locale: string): (count: number, singular: string, plural?: string) => string;
 //# sourceMappingURL=pluralize.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pluralize.d.ts","sourceRoot":"","sources":["../../src/string/pluralize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAMR"}
+{"version":3,"file":"pluralize.d.ts","sourceRoot":"","sources":["../../src/string/pluralize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAClC,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,IACpC,OAAO,MAAM,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,KAAG,MAAM,CAElE"}

package/dist/string/pluralize.js

@@ -1,26 +1,59 @@
+const pluralRules = new Map();
+function takesSingular(count, locale) {
+    let rules = pluralRules.get(locale);
+    if (!rules) {
+        rules = new Intl.PluralRules(locale);
+        pluralRules.set(locale, rules);
+    }
+    return rules.select(count) === "one";
+}
+function defaultPlural(singular, locale) {
+    const language = locale.split("-")[0]?.toLowerCase();
+    if (language === "fr") {
+        return /[sxz]$/i.test(singular) ? singular : `${singular}s`;
+    }
+    if (language === "en") {
+        if (/[sxz]$|[cs]h$/i.test(singular))
+            return `${singular}es`;
+        if (/[^aeiou]y$/i.test(singular))
+            return `${singular.slice(0, -1)}ies`;
+    }
+    return `${singular}s`;
+}
 /**
- * Pluralizes a word based on a count, with a naive English default (`s`
- * suffix, `y` → `ies`, `es` after `s`/`x`/`z`/`sh`/`ch`) or an explicit
- * plural form for irregular words.
+ * Pluralizes a word based on a count. Which counts take the singular follows
+ * the locale's plural rules (`Intl.PluralRules`). Without an explicit plural
+ * form, the default suffix is naive: in English `s`, `y` → `ies`, `es` after
+ * `s`/`x`/`z`/`sh`/`ch`; in French `s`, nothing after `s`/`x`/`z`; `s` in
+ * any other language.
  *
  * @param count - The count driving singular vs. plural.
  * @param singular - The singular form.
- * @param plural - An explicit plural form (overrides the naive default).
- * @returns `singular` when `count` is 1 or -1, otherwise the plural form.
+ * @param options - An explicit plural form, or `{ plural?, locale? }`.
+ * @returns The singular or plural form.
  * @example
  * pluralize(1, "item"); // => "item"
- * pluralize(3, "item"); // => "items"
  * pluralize(3, "city"); // => "cities"
  * pluralize(2, "child", "children"); // => "children"
+ * pluralize(0, "chant", { locale: "fr" }); // => "chant"
+ * pluralize(2, "journal", { plural: "journaux", locale: "fr" }); // => "journaux"
  */
-export function pluralize(count, singular, plural) {
-    if (Math.abs(count) === 1)
+export function pluralize(count, singular, options) {
+    const { plural, locale = "en" } = typeof options === "string" ? { plural: options } : (options ?? {});
+    if (takesSingular(count, locale))
         return singular;
-    if (plural !== undefined)
-        return plural;
-    if (/[sxz]$|[cs]h$/i.test(singular))
-        return `${singular}es`;
-    if (/[^aeiou]y$/i.test(singular))
-        return `${singular.slice(0, -1)}ies`;
-    return `${singular}s`;
+    return plural ?? defaultPlural(singular, locale);
+}
+/**
+ * Returns `pluralize` bound to a locale, to declare once per app.
+ *
+ * @param locale - The locale of every call.
+ * @returns `(count, singular, plural?) => string`.
+ * @example
+ * const plural = createPluralize("fr");
+ * plural(0, "chant"); // => "chant"
+ * plural(2, "est", "sont"); // => "sont"
+ */
+export function createPluralize(locale) {
+    return (count, singular, plural) => pluralize(count, singular, { plural, locale });
 }

package/dist/version/compareVersions.d.ts

@@ -1,7 +1,14 @@
 /**
- * Compares two "x.y.z" version strings, segment by segment.
+ * Compares two version strings following semver precedence: "x.y.z"
+ * segments first (missing ones count as `0`), then pre-release identifiers
+ * (`1.0.0-beta.2` < `1.0.0-beta.10` < `1.0.0`). A leading `v` and build
+ * metadata (`+build.1`) are ignored.
  *
  * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ * @example
+ * compareVersions("1.10.0", "1.2.0"); // => 1
+ * compareVersions("1.0.0-beta", "1.0.0"); // => -1
+ * compareVersions("v2.0.0", "2.0.0"); // => 0
  */
 export declare function compareVersions(a: string, b: string): number;
 //# sourceMappingURL=compareVersions.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"compareVersions.d.ts","sourceRoot":"","sources":["../../src/version/compareVersions.ts"],"names":[],"mappings":"AA6CA;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAe5D"}

package/dist/version/compareVersions.js

@@ -1,17 +1,71 @@
+function parseVersion(version) {
+    // Drop a leading "v" (git tags) and build metadata ("+build.1"), which
+    // semver ignores for precedence.
+    const [withoutBuild = ""] = version.trim().replace(/^v/i, "").split("+");
+    const dashIndex = withoutBuild.indexOf("-");
+    const core = dashIndex === -1 ? withoutBuild : withoutBuild.slice(0, dashIndex);
+    const prerelease = dashIndex === -1 ? "" : withoutBuild.slice(dashIndex + 1);
+    return {
+        core: core.split(".").map((part) => Number(part) || 0),
+        prerelease: prerelease === "" ? [] : prerelease.split("."),
+    };
+}
+function compareNumbers(a, b) {
+    if (a === b)
+        return 0;
+    return a > b ? 1 : -1;
+}
+// Semver rules: numeric identifiers compare numerically and rank below
+// alphanumeric ones, which compare in ASCII order; with equal leading
+// identifiers, the longer list ranks higher.
+function comparePrerelease(a, b) {
+    const length = Math.max(a.length, b.length);
+    for (let i = 0; i < length; i++) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === undefined)
+            return -1;
+        if (idB === undefined)
+            return 1;
+        if (idA === idB)
+            continue;
+        const numA = /^\d+$/.test(idA) ? Number(idA) : null;
+        const numB = /^\d+$/.test(idB) ? Number(idB) : null;
+        if (numA !== null && numB !== null)
+            return compareNumbers(numA, numB);
+        if (numA !== null)
+            return -1;
+        if (numB !== null)
+            return 1;
+        return idA > idB ? 1 : -1;
+    }
+    return 0;
+}
 /**
- * Compares two "x.y.z" version strings, segment by segment.
+ * Compares two version strings following semver precedence: "x.y.z"
+ * segments first (missing ones count as `0`), then pre-release identifiers
+ * (`1.0.0-beta.2` < `1.0.0-beta.10` < `1.0.0`). A leading `v` and build
+ * metadata (`+build.1`) are ignored.
  *
  * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ * @example
+ * compareVersions("1.10.0", "1.2.0"); // => 1
+ * compareVersions("1.0.0-beta", "1.0.0"); // => -1
+ * compareVersions("v2.0.0", "2.0.0"); // => 0
  */
 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);
+    const parsedA = parseVersion(a);
+    const parsedB = parseVersion(b);
+    const length = Math.max(parsedA.core.length, parsedB.core.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;
+        const result = compareNumbers(parsedA.core[i] ?? 0, parsedB.core[i] ?? 0);
+        if (result !== 0)
+            return result;
     }
-    return 0;
+    // A version without pre-release identifiers ranks above one that has some.
+    const isPrereleaseA = parsedA.prerelease.length > 0;
+    const isPrereleaseB = parsedB.prerelease.length > 0;
+    if (isPrereleaseA !== isPrereleaseB)
+        return isPrereleaseA ? -1 : 1;
+    return comparePrerelease(parsedA.prerelease, parsedB.prerelease);
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
+  "sideEffects": false,
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -21,12 +22,12 @@
     "./*": "./dist/*.js"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "5.0.2",
     "eslint": "10.7.0",
-    "jsdom": "^29.1.1",
+    "jsdom": "^30.1.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10",
-    "@forthtilliath/eslint-config": "0.7.0",
+    "vitest": "^5.0.2",
+    "@forthtilliath/eslint-config": "0.8.0",
     "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
@@ -34,7 +35,7 @@
     "build": "tsc -p tsconfig.build.json",
     "check-types": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
-    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage"