@kensio/yulin 1.21.14 → 1.21.15

package/dist/util/background/background-clock-waits.d.ts

@@ -26,10 +26,17 @@ export declare class BackgroundClockWaits {
      */
     around<T>(wait: BackgroundClockWait, work: () => Promise<T>): Promise<T>;
     /**
-     * The work in a set that is neither waiting on the clock nor the work asking
-     * about it.
+     * The work in a set that completion has anything to wait for.
+     *
+     * The work asking is always left out. Waiting for the invocation the asking
+     * code is part of would be waiting for itself.
+     *
+     * Work waiting on the clock is left out where simulated time stands still,
+     * since only a caller moving the clock brings the instant it waits for, and
+     * that caller is the one waiting here. A running clock reaches the instant on
+     * its own, and this waits for the work to get there.
      */
-    runnable(held: ReadonlyMap<Promise<unknown>, BackgroundClockWait>): Promise<unknown>[];
+    runnable(held: ReadonlyMap<Promise<unknown>, BackgroundClockWait>, clockIsRunning?: boolean): Promise<unknown>[];
     /**
      * Whether the code running now is already inside outstanding work, and so
      * already counted.

package/dist/util/background/background-clock-waits.js

@@ -23,14 +23,21 @@ export class BackgroundClockWaits {
         return await this.storage.run(wait, work);
     }
     /**
-     * The work in a set that is neither waiting on the clock nor the work asking
-     * about it.
+     * The work in a set that completion has anything to wait for.
+     *
+     * The work asking is always left out. Waiting for the invocation the asking
+     * code is part of would be waiting for itself.
+     *
+     * Work waiting on the clock is left out where simulated time stands still,
+     * since only a caller moving the clock brings the instant it waits for, and
+     * that caller is the one waiting here. A running clock reaches the instant on
+     * its own, and this waits for the work to get there.
      */
-    runnable(held) {
+    runnable(held, clockIsRunning = false) {
         const own = this.storage.getStore();
         return held
             .entries()
-            .filter(([, wait]) => wait.count === 0 && wait !== own)
+            .filter(([, wait]) => wait !== own && (clockIsRunning || wait.count === 0))
             .map(([promise]) => promise)
             .toArray();
     }

package/dist/util/background/background-pending-tasks.d.ts

@@ -35,21 +35,27 @@ export declare class BackgroundPendingTasks {
      */
     get size(): number;
     /**
-     * Wait until nothing is outstanding but work that is waiting on the clock.
+     * Wait until nothing is outstanding that can still get somewhere.
      *
-     * Work that parks part way through ends the wait rather than extending it:
-     * only moving the clock releases it, and moving the clock is what waits
-     * here. The loop then looks again at what is left running, so work that
-     * carries on is waited for again.
+     * Where simulated time stands still, work that parks on the clock ends the
+     * wait rather than extending it. Only moving the clock releases it, and
+     * moving the clock is what waits here. The loop then looks again at what is
+     * left running, so work that carries on is waited for again.
+     *
+     * A running clock reaches those instants by itself, and the work parked on
+     * them is waited for like any other. What bounds the wait is the instant
+     * itself, which arrives in the real time between here and there.
      */
-    complete(): Promise<void>;
+    complete(clockIsRunning?: boolean): Promise<void>;
     /**
-     * The work completion has anything to wait for, which is whatever is
-     * neither waiting on the clock nor waiting for completion itself.
+     * The work completion has anything to wait for.
      *
      * Work that asks for the simulation to settle from inside itself is left
      * out. A handler advancing the clock is the ordinary case, and waiting for
      * the invocation it is part of would be waiting for itself.
+     *
+     * Work waiting on the clock joins it once simulated time is running, since
+     * a running clock is what brings the instant it waits for.
      */
-    running(): Promise<unknown>[];
+    running(clockIsRunning?: boolean): Promise<unknown>[];
 }

package/dist/util/background/background-pending-tasks.js

@@ -52,15 +52,19 @@ export class BackgroundPendingTasks {
         return this.#held.size;
     }
     /**
-     * Wait until nothing is outstanding but work that is waiting on the clock.
+     * Wait until nothing is outstanding that can still get somewhere.
      *
-     * Work that parks part way through ends the wait rather than extending it:
-     * only moving the clock releases it, and moving the clock is what waits
-     * here. The loop then looks again at what is left running, so work that
-     * carries on is waited for again.
+     * Where simulated time stands still, work that parks on the clock ends the
+     * wait rather than extending it. Only moving the clock releases it, and
+     * moving the clock is what waits here. The loop then looks again at what is
+     * left running, so work that carries on is waited for again.
+     *
+     * A running clock reaches those instants by itself, and the work parked on
+     * them is waited for like any other. What bounds the wait is the instant
+     * itself, which arrives in the real time between here and there.
      */
-    async complete() {
-        let running = this.running();
+    async complete(clockIsRunning = false) {
+        let running = this.running(clockIsRunning);
         while (running.length > 0) {
             // oxlint-disable-next-line no-await-in-loop
             const settled = await Promise.race([
@@ -68,19 +72,21 @@ export class BackgroundPendingTasks {
                 this.#clockWaits.next,
             ]);
             new BackgroundSettledTasks(settled).throwFirstFailure();
-            running = this.running();
+            running = this.running(clockIsRunning);
         }
     }
     /**
-     * The work completion has anything to wait for, which is whatever is
-     * neither waiting on the clock nor waiting for completion itself.
+     * The work completion has anything to wait for.
      *
      * Work that asks for the simulation to settle from inside itself is left
      * out. A handler advancing the clock is the ordinary case, and waiting for
      * the invocation it is part of would be waiting for itself.
+     *
+     * Work waiting on the clock joins it once simulated time is running, since
+     * a running clock is what brings the instant it waits for.
      */
-    running() {
-        return this.#clockWaits.runnable(this.#held);
+    running(clockIsRunning = false) {
+        return this.#clockWaits.runnable(this.#held, clockIsRunning);
     }
     /**
      * Keep work outstanding under its own record until it settles.

package/dist/util/background/background.d.ts

@@ -141,9 +141,11 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
      *
-     * Work waiting on the clock is not waited for: it is not outstanding, it is
-     * scheduled for a simulated instant that has not arrived. Only moving the
-     * clock releases it.
+     * What happens to work waiting on the clock follows the clock. Where
+     * simulated time stands still the work stays where it is, scheduled for an
+     * instant only a caller can bring, and this returns without it. Where
+     * simulated time runs, the instant arrives by itself and this waits for the
+     * work to get through it.
      */
     complete(): Promise<void>;
     /**
@@ -154,5 +156,11 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * See how many tasks are waiting for simulated time to reach them.
      */
     get dueTaskCount(): number;
+    /**
+     * Whether simulated time reaches a scheduled instant on its own.
+     *
+     * A clock with nothing to say about it advances, as the host clock does.
+     */
+    private get clockIsRunning();
 }
 export {};

package/dist/util/background/background.js

@@ -79,12 +79,14 @@ export class BackgroundTasks {
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
      *
-     * Work waiting on the clock is not waited for: it is not outstanding, it is
-     * scheduled for a simulated instant that has not arrived. Only moving the
-     * clock releases it.
+     * What happens to work waiting on the clock follows the clock. Where
+     * simulated time stands still the work stays where it is, scheduled for an
+     * instant only a caller can bring, and this returns without it. Where
+     * simulated time runs, the instant arrives by itself and this waits for the
+     * work to get through it.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clockIsRunning);
     }
     /**
      * See how many outstanding background tasks are scheduled.
@@ -98,4 +100,12 @@ export class BackgroundTasks {
     get dueTaskCount() {
         return this.dueTasks.size;
     }
+    /**
+     * Whether simulated time reaches a scheduled instant on its own.
+     *
+     * A clock with nothing to say about it advances, as the host clock does.
+     */
+    get clockIsRunning() {
+        return this.clock.advances !== false;
+    }
 }

package/dist/util/background/non-deterministic-background.d.ts

@@ -55,6 +55,10 @@ export declare class NonDeterministicBackgroundTasks implements BackgroundSchedu
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     complete(): Promise<void>;
     /**

package/dist/util/background/non-deterministic-background.js

@@ -79,9 +79,13 @@ export class NonDeterministicBackgroundTasks {
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clock.advances !== false);
     }
     /**
      * See how many outstanding background tasks are scheduled.

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

@@ -11,6 +11,18 @@ export interface SimClock {
      * Get the current time in this simulation.
      */
     now(): Date;
+    /**
+     * Whether simulated time moves on this clock by itself.
+     *
+     * A scheduler reads this to decide what waiting for a simulation to settle
+     * means. Time that advances brings the instant a task is scheduled for on
+     * its own, and settling waits for that task. Time that stands still leaves
+     * the instant to whoever moves the clock, and settling leaves the task where
+     * it is.
+     *
+     * A clock that says nothing advances, as the host clock does.
+     */
+    readonly advances?: boolean;
 }
 /**
  * Clock that reports the real system time.
@@ -19,6 +31,8 @@ export interface SimClock {
  * something deliberately replaces it.
  */
 export declare class SimRealClock implements SimClock {
+    /** Real time moves by itself. */
+    readonly advances = true;
     /**
      * Get the current real system time.
      */
@@ -31,6 +45,8 @@ export declare class SimRealClock implements SimClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export declare class SimFixedClock implements SimClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    readonly advances = false;
     private readonly instant;
     constructor(instant: Date);
     /**

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

@@ -5,6 +5,8 @@
  * something deliberately replaces it.
  */
 export class SimRealClock {
+    /** Real time moves by itself. */
+    advances = true;
     /**
      * Get the current real system time.
      */
@@ -19,6 +21,8 @@ export class SimRealClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export class SimFixedClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    advances = false;
     instant;
     constructor(instant) {
         this.instant = new Date(instant);

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

@@ -33,6 +33,17 @@ export declare class SimControllableClock implements SimClock {
      * Whether simulated time is currently standing still.
      */
     get isFrozen(): boolean;
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances(): boolean;
     /**
      * Stop simulated time where it currently reads.
      */

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

@@ -32,6 +32,19 @@ export class SimControllableClock {
     get isFrozen() {
         return this.mode.isFrozen;
     }
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances() {
+        return !this.mode.isFrozen && this.base.advances !== false;
+    }
     /**
      * Stop simulated time where it currently reads.
      */

package/docs/services/lambda/README.md

@@ -3269,6 +3269,17 @@ An interval runs once for each period an advance covers. Advancing eleven second
 interval runs it five times. A delay of zero, or none at all, is due at the instant it was asked
 for, and a handler yielding with `setTimeout(resolve, 0)` gets going again without the clock moving.
 
+Where the clock is left running, the delay passes in real time and nothing has to move it.
+`simAws.backgroundTasksComplete()` waits for a handler sleeping on a clock that is moving. An S3
+event notification, a stream record or an asynchronous invocation whose handler uses a timer has
+finished by the time the drain returns, and the function's `Timeout` bounds how long that wait can
+last.
+
+Two things leave a clock standing still. `freeze()`, `advanceBy(...)` and `setTo(...)` all leave it
+frozen, and a `SimAws` built on a `SimFixedClock` reports one instant however long the host runs.
+Under either the drain comes back while the handler sleeps, and moving the clock is what releases
+it.
+
 The function's `Timeout` is a deadline on the same clock. Where it arrives before the handler
 answers, the invocation ends in the error the real runtime reports.
 

package/docs/time/README.md

@@ -63,6 +63,13 @@ example, a simulation advanced by one hour continues to run one hour ahead of th
 
 Read `simAws.clock().isFrozen` to check the current mode.
 
+The mode also decides what waiting for the simulation to settle means.
+`simAws.backgroundTasksComplete()` waits for background work sleeping on a clock that is moving,
+because the instant that work sleeps until arrives by itself. Under a clock standing still the same
+work is left where it is, and `advanceBy(...)` or a forward `setTo(...)` is what brings the instant
+and waits for what follows from it. A simulation built on a `SimFixedClock` stands still under a
+running mode too, since simulated time here moves only as far as the clock underneath moves.
+
 ## Advancing time
 
 `advanceBy(...)` accepts days, hours, minutes, seconds, and milliseconds. The values are added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.14",
+  "version": "1.21.15",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",