@c9up/chronos 0.1.3

package/src/atlas.ts

@@ -0,0 +1,160 @@
+/**
+ * `@c9up/chronos/atlas` — Atlas column-type adapter for {@link DateTime}.
+ *
+ * Wires `Chronos.DateTime` into Atlas's `@Column({ prepare, consume })` opt-in
+ * column pipeline. Lives on a sub-export so the default `@c9up/chronos` import
+ * surface stays adapter-free.
+ *
+ * Mirrors Adonis Lucid's `@column.prepare` / `@column.consume` pattern —
+ * callbacks are baked into the entity definition; no global registry, no
+ * boot-time wiring. Same shape as `@c9up/atom/atlas` (story 35.10).
+ *
+ * Usage (imports referenced here as prose to keep this JSDoc free of literal
+ * `from "@c9up/<sibling>"` strings — that pattern would create false positives
+ * for the no-cross-package-import grep gate):
+ *
+ *     // Pull `Column`, `Entity`, `BaseEntity`, `PrimaryKey` from @c9up/atlas
+ *     // Pull `DateTime` from @c9up/chronos
+ *     // Pull `dateTimeAtlasAdapter` from @c9up/chronos/atlas
+ *
+ *     @Entity('events')
+ *     class Event extends BaseEntity {
+ *       @PrimaryKey() id!: number
+ *       @Column(dateTimeAtlasAdapter) createdAt!: DateTime | null
+ *     }
+ *
+ * @implements Story 36.14
+ */
+
+import { DateTime } from "./DateTime.js";
+
+/**
+ * Cross-realm-safe `DateTime` check. Returns `true` if `value` is either:
+ *   - a `DateTime` from the current module-realm (`instanceof` matches), OR
+ *   - a structurally-compatible `DateTime` from another realm — i.e. an
+ *     object exposing both `toISO(): string` and `equals(other): boolean`,
+ *     the two methods this adapter relies on.
+ *
+ * The fallback is needed when pnpm hoisting + transitive duplication produce
+ * two distinct `DateTime` constructors at runtime (workspace symlinks +
+ * a separately-installed copy under a parent `node_modules`). Without it,
+ * `instanceof` returns `false` for instances built from the consumer's
+ * own import, and `prepare` would reject perfectly valid `DateTime` values.
+ */
+function isDateTimeLike(value: unknown): value is DateTime {
+	if (value instanceof DateTime) return true;
+	if (value === null || typeof value !== "object") return false;
+	const obj = value as { toISO?: unknown; equals?: unknown };
+	return typeof obj.toISO === "function" && typeof obj.equals === "function";
+}
+
+/**
+ * Atlas adapter for `timestamp` / `timestamptz` / `datetime` columns.
+ * `consume` lifts string / `Date` / `number` / `bigint` DB values into a
+ * {@link DateTime}; `prepare` lowers a `DateTime` back to its ISO 8601 string
+ * for the SQL bind parameter.
+ *
+ * - `consume(null)` / `consume(undefined)` returns `null` so nullable columns
+ *   keep their semantics through the adapter pipeline.
+ * - `consume(existingDateTime)` is idempotent — re-consuming an already-
+ *   hydrated value returns the same instance untouched.
+ * - `consume(number)` and `consume(bigint)` are interpreted as **epoch
+ *   milliseconds** (matches `Date(ms)` and `DateTime.fromMillis`). If a driver
+ *   returns timestamps as integer seconds (e.g., a Postgres `int8` column
+ *   storing unix epochs), wrap them yourself: `new DateTime(seconds * 1000)`.
+ * - `prepare(null)` / `prepare(undefined)` returns `null` symmetrically.
+ * - `prepare` rejects anything that is not a `DateTime` instance — protects
+ *   against the common "I forgot to wrap" footgun where a JS `Date` or ISO
+ *   string would otherwise silently land in the bind parameter and bypass the
+ *   chronos engine's normalization.
+ *
+ * **Round-trip canonicalization:** chronos's internal ISO normalization
+ * collapses trailing `.000Z` to a bare `Z`. So
+ * `prepare(consume('2026-04-30T12:00:00.000Z'))` returns
+ * `'2026-04-30T12:00:00Z'` — same instant, compact form. Subsecond precision
+ * with non-zero digits (e.g., `.123Z`) is preserved verbatim.
+ *
+ * **Driver expectations:** `timestamp` columns may come back from the driver
+ * as either an ISO 8601 `string`, a JS `Date`, or (rarely) an integer epoch.
+ * `node-postgres` returns `Date` for `timestamp` / `timestamptz` by default;
+ * SQLite returns whatever the bound type was; configuring drivers to emit
+ * ISO strings or `Date` is the supported path. Strings that are NOT parseable
+ * ISO 8601 will surface a `RangeError: Invalid time value` from the
+ * underlying `Date` constructor — align your DB column / driver settings with
+ * ISO 8601 wire format.
+ *
+ * **Timezone handling — UTC-only:** chronos's internal storage is always UTC.
+ * Consequences for this adapter:
+ *   - Z-suffixed ISO (`'2026-04-30T12:00:00Z'`) → exactly UTC, no
+ *     transformation.
+ *   - Offset-bearing ISO (`'2026-04-30T12:00:00+02:00'`) → silently
+ *     UTC-rebased to `'2026-04-30T10:00:00Z'`. The original offset is NOT
+ *     preserved on round-trip. Pair with `timestamptz` columns (the only
+ *     SQL type whose contract is "store UTC instant"). Do **not** use this
+ *     adapter for `timestamp without time zone` columns where wall-clock
+ *     fidelity matters — you will lose the offset on read and silently
+ *     rebase on write.
+ *   - Naive ISO (`'2026-04-30T12:00:00'` or SQLite-style
+ *     `'2026-04-30 12:00:00'`, no `Z`, no offset) → parsed by `new Date(...)`
+ *     in the JS runtime's **local** zone. This means the same DB row hydrates
+ *     differently across machines (CI host on UTC vs. dev laptop in
+ *     Europe/Zurich). Do **not** store naive timestamps in columns reaching
+ *     this adapter; configure your DB / driver to emit Z-suffixed strings or
+ *     `Date` instances, or pre-process via `DateTime.fromSQL`.
+ *
+ * **Stacking caveat with `@column.dateTime({ autoCreate, autoUpdate })`:**
+ * the auto-timestamp decorator (story 32.8) writes `new Date()` (a JS `Date`)
+ * to the entity property when `autoCreate` / `autoUpdate` is set. If you
+ * ALSO tag the same property with `@Column(dateTimeAtlasAdapter)`, `prepare`
+ * will receive a `Date` and throw the "expected a DateTime instance"
+ * `TypeError` at INSERT / UPDATE time. **Only the `autoCreate` / `autoUpdate`
+ * flags conflict** — plain `@column.dateTime()` (no flags) does not write
+ * anything and is safe to stack. Mitigations when you need auto-timestamps:
+ *   - **Adapter only**: drop `@column.dateTime({ autoCreate, autoUpdate })`
+ *     and assign manually (e.g., in a model hook:
+ *     `entity.createdAt = DateTime.now()`).
+ *   - **`@column.dateTime({ ... })` only**: drop the adapter and manually
+ *     wrap reads with `new DateTime(row.createdAt)` at the call site.
+ * The adapter does NOT silently coerce `Date` → `DateTime` because that
+ * would mask the inconsistency between the two mechanisms.
+ *
+ * The shape `{ prepare, consume }` is **passable directly** to `@Column(...)`:
+ * `@Column(dateTimeAtlasAdapter)` is identical to
+ * `@Column({ prepare: dateTimeAtlasAdapter.prepare, consume: dateTimeAtlasAdapter.consume })`.
+ *
+ * The exported object is `Object.freeze`d, which blocks the most common
+ * direct-assignment tampering of the adapter's own slots. `Object.freeze`
+ * is shallow: prototype-level mutation of `DateTime` itself, or wholesale
+ * replacement via `structuredClone(adapter)` followed by re-binding, are
+ * out of scope for the freeze defense.
+ *
+ * **Cross-realm safety:** `consume` and `prepare` test the input via a
+ * structural duck-typed check (`toISO` + `equals` methods present), not a
+ * plain `instanceof DateTime`. This protects against pnpm-hoisting quirks
+ * where a consumer's `DateTime` import resolves to a duplicate copy of the
+ * class — the adapter still recognizes it as a `DateTime` and round-trips
+ * cleanly.
+ */
+export const dateTimeAtlasAdapter = Object.freeze({
+	consume(raw: unknown): DateTime | null {
+		if (raw === null || raw === undefined) return null;
+		if (isDateTimeLike(raw)) return raw;
+		if (raw instanceof Date) return DateTime.fromJSDate(raw);
+		if (typeof raw === "string") return new DateTime(raw);
+		if (typeof raw === "number") return DateTime.fromMillis(raw);
+		if (typeof raw === "bigint") return DateTime.fromMillis(Number(raw));
+		throw new TypeError(
+			`dateTimeAtlasAdapter.consume: expected string | Date | DateTime | number | bigint | null, got ${typeof raw}`,
+		);
+	},
+	prepare(value: unknown): string | null {
+		if (value === null || value === undefined) return null;
+		if (!isDateTimeLike(value)) {
+			throw new TypeError(
+				`dateTimeAtlasAdapter.prepare: expected a DateTime instance, got ${typeof value === "object" ? Object.prototype.toString.call(value) : typeof value}. ` +
+					"Wrap the value with `new DateTime(...)` before assigning to a column tagged with this adapter.",
+			);
+		}
+		return value.toISO();
+	},
+});

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @c9up/chronos — advanced date/time and recurrence.
+ * The Rust N-API binary is required — there is no JS/TS fallback.
+ */
+
+export type {
+	BoundUnit,
+	CalendarParts,
+	DateInput,
+	DateRange,
+	DateUnit,
+	RangeCompareOptions,
+	RangeRelation,
+} from "./DateTime.js";
+export {
+	analyzeRange,
+	containsRange,
+	DateTime,
+	inRange,
+	overlapsRange,
+} from "./DateTime.js";
+export type { DurationObject, DurationUnit } from "./Duration.js";
+export { Duration } from "./Duration.js";
+export { Interval } from "./Interval.js";
+export type { RRuleBuild } from "./rrule.js";
+export { expandRRule, toRRuleString } from "./rrule.js";
+
+// `isNativeAvailable` removed — NAPI is now mandatory (no fallback).
+
+import {
+	analyzeRange,
+	containsRange,
+	type DateRange,
+	DateTime,
+	type DateUnit,
+	inRange,
+	overlapsRange,
+	type RangeCompareOptions,
+} from "./DateTime.js";
+import { expandRRule, type RRuleBuild, toRRuleString } from "./rrule.js";
+
+export function at(input?: string | Date): DateTime {
+	return new DateTime(input);
+}
+
+export const Chronos = {
+	at,
+	now: (): DateTime => new DateTime(),
+	parse: (input: string | Date): DateTime => new DateTime(input),
+	add: (input: string | Date, amount: number, unit: DateUnit): DateTime =>
+		new DateTime(input).plus(amount, unit),
+	subtract: (input: string | Date, amount: number, unit: DateUnit): DateTime =>
+		new DateTime(input).minus(amount, unit),
+	diff: (a: string | Date, b: string | Date, unit: DateUnit): number =>
+		new DateTime(a).diff(b, unit),
+	inRange,
+	rangeContains: (
+		outer: DateRange,
+		inner: DateRange,
+		options?: RangeCompareOptions,
+	): boolean => containsRange(outer, inner, options),
+	rangesOverlap: (
+		a: DateRange,
+		b: DateRange,
+		options?: RangeCompareOptions,
+	): boolean => overlapsRange(a, b, options),
+	rangeRelation: (a: DateRange, b: DateRange, options?: RangeCompareOptions) =>
+		analyzeRange(a, b, options),
+	rrule: (
+		startIso: string,
+		rrule: string | RRuleBuild,
+		limit = 100,
+	): string[] => expandRRule(startIso, rrule, limit),
+	buildRRule: (rule: RRuleBuild): string => toRRuleString(rule),
+};

package/src/native.ts

@@ -0,0 +1,124 @@
+/**
+ * Universal engine loader — auto-detects Node (NAPI) vs Browser (WASM).
+ *
+ * **No fallback.** If neither NAPI nor WASM loads, `nativeChronos()` throws
+ * immediately. Chronos operations (timezone, DST, RFC 5545) are too complex
+ * for a pure-TS fallback.
+ */
+
+export interface NativeChronos {
+	add(iso: string, amount: number, unit: string): string;
+	diff(aIso: string, bIso: string, unit: string): number;
+	startOf(iso: string, unit: string): string;
+	endOf(iso: string, unit: string): string;
+	format(iso: string, pattern: string): string;
+	validateTimezone(zone: string): string;
+	toZone(
+		utcIso: string,
+		zone: string,
+	): { iso: string; offsetMinutes: number; zoneName: string };
+	addInZone(utcIso: string, amount: number, unit: string, zone: string): string;
+	diffInZone(aUtc: string, bUtc: string, unit: string, zone: string): number;
+	zoneOffset(utcIso: string, zone: string): number;
+	fromLocal(naiveIso: string, zone: string): string;
+	parseRfc2822(input: string): string;
+	parseSql(input: string): string;
+	parseHttp(input: string): string;
+	rruleExpand(startIso: string, rrule: string, limit: number): string[];
+	calendarParts(iso: string): {
+		year: number;
+		month: number;
+		day: number;
+		hour: number;
+		minute: number;
+		second: number;
+		millisecond: number;
+		weekday: number;
+		weekNumber: number;
+		weekYear: number;
+		ordinal: number;
+		quarter: number;
+		daysInMonth: number;
+		daysInYear: number;
+		isLeapYear: boolean;
+	};
+}
+
+let native: NativeChronos | undefined;
+let loadError: unknown;
+
+const isNode =
+	typeof globalThis.process !== "undefined" &&
+	typeof globalThis.process.versions?.node === "string";
+
+if (isNode) {
+	try {
+		const { createRequire } = await import("node:module");
+		const { dirname, join } = await import("node:path");
+		const { fileURLToPath } = await import("node:url");
+		const { arch, platform } = await import("node:process");
+
+		const nodeRequire = createRequire(import.meta.url);
+		const currentDir = dirname(fileURLToPath(import.meta.url));
+
+		const platformMap: Record<string, string> = {
+			"linux-x64": "linux-x64-gnu",
+			"linux-arm64": "linux-arm64-gnu",
+			"darwin-x64": "darwin-x64",
+			"darwin-arm64": "darwin-arm64",
+			"win32-x64": "win32-x64-msvc",
+		};
+
+		const suffix = platformMap[`${platform}-${arch}`];
+		if (suffix) {
+			native = nodeRequire(join(currentDir, `../index.${suffix}.node`));
+		}
+	} catch (e) {
+		loadError = e;
+	}
+} else {
+	try {
+		// wasm-bindgen preserves Rust snake_case names (start_of, end_of, etc.)
+		// while NAPI-RS auto-converts to camelCase. We adapt the WASM module
+		// shape (which uses bigint for large integers) to the NativeChronos
+		// interface (number-based), so consumers don't deal with the difference.
+		const wasm = await import("../wasm/chronos_engine_wasm.js");
+		await wasm.default();
+		native = {
+			add: (iso, amount, unit) => wasm.add(iso, BigInt(amount), unit),
+			diff: (a, b, unit) => Number(wasm.diff(a, b, unit)),
+			startOf: (iso, unit) => wasm.start_of(iso, unit),
+			endOf: (iso, unit) => wasm.end_of(iso, unit),
+			format: (iso, pattern) => wasm.format(iso, pattern),
+			validateTimezone: (zone) => wasm.validate_timezone(zone),
+			toZone: (iso, zone) => wasm.to_zone(iso, zone),
+			addInZone: (iso, amount, unit, zone) =>
+				wasm.add_in_zone(iso, BigInt(amount), unit, zone),
+			diffInZone: (a, b, unit, zone) =>
+				Number(wasm.diff_in_zone(a, b, unit, zone)),
+			zoneOffset: (iso, zone) => wasm.zone_offset(iso, zone),
+			fromLocal: (naive, zone) => wasm.from_local(naive, zone),
+			parseRfc2822: (input) => wasm.parse_rfc2822(input),
+			parseSql: (input) => wasm.parse_sql(input),
+			parseHttp: (input) => wasm.parse_http(input),
+			rruleExpand: (start, rrule, limit) =>
+				wasm.rrule_expand(start, rrule, limit),
+			calendarParts: (iso) => wasm.calendar_parts(iso),
+		};
+	} catch (e) {
+		loadError = e;
+	}
+}
+
+export function nativeChronos(): NativeChronos {
+	if (!native) {
+		throw new Error(
+			`[CHRONOS_ENGINE_REQUIRED] The Chronos engine is required but not loaded.\n` +
+				`  Environment: ${isNode ? "Node" : "Browser"}\n` +
+				`  Reason: ${loadError ?? "binary not found"}\n` +
+				`  Fix (Node): cd packages/chronos && pnpm build:napi\n` +
+				`  Fix (Browser): cd packages/chronos && pnpm build:wasm`,
+		);
+	}
+	return native;
+}

package/src/rrule.ts

@@ -0,0 +1,102 @@
+import { nativeChronos } from "./native.js";
+
+export type RRuleWeekday = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
+export type RRuleByDayToken = RRuleWeekday | `${number}${RRuleWeekday}`;
+
+export interface RRuleBuild {
+	freq:
+		| "SECONDLY"
+		| "MINUTELY"
+		| "HOURLY"
+		| "DAILY"
+		| "WEEKLY"
+		| "MONTHLY"
+		| "YEARLY";
+	interval?: number;
+	wkst?: RRuleWeekday;
+	byDay?: RRuleByDayToken[];
+	byMonthDay?: number[];
+	byMonth?: number[];
+	byWeekNo?: number[];
+	byYearDay?: number[];
+	bySetPos?: number[];
+	byHour?: number[];
+	byMinute?: number[];
+	bySecond?: number[];
+	count?: number;
+	until?: string;
+}
+
+function pushNumericList(
+	parts: string[],
+	key: string,
+	values: number[] | undefined,
+): void {
+	if (!values || values.length === 0) return;
+	parts.push(`${key}=${values.join(",")}`);
+}
+
+export function toRRuleString(rule: RRuleBuild): string {
+	const parts: string[] = [`FREQ=${rule.freq}`];
+
+	if (rule.interval && rule.interval !== 1)
+		parts.push(`INTERVAL=${rule.interval}`);
+	if (rule.wkst) parts.push(`WKST=${rule.wkst}`);
+	if (rule.byDay?.length) parts.push(`BYDAY=${rule.byDay.join(",")}`);
+
+	pushNumericList(parts, "BYMONTHDAY", rule.byMonthDay);
+	pushNumericList(parts, "BYMONTH", rule.byMonth);
+	pushNumericList(parts, "BYWEEKNO", rule.byWeekNo);
+	pushNumericList(parts, "BYYEARDAY", rule.byYearDay);
+	pushNumericList(parts, "BYSETPOS", rule.bySetPos);
+	pushNumericList(parts, "BYHOUR", rule.byHour);
+	pushNumericList(parts, "BYMINUTE", rule.byMinute);
+	pushNumericList(parts, "BYSECOND", rule.bySecond);
+
+	if (rule.count !== undefined) parts.push(`COUNT=${rule.count}`);
+	if (rule.until) {
+		// RFC 5545 §3.3.10 UNTIL format: YYYYMMDDTHHMMSSZ (no hyphens/colons/ms).
+		parts.push(
+			`UNTIL=${new Date(rule.until)
+				.toISOString()
+				.replace(/[-:]/g, "")
+				.replace(/\.\d+Z$/, "Z")}`,
+		);
+	}
+
+	return parts.join(";");
+}
+
+/**
+ * Expand an RRULE into concrete occurrence dates. **NAPI-only** — the Rust
+ * engine handles the full RFC 5545 spec (BYDAY, BYSETPOS, BYMONTHDAY,
+ * BYWEEKNO, BYYEARDAY, UNTIL, COUNT, INTERVAL, WKST). No TS fallback.
+ */
+/**
+ * Hard cap on `expandRRule(... , limit)` so a caller passing an absurd
+ * number (or one derived from user input) can't ask the Rust engine to
+ * allocate gigabytes / run for seconds. 10_000 covers any realistic
+ * pagination + cushion (a year of every-minute occurrences = ~525k, so
+ * apps wanting that should iterate or stream, not call once).
+ */
+const MAX_RRULE_EXPAND = 10_000;
+
+export function expandRRule(
+	startIso: string,
+	rrule: string | RRuleBuild,
+	limit = 100,
+): string[] {
+	if (!Number.isInteger(limit) || limit < 1) {
+		throw new RangeError(
+			`expandRRule(limit) must be a positive integer (got ${String(limit)})`,
+		);
+	}
+	if (limit > MAX_RRULE_EXPAND) {
+		throw new RangeError(
+			`expandRRule(limit=${limit}) exceeds the safety cap of ${MAX_RRULE_EXPAND}. ` +
+				"Page through the result set instead of asking for everything at once.",
+		);
+	}
+	const built = typeof rrule === "string" ? rrule : toRRuleString(rrule);
+	return nativeChronos().rruleExpand(startIso, built, limit);
+}

package/src/utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared helpers for DateTime and RRule modules.
+ */
+
+/**
+ * Normalize an ISO 8601 string: strip the `.000` when subseconds are zero
+ * for compact output that matches `new Date(iso).toISOString().replace('.000Z', 'Z')`.
+ * When subseconds are non-zero, preserve them so precision isn't silently lost.
+ */
+export function normalizeIso(iso: string): string {
+	return iso.replace(".000Z", "Z");
+}

package/wasm/chronos_engine_wasm.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Type stub for the WASM module emitted by `wasm-pack build` during the
+ * chronos release pipeline. The actual `.js` + `.wasm` artifacts are not
+ * checked into the source tree; they live alongside this `.d.ts` at
+ * publish time so the browser/edge fallback path in `src/native.ts`
+ * resolves at runtime. The stub lets `tsc --noEmit` typecheck during
+ * development without forcing every contributor to run `wasm-pack`.
+ *
+ * Signature mirrors the wasm-bindgen-generated `chronos_engine_wasm.js`,
+ * preserving Rust snake_case names that `src/native.ts` adapts to the
+ * camelCase `NativeChronos` interface.
+ */
+export default function init(): Promise<unknown>;
+export function add(iso: string, amount: bigint, unit: string): string;
+export function diff(a: string, b: string, unit: string): bigint;
+export function start_of(iso: string, unit: string): string;
+export function end_of(iso: string, unit: string): string;
+export function format(iso: string, pattern: string): string;
+export function validate_timezone(zone: string): string;
+export function to_zone(
+	iso: string,
+	zone: string,
+): { iso: string; offsetMinutes: number; zoneName: string };
+export function add_in_zone(
+	iso: string,
+	amount: bigint,
+	unit: string,
+	zone: string,
+): string;
+export function diff_in_zone(
+	a: string,
+	b: string,
+	unit: string,
+	zone: string,
+): bigint;
+export function zone_offset(iso: string, zone: string): number;
+export function from_local(naive: string, zone: string): string;
+export function parse_rfc2822(input: string): string;
+export function parse_sql(input: string): string;
+export function parse_http(input: string): string;
+export function rrule_expand(
+	start: string,
+	rrule: string,
+	limit: number,
+): string[];
+export function calendar_parts(iso: string): {
+	year: number;
+	month: number;
+	day: number;
+	hour: number;
+	minute: number;
+	second: number;
+	millisecond: number;
+	weekday: number;
+	weekNumber: number;
+	weekYear: number;
+	ordinal: number;
+	quarter: number;
+	daysInMonth: number;
+	daysInYear: number;
+	isLeapYear: boolean;
+};