@spine-event-engine/testing 2.0.0-snapshot.21 → 2.0.0-snapshot.22

package/dist/black-box/black-box.d.ts

@@ -54,6 +54,7 @@ export interface BlackBoxScope extends ClientRequest {
      * @param schema The schema of the event message.
      * @param message The event message to post.
      * @returns A promise that resolves after the event is posted.
+     * @typeParam Schema The domain schema that determines the accepted message shape.
      */
     postEvent<Schema extends GenMessage<Message>>(schema: Schema, message: MessageShape<Schema>): Promise<void>;
     /**
@@ -62,6 +63,7 @@ export interface BlackBoxScope extends ClientRequest {
      * @param schema The schema of the external event message.
      * @param message The external event message.
      * @returns A promise that resolves after external event admission.
+     * @typeParam Schema The domain schema that determines the accepted message shape.
      */
     postExternalEvent<Schema extends GenMessage<Message>>(schema: Schema, message: MessageShape<Schema>): Promise<void>;
 }
@@ -70,6 +72,15 @@ export interface BlackBoxScope extends ClientRequest {
  */
 export declare class BlackBox {
     #private;
+    /**
+     * Captures the server, client, test options, and produced-signal observation.
+     *
+     * @param context The bounded context under test.
+     * @param server The started local server.
+     * @param client The client connected to that server.
+     * @param options The validated tenant, zone, and wait settings.
+     * @param observation The optional produced-signal observer.
+     */
     private constructor();
     /**
      * Starts an ephemeral local server and public client for a context or builder.
@@ -111,14 +122,20 @@ export declare class BlackBox {
      * @param accept The predicate that accepts a produced value.
      * @param options Optional wait limits for this operation.
      * @returns The first accepted value.
+     * @typeParam Value The value type carried through reading or delivery.
      */
     eventually<Value>(read: () => Value | Promise<Value>, accept: (value: Value) => boolean, options?: Pick<BlackBoxOptions, "timeoutMs" | "intervalMs">): Promise<Value>;
     /**
-     * Stops admission, cancels owned subscriptions, and closes the client and server once.
+     * Stops admission, cancels registered subscriptions, and closes the client and server once.
      *
      * @returns A shared promise that resolves after cleanup completes.
      */
     close(): Promise<void>;
+    /**
+     * Stops admission and waits, cancels subscriptions, and closes the client and server.
+     *
+     * @returns Completion after all cleanup settles, or an aggregate of failures.
+     */
     private closeOnce;
 }
 /**
@@ -129,13 +146,13 @@ export interface BlackBoxTestAccess {
      * Creates a BlackBox with supplied closeable resources.
      *
      * @param resources The test client, server, and optional subscriptions.
-     * @returns A BlackBox that owns the supplied resources.
+     * @returns A BlackBox configured with the supplied resources.
      */
     create(resources: BlackBoxTestResources): BlackBox;
     /**
      * Returns a generic subscription-like handle for lifecycle regression tests.
      *
-     * @param blackBox The BlackBox that owns the handle.
+     * @param blackBox The BlackBox tracking the handle.
      * @param handle The cancelable async handle to track.
      * @returns The tracked handle.
      */

package/dist/black-box/black-box.d.ts.map

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

package/dist/black-box/black-box.js

@@ -11,8 +11,8 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
+import { Time } from "@spine-event-engine/core/time";
 import { clone, create } from "@bufbuild/protobuf";
-import { TimestampSchema } from "@bufbuild/protobuf/wkt";
 import { Client as NodeClient, } from "@spine-event-engine/client-node";
 import { SignalEnvelopes } from "@spine-event-engine/core";
 import { ActorContextSchema, CommandSchema, EventContextSchema, EventSchema, TenantIdSchema, UserIdSchema, ZoneIdSchema, } from "@spine-event-engine/proto";
@@ -64,6 +64,15 @@ export class BlackBox {
     #observation;
     #admitting = true;
     #closing;
+    /**
+     * Captures the server, client, test options, and produced-signal observation.
+     *
+     * @param context The bounded context under test.
+     * @param server The started local server.
+     * @param client The client connected to that server.
+     * @param options The validated tenant, zone, and wait settings.
+     * @param observation The optional produced-signal observer.
+     */
     constructor(context, server, client, options, observation) {
         this.#context = context;
         this.#server = server;
@@ -151,24 +160,25 @@ export class BlackBox {
      * @param accept The predicate that accepts a produced value.
      * @param options Optional wait limits for this operation.
      * @returns The first accepted value.
+     * @typeParam Value The value type carried through reading or delivery.
      */
     async eventually(read, accept, options = {}) {
         this.#assertOpen();
         const timeoutMs = BlackBoxOptionsValues.positiveInteger(options.timeoutMs ?? this.#timeoutMs, "timeoutMs");
         const intervalMs = BlackBoxOptionsValues.positiveInteger(options.intervalMs ?? this.#intervalMs, "intervalMs");
-        const deadline = Date.now() + timeoutMs;
+        const deadline = Time.monotonicTime() + timeoutMs;
         for (;;) {
             const value = await read();
             this.#assertOpen();
             if (accept(value))
                 return value;
-            if (Date.now() >= deadline)
+            if (Time.monotonicTime() >= deadline)
                 throw new BlackBoxTimeoutError(timeoutMs);
-            await BlackBoxClock.wait(Math.min(intervalMs, deadline - Date.now()), this.#waits.signal);
+            await BlackBoxClock.wait(Math.min(intervalMs, deadline - Time.monotonicTime()), this.#waits.signal);
         }
     }
     /**
-     * Stops admission, cancels owned subscriptions, and closes the client and server once.
+     * Stops admission, cancels registered subscriptions, and closes the client and server once.
      *
      * @returns A shared promise that resolves after cleanup completes.
      */
@@ -176,10 +186,22 @@ export class BlackBox {
         this.#closing ??= this.closeOnce();
         return this.#closing;
     }
+    /**
+     * Rejects calls once BlackBox cleanup has begun.
+     */
     #assertOpen() {
         if (!this.#admitting)
             throw new BlackBoxClosedError();
     }
+    /**
+     * Posts a direct event with a controlled occurrence timestamp and actor context.
+     *
+     * @typeParam Schema The domain schema that determines the accepted message shape.
+     * @param actor The actor identifier recorded in signal contexts.
+     * @param schema The domain message schema used to encode the payload.
+     * @param message The domain payload to post.
+     * @returns Completion after the event bus accepts the direct event.
+     */
     async #postEvent(actor, schema, message) {
         this.#assertOpen();
         await this.#context.eventBus().post(SignalEnvelopes.event({
@@ -191,6 +213,15 @@ export class BlackBox {
             message,
         }));
     }
+    /**
+     * Admits an external event with controlled occurrence time through server intake.
+     *
+     * @typeParam Schema The domain schema that determines the accepted message shape.
+     * @param actor The actor identifier recorded in signal contexts.
+     * @param schema The domain message schema used to encode the payload.
+     * @param message The domain payload to post.
+     * @returns Completion after server intake accepts the external event.
+     */
     async #postExternalEvent(actor, schema, message) {
         this.#assertOpen();
         await postExternalEvent(this.#context, SignalEnvelopes.event({
@@ -202,14 +233,31 @@ export class BlackBox {
             message,
         }));
     }
+    /**
+     * Registers a cancelable subscription for session cleanup.
+     *
+     * @typeParam Handle The cancelable handle type retained when tracking it.
+     * @param handle The cancelable handle to track.
+     * @returns The same handle registered for cleanup.
+     */
     #track(handle) {
         this.#assertOpen();
         this.#subscriptions.add(handle);
         return handle;
     }
+    /**
+     * Removes a completed subscription from session cleanup.
+     *
+     * @param handle The cancelable handle to track.
+     */
     #release(handle) {
         this.#subscriptions.delete(handle);
     }
+    /**
+     * Creates a test actor context with cloned tenant and zone and controlled occurrence time.
+     *
+     * @param actor The actor identifier recorded in signal contexts.
+     */
     #actorContext(actor) {
         return create(ActorContextSchema, {
             ...(this.#tenant === undefined ? {} : { tenantId: clone(TenantIdSchema, this.#tenant) }),
@@ -218,6 +266,11 @@ export class BlackBox {
             timestamp: BlackBoxClock.timestamp(),
         });
     }
+    /**
+     * Stops admission and waits, cancels subscriptions, and closes the client and server.
+     *
+     * @returns Completion after all cleanup settles, or an aggregate of failures.
+     */
     async closeOnce() {
         this.#admitting = false;
         this.#waits.abort(new BlackBoxClosedError());
@@ -249,13 +302,19 @@ const BlackBoxAccess = (() => {
     return Object.freeze({
         // prettier-ignore
         /**
-         * Associates internal operations with a BlackBox.
+         * Stores private lifecycle operations for the corresponding BlackBox instance.
+         *
+         * @param blackBox The BlackBox instance associated with these internals.
+         * @param internals The private operations for that instance.
          */
         set(blackBox, internals) {
             values.set(blackBox, internals);
         },
         /**
-         * Obtains the internal operations for a BlackBox.
+         * Returns private lifecycle operations or rejects an unregistered instance.
+         *
+         * @param blackBox The BlackBox instance associated with these internals.
+         * @returns The private operations registered for this instance.
          */
         get(blackBox) {
             const internals = values.get(blackBox);
@@ -274,7 +333,7 @@ export const BlackBoxTestAccess = Object.freeze({
      * Creates a BlackBox with supplied closeable resources.
      *
      * @param resources The test client, server, and optional subscriptions.
-     * @returns A BlackBox that owns the supplied resources.
+     * @returns A BlackBox configured with the supplied resources.
      */
     create(resources) {
         const blackBox = BlackBoxLifecycle.instantiate({}, resources.server, resources.client, BlackBoxOptionsValues.defaults(), resources.observation ?? Object.freeze({ close: () => undefined }));
@@ -285,7 +344,7 @@ export const BlackBoxTestAccess = Object.freeze({
     /**
      * Returns a generic subscription-like handle for lifecycle regression tests.
      *
-     * @param blackBox The BlackBox that owns the handle.
+     * @param blackBox The BlackBox tracking the handle.
      * @param handle The cancelable async handle to track.
      * @returns The tracked handle.
      */
@@ -306,12 +365,18 @@ export const BlackBoxTestAccess = Object.freeze({
     },
 });
 /**
- * Constructs BlackBox instances and compensates for failed startup.
+ * Creates BlackBox instances and compensates for failed startup.
  */
 const BlackBoxLifecycle = Object.freeze({
     // prettier-ignore
     /**
      * Opens the server and client before constructing a BlackBox.
+     *
+     * @param context The bounded context used to start the test server.
+     * @param options The validated tenant, zone, and wait settings.
+     * @param start The operation that starts the test server.
+     * @param connect The operation that connects a client to the started server.
+     * @returns The started BlackBox or a startup cleanup failure.
      */
     async open(context, options, start, connect) {
         let server;
@@ -339,36 +404,92 @@ const BlackBoxLifecycle = Object.freeze({
         }
     },
     /**
-     * Instantiates a BlackBox through its deliberately private constructor.
+     * Creates a BlackBox through its deliberately private constructor.
+     *
+     * @param context The bounded context under test.
+     * @param server The started local server.
+     * @param client The client connected to that server.
+     * @param options The validated tenant, zone, and wait settings.
+     * @param observation The optional produced-signal observer.
+     * @returns A BlackBox containing the supplied resources.
      */
     instantiate(context, server, client, options, observation) {
         const Constructor = BlackBox;
         return new Constructor(context, server, client, options, observation);
     },
 });
+/**
+ * Keeps an actor and fixed tenant and zone settings for fresh request contexts.
+ */
 class Request {
     #internals;
     #request;
     #actor;
+    /**
+     * Captures the selected actor and immutable request settings.
+     *
+     * @param blackBox The BlackBox instance associated with these internals.
+     * @param request The scoped client request used for public operations.
+     * @param actor The actor identifier recorded in signal contexts.
+     */
     constructor(blackBox, request, actor) {
         this.#internals = BlackBoxAccess.get(blackBox);
         this.#request = request;
         this.#actor = actor;
     }
+    /**
+     * Posts a command with a fresh actor context and validates the acknowledged command ID.
+     *
+     * @typeParam Schema The domain schema that determines the accepted message shape.
+     * @param schema The domain message schema used to encode the payload.
+     * @param message The domain payload to post.
+     * @param options The optional signal that cancels the command request.
+     * @returns The acknowledged application outcome.
+     */
     post(schema, message, options = {}) {
         this.#internals.assertOpen();
         return this.#request.post(schema, message, options);
     }
+    /**
+     * Posts a domain Event through the BlackBox context for this actor.
+     *
+     * @typeParam Schema The domain schema that determines the accepted message shape.
+     * @param schema The domain message schema used to encode the payload.
+     * @param message The domain payload to post.
+     * @returns Completion after the direct event is posted.
+     */
     postEvent(schema, message) {
         return this.#internals.postEvent(this.#actor, schema, message);
     }
+    /**
+     * Posts an external domain Event through the BlackBox context for this actor.
+     *
+     * @typeParam Schema The domain schema that determines the accepted message shape.
+     * @param schema The domain message schema used to encode the payload.
+     * @param message The domain payload to post.
+     * @returns Completion after external event admission.
+     */
     postExternalEvent(schema, message) {
         return this.#internals.postExternalEvent(this.#actor, schema, message);
     }
+    /**
+     * Reads through the scoped client after confirming the BlackBox remains open.
+     *
+     * @param query The query message or builder to read.
+     * @param options The cancellation settings for this read.
+     * @returns The query response from the scoped client.
+     */
     send(query, options) {
         this.#internals.assertOpen();
         return this.#request.send(query, options);
     }
+    /**
+     * Validates the subscription kind and creates an inactive, client-managed topic stream.
+     *
+     * @param topic The requested topic with its target.
+     * @param options The subscription kind, recovery query, and optional cancellation signal.
+     * @returns The inactive tracked subscription.
+     */
     async createSubscription(topic, options) {
         this.#internals.assertOpen();
         const subscription = await this.#request.createSubscription(topic, options);
@@ -378,24 +499,54 @@ class Request {
         return this.#internals.track(tracked);
     }
 }
+/**
+ * Tracks stream completion and cancellation for BlackBox cleanup.
+ */
 class TrackedSubscription {
     #handle;
     #onRelease;
     #released = false;
     #cancellation;
+    /**
+     * Wraps a subscription and registers its release callback.
+     *
+     * @param handle The cancelable handle to track.
+     * @param onRelease The callback removing a completed handle from cleanup tracking.
+     */
     constructor(handle, onRelease) {
         this.#handle = handle;
         this.#onRelease = onRelease;
     }
+    /**
+     * Wraps live updates so terminal iteration releases cleanup tracking.
+     *
+     * @returns An iterable of live updates and authoritative recovery values.
+     */
     get updates() {
         return this.trackStream(this.#handle.updates);
     }
+    /**
+     * Wraps lifecycle notices so terminal iteration releases cleanup tracking.
+     *
+     * @returns An iterable of lifecycle notices for this subscription.
+     */
     get lifecycle() {
         return this.trackStream(this.#handle.lifecycle);
     }
+    /**
+     * Sends activation to the underlying subscription.
+     *
+     * @param options The optional signal that cancels activation.
+     * @returns Completion after remote activation.
+     */
     activate(options) {
         return this.#handle.activate(options);
     }
+    /**
+     * Cancels the underlying subscription once and releases cleanup tracking.
+     *
+     * @returns Completion after remote cleanup.
+     */
     async cancel() {
         try {
             this.#cancellation ??= this.#handle.cancel();
@@ -405,12 +556,24 @@ class TrackedSubscription {
             this.release();
         }
     }
+    /**
+     * Removes cleanup tracking when iteration ends, fails, or returns early.
+     *
+     * @typeParam Value The update or lifecycle value yielded by the tracked stream.
+     * @param source The subscription stream whose terminal iteration releases tracking.
+     * @returns An iterable that releases tracking on terminal iteration.
+     */
     trackStream(source) {
         const onRelease = () => {
             this.release();
         };
         const onCancel = () => this.cancel();
         return {
+            /**
+             * Returns an iterator that releases subscription tracking when it terminates.
+             *
+             * @returns An iterator that releases tracking when it terminates.
+             */
             [Symbol.asyncIterator]() {
                 const iterator = source[Symbol.asyncIterator]();
                 return {
@@ -451,6 +614,9 @@ class TrackedSubscription {
             },
         };
     }
+    /**
+     * Executes the release callback at most once.
+     */
     release() {
         if (this.#released)
             return;
@@ -458,14 +624,31 @@ class TrackedSubscription {
         this.#onRelease();
     }
 }
+/**
+ * Wraps a cancelable test handle and tracks its completion.
+ *
+ * @typeParam Handle The cancelable handle type retained when tracking it.
+ */
 class Tracked {
     #handle;
     #onRelease;
     #cancellation;
+    /**
+     * Captures the handle and callback that removes it from cleanup tracking.
+     *
+     * @param handle The cancelable handle to track.
+     * @param onRelease The callback removing a completed handle from cleanup tracking.
+     */
     constructor(handle, onRelease) {
         this.#handle = handle;
         this.#onRelease = onRelease;
     }
+    /**
+     * Activates a subscription-like test handle or rejects an unsupported handle.
+     *
+     * @param arguments_ The arguments forwarded to the wrapped activation.
+     * @returns Completion after remote activation.
+     */
     async activate(...arguments_) {
         const subscription = this.#handle;
         if (subscription.activate === undefined) {
@@ -473,6 +656,11 @@ class Tracked {
         }
         await subscription.activate(...arguments_);
     }
+    /**
+     * Removes a tracked handle when iteration ends or fails.
+     *
+     * @returns An iterator that releases tracking when it terminates.
+     */
     [Symbol.asyncIterator]() {
         const iterator = this.#handle[Symbol.asyncIterator]();
         return {
@@ -513,6 +701,11 @@ class Tracked {
             },
         };
     }
+    /**
+     * Cancels the wrapped handle once and releases it even after failure.
+     *
+     * @returns Completion after remote cleanup.
+     */
     async cancel() {
         try {
             this.#cancellation ??= this.#handle.cancel();
@@ -530,6 +723,10 @@ const BlackBoxOptionsValues = Object.freeze({
     // prettier-ignore
     /**
      * Normalizes options for one context.
+     *
+     * @param context The bounded context whose tenant mode is validated.
+     * @param options The requested tenant and wait settings.
+     * @returns Validated immutable test settings.
      */
     normalize(context, options) {
         const multi = context instanceof BoundedContext ? context.isMultitenant : context.isMultitenant();
@@ -546,13 +743,18 @@ const BlackBoxOptionsValues = Object.freeze({
         });
     },
     /**
-     * Clones an optional tenant message.
+     * Returns a separate tenant message when a tenant was selected.
+     *
+     * @param value The optional tenant message to clone.
+     * @returns A clone of the tenant or undefined.
      */
     cloneTenant(value) {
         return value === undefined ? undefined : clone(TenantIdSchema, value);
     },
     /**
      * Creates default normalized options for internal test seams.
+     *
+     * @returns Immutable tenant, zone, and wait defaults for test seams.
      */
     defaults() {
         return Object.freeze({
@@ -564,6 +766,9 @@ const BlackBoxOptionsValues = Object.freeze({
     },
     /**
      * Converts a tenant option to its message form.
+     *
+     * @param value The optional tenant string or identifier to validate and clone.
+     * @returns A cloned tenant identifier or undefined.
      */
     tenant(value) {
         if (value === undefined)
@@ -579,6 +784,9 @@ const BlackBoxOptionsValues = Object.freeze({
     },
     /**
      * Converts a zone option to its message form.
+     *
+     * @param value The optional zone string or identifier; omitted values use current Time.
+     * @returns A cloned zone identifier.
      */
     zoneId(value) {
         if (typeof value !== "string" && value !== undefined) {
@@ -586,13 +794,17 @@ const BlackBoxOptionsValues = Object.freeze({
                 throw new TypeError("BlackBox zoneId must not be empty.");
             return clone(ZoneIdSchema, value);
         }
-        const zone = value ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const zone = value ?? Time.currentTimeZone();
         if (zone.length === 0)
             throw new TypeError("BlackBox zoneId must not be empty.");
         return create(ZoneIdSchema, { value: zone });
     },
     /**
      * Validates a positive whole-number duration.
+     *
+     * @param value The configured wait duration in milliseconds.
+     * @param name The duration option named in validation errors.
+     * @returns The validated positive integer.
      */
     positiveInteger(value, name) {
         if (!Number.isInteger(value) || value <= 0)
@@ -606,13 +818,19 @@ const BlackBoxOptionsValues = Object.freeze({
 const BlackBoxClock = Object.freeze({
     // prettier-ignore
     /**
-     * Creates the current Protobuf timestamp.
+     * Returns the configured occurrence Time for posted events and actor contexts.
+     *
+     * @returns The current controlled Protobuf timestamp.
      */
     timestamp() {
-        return create(TimestampSchema, { seconds: BigInt(Math.floor(Date.now() / 1_000)) });
+        return Time.currentTime();
     },
     /**
      * Waits for a delay or rejects when the supplied signal aborts.
+     *
+     * @param milliseconds The timer delay in milliseconds.
+     * @param signal The abort signal for this operation.
+     * @returns Completion when the timer expires unless aborted.
      */
     wait(milliseconds, signal) {
         return new Promise((resolve, reject) => {
@@ -635,6 +853,9 @@ const BlackBoxFailures = Object.freeze({
     // prettier-ignore
     /**
      * Returns reasons from rejected promises.
+     *
+     * @param results The settled cleanup operation results.
+     * @returns Failure reasons in their settled result order.
      */
     rejected(results) {
         const failures = [];