@corbet-labs/cdate 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @corbet-labs/cdate
+
+Deterministic locale-correct date formats for formal correspondence. Pure
+port of the [cdate](https://github.com/corbet-labs/cdate) Rust crate: zero
+dependencies, zero Node APIs, synchronous, no I/O.
+
+```ts
+import { longDate, monthYear } from '@corbet-labs/cdate';
+
+longDate('de-CH', 2026, 9, 7); // 7. September 2026
+monthYear('en', 2026, 9); // September 2026
+```
+
+Unknown locales fall back through the base language to English. Invalid
+calendar dates yield `null`, never a best effort. Behavior is defined by
+`tables/*.json` at the repository root; `tests/vectors/*.json` is the
+shared conformance suite.
+
+Run `bun ./scripts/conformance.mts` and `tsc --noEmit -p ./tsconfig.json`
+before pushing.
+
+## License
+
+FSL-1.1-ALv2. Each published version becomes available under Apache-2.0
+two years after publication.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@corbet-labs/cdate",
+  "version": "0.1.0",
+  "description": "Deterministic locale-correct date formats for formal correspondence. Mirrors the cdate Rust crate release line.",
+  "license": "FSL-1.1-ALv2",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/corbet-labs/cdate.git",
+    "directory": "js/@corbet-labs/cdate"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "bash ./scripts/sync-assets.sh",
+    "conformance": "bun ./scripts/conformance.mts",
+    "typecheck": "tsc --noEmit -p ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "25.8.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/generated/tables.ts

@@ -0,0 +1,3 @@
+// GENERATED by scripts/sync-assets.sh — do not edit.
+export const PACKAGE_VERSION = "0.1.0";
+export const DATES_TABLE = {"fallback": "en", "locales": {"de": {"long": "{day}. {month_long} {yyyy}", "medium": "{dd}.{mm}.{yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"], "short": "{dd}.{mm}.{yy}"}, "de-AT": {"long": "{day}. {month_long} {yyyy}", "medium": "{dd}.{mm}.{yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"], "short": "{dd}.{mm}.{yy}"}, "de-CH": {"long": "{day}. {month_long} {yyyy}", "medium": "{dd}.{mm}.{yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"], "short": "{dd}.{mm}.{yy}"}, "en": {"long": "{month_long} {day}, {yyyy}", "medium": "{month_short} {day}, {yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], "months_short": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], "short": "{month}/{day}/{yy}"}, "en-GB": {"long": "{day} {month_long} {yyyy}", "medium": "{day} {month_short} {yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], "months_short": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sept", "Oct", "Nov", "Dec"], "short": "{dd}/{mm}/{yyyy}"}, "en-US": {"long": "{month_long} {day}, {yyyy}", "medium": "{month_short} {day}, {yyyy}", "month_year": "{month_long} {yyyy}", "months_long": ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], "months_short": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], "short": "{month}/{day}/{yy}"}}, "supported": ["de", "de-AT", "de-CH", "en", "en-GB", "en-US"]};

package/src/index.ts

@@ -0,0 +1,167 @@
+/**
+ * Deterministic locale-correct date formats for formal correspondence.
+ *
+ * Pure TypeScript port of the cdate Rust crate: zero dependencies, zero
+ * Node APIs, synchronous, no I/O. Behavior is defined by `tables/*.json`
+ * at the repository root; `tests/vectors/*.json` is the shared conformance
+ * suite.
+ */
+import { DATES_TABLE } from './generated/tables.js';
+
+export interface LocaleEntry {
+    long: string;
+    medium: string;
+    short: string;
+    month_year: string;
+    months_long: string[];
+    months_short?: string[];
+}
+
+export interface DatesTable {
+    locales: Record<string, LocaleEntry>;
+    supported: string[];
+    fallback: string;
+}
+
+const table = DATES_TABLE as DatesTable;
+
+/** Lowercased table key → canonical BCP 47 key. Tables keep canonical keys
+ * for compatibility; inputs resolve case-insensitively through this index. */
+const canonicalByLower: Record<string, string> = {};
+for (const key of Object.keys(table.locales)) {
+    canonicalByLower[key.toLowerCase()] = key;
+}
+
+function baseLanguage(locale: string): string {
+    return locale.split('-')[0] ?? locale;
+}
+
+function resolveKey(locale: string): string {
+    if (Object.hasOwn(table.locales, locale)) return locale;
+    const lowered = locale.toLowerCase();
+    const exact = canonicalByLower[lowered];
+    if (exact !== undefined) return exact;
+    const base = canonicalByLower[baseLanguage(lowered)];
+    if (base !== undefined) return base;
+    return table.fallback;
+}
+
+function daysInMonth(year: number, month: number): number {
+    switch (month) {
+        case 1:
+        case 3:
+        case 5:
+        case 7:
+        case 8:
+        case 10:
+        case 12:
+            return 31;
+        case 4:
+        case 6:
+        case 9:
+        case 11:
+            return 30;
+        case 2:
+            return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+        default:
+            return 0;
+    }
+}
+
+/** Whether a proleptic Gregorian calendar date exists. */
+export function isValidDate(year: number, month: number, day: number): boolean {
+    return (
+        Number.isInteger(year) &&
+        Number.isInteger(month) &&
+        Number.isInteger(day) &&
+        month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth(year, month)
+    );
+}
+
+function padTwo(value: number): string {
+    return value < 10 ? `0${value}` : `${value}`;
+}
+
+function padYear(year: number): string {
+    const text = `${year}`;
+    if (year < 0 || year >= 1000) return text;
+    if (year >= 100) return `0${text}`;
+    if (year >= 10) return `00${text}`;
+    return `000${text}`;
+}
+
+function render(entry: LocaleEntry, pattern: string, year: number, month: number, day: number): string {
+    return pattern
+        .replaceAll('{yyyy}', padYear(year))
+        .replaceAll('{yy}', padTwo(((year % 100) + 100) % 100))
+        .replaceAll('{month_long}', entry.months_long[month - 1] ?? '')
+        .replaceAll('{month_short}', entry.months_short?.[month - 1] ?? '')
+        .replaceAll('{dd}', padTwo(day))
+        .replaceAll('{mm}', padTwo(month))
+        .replaceAll('{day}', `${day}`)
+        .replaceAll('{month}', `${month}`);
+}
+
+function formatWith(
+    locale: string,
+    select: (entry: LocaleEntry) => string,
+    year: number,
+    month: number,
+    day: number,
+): string | null {
+    if (!isValidDate(year, month, day)) return null;
+    const entry = table.locales[resolveKey(locale)];
+    if (entry === undefined) return null;
+    return render(entry, select(entry), year, month, day);
+}
+
+/**
+ * Long date for a locale: `7. September 2026` (de),
+ * `September 7, 2026` (en). Unknown locales fall back through the base
+ * language to English. Returns `null` for invalid calendar dates.
+ */
+export function longDate(locale: string, year: number, month: number, day: number): string | null {
+    return formatWith(locale, (entry) => entry.long, year, month, day);
+}
+
+/**
+ * Medium date for a locale: `07.09.2026` (de), `Sep 7, 2026` (en).
+ * Returns `null` for invalid calendar dates.
+ */
+export function mediumDate(locale: string, year: number, month: number, day: number): string | null {
+    return formatWith(locale, (entry) => entry.medium, year, month, day);
+}
+
+/**
+ * Short numeric date for a locale: `07.09.26` (de), `9/7/26` (en).
+ * Returns `null` for invalid calendar dates.
+ */
+export function shortDate(locale: string, year: number, month: number, day: number): string | null {
+    return formatWith(locale, (entry) => entry.short, year, month, day);
+}
+
+/**
+ * Month and year for a correspondence dateline: `September 2026`.
+ * Returns `null` for an invalid month.
+ */
+export function monthYear(locale: string, year: number, month: number): string | null {
+    if (!Number.isInteger(year) || !Number.isInteger(month) || month < 1 || month > 12) return null;
+    const entry = table.locales[resolveKey(locale)];
+    if (entry === undefined) return null;
+    return render(entry, entry.month_year, year, month, 1);
+}
+
+/** BCP 47 locale codes with a date-format entry, sorted. */
+export function availableLocales(): string[] {
+    return Object.keys(table.locales).sort();
+}
+
+/** Whether a locale code is supported: present in the supported set
+ * directly or through its (lowercased) base language. */
+export function isSupported(locale: string): boolean {
+    if (table.supported.includes(locale)) return true;
+    return table.supported.includes(baseLanguage(locale.toLowerCase()));
+}