@kensio/yulin 0.34.2 → 0.36.0

package/dist/util/clock/sim-clock-control.d.ts

@@ -0,0 +1,94 @@
+import type { BackgroundCompleter, BackgroundDueTaskSource, BackgroundScheduler } from "../background/background.js";
+import type { SimClock } from "./sim-clock.js";
+import type { SimControllableClock } from "./sim-controllable-clock.js";
+import { SimDuration, type SimDurationInput } from "./sim-duration.js";
+/**
+ * The scheduler a clock control moves time for: it releases work waiting on the
+ * clock, and it can be waited on until the simulation settles.
+ */
+export type SimClockControlBackground = BackgroundScheduler & BackgroundCompleter & BackgroundDueTaskSource;
+interface SimClockControlProperties {
+    readonly clock: SimControllableClock;
+    readonly background: SimClockControlBackground;
+}
+/**
+ * Control over one simulation's sense of time.
+ *
+ * Moving the clock is only half of what a test needs. The other half is that
+ * whatever the passage of time should have caused has actually happened by the
+ * time the call returns, so the next line can assert rather than wait. So this
+ * class owns both the clock and the scheduler: advancing walks simulated time
+ * forward through everything that falls due in the interval, running each task
+ * at its own due time, and returns once nothing is left pending.
+ *
+ * Control is per simulation. Moving time here never touches another simulation
+ * or the real clock, which is what keeps a SimAws instance safe to construct
+ * per test case.
+ */
+export declare class SimClockControl implements SimClock {
+    private readonly clock;
+    private readonly background;
+    constructor(properties: SimClockControlProperties);
+    /**
+     * Get the current simulated time.
+     */
+    now(): Date;
+    /**
+     * Whether simulated time is currently standing still.
+     */
+    get isFrozen(): boolean;
+    /**
+     * Stop simulated time where it currently reads.
+     *
+     * A frozen clock reports the same instant however long the host takes, so a
+     * slow test cannot drift past the state it set up.
+     */
+    freeze(): void;
+    /**
+     * Let simulated time pass by itself again, carrying on from where it stopped.
+     *
+     * Time then runs at real speed, offset by however far it has been moved, so
+     * "jump forward an hour and carry on" behaves as it sounds.
+     */
+    resume(): void;
+    /**
+     * Set simulated time to an instant, running whatever falls due on the way.
+     *
+     * Setting time backwards runs nothing: it simply moves the clock, and work
+     * already scheduled waits for time to reach it again.
+     *
+     * Work that fails throws from here, leaving the clock at the failed task's
+     * due time rather than at the instant asked for. Simulated time got that far
+     * and then something broke, and saying so is more use than claiming the whole
+     * interval elapsed. Whatever was still queued stays queued.
+     */
+    setTo(instant: Date): Promise<void>;
+    /**
+     * Move simulated time forward by a duration, running whatever falls due.
+     *
+     * Returns once the simulation has settled, so a test can advance and then
+     * assert without waiting again.
+     */
+    advanceBy(duration: SimDuration | SimDurationInput): Promise<void>;
+    /**
+     * Dispatch everything due at or before an instant, in due order.
+     *
+     * Each task runs with the clock reading its own due time rather than the
+     * final one, so a task that stamps a timestamp records when it happened. Work
+     * a task schedules for itself settles before the next due task is taken,
+     * which keeps cascading work in order too.
+     *
+     * The loop runs as long as work keeps falling due inside the interval, as
+     * draining does generally: a task that endlessly reschedules itself inside
+     * the interval is asking for endless work, and cutting it off part way would
+     * report a settled simulation that is nothing of the kind.
+     */
+    private runDueTasksUpTo;
+    /**
+     * Keep the clock moving forward: an overdue task runs at the current time
+     * rather than dragging simulated time backwards to when it should have run.
+     */
+    private laterOfNow;
+}
+export {};
+//# sourceMappingURL=sim-clock-control.d.ts.map

package/dist/util/clock/sim-clock-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock-control.d.ts","sourceRoot":"","sources":["../../../src/util/clock/sim-clock-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GACzD,mBAAmB,GACnB,uBAAuB,CAAC;AAE1B,UAAU,yBAAyB;IACjC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IAEvD,YAAY,UAAU,EAAE,yBAAyB,EAGhD;IAED;;OAEG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;OAKG;IACH,MAAM,IAAI,IAAI,CAEb;IAED;;;;;OAKG;IACH,MAAM,IAAI,IAAI,CAEb;IAED;;;;;;;;;;OAUG;IACG,KAAK,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxC;IAED;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;IAED;;;;;;;;;;;;OAYG;YACW,eAAe;IAc7B;;;OAGG;IACH,OAAO,CAAC,UAAU;CASnB"}

package/dist/util/clock/sim-clock-control.js

@@ -0,0 +1,116 @@
+import { SimDuration } from "./sim-duration.js";
+/**
+ * Control over one simulation's sense of time.
+ *
+ * Moving the clock is only half of what a test needs. The other half is that
+ * whatever the passage of time should have caused has actually happened by the
+ * time the call returns, so the next line can assert rather than wait. So this
+ * class owns both the clock and the scheduler: advancing walks simulated time
+ * forward through everything that falls due in the interval, running each task
+ * at its own due time, and returns once nothing is left pending.
+ *
+ * Control is per simulation. Moving time here never touches another simulation
+ * or the real clock, which is what keeps a SimAws instance safe to construct
+ * per test case.
+ */
+export class SimClockControl {
+    clock;
+    background;
+    constructor(properties) {
+        this.clock = properties.clock;
+        this.background = properties.background;
+    }
+    /**
+     * Get the current simulated time.
+     */
+    now() {
+        return this.clock.now();
+    }
+    /**
+     * Whether simulated time is currently standing still.
+     */
+    get isFrozen() {
+        return this.clock.isFrozen;
+    }
+    /**
+     * Stop simulated time where it currently reads.
+     *
+     * A frozen clock reports the same instant however long the host takes, so a
+     * slow test cannot drift past the state it set up.
+     */
+    freeze() {
+        this.clock.freeze();
+    }
+    /**
+     * Let simulated time pass by itself again, carrying on from where it stopped.
+     *
+     * Time then runs at real speed, offset by however far it has been moved, so
+     * "jump forward an hour and carry on" behaves as it sounds.
+     */
+    resume() {
+        this.clock.resume();
+    }
+    /**
+     * Set simulated time to an instant, running whatever falls due on the way.
+     *
+     * Setting time backwards runs nothing: it simply moves the clock, and work
+     * already scheduled waits for time to reach it again.
+     *
+     * Work that fails throws from here, leaving the clock at the failed task's
+     * due time rather than at the instant asked for. Simulated time got that far
+     * and then something broke, and saying so is more use than claiming the whole
+     * interval elapsed. Whatever was still queued stays queued.
+     */
+    async setTo(instant) {
+        if (instant.getTime() >= this.now().getTime()) {
+            await this.runDueTasksUpTo(instant);
+        }
+        this.clock.setTo(instant);
+        await this.background.complete();
+    }
+    /**
+     * Move simulated time forward by a duration, running whatever falls due.
+     *
+     * Returns once the simulation has settled, so a test can advance and then
+     * assert without waiting again.
+     */
+    async advanceBy(duration) {
+        const milliseconds = SimDuration.of(duration).toMilliseconds();
+        await this.setTo(new Date(this.now().getTime() + milliseconds));
+    }
+    /**
+     * Dispatch everything due at or before an instant, in due order.
+     *
+     * Each task runs with the clock reading its own due time rather than the
+     * final one, so a task that stamps a timestamp records when it happened. Work
+     * a task schedules for itself settles before the next due task is taken,
+     * which keeps cascading work in order too.
+     *
+     * The loop runs as long as work keeps falling due inside the interval, as
+     * draining does generally: a task that endlessly reschedules itself inside
+     * the interval is asking for endless work, and cutting it off part way would
+     * report a settled simulation that is nothing of the kind.
+     */
+    async runDueTasksUpTo(instant) {
+        let due = this.background.takeNextDueBy(instant);
+        while (due !== undefined) {
+            this.clock.setTo(this.laterOfNow(due.dueTime));
+            this.background.schedule(due.task);
+            // eslint-disable-next-line no-await-in-loop
+            await this.background.complete();
+            due = this.background.takeNextDueBy(instant);
+        }
+    }
+    /**
+     * Keep the clock moving forward: an overdue task runs at the current time
+     * rather than dragging simulated time backwards to when it should have run.
+     */
+    laterOfNow(instant) {
+        const now = this.now();
+        if (instant.getTime() < now.getTime()) {
+            return now;
+        }
+        return instant;
+    }
+}
+//# sourceMappingURL=sim-clock-control.js.map

package/dist/util/clock/sim-clock-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock-control.js","sourceRoot":"","sources":["../../../src/util/clock/sim-clock-control.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAyB,MAAM,mBAAmB,CAAC;AAevE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,eAAe;IACT,KAAK,CAAuB;IAC5B,UAAU,CAA4B;IAEvD,YAAY,UAAqC;QAC/C,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,MAAM;QACJ,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED;;;;;OAKG;IACH,MAAM;QACJ,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,CAAC,OAAa;QACvB,IAAI,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAE1B,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,QAAwC;QACtD,MAAM,YAAY,GAAG,WAAW,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,CAAC;QAE/D,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;OAYG;IACK,KAAK,CAAC,eAAe,CAAC,OAAa;QACzC,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAEjD,OAAO,GAAG,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAEnC,4CAA4C;YAC5C,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;YAEjC,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,UAAU,CAAC,OAAa;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC;QACb,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/util/clock/sim-clock-mode.d.ts

@@ -0,0 +1,74 @@
+import type { SimClock } from "./sim-clock.js";
+/**
+ * How a controllable clock relates simulated time to the clock underneath it.
+ *
+ * There are two ways to be in control of time, and they answer different
+ * questions. A frozen clock is what a deterministic assertion wants: simulated
+ * time only moves when something moves it, so a slow test never drifts. A
+ * running clock offset from the one underneath is what "jump forward an hour and
+ * carry on" wants: time still passes by itself, just somewhere else on the
+ * timeline.
+ *
+ * Each mode knows how to become the other, so switching never loses the current
+ * simulated instant.
+ */
+export interface SimClockMode {
+    /**
+     * Whether simulated time is standing still in this mode.
+     */
+    readonly isFrozen: boolean;
+    /**
+     * Get the simulated time this mode reports.
+     */
+    now(base: SimClock): Date;
+    /**
+     * Stop simulated time where it currently reads.
+     */
+    freeze(base: SimClock): SimClockMode;
+    /**
+     * Let simulated time run again from where it currently reads.
+     */
+    resume(base: SimClock): SimClockMode;
+}
+/**
+ * Simulated time stopped at an instant, moving only when something moves it.
+ */
+export declare class SimFrozenClockMode implements SimClockMode {
+    readonly isFrozen = true;
+    private readonly instant;
+    constructor(instant: Date);
+    /**
+     * Get the instant this mode is stopped at.
+     */
+    now(): Date;
+    /**
+     * Stay stopped: freezing an already frozen clock changes nothing.
+     */
+    freeze(): SimClockMode;
+    /**
+     * Run again from the frozen instant, keeping it as the offset from the clock
+     * underneath, so no simulated time is gained or lost by resuming.
+     */
+    resume(base: SimClock): SimClockMode;
+}
+/**
+ * Simulated time passing by itself, shifted from the clock underneath.
+ */
+export declare class SimRunningClockMode implements SimClockMode {
+    readonly isFrozen = false;
+    private readonly offsetMs;
+    constructor(offsetMs?: number);
+    /**
+     * Get the time the clock underneath reports, shifted by this offset.
+     */
+    now(base: SimClock): Date;
+    /**
+     * Stop at whatever simulated time currently reads.
+     */
+    freeze(base: SimClock): SimClockMode;
+    /**
+     * Keep running: resuming an already running clock changes nothing.
+     */
+    resume(): SimClockMode;
+}
+//# sourceMappingURL=sim-clock-mode.d.ts.map

package/dist/util/clock/sim-clock-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock-mode.d.ts","sourceRoot":"","sources":["../../../src/util/clock/sim-clock-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;IAErC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CACtC;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,SAAgB,QAAQ,QAAQ;IAEhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAO;IAE/B,YAAY,OAAO,EAAE,IAAI,EAExB;IAED;;OAEG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;OAEG;IACH,MAAM,IAAI,YAAY,CAErB;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAInC;CACF;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IACtD,SAAgB,QAAQ,SAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,QAAQ,SAAI,EAEvB;IAED;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAExB;IAED;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAEnC;IAED;;OAEG;IACH,MAAM,IAAI,YAAY,CAErB;CACF"}

package/dist/util/clock/sim-clock-mode.js

@@ -0,0 +1,58 @@
+/**
+ * Simulated time stopped at an instant, moving only when something moves it.
+ */
+export class SimFrozenClockMode {
+    isFrozen = true;
+    instant;
+    constructor(instant) {
+        this.instant = new Date(instant);
+    }
+    /**
+     * Get the instant this mode is stopped at.
+     */
+    now() {
+        return new Date(this.instant);
+    }
+    /**
+     * Stay stopped: freezing an already frozen clock changes nothing.
+     */
+    freeze() {
+        return this;
+    }
+    /**
+     * Run again from the frozen instant, keeping it as the offset from the clock
+     * underneath, so no simulated time is gained or lost by resuming.
+     */
+    resume(base) {
+        return new SimRunningClockMode(this.instant.getTime() - base.now().getTime());
+    }
+}
+/**
+ * Simulated time passing by itself, shifted from the clock underneath.
+ */
+export class SimRunningClockMode {
+    isFrozen = false;
+    offsetMs;
+    constructor(offsetMs = 0) {
+        this.offsetMs = offsetMs;
+    }
+    /**
+     * Get the time the clock underneath reports, shifted by this offset.
+     */
+    now(base) {
+        return new Date(base.now().getTime() + this.offsetMs);
+    }
+    /**
+     * Stop at whatever simulated time currently reads.
+     */
+    freeze(base) {
+        return new SimFrozenClockMode(this.now(base));
+    }
+    /**
+     * Keep running: resuming an already running clock changes nothing.
+     */
+    resume() {
+        return this;
+    }
+}
+//# sourceMappingURL=sim-clock-mode.js.map

package/dist/util/clock/sim-clock-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock-mode.js","sourceRoot":"","sources":["../../../src/util/clock/sim-clock-mode.ts"],"names":[],"mappings":"AAqCA;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACb,QAAQ,GAAG,IAAI,CAAC;IAEf,OAAO,CAAO;IAE/B,YAAY,OAAa;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAAc;QACnB,OAAO,IAAI,mBAAmB,CAC5B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAC9C,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAmB;IACd,QAAQ,GAAG,KAAK,CAAC;IAEhB,QAAQ,CAAS;IAElC,YAAY,QAAQ,GAAG,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAc;QAChB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAAc;QACnB,OAAO,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/util/clock/sim-clock.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Source of the current time inside one simulated environment.
+ *
+ * Every simulated timestamp comes from a clock rather than a direct `new Date()`,
+ * so a simulation's sense of time belongs to its own SimAws instance rather than
+ * to the process running it. That keeps instances independent: controlling time
+ * in one simulation cannot disturb another, or the real clock.
+ */
+export interface SimClock {
+    /**
+     * Get the current time in this simulation.
+     */
+    now(): Date;
+}
+/**
+ * Clock that reports the real system time.
+ *
+ * This is the default, so a simulation runs in step with the host clock until
+ * something deliberately replaces it.
+ */
+export declare class SimRealClock implements SimClock {
+    /**
+     * Get the current real system time.
+     */
+    now(): Date;
+}
+/**
+ * Clock stopped at a fixed instant.
+ *
+ * Useful wherever a test wants timestamps it can assert on exactly, without
+ * reaching for a library that replaces the clock for the whole process.
+ */
+export declare class SimFixedClock implements SimClock {
+    private readonly instant;
+    constructor(instant: Date);
+    /**
+     * Get the fixed instant this clock reports.
+     */
+    now(): Date;
+}
+//# sourceMappingURL=sim-clock.d.ts.map

package/dist/util/clock/sim-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock.d.ts","sourceRoot":"","sources":["../../../src/util/clock/sim-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,GAAG,IAAI,IAAI,CAAC;CACb;AAED;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C;;OAEG;IACH,GAAG,IAAI,IAAI,CAEV;CACF;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAO;IAE/B,YAAY,OAAO,EAAE,IAAI,EAExB;IAED;;OAEG;IACH,GAAG,IAAI,IAAI,CAEV;CACF"}

package/dist/util/clock/sim-clock.js

@@ -0,0 +1,33 @@
+/**
+ * Clock that reports the real system time.
+ *
+ * This is the default, so a simulation runs in step with the host clock until
+ * something deliberately replaces it.
+ */
+export class SimRealClock {
+    /**
+     * Get the current real system time.
+     */
+    now() {
+        return new Date();
+    }
+}
+/**
+ * Clock stopped at a fixed instant.
+ *
+ * Useful wherever a test wants timestamps it can assert on exactly, without
+ * reaching for a library that replaces the clock for the whole process.
+ */
+export class SimFixedClock {
+    instant;
+    constructor(instant) {
+        this.instant = new Date(instant);
+    }
+    /**
+     * Get the fixed instant this clock reports.
+     */
+    now() {
+        return new Date(this.instant);
+    }
+}
+//# sourceMappingURL=sim-clock.js.map

package/dist/util/clock/sim-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock.js","sourceRoot":"","sources":["../../../src/util/clock/sim-clock.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACvB;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,IAAI,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACP,OAAO,CAAO;IAE/B,YAAY,OAAa;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/util/clock/sim-controllable-clock.d.ts

@@ -0,0 +1,55 @@
+import { type SimClock } from "./sim-clock.js";
+import { SimDuration, type SimDurationInput } from "./sim-duration.js";
+interface SimControllableClockProperties {
+    /**
+     * The clock this one is measured against, defaulting to the real system
+     * clock. Freezing and offsetting are applied on top of it, so a simulation
+     * given a clock of its own stays controllable.
+     */
+    readonly base?: SimClock | undefined;
+}
+/**
+ * A clock whose time can be moved.
+ *
+ * This is what lets a test exercise behaviour that only happens once time
+ * passes, without waiting for it and without replacing the clock for the whole
+ * process. Control belongs to one clock instance, so moving time here cannot
+ * disturb another simulation, or the real clock.
+ *
+ * Moving time deliberately freezes it. Having asked for a specific instant, a
+ * test should get to assert on that instant rather than on that instant plus
+ * however long the assertion took to run. `resume()` is the way back to time
+ * passing by itself.
+ */
+export declare class SimControllableClock implements SimClock {
+    private readonly base;
+    private mode;
+    constructor(properties?: SimControllableClockProperties);
+    /**
+     * Get the current simulated time.
+     */
+    now(): Date;
+    /**
+     * Whether simulated time is currently standing still.
+     */
+    get isFrozen(): boolean;
+    /**
+     * Stop simulated time where it currently reads.
+     */
+    freeze(): void;
+    /**
+     * Let simulated time pass by itself again, carrying on from where it stopped
+     * rather than snapping back to the clock underneath.
+     */
+    resume(): void;
+    /**
+     * Set simulated time to an instant, and stop there.
+     */
+    setTo(instant: Date): void;
+    /**
+     * Move simulated time forward by a duration, and stop there.
+     */
+    advanceBy(duration: SimDuration | SimDurationInput): void;
+}
+export {};
+//# sourceMappingURL=sim-controllable-clock.d.ts.map

package/dist/util/clock/sim-controllable-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-controllable-clock.d.ts","sourceRoot":"","sources":["../../../src/util/clock/sim-controllable-clock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAgB,MAAM,gBAAgB,CAAC;AAM7D,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,UAAU,8BAA8B;IACtC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACtC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,YAAW,QAAQ;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAChC,OAAO,CAAC,IAAI,CAA2C;IAEvD,YAAY,UAAU,GAAE,8BAAmC,EAE1D;IAED;;OAEG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,MAAM,IAAI,IAAI,CAEb;IAED;;;OAGG;IACH,MAAM,IAAI,IAAI,CAEb;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAEzB;IAED;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAIxD;CACF"}

package/dist/util/clock/sim-controllable-clock.js

@@ -0,0 +1,62 @@
+import { SimRealClock } from "./sim-clock.js";
+import { SimFrozenClockMode, SimRunningClockMode, } from "./sim-clock-mode.js";
+import { SimDuration } from "./sim-duration.js";
+/**
+ * A clock whose time can be moved.
+ *
+ * This is what lets a test exercise behaviour that only happens once time
+ * passes, without waiting for it and without replacing the clock for the whole
+ * process. Control belongs to one clock instance, so moving time here cannot
+ * disturb another simulation, or the real clock.
+ *
+ * Moving time deliberately freezes it. Having asked for a specific instant, a
+ * test should get to assert on that instant rather than on that instant plus
+ * however long the assertion took to run. `resume()` is the way back to time
+ * passing by itself.
+ */
+export class SimControllableClock {
+    base;
+    mode = new SimRunningClockMode();
+    constructor(properties = {}) {
+        this.base = properties.base ?? new SimRealClock();
+    }
+    /**
+     * Get the current simulated time.
+     */
+    now() {
+        return this.mode.now(this.base);
+    }
+    /**
+     * Whether simulated time is currently standing still.
+     */
+    get isFrozen() {
+        return this.mode.isFrozen;
+    }
+    /**
+     * Stop simulated time where it currently reads.
+     */
+    freeze() {
+        this.mode = this.mode.freeze(this.base);
+    }
+    /**
+     * Let simulated time pass by itself again, carrying on from where it stopped
+     * rather than snapping back to the clock underneath.
+     */
+    resume() {
+        this.mode = this.mode.resume(this.base);
+    }
+    /**
+     * Set simulated time to an instant, and stop there.
+     */
+    setTo(instant) {
+        this.mode = new SimFrozenClockMode(instant);
+    }
+    /**
+     * Move simulated time forward by a duration, and stop there.
+     */
+    advanceBy(duration) {
+        const milliseconds = SimDuration.of(duration).toMilliseconds();
+        this.setTo(new Date(this.now().getTime() + milliseconds));
+    }
+}
+//# sourceMappingURL=sim-controllable-clock.js.map

package/dist/util/clock/sim-controllable-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-controllable-clock.js","sourceRoot":"","sources":["../../../src/util/clock/sim-controllable-clock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACL,kBAAkB,EAElB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAyB,MAAM,mBAAmB,CAAC;AAWvE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,oBAAoB;IACd,IAAI,CAAW;IACxB,IAAI,GAAiB,IAAI,mBAAmB,EAAE,CAAC;IAEvD,YAAY,UAAU,GAAmC,EAAE;QACzD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,IAAI,YAAY,EAAE,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,MAAM;QACJ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAa;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAAwC;QAChD,MAAM,YAAY,GAAG,WAAW,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,CAAC;QAE/D,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/util/clock/sim-duration.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A length of time, written the way a test wants to say it.
+ *
+ * Every component is optional and they add together, so `{ hours: 1, minutes: 30 }`
+ * is ninety minutes. This is the literal a caller writes; SimDuration is what the
+ * simulator works with.
+ */
+export interface SimDurationInput {
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly milliseconds?: number;
+}
+/**
+ * Thrown for a duration that cannot describe an amount of elapsed time.
+ */
+export declare class SimInvalidDuration extends Error {
+    constructor(component: keyof SimDurationInput, value: number);
+}
+/**
+ * An amount of elapsed simulated time.
+ *
+ * Durations are never negative. Time passing is a forward-only idea, and a
+ * simulation that wants to be at an earlier instant sets its clock to that
+ * instant rather than advancing by a negative amount.
+ */
+export declare class SimDuration {
+    private readonly milliseconds;
+    private constructor();
+    /**
+     * Build a duration from the components a caller wrote, or pass one through.
+     */
+    static of(duration: SimDuration | SimDurationInput): SimDuration;
+    /**
+     * Build a duration from a plain number of milliseconds.
+     */
+    static ofMilliseconds(milliseconds: number): SimDuration;
+    /**
+     * Get this duration as a number of milliseconds, for Date arithmetic.
+     */
+    toMilliseconds(): number;
+}
+//# sourceMappingURL=sim-duration.d.ts.map

package/dist/util/clock/sim-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-duration.d.ts","sourceRoot":"","sources":["../../../src/util/clock/sim-duration.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAOD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,SAAS,EAAE,MAAM,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAK3D;CACF;AAiCD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,OAAO,eAEN;IAED;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,GAAG,gBAAgB,GAAG,WAAW,CAM/D;IAED;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAEvD;IAED;;OAEG;IACH,cAAc,IAAI,MAAM,CAEvB;CACF"}