@c9up/helix 0.1.3 → 0.1.4

package/dist/runtime/vi/spyOn.js

@@ -0,0 +1,121 @@
+/**
+ * `vi.spyOn(obj, key)` — replaces `obj[key]` with a spy that calls through
+ * to the original. `spy.mockRestore()` puts the original back.
+ *
+ * Supports:
+ *   - data properties whose value is a function (most methods);
+ *   - accessor properties (`get` / `set`);
+ *   - methods inherited via the prototype chain (the spy is installed as an
+ *     own property on the target, and `mockRestore()` deletes the own
+ *     property so inheritance resumes).
+ *
+ * `this` binding: the spy's default implementation uses a `function` form
+ * (not arrow) so the caller's receiver is forwarded to the original. This
+ * is essential when spying on a prototype method that depends on `this`.
+ *
+ * Double-spy detection: throws if the property is already a Helix spy, to
+ * avoid the subtle double-counting bug where the inner spy's `calls` is
+ * incremented by pass-through from the outer one.
+ */
+import { createSpy, isSpy } from "./spy.js";
+function findDescriptor(obj, key) {
+    let cursor = obj;
+    while (cursor !== null) {
+        const desc = Object.getOwnPropertyDescriptor(cursor, key);
+        if (desc) {
+            return { descriptor: desc, onPrototype: cursor !== obj };
+        }
+        cursor = Object.getPrototypeOf(cursor);
+    }
+    throw new Error(`vi.spyOn: property "${String(key)}" does not exist on the target`);
+}
+function buildRestore(obj, key, ownDescBefore, onPrototype) {
+    return () => {
+        if (onPrototype && !ownDescBefore) {
+            Reflect.deleteProperty(obj, key);
+            return;
+        }
+        if (ownDescBefore) {
+            Object.defineProperty(obj, key, ownDescBefore);
+        }
+    };
+}
+export function spyOn(obj, key, options = {}) {
+    const label = String(key);
+    const { descriptor, onPrototype } = findDescriptor(obj, key);
+    const ownDescBefore = Object.getOwnPropertyDescriptor(obj, key);
+    // Double-spy guard: refuse to spy on an already-spied value.
+    if (descriptor.value !== undefined && isSpy(descriptor.value)) {
+        throw new Error(`vi.spyOn: "${label}" is already a spy. Call mockRestore() before spying again.`);
+    }
+    const restore = buildRestore(obj, key, ownDescBefore, onPrototype);
+    if (descriptor.get || descriptor.set) {
+        const kind = options.accessor ?? "get";
+        const originalGet = descriptor.get;
+        const originalSet = descriptor.set;
+        if (kind === "get") {
+            if (!originalGet) {
+                throw new Error(`vi.spyOn: "${label}" has no getter (pass { accessor: "set" } to spy on the setter)`);
+            }
+            // Use `function` so the shim + spy forward the caller's `this`.
+            const spy = createSpy({
+                name: label,
+                defaultImplementation: function () {
+                    return originalGet.call(this);
+                },
+            });
+            Object.defineProperty(obj, key, {
+                configurable: true,
+                enumerable: descriptor.enumerable ?? true,
+                get() {
+                    return spy.call(this);
+                },
+                set: originalSet,
+            });
+            spy.__setRestore(restore);
+            return spy;
+        }
+        if (!originalSet) {
+            throw new Error(`vi.spyOn: "${label}" has no setter`);
+        }
+        const spy = createSpy({
+            name: label,
+            defaultImplementation: function (v) {
+                originalSet.call(this, v);
+            },
+        });
+        Object.defineProperty(obj, key, {
+            configurable: true,
+            enumerable: descriptor.enumerable ?? true,
+            get: originalGet,
+            set(v) {
+                spy.call(this, v);
+            },
+        });
+        spy.__setRestore(restore);
+        return spy;
+    }
+    const originalValue = descriptor.value;
+    if (typeof originalValue !== "function") {
+        throw new Error(`vi.spyOn: "${label}" is not a function (got ${typeof originalValue}). Pass { accessor } for accessors.`);
+    }
+    const originalFn = originalValue;
+    const spy = createSpy({
+        name: label,
+        defaultImplementation: function (...args) {
+            // `this` is the call-site receiver (e.g. the class instance); the
+            // original method is forwarded its real receiver. Fixes the bug
+            // where `spyOn(Proto, 'method')` used to hard-bind `this = Proto`.
+            return originalFn.apply(this, args);
+        },
+    });
+    Object.defineProperty(obj, key, {
+        configurable: true,
+        enumerable: descriptor.enumerable ?? true,
+        writable: descriptor.writable ?? true,
+        value: spy,
+    });
+    spy.__setRestore(restore);
+    return spy;
+}
+//# sourceMappingURL=spyOn.js.map

package/dist/runtime/vi/spyOn.js.map

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

package/dist/runtime/vi/system-time.d.ts

@@ -0,0 +1,30 @@
+/**
+ * System-time control — pins `Date.now()` and `new Date()` to a fake
+ * epoch. Each `ViContext` owns its own `SystemClock` instance; the Date
+ * shim read-through to `context.fakeEpoch`, so concurrent test files
+ * never share wall-clock state (AC 6 isolation).
+ *
+ * The shim is installed globally on first activation across ANY context
+ * (Date is a singleton per realm), but the shim ALWAYS reads from the
+ * currently-active context via the `readContext` resolver passed in. When
+ * all contexts deactivate, the shim uninstalls.
+ */
+export interface SystemClock {
+    /** Fake epoch in ms, or `null` if this context is on real time. */
+    fakeEpoch: number | null;
+}
+export declare function createSystemClock(): SystemClock;
+/**
+ * Register one context's interest in the Date shim. Returns an
+ * unregister function.
+ */
+type ContextResolver = () => SystemClock | undefined;
+export declare function registerSystemClockContext(resolver: ContextResolver): () => void;
+export declare function setFakeEpoch(clock: SystemClock, time: Date | number): void;
+export declare function clearFakeEpoch(clock: SystemClock): void;
+/** Get the original `Date.now` even after the shim is installed. */
+export declare function getRealNow(): number;
+/** Get the original `Date` constructor. */
+export declare function getRealDate(): DateConstructor;
+export {};
+//# sourceMappingURL=system-time.d.ts.map

package/dist/runtime/vi/system-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-time.d.ts","sourceRoot":"","sources":["../../../src/runtime/vi/system-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,WAAW;IAC3B,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED;;;GAGG;AACH,KAAK,eAAe,GAAG,MAAM,WAAW,GAAG,SAAS,CAAC;AAerD,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,eAAe,GACvB,MAAM,IAAI,CAOZ;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAe1E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAEvD;AAuCD,oEAAoE;AACpE,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,IAAI,eAAe,CAE7C"}

package/dist/runtime/vi/system-time.js

@@ -0,0 +1,100 @@
+/**
+ * System-time control — pins `Date.now()` and `new Date()` to a fake
+ * epoch. Each `ViContext` owns its own `SystemClock` instance; the Date
+ * shim read-through to `context.fakeEpoch`, so concurrent test files
+ * never share wall-clock state (AC 6 isolation).
+ *
+ * The shim is installed globally on first activation across ANY context
+ * (Date is a singleton per realm), but the shim ALWAYS reads from the
+ * currently-active context via the `readContext` resolver passed in. When
+ * all contexts deactivate, the shim uninstalls.
+ */
+const OriginalDate = globalThis.Date;
+const originalNow = OriginalDate.now.bind(OriginalDate);
+export function createSystemClock() {
+    return { fakeEpoch: null };
+}
+const resolvers = new Set();
+let installed = false;
+function resolveEpoch() {
+    for (const resolve of resolvers) {
+        const ctx = resolve();
+        if (ctx?.fakeEpoch !== null && ctx?.fakeEpoch !== undefined) {
+            return ctx.fakeEpoch;
+        }
+    }
+    return null;
+}
+export function registerSystemClockContext(resolver) {
+    resolvers.add(resolver);
+    install();
+    return () => {
+        resolvers.delete(resolver);
+        if (resolvers.size === 0)
+            restore();
+    };
+}
+export function setFakeEpoch(clock, time) {
+    let epoch;
+    if (time instanceof OriginalDate) {
+        epoch = time.getTime();
+    }
+    else if (typeof time === "number") {
+        epoch = time;
+    }
+    else {
+        throw new Error(`vi.setSystemTime: expected Date or number, got ${typeof time}`);
+    }
+    if (!Number.isFinite(epoch)) {
+        throw new Error(`vi.setSystemTime: expected a finite epoch, got ${epoch}`);
+    }
+    clock.fakeEpoch = epoch;
+}
+export function clearFakeEpoch(clock) {
+    clock.fakeEpoch = null;
+}
+function buildShim() {
+    const shim = function DateShim(...args) {
+        const epoch = resolveEpoch();
+        // Called without `new`: return a toString of the pinned (or real) time.
+        if (!new.target) {
+            return epoch !== null
+                ? new OriginalDate(epoch).toString()
+                : new OriginalDate().toString();
+        }
+        if (args.length === 0 && epoch !== null) {
+            return new OriginalDate(epoch);
+        }
+        return Reflect.construct(OriginalDate, args);
+    };
+    shim.prototype = OriginalDate.prototype;
+    Object.defineProperty(shim, "name", { value: "Date", configurable: true });
+    Reflect.set(shim, "now", () => {
+        const epoch = resolveEpoch();
+        return epoch !== null ? epoch : originalNow();
+    });
+    Reflect.set(shim, "parse", OriginalDate.parse.bind(OriginalDate));
+    Reflect.set(shim, "UTC", OriginalDate.UTC.bind(OriginalDate));
+    return shim;
+}
+function install() {
+    if (installed)
+        return;
+    installed = true;
+    Reflect.set(globalThis, "Date", buildShim());
+}
+function restore() {
+    if (!installed)
+        return;
+    installed = false;
+    Reflect.set(globalThis, "Date", OriginalDate);
+}
+/** Get the original `Date.now` even after the shim is installed. */
+export function getRealNow() {
+    return originalNow();
+}
+/** Get the original `Date` constructor. */
+export function getRealDate() {
+    return OriginalDate;
+}
+//# sourceMappingURL=system-time.js.map

package/dist/runtime/vi/system-time.js.map

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

package/dist/runtime/worker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Worker entry — loads a single test file, collects its `describe`/`test`
+ * declarations, executes them, and emits a `FileResult`.
+ *
+ * Usage modes:
+ *   1. Direct (unit tests): `runTestFile("/abs/path.test.ts")` → `FileResult`
+ *   2. Child process (orchestrator): `main()` reads file paths from IPC
+ *      messages and replies on `process.send`. Exactly one `main()` runs
+ *      per worker process (guarded); IPC runs are serialized so concurrent
+ *      messages cannot race on internal state.
+ *
+ * File collection is scoped per invocation via AsyncLocalStorage (see
+ * `suite.ts#withCollection`) — no shared mutable state across concurrent
+ * `runTestFile` calls.
+ */
+import { type ExecuteOptions, type FileResult } from "./run.js";
+export interface RunFileOptions extends ExecuteOptions {
+    /**
+     * Bust the ESM module cache so repeated runs of the same path re-execute
+     * the file body and re-collect tests. Default: true.
+     */
+    freshImport?: boolean;
+}
+export declare function runTestFile(absolutePath: string, options?: RunFileOptions): Promise<FileResult>;
+export declare function main(): Promise<void>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/runtime/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/runtime/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,KAAK,cAAc,EAAe,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAI7E,MAAM,WAAW,cAAe,SAAQ,cAAc;IACrD;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAuFD,wBAAsB,WAAW,CAChC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,cAAmB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAmBrB;AA2CD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0D1C"}

package/dist/runtime/worker.js

@@ -0,0 +1,195 @@
+/**
+ * Worker entry — loads a single test file, collects its `describe`/`test`
+ * declarations, executes them, and emits a `FileResult`.
+ *
+ * Usage modes:
+ *   1. Direct (unit tests): `runTestFile("/abs/path.test.ts")` → `FileResult`
+ *   2. Child process (orchestrator): `main()` reads file paths from IPC
+ *      messages and replies on `process.send`. Exactly one `main()` runs
+ *      per worker process (guarded); IPC runs are serialized so concurrent
+ *      messages cannot race on internal state.
+ *
+ * File collection is scoped per invocation via AsyncLocalStorage (see
+ * `suite.ts#withCollection`) — no shared mutable state across concurrent
+ * `runTestFile` calls.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { executeRoot } from "./run.js";
+import { withCollection } from "./suite.js";
+import { withViContext } from "./vi/index.js";
+function assertAbsolute(p) {
+    if (!path.isAbsolute(p)) {
+        throw new Error(`runTestFile: expected absolute path, got "${p}". Resolve against cwd or __dirname before calling.`);
+    }
+}
+/** Turn values that `JSON.stringify` rejects into readable fallbacks. */
+function safeValue(v, seen = new WeakSet()) {
+    if (v === null || v === undefined)
+        return v;
+    if (typeof v === "bigint")
+        return `${v}n`;
+    if (typeof v === "function")
+        return `[Function ${v.name || "anonymous"}]`;
+    if (typeof v === "symbol")
+        return v.toString();
+    if (typeof v !== "object")
+        return v;
+    if (seen.has(v))
+        return "[Circular]";
+    seen.add(v);
+    if (Array.isArray(v))
+        return v.map((item) => safeValue(item, seen));
+    if (v instanceof Map) {
+        const out = [];
+        for (const [k, val] of v)
+            out.push([safeValue(k, seen), safeValue(val, seen)]);
+        return { __type: "Map", entries: out };
+    }
+    if (v instanceof Set) {
+        return { __type: "Set", values: [...v].map((x) => safeValue(x, seen)) };
+    }
+    if (v instanceof Date)
+        return { __type: "Date", iso: v.toISOString() };
+    if (v instanceof RegExp)
+        return { __type: "RegExp", src: v.source, flags: v.flags };
+    if (v instanceof Error) {
+        return {
+            __type: "Error",
+            name: v.name,
+            message: v.message,
+            stack: v.stack,
+        };
+    }
+    const rec = {};
+    for (const key of Object.keys(v)) {
+        rec[key] = safeValue(Reflect.get(v, key), seen);
+    }
+    return rec;
+}
+function sanitizeTest(t) {
+    if (!t.error)
+        return t;
+    return {
+        ...t,
+        error: {
+            ...t.error,
+            actual: safeValue(t.error.actual),
+            expected: safeValue(t.error.expected),
+        },
+    };
+}
+function sanitizeSuite(s) {
+    return {
+        ...s,
+        hookErrors: s.hookErrors.map((e) => ({
+            ...e,
+            actual: safeValue(e.actual),
+            expected: safeValue(e.expected),
+        })),
+        children: s.children.map((c) => "children" in c ? sanitizeSuite(c) : sanitizeTest(c)),
+    };
+}
+function sanitize(result) {
+    return {
+        ...result,
+        tests: result.tests.map(sanitizeTest),
+        suites: result.suites.map(sanitizeSuite),
+    };
+}
+let importCounter = 0;
+export async function runTestFile(absolutePath, options = {}) {
+    assertAbsolute(absolutePath);
+    const baseUrl = pathToFileURL(absolutePath).href;
+    // Cache-busting query param so the ESM loader re-evaluates the module on
+    // every call — otherwise `describe`/`test` would only register on the
+    // first call and subsequent runs would see an empty suite tree.
+    const url = options.freshImport === false
+        ? baseUrl
+        : `${baseUrl}?helix=${Date.now()}-${++importCounter}`;
+    return withViContext(async () => {
+        const root = await withCollection(async () => {
+            await import(url);
+        });
+        const raw = await executeRoot(root, absolutePath, {
+            timeoutMs: options.timeoutMs,
+        });
+        return sanitize(raw);
+    });
+}
+const FRAME_PREFIX = "__HELIX_RESULT__";
+function send(msg) {
+    if (typeof process.send === "function") {
+        process.send(msg);
+        return;
+    }
+    // Fallback: framed line on stderr so it doesn't collide with test
+    // console.log output on stdout. Parent parses lines starting with the
+    // `FRAME_PREFIX` magic.
+    process.stderr.write(`${FRAME_PREFIX}${JSON.stringify(msg)}\n`);
+}
+function isWorkerIncoming(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const r = v;
+    return r.type === "run" && typeof r.file === "string";
+}
+let mainStarted = false;
+export async function main() {
+    if (mainStarted)
+        return;
+    mainStarted = true;
+    // Unhandled rejections from test code (e.g. a dangling Promise.reject)
+    // would crash the worker on Node 15+ or leak silently. Log them and keep
+    // the process alive so currently-running tests can complete.
+    process.on("unhandledRejection", (reason) => {
+        process.stderr.write(`${FRAME_PREFIX}${JSON.stringify({
+            type: "error",
+            file: undefined,
+            message: `unhandledRejection: ${reason instanceof Error ? reason.message : String(reason)}`,
+            stack: reason instanceof Error ? reason.stack : undefined,
+        })}\n`);
+    });
+    // IPC mode: parent drives us via `{ type: "run", file }` messages.
+    if (typeof process.send === "function") {
+        let pending = Promise.resolve();
+        process.on("message", (raw) => {
+            if (!isWorkerIncoming(raw))
+                return;
+            const msg = raw;
+            // Serialize IPC runs: a second message waits for the first to
+            // finish so module-scoped watchers / handlers don't race.
+            pending = pending
+                .then(() => runTestFile(msg.file, { timeoutMs: msg.timeoutMs }))
+                .then((result) => send({ type: "result", result }))
+                .catch((err) => {
+                const e = err instanceof Error ? err : new Error(String(err));
+                send({
+                    type: "error",
+                    file: msg.file,
+                    message: e.message,
+                    stack: e.stack,
+                });
+            });
+        });
+        return;
+    }
+    // CLI fallback: `node worker.js <file>`.
+    const file = process.argv[2];
+    if (!file) {
+        process.stderr.write("helix worker: missing file arg\n");
+        process.exit(2);
+    }
+    try {
+        const abs = path.resolve(file);
+        const result = await runTestFile(abs);
+        send({ type: "result", result });
+        process.exit(result.totals.fail > 0 ? 1 : 0);
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        send({ type: "error", file, message: e.message, stack: e.stack });
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/runtime/worker.js.map

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

package/dist/time/freeze.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/** Anything with a `toMillis()` method (e.g. chronos `DateTime`,
+ *  Luxon `DateTime`) is accepted via duck typing — no import. */
+interface MillisLike {
+    toMillis(): number;
+}
+/** Inputs accepted by `freeze` / `travelTo`. */
+export type TimeInput = string | number | Date | MillisLike;
+/** Calendar units supported by `time.travel`. `ms` is the bare-metal
+ *  fallback; `month` and `year` use `Date.UTC` math; the rest are pure
+ *  ms multipliers. UTC-only — tests should freeze to a UTC instant. */
+export type TimeUnit = "ms" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/**
+ * 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 declare function freeze(input: TimeInput): void;
+/**
+ * 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 declare function travel(amount: number, unit?: TimeUnit): void;
+/**
+ * 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 declare function travelTo(target: TimeInput): void;
+/**
+ * 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 declare function unfreeze(): void;
+/**
+ * Read the currently frozen epoch, or `null` when running on real
+ * time. Useful for tests that compose `freeze` with their own clock
+ * arithmetic.
+ */
+export declare function frozenAt(): number | null;
+export {};
+//# sourceMappingURL=freeze.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/time/freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH;iEACiE;AACjE,UAAU,UAAU;IACnB,QAAQ,IAAI,MAAM,CAAC;CACnB;AAED,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,CAAC;AAE5D;;uEAEuE;AACvE,MAAM,MAAM,QAAQ,GACjB,IAAI,GACJ,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,KAAK,GACL,MAAM,GACN,OAAO,GACP,MAAM,CAAC;AAOV;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAO7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,QAAe,GAAG,IAAI,CAqBlE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,GAAG,IAAI,CAExC"}