@c9up/helix 0.1.3 → 0.1.4

package/dist/time/freeze.js

@@ -0,0 +1,184 @@
+/**
+ * Time freeze / travel — ergonomic surface over `vi.setSystemTime`
+ * with per-test auto-restore.
+ *
+ * **Helix is agnostic — no cross-package imports.** This module
+ * never imports `@c9up/chronos`. The clock pin happens entirely
+ * through `vi.setSystemTime` (which shims `globalThis.Date`); any
+ * code in user-land that calls `new Date()` — chronos `DateTime`
+ * included — picks up the frozen epoch automatically.
+ *
+ * Calendar arithmetic for `month` / `year` uses `Date.UTC` math
+ * locally so we don't take a runtime dependency on chronos.
+ *
+ * **Concurrency note.** `vi.setSystemTime` writes to the `vi`
+ * context that wraps the current test FILE (`withViContext`), not
+ * the per-test frame (`withTestContext`). Two `withTestContext`
+ * frames running in parallel inside the same file (e.g. via
+ * `Promise.all([withTestContext(A), withTestContext(B)])`) share
+ * one Date shim — A's freeze leaks into B. The helix runtime
+ * executes tests strictly sequentially (`runSuite`'s for-await
+ * loop), so this is not reachable through the documented test
+ * path. Callers who manually compose `withTestContext` in parallel
+ * inside a single file must serialise their freezes themselves.
+ */
+import { inTestContext, registerTestCleanup } from "../runtime/test-context.js";
+import { vi } from "../runtime/vi/index.js";
+/** JS `Date` represents instants from `-8.64e15` to `+8.64e15` ms.
+ *  Anything beyond becomes "Invalid Date" — refuse early so callers
+ *  see a clear error instead of `setSystemTime(NaN)` downstream. */
+const JS_DATE_MAX = 8_640_000_000_000_000;
+/**
+ * Pin `Date.now()` / `new Date()` (and anything that reads through
+ * them — e.g. `DateTime.now()`) to the given moment. Auto-restored
+ * at end-of-test via the helix test frame, so a forgotten
+ * `unfreeze()` does not leak into the next test.
+ *
+ * Throws when called outside a test frame — a queued cleanup would
+ * never fire there, so the freeze would leak across tests silently.
+ */
+export function freeze(input) {
+    requireTestContext("freeze");
+    const ms = inputToMs(input);
+    vi.setSystemTime(ms);
+    registerTestCleanup(() => {
+        vi.useRealSystemTime();
+    });
+}
+/**
+ * Advance the clock by `amount` × `unit`. If the clock isn't frozen
+ * yet, freezes it relative to the real `Date.now()` first, then
+ * applies the delta — so a one-shot `time.travel(7, 'day')` works
+ * without an explicit `freeze()`.
+ *
+ * Always queues a cleanup so the auto-restore path is uniform —
+ * cleanups are idempotent (each calls `vi.useRealSystemTime`),
+ * accumulating closures across many `travel` calls in one test is
+ * intentional and cheap.
+ *
+ * Throws when called outside a test frame, same reason as `freeze`.
+ */
+export function travel(amount, unit = "ms") {
+    requireTestContext("travel");
+    if (!Number.isFinite(amount)) {
+        throw new Error(`helix.time.travel: amount must be finite, got ${amount}.`);
+    }
+    if ((unit === "month" || unit === "year") && !Number.isInteger(amount)) {
+        throw new Error(`helix.time.travel: '${unit}' requires an integer amount, got ${amount}. Calendar units don't compose cleanly with fractions.`);
+    }
+    const base = vi.getMockedSystemTime() ?? Date.now();
+    const next = applyDelta(base, amount, unit);
+    requireInDateRange(next, "travel");
+    vi.setSystemTime(next);
+    // Always queue — `vi.useRealSystemTime` is idempotent so duplicate
+    // cleanups across `freeze + travel` are harmless. Always-queue
+    // guards against the "user pinned via raw `vi.setSystemTime`,
+    // then called `travel`" trap where the heuristic would skip.
+    registerTestCleanup(() => {
+        vi.useRealSystemTime();
+    });
+}
+/**
+ * Travel TO a specific moment. Equivalent to `freeze(target)` —
+ * exists as an explicit verb so "travel to 2026" reads better than
+ * "freeze at 2026" in tests.
+ */
+export function travelTo(target) {
+    freeze(target);
+}
+/**
+ * Restore the real system clock immediately. Idempotent — safe to
+ * call when not currently frozen. Auto-restore still fires at
+ * end-of-test, so calling `unfreeze` early is purely a
+ * test-readability choice.
+ */
+export function unfreeze() {
+    vi.useRealSystemTime();
+}
+/**
+ * Read the currently frozen epoch, or `null` when running on real
+ * time. Useful for tests that compose `freeze` with their own clock
+ * arithmetic.
+ */
+export function frozenAt() {
+    return vi.getMockedSystemTime();
+}
+function requireTestContext(verb) {
+    if (!inTestContext()) {
+        throw new Error(`helix.time.${verb}: must be called inside a test (no active test frame). Calls from top-level setup leak across tests — use vi.setSystemTime directly with manual cleanup if that is what you want.`);
+    }
+}
+function inputToMs(input) {
+    let ms;
+    if (typeof input === "number") {
+        ms = input;
+    }
+    else if (input instanceof Date) {
+        ms = input.getTime();
+    }
+    else if (typeof input === "string") {
+        ms = Date.parse(input);
+        if (Number.isNaN(ms)) {
+            throw new Error(`helix.time: cannot parse '${input}' as a date — pass an ISO 8601 string, Date, number (epoch ms), or an object with toMillis().`);
+        }
+    }
+    else if (typeof input === "object" &&
+        input !== null &&
+        typeof input.toMillis === "function") {
+        const result = input.toMillis();
+        if (typeof result !== "number") {
+            throw new Error(`helix.time: input.toMillis() must return a number, got ${typeof result}.`);
+        }
+        ms = result;
+    }
+    else {
+        throw new Error(`helix.time: unsupported input type ${typeof input}. Use string / Date / number / { toMillis() }.`);
+    }
+    requireInDateRange(ms, "freeze");
+    return ms;
+}
+function requireInDateRange(ms, verb) {
+    if (!Number.isFinite(ms)) {
+        throw new Error(`helix.time.${verb}: epoch must be finite, got ${ms}. (Did you pass an Invalid Date or a NaN?)`);
+    }
+    if (Math.abs(ms) > JS_DATE_MAX) {
+        throw new Error(`helix.time.${verb}: epoch ${ms} exceeds the JS Date range (±8.64e15 ms). The resulting clock would be 'Invalid Date'.`);
+    }
+}
+function applyDelta(base, amount, unit) {
+    switch (unit) {
+        case "ms":
+            return base + amount;
+        case "second":
+            return base + amount * 1_000;
+        case "minute":
+            return base + amount * 60_000;
+        case "hour":
+            return base + amount * 3_600_000;
+        case "day":
+            return base + amount * 86_400_000;
+        case "week":
+            return base + amount * 604_800_000;
+        case "month":
+        case "year": {
+            // UTC calendar math — JS `Date` mutators handle month
+            // overflow (e.g. month 13 → year+1 month 1) and clamp
+            // month-end days (e.g. Jan 31 + 1 month → Feb 28/29).
+            const d = new Date(base);
+            if (unit === "year") {
+                d.setUTCFullYear(d.getUTCFullYear() + amount);
+            }
+            else {
+                d.setUTCMonth(d.getUTCMonth() + amount);
+            }
+            return d.getTime();
+        }
+        default: {
+            // Defensive — TS narrows this branch to `never`, but a
+            // runtime cast (`unit as TimeUnit`) could land here.
+            const exhaustive = unit;
+            throw new Error(`helix.time.travel: unknown unit '${exhaustive}'.`);
+        }
+    }
+}
+//# sourceMappingURL=freeze.js.map

package/dist/time/freeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.js","sourceRoot":"","sources":["../../src/time/freeze.ts"],"names":[],"mappings":"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"}

package/dist/time/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@c9up/helix/time` — time freeze / travel for tests.
+ *
+ * Pins `Date.now()`, `new Date()`, and `DateTime.now()` to a fake
+ * epoch. Auto-restored after each test via the per-test frame.
+ *
+ *   import { time } from "@c9up/helix";
+ *
+ *   time.freeze("2026-01-01");
+ *   // ... test that depends on a fixed clock
+ *   time.travel(7, "day");
+ *   expect(DateTime.now().toISO()).toMatch(/^2026-01-08/);
+ */
+export type { TimeUnit } from "./freeze.js";
+export { freeze, frozenAt, travel, travelTo, unfreeze } from "./freeze.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/time/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/time/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@c9up/helix/time` — time freeze / travel for tests.
+ *
+ * Pins `Date.now()`, `new Date()`, and `DateTime.now()` to a fake
+ * epoch. Auto-restored after each test via the per-test frame.
+ *
+ *   import { time } from "@c9up/helix";
+ *
+ *   time.freeze("2026-01-01");
+ *   // ... test that depends on a fixed clock
+ *   time.travel(7, "day");
+ *   expect(DateTime.now().toISO()).toMatch(/^2026-01-08/);
+ */
+export { freeze, frozenAt, travel, travelTo, unfreeze } from "./freeze.js";
+//# sourceMappingURL=index.js.map

package/dist/time/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/time/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/helix",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Helix — framework-agnostic test runtime for the Ream ecosystem (Vitest-compatible runner, spies, container overrides, time-travel). Per-package fakes live in each package's /testing.",
   "license": "MIT",
   "type": "module",