@kensio/yulin 1.21.3 → 1.21.4

package/dist/service/s3/upload/sim-s3-multipart-upload.d.ts

@@ -1,5 +1,8 @@
 import type { Brand } from "../../../util/brand.type.js";
 import type { SimS3ObjectMetadata } from "../object/s3-object.js";
+import { SimS3ObjectTagSet } from "../object/s3-object-tags.js";
+import type { SimS3ServerSideEncryption } from "../object/s3-server-side-encryption.js";
+import { type SimS3StorageClass } from "../object/s3-storage-class.js";
 export type SimS3UploadId = Brand<string, "SimS3UploadId">;
 /**
  * One numbered part of a multipart upload, as S3 holds it between the
@@ -21,6 +24,18 @@ interface SimS3MultipartUploadProperties {
     readonly key: string;
     readonly metadata: SimS3ObjectMetadata;
     readonly initiated: Date;
+    /**
+     * Where and how the completed Object will be stored. Real S3 takes both at
+     * `CreateMultipartUpload`, alongside the metadata, rather than at completion.
+     */
+    readonly storageClass?: SimS3StorageClass;
+    readonly serverSideEncryption?: SimS3ServerSideEncryption | undefined;
+    /**
+     * The tags the completed Object will carry. Real S3 takes these at
+     * `CreateMultipartUpload` too, for the same reason it takes the metadata
+     * there: the request describing the Object arrives before its bytes.
+     */
+    readonly tags?: SimS3ObjectTagSet | undefined;
 }
 /**
  * A simulated S3 multipart upload in progress.
@@ -40,6 +55,9 @@ export declare class SimS3MultipartUpload {
     readonly key: string;
     readonly metadata: SimS3ObjectMetadata;
     readonly initiated: Date;
+    readonly storageClass: SimS3StorageClass;
+    readonly serverSideEncryption: SimS3ServerSideEncryption | undefined;
+    readonly tags: SimS3ObjectTagSet;
     private readonly parts;
     constructor(properties: SimS3MultipartUploadProperties);
     /**

package/dist/service/s3/upload/sim-s3-multipart-upload.js

@@ -1,4 +1,6 @@
 import { createHash } from "node:crypto";
+import { SimS3ObjectTagSet } from "../object/s3-object-tags.js";
+import { simS3DefaultStorageClass, } from "../object/s3-storage-class.js";
 /**
  * One numbered part of a multipart upload, as S3 holds it between the
  * `UploadPart` that stored it and the `CompleteMultipartUpload` that joins it
@@ -37,12 +39,18 @@ export class SimS3MultipartUpload {
     key;
     metadata;
     initiated;
+    storageClass;
+    serverSideEncryption;
+    tags;
     parts = new Map();
     constructor(properties) {
         this.uploadId = properties.uploadId;
         this.key = properties.key;
         this.metadata = properties.metadata;
         this.initiated = new Date(properties.initiated);
+        this.storageClass = properties.storageClass ?? simS3DefaultStorageClass;
+        this.serverSideEncryption = properties.serverSideEncryption;
+        this.tags = properties.tags ?? SimS3ObjectTagSet.empty();
     }
     /**
      * Store a numbered part, replacing whatever was under that number.

package/dist/service/s3/upload/sim-s3-multipart-uploads.d.ts

@@ -1,9 +1,15 @@
 import type { SimS3ObjectMetadata } from "../object/s3-object.js";
+import type { SimS3ObjectTagSet } from "../object/s3-object-tags.js";
+import type { SimS3ServerSideEncryption } from "../object/s3-server-side-encryption.js";
+import type { SimS3StorageClass } from "../object/s3-storage-class.js";
 import { SimS3MultipartUpload, type SimS3UploadId } from "./sim-s3-multipart-upload.js";
 interface SimS3StartUploadProperties {
     readonly key: string;
     readonly metadata: SimS3ObjectMetadata;
     readonly initiated: Date;
+    readonly storageClass?: SimS3StorageClass;
+    readonly serverSideEncryption?: SimS3ServerSideEncryption | undefined;
+    readonly tags?: SimS3ObjectTagSet | undefined;
 }
 /**
  * The multipart uploads one Bucket has in progress.

package/dist/service/s3/upload/sim-s3-multipart-uploads.js

@@ -23,6 +23,11 @@ export class SimS3MultipartUploads {
             key: properties.key,
             metadata: properties.metadata,
             initiated: properties.initiated,
+            ...(properties.storageClass !== undefined && {
+                storageClass: properties.storageClass,
+            }),
+            serverSideEncryption: properties.serverSideEncryption,
+            tags: properties.tags,
         });
         this.uploads.set(upload.uploadId, upload);
         return upload;

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

@@ -0,0 +1,52 @@
+/**
+ * How many things one running scheduled task is waiting on the clock for.
+ */
+export interface BackgroundClockWait {
+    count: number;
+}
+/**
+ * Which scheduled tasks are waiting for the clock rather than for the host.
+ *
+ * Completing a simulation waits for the work that can still get somewhere on
+ * its own. A task blocked on an instant the clock has not reached is not that
+ * kind of work: only moving the clock releases it, and whatever moves the
+ * clock is what waits for completion. Left in, it would be waiting for itself.
+ *
+ * A task says so for itself, from wherever inside it the wait happens, so a
+ * scheduler needs no way of telling one kind of work from another. Code
+ * running outside a scheduled task has nothing to say, and changes nothing by
+ * saying it, which is what keeps this invisible to a caller who holds the
+ * promise itself.
+ */
+export declare class BackgroundClockWaits {
+    private readonly storage;
+    private started;
+    /**
+     * Run outstanding work with a record of what it waits on the clock for.
+     */
+    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.
+     */
+    runnable(held: ReadonlyMap<Promise<unknown>, BackgroundClockWait>): Promise<unknown>[];
+    /**
+     * Whether the code running now is already inside outstanding work, and so
+     * already counted.
+     */
+    get inWork(): boolean;
+    /**
+     * Say that the task running now is waiting for simulated time to reach an
+     * instant, and get back the way to say it no longer is.
+     */
+    begin(): () => void;
+    /**
+     * Resolves the next time a task starts waiting on the clock.
+     *
+     * Whoever is waiting for the simulation to complete takes this alongside the
+     * tasks it is waiting for, so a task that parks part way through stops the
+     * wait rather than extending it forever.
+     */
+    get next(): Promise<undefined>;
+    private wake;
+}

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

@@ -0,0 +1,76 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Which scheduled tasks are waiting for the clock rather than for the host.
+ *
+ * Completing a simulation waits for the work that can still get somewhere on
+ * its own. A task blocked on an instant the clock has not reached is not that
+ * kind of work: only moving the clock releases it, and whatever moves the
+ * clock is what waits for completion. Left in, it would be waiting for itself.
+ *
+ * A task says so for itself, from wherever inside it the wait happens, so a
+ * scheduler needs no way of telling one kind of work from another. Code
+ * running outside a scheduled task has nothing to say, and changes nothing by
+ * saying it, which is what keeps this invisible to a caller who holds the
+ * promise itself.
+ */
+export class BackgroundClockWaits {
+    storage = new AsyncLocalStorage();
+    started = Promise.withResolvers();
+    /**
+     * Run outstanding work with a record of what it waits on the clock for.
+     */
+    async around(wait, work) {
+        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.
+     */
+    runnable(held) {
+        const own = this.storage.getStore();
+        return held
+            .entries()
+            .filter(([, wait]) => wait.count === 0 && wait !== own)
+            .map(([promise]) => promise)
+            .toArray();
+    }
+    /**
+     * Whether the code running now is already inside outstanding work, and so
+     * already counted.
+     */
+    get inWork() {
+        return this.storage.getStore() !== undefined;
+    }
+    /**
+     * Say that the task running now is waiting for simulated time to reach an
+     * instant, and get back the way to say it no longer is.
+     */
+    begin() {
+        const wait = this.storage.getStore();
+        if (wait === undefined) {
+            return () => {
+                // Nothing scheduled is waiting, so nothing stops waiting either.
+            };
+        }
+        wait.count += 1;
+        this.wake();
+        return () => {
+            wait.count -= 1;
+        };
+    }
+    /**
+     * Resolves the next time a task starts waiting on the clock.
+     *
+     * Whoever is waiting for the simulation to complete takes this alongside the
+     * tasks it is waiting for, so a task that parks part way through stops the
+     * wait rather than extending it forever.
+     */
+    get next() {
+        return this.started.promise;
+    }
+    wake() {
+        const { resolve } = this.started;
+        this.started = Promise.withResolvers();
+        resolve(undefined);
+    }
+}

package/dist/util/background/background-jitter.js

@@ -1,3 +1,4 @@
+import { setTimeout } from "node:timers";
 /**
  * A short random pause between scheduling a task and running it.
  *

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

@@ -0,0 +1,55 @@
+import type { BackgroundTask } from "./background.js";
+/**
+ * The work one scheduler has outstanding, and how much of it is worth waiting
+ * for.
+ *
+ * Work gets here two ways. A task the scheduler was handed is held here until
+ * it settles, and its failure is kept for whoever waits for the simulation to
+ * complete. Work a caller started is held here too, but answers to that caller
+ * instead, because reporting the same failure twice would fail somebody who
+ * never asked for the work.
+ *
+ * Either way, what completion waits for is what can still get somewhere on its
+ * own. Work waiting on the clock cannot, and neither can the work asking for
+ * the simulation to settle.
+ */
+export declare class BackgroundPendingTasks {
+    #private;
+    /**
+     * Hold a task until it settles, keeping how it settled for whoever waits.
+     */
+    hold(task: BackgroundTask): void;
+    /**
+     * Hold work a caller started, answering with what it settles with.
+     *
+     * Work already running inside a held task is counted where it is, and simply
+     * runs.
+     */
+    holdCallers<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Say that the held task running now is waiting on the clock.
+     */
+    waitingOnClock(): () => void;
+    /**
+     * How much work is outstanding, whatever it is waiting for.
+     */
+    get size(): number;
+    /**
+     * Wait until nothing is outstanding but work that is waiting on the clock.
+     *
+     * 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.
+     */
+    complete(): Promise<void>;
+    /**
+     * The work completion has anything to wait for, which is whatever is
+     * neither waiting on the clock nor waiting for completion itself.
+     *
+     * 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.
+     */
+    running(): Promise<unknown>[];
+}

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

@@ -0,0 +1,117 @@
+import { BackgroundSettledTasks } from "./background-settled-tasks.js";
+import { BackgroundClockWaits, } from "./background-clock-waits.js";
+/**
+ * The work one scheduler has outstanding, and how much of it is worth waiting
+ * for.
+ *
+ * Work gets here two ways. A task the scheduler was handed is held here until
+ * it settles, and its failure is kept for whoever waits for the simulation to
+ * complete. Work a caller started is held here too, but answers to that caller
+ * instead, because reporting the same failure twice would fail somebody who
+ * never asked for the work.
+ *
+ * Either way, what completion waits for is what can still get somewhere on its
+ * own. Work waiting on the clock cannot, and neither can the work asking for
+ * the simulation to settle.
+ */
+export class BackgroundPendingTasks {
+    #held = new Map();
+    #clockWaits = new BackgroundClockWaits();
+    /**
+     * Hold a task until it settles, keeping how it settled for whoever waits.
+     */
+    hold(task) {
+        const wait = { count: 0 };
+        this.#keep(wait, this.#clockWaits.around(wait, task));
+    }
+    /**
+     * Hold work a caller started, answering with what it settles with.
+     *
+     * Work already running inside a held task is counted where it is, and simply
+     * runs.
+     */
+    async holdCallers(work) {
+        if (this.#clockWaits.inWork) {
+            return await work();
+        }
+        const wait = { count: 0 };
+        const answer = this.#clockWaits.around(wait, work);
+        this.#keep(wait, ignoringFailure(answer));
+        return await answer;
+    }
+    /**
+     * Say that the held task running now is waiting on the clock.
+     */
+    waitingOnClock() {
+        return this.#clockWaits.begin();
+    }
+    /**
+     * How much work is outstanding, whatever it is waiting for.
+     */
+    get size() {
+        return this.#held.size;
+    }
+    /**
+     * Wait until nothing is outstanding but work that is waiting on the clock.
+     *
+     * 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.
+     */
+    async complete() {
+        let running = this.running();
+        while (running.length > 0) {
+            // oxlint-disable-next-line no-await-in-loop
+            const settled = await Promise.race([
+                Promise.allSettled(running),
+                this.#clockWaits.next,
+            ]);
+            new BackgroundSettledTasks(settled).throwFirstFailure();
+            running = this.running();
+        }
+    }
+    /**
+     * The work completion has anything to wait for, which is whatever is
+     * neither waiting on the clock nor waiting for completion itself.
+     *
+     * 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.
+     */
+    running() {
+        return this.#clockWaits.runnable(this.#held);
+    }
+    /**
+     * Keep work outstanding under its own record until it settles.
+     */
+    #keep(wait, work) {
+        const promise = settling(work, () => {
+            this.#held.delete(promise);
+        });
+        this.#held.set(promise, wait);
+    }
+}
+/**
+ * Answer for work, letting go of it once it has settled either way.
+ */
+async function settling(work, settled) {
+    try {
+        return await work;
+    }
+    finally {
+        settled();
+    }
+}
+/**
+ * Wait for work without taking on how it failed, which the caller holding it
+ * is told about instead.
+ */
+async function ignoringFailure(work) {
+    try {
+        await work;
+    }
+    catch {
+        // Reported to the caller, not to whoever waits for completion.
+    }
+}

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

@@ -5,10 +5,13 @@
  * throws has nowhere to report to. Waiting for tasks to settle is that
  * moment: this is what turns a settled batch back into a thrown error, so a
  * failure in the background surfaces to whoever waited rather than vanishing.
+ *
+ * A wait that ended on something else, such as a task parking on the clock,
+ * settled no batch at all and has no failure to report.
  */
 export declare class BackgroundSettledTasks {
     private readonly results;
-    constructor(results: PromiseSettledResult<void>[]);
+    constructor(results?: readonly PromiseSettledResult<unknown>[]);
     /**
      * Throw the first task failure in the batch, if there was one.
      */

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

@@ -5,10 +5,13 @@
  * throws has nowhere to report to. Waiting for tasks to settle is that
  * moment: this is what turns a settled batch back into a thrown error, so a
  * failure in the background surfaces to whoever waited rather than vanishing.
+ *
+ * A wait that ended on something else, such as a task parking on the clock,
+ * settled no batch at all and has no failure to report.
  */
 export class BackgroundSettledTasks {
     results;
-    constructor(results) {
+    constructor(results = []) {
         this.results = results;
     }
     /**

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

@@ -19,6 +19,27 @@ export interface BackgroundScheduler extends SimClock {
      */
     sequence(): Promise<void>;
     schedule(task: BackgroundTask): void;
+    /**
+     * Count work a caller started as outstanding until it settles.
+     *
+     * Completion then waits for it, so a simulation asked to settle takes in
+     * work a caller is holding the promise of as well as work it was handed.
+     * Whoever asked for it still gets what it settles with, failure included.
+     *
+     * Work already running as a scheduled task is counted where it is, and this
+     * simply runs it.
+     */
+    outstanding<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Run a task that is already due, and keep it outstanding until it settles.
+     *
+     * Started here and now rather than deferred to a host timer, because
+     * advancing the clock steps through every instant work falls due at and a
+     * timer for each of them would cost real time. It is counted as outstanding
+     * work all the same, so a task that goes on to wait for the clock stops
+     * holding up whatever is moving it.
+     */
+    runDue(task: BackgroundTask): void;
     /**
      * Schedule a task to happen once simulated time reaches an instant.
      *
@@ -35,6 +56,16 @@ export interface BackgroundScheduler extends SimClock {
      * already run, is nothing to give up on.
      */
     cancelScheduled(task: BackgroundTask): void;
+    /**
+     * Say that the scheduled task running now is waiting for simulated time to
+     * reach an instant, and get back the way to say it no longer is.
+     *
+     * Completion stops waiting for the task while it waits here, because moving
+     * the clock is the only thing that releases it and completion is what
+     * moving the clock waits for. Called from outside a scheduled task, such as
+     * from work a caller is holding the promise of, this changes nothing.
+     */
+    waitingOnClock(): () => void;
 }
 interface BackgroundTasksProperties {
     readonly clock?: SimClock;
@@ -82,6 +113,14 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * Schedule a task to happen asynchronously in the background.
      */
     schedule(task: BackgroundTask): void;
+    /**
+     * Run a task that is already due, keeping it outstanding until it settles.
+     */
+    runDue(task: BackgroundTask): void;
+    /**
+     * Count work a caller started as outstanding until it settles.
+     */
+    outstanding<T>(work: () => Promise<T>): Promise<T>;
     /**
      * Schedule a task to happen once simulated time reaches an instant.
      */
@@ -90,6 +129,10 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * Give up on a task scheduled to happen at a simulated instant.
      */
     cancelScheduled(task: BackgroundTask): void;
+    /**
+     * Say that the scheduled task running now is waiting on the clock.
+     */
+    waitingOnClock(): () => void;
     /**
      * Take the next task due at or before an instant, earliest first.
      */

package/dist/util/background/background.js

@@ -1,5 +1,7 @@
 /* oxlint-disable unicorn-js/prefer-await  */
+import { setTimeout } from "node:timers";
 import { SimRealClock } from "../clock/sim-clock.js";
+import { BackgroundPendingTasks } from "./background-pending-tasks.js";
 import { BackgroundDueTasks, } from "./background-due-tasks.js";
 /**
  * Deterministic async background tasks scheduler.
@@ -8,7 +10,7 @@ import { BackgroundDueTasks, } from "./background-due-tasks.js";
  * the order they were scheduled.
  */
 export class BackgroundTasks {
-    pending = new Set();
+    pending = new BackgroundPendingTasks();
     dueTasks = new BackgroundDueTasks();
     clock;
     constructor(properties = {}) {
@@ -30,21 +32,24 @@ export class BackgroundTasks {
      * Schedule a task to happen asynchronously in the background.
      */
     schedule(task) {
-        const promise = new Promise((resolve) => {
-            setTimeout(resolve, 0);
-        })
-            .then(task)
-            .then(() => {
-            //
-        }, (error) => {
-            // Keep the promise rejected so complete() can surface failures
-            // deterministically.
-            throw error;
-        })
-            .finally(() => {
-            this.pending.delete(promise);
+        this.pending.hold(async () => {
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            await task();
         });
-        this.pending.add(promise);
+    }
+    /**
+     * Run a task that is already due, keeping it outstanding until it settles.
+     */
+    runDue(task) {
+        this.pending.hold(task);
+    }
+    /**
+     * Count work a caller started as outstanding until it settles.
+     */
+    async outstanding(work) {
+        return await this.pending.holdCallers(work);
     }
     /**
      * Schedule a task to happen once simulated time reaches an instant.
@@ -58,6 +63,12 @@ export class BackgroundTasks {
     cancelScheduled(task) {
         this.dueTasks.cancel(task);
     }
+    /**
+     * Say that the scheduled task running now is waiting on the clock.
+     */
+    waitingOnClock() {
+        return this.pending.waitingOnClock();
+    }
     /**
      * Take the next task due at or before an instant, earliest first.
      */
@@ -73,10 +84,7 @@ export class BackgroundTasks {
      * clock releases it.
      */
     async complete() {
-        while (this.pending.size > 0) {
-            // oxlint-disable-next-line no-await-in-loop
-            await Promise.all(this.pending);
-        }
+        await this.pending.complete();
     }
     /**
      * See how many outstanding background tasks are scheduled.

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

@@ -28,6 +28,14 @@ export declare class NonDeterministicBackgroundTasks implements BackgroundSchedu
      * Schedule a task to happen asynchronously in the background.
      */
     schedule(task: BackgroundTask): void;
+    /**
+     * Run a task that is already due, keeping it outstanding until it settles.
+     */
+    runDue(task: BackgroundTask): void;
+    /**
+     * Count work a caller started as outstanding until it settles.
+     */
+    outstanding<T>(work: () => Promise<T>): Promise<T>;
     /**
      * Schedule a task to happen once simulated time reaches an instant.
      */
@@ -36,6 +44,10 @@ export declare class NonDeterministicBackgroundTasks implements BackgroundSchedu
      * Give up on a task scheduled to happen at a simulated instant.
      */
     cancelScheduled(task: BackgroundTask): void;
+    /**
+     * Say that the scheduled task running now is waiting on the clock.
+     */
+    waitingOnClock(): () => void;
     /**
      * Take the next task due at or before an instant, earliest first.
      */