@photon-grove/evt 0.0.0 → 0.1.1

package/dist/store.js

@@ -0,0 +1,246 @@
+// The Store: loads aggregates, runs commands, and commits their events with the snapshots the
+// snapshot policy calls for.
+import { encodeEventData, replayEvent, } from './aggregate.js';
+import { commitIds } from './commit-id.js';
+import { EvtError, SequenceGapError, SnapshotError, isConflict, isRetryable } from './errors.js';
+import { eventId } from './event.js';
+import { emptyMetadata } from './metadata.js';
+import { DEFAULT_RETRY_POLICY, checkRetryPolicy, retryDelay, sleep, } from './retry.js';
+import { MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue } from './snapshots.js';
+/** The default number of events between snapshots, as in Go and Rust. */
+export const DEFAULT_SNAPSHOT_INTERVAL = 5;
+// How many times a load reads the stream when it finds a sequence gap.
+const LOAD_ATTEMPTS = 3;
+const INT64_MAX = 2n ** 63n - 1n;
+export class Store {
+    repository;
+    #region;
+    #clock;
+    #snapshotInterval;
+    #commitId;
+    constructor(repository, options = {}) {
+        const interval = options.snapshotInterval ?? DEFAULT_SNAPSHOT_INTERVAL;
+        if (!Number.isSafeInteger(interval) || interval < 0) {
+            throw new EvtError('invalidArgument', `the snapshot interval must be a whole number of events: ${interval}`);
+        }
+        this.repository = repository;
+        this.#region = options.region ?? '';
+        this.#clock = options.clock ?? Date.now;
+        this.#snapshotInterval = interval;
+        this.#commitId = options.commitId ?? commitIds(this.#clock);
+    }
+    /** The number of events between snapshots of `aggregate`: its own interval, or the store's. */
+    snapshotInterval(aggregate) {
+        return aggregate.snapshotInterval ?? this.#snapshotInterval;
+    }
+    /**
+     * Loads an aggregate from its snapshot and the events after it, or from every event when it has
+     * no snapshot. An entity with no events loads as the initial state at sequence 0.
+     *
+     * The events must continue the sequence. A gap means another writer snapshotted and compacted
+     * the stream between the two reads, so the load starts over, up to three times, and then fails
+     * with a {@link SequenceGapError}. When no events follow, the snapshot is read again to rule out
+     * a compaction that left no gap to see.
+     */
+    async load(aggregate, entityId, options = {}) {
+        // Each attempt waits for the one before it.
+        /* oxlint-disable no-await-in-loop */
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.#loadOnce(aggregate, entityId, options);
+            }
+            catch (error) {
+                if (!isConflict(error) || attempt >= LOAD_ATTEMPTS) {
+                    throw error;
+                }
+            }
+        }
+        /* oxlint-enable no-await-in-loop */
+    }
+    /**
+     * Loads the aggregate, runs the command, and commits its events, with a snapshot when the
+     * commit reaches the snapshot interval. A snapshot whose item is over the per-item commit budget
+     * is left out, so the commit still succeeds and later loads replay from the one before.
+     *
+     * A command ID already carried by an event folded in since the latest snapshot makes the
+     * command a `duplicate`, and the handler doesn't run. A conflict with another writer throws;
+     * {@link executeWithRetry} runs the command again.
+     */
+    async execute(aggregate, entityId, command, options = {}) {
+        const metadata = this.#metadata(options.metadata);
+        const loaded = await this.load(aggregate, entityId, options);
+        const commandId = metadata.commandId;
+        if (commandId !== null && commandId !== '' && loaded.seenCommandIds.has(commandId)) {
+            return { kind: 'duplicate', commandId };
+        }
+        const decision = await aggregate.handle(loaded.state, command);
+        if (decision.kind === 'reject') {
+            return { kind: 'rejected', rejection: decision.rejection, state: loaded };
+        }
+        if (decision.events.length === 0) {
+            return { kind: 'committed', state: loaded, events: [] };
+        }
+        const { state, events, snapshot } = this.#stage(aggregate, loaded, decision.events, metadata);
+        await this.repository.commit({ entityId, events, snapshot }, options);
+        return { kind: 'committed', state, events };
+    }
+    /**
+     * Like {@link execute}, but loads and runs the command again after a retryable error (see
+     * {@link isRetryable}), waiting {@link retryDelay} between attempts. When the attempts run out,
+     * the last error is thrown. A rejection or a duplicate is a result, never retried.
+     */
+    async executeWithRetry(aggregate, entityId, command, options = {}) {
+        const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+        checkRetryPolicy(policy);
+        const wait = options.sleep ?? sleep;
+        // Each attempt waits for the one before it.
+        /* oxlint-disable no-await-in-loop */
+        for (let retry = 0;; retry++) {
+            try {
+                return await this.execute(aggregate, entityId, command, options);
+            }
+            catch (error) {
+                if (!isRetryable(error) || retry + 1 >= policy.maxAttempts) {
+                    throw error;
+                }
+            }
+            await wait(retryDelay(policy, retry), options.signal);
+        }
+        /* oxlint-enable no-await-in-loop */
+    }
+    async #loadOnce(aggregate, entityId, options) {
+        const snapshot = await this.repository.snapshot(entityId, options);
+        let state = aggregate.initial();
+        let sequence = 0n;
+        let snapshotSequence = 0n;
+        if (snapshot) {
+            try {
+                state = aggregate.state.decode(snapshot.payload ?? new Uint8Array());
+            }
+            catch (error) {
+                throw new SnapshotError(entityId, error);
+            }
+            sequence = snapshot.eventSequence;
+            snapshotSequence = snapshot.sequence;
+        }
+        const events = snapshot
+            ? await this.repository.eventsAfter(entityId, sequence, options)
+            : await this.repository.events(entityId, options);
+        // With no events after it, a snapshot and a compaction between the two reads would leave no
+        // gap to see, so the snapshot is read again: a newer one means the stream moved past it.
+        if (events.length === 0) {
+            const covered = (await this.repository.snapshot(entityId, options))?.eventSequence ?? 0n;
+            if (covered > sequence) {
+                throw new SequenceGapError(entityId, sequence, covered + 1n);
+            }
+        }
+        const seenCommandIds = new Set();
+        for (const stored of events) {
+            if (stored.sequence !== sequence + 1n) {
+                throw new SequenceGapError(entityId, sequence, stored.sequence);
+            }
+            state = aggregate.apply(state, replayEvent(aggregate.events, stored));
+            sequence = stored.sequence;
+            const commandId = stored.metadata.commandId;
+            if (commandId !== null && commandId !== '') {
+                seenCommandIds.add(commandId);
+            }
+        }
+        return { entityId, state, sequence, snapshotSequence, seenCommandIds };
+    }
+    // Applies the decided events, and builds the stored events and the snapshot the policy calls
+    // for. The state is only used once the commit succeeds.
+    #stage(aggregate, loaded, decided, metadata) {
+        const entityId = loaded.entityId;
+        let sequence = loaded.sequence;
+        let state = loaded.state;
+        const events = [];
+        for (const event of decided) {
+            if (sequence >= INT64_MAX) {
+                throw new EvtError('invalidCommit', `invalid commit: entity ${entityId} is at the maximum event sequence`);
+            }
+            sequence++;
+            const { version, payload } = encodeEventData(aggregate.events, event);
+            events.push({
+                id: eventId(entityId, sequence),
+                sequence,
+                type: event.type,
+                version,
+                entityId,
+                entityType: aggregate.type,
+                payload,
+                metadata: copyMetadata(metadata),
+            });
+            state = aggregate.apply(state, event);
+        }
+        const interval = this.snapshotInterval(aggregate);
+        let snapshot = null;
+        if (snapshotEventsDue(loaded.sequence, decided.length, interval) > 0) {
+            snapshot = {
+                entityType: aggregate.type,
+                sequence: loaded.snapshotSequence + 1n,
+                payload: aggregate.state.encode(state),
+            };
+            // A snapshot over the per-item budget would fail every commit that carries it.
+            const size = snapshotCommitSize({ ...snapshot, entityId, eventSequence: sequence });
+            if (size > MAX_COMMIT_ITEM_BYTES) {
+                snapshot = null;
+            }
+        }
+        const seenCommandIds = new Set(loaded.seenCommandIds);
+        if (metadata.commandId !== null && metadata.commandId !== '') {
+            seenCommandIds.add(metadata.commandId);
+        }
+        return {
+            state: {
+                entityId,
+                state,
+                sequence,
+                snapshotSequence: snapshot ? snapshot.sequence : loaded.snapshotSequence,
+                seenCommandIds,
+            },
+            events,
+            snapshot,
+        };
+    }
+    // The command's metadata with the store's region and the clock's timestamp where it has none,
+    // and the commit ID the engine stamps: the command ID, else the caller's, else a generated one.
+    // Field by field, so a field an untyped caller set to undefined is empty too, and every key is
+    // written.
+    #metadata(partial = {}) {
+        const empty = emptyMetadata();
+        const metadata = {
+            commandId: partial.commandId ?? empty.commandId,
+            trace: partial.trace ? new Map(partial.trace) : empty.trace,
+            origin: partial.origin ? { ...partial.origin } : empty.origin,
+            address: partial.address ?? empty.address,
+            region: partial.region || this.#region,
+            timestamp: partial.timestamp || rfc3339Seconds(this.#clock()),
+            principalId: partial.principalId ?? empty.principalId,
+            causationId: partial.causationId ?? empty.causationId,
+            extensions: partial.extensions ? new Map(partial.extensions) : empty.extensions,
+            commitId: partial.commitId ?? empty.commitId,
+        };
+        if (metadata.commandId !== null && metadata.commandId !== '') {
+            metadata.commitId = metadata.commandId;
+        }
+        else if (metadata.commitId === '') {
+            metadata.commitId = this.#commitId();
+        }
+        return metadata;
+    }
+}
+// Each stored event gets its own metadata, so changing one changes no other.
+function copyMetadata(metadata) {
+    return {
+        ...metadata,
+        trace: metadata.trace && new Map(metadata.trace),
+        origin: metadata.origin && { ...metadata.origin },
+        extensions: new Map(metadata.extensions),
+    };
+}
+// RFC 3339 in UTC, to the second, as Go's time.RFC3339 formats a UTC time.
+function rfc3339Seconds(ms) {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/testing/equal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A failed assertion. It carries `actual` and `expected` the way Node's `assert` does, so runners
+ * such as Vitest and Jest show a diff, and `node:test` prints both.
+ */
+export declare class AssertionError extends Error {
+    readonly name = "AssertionError";
+    readonly actual: unknown;
+    readonly expected: unknown;
+    constructor(message: string, actual?: unknown, expected?: unknown);
+}
+/**
+ * Whether two values have the same structure: objects of the same prototype by their own
+ * enumerable string and symbol keys (a key whose value is `undefined` counts as absent), arrays by
+ * their elements, holes included, `Map`s by their entries and `Set`s by their members, buffers and
+ * typed arrays by their bytes, dates by their time, regular expressions by their source and flags,
+ * and everything else with `Object.is`. `Map` keys and `Set` members match by identity, and
+ * `#private` fields aren't seen.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Prints a value for an assertion message, with `bigint`s, `Map`s and byte arrays legible. */
+export declare function show(value: unknown): string;
+//# sourceMappingURL=equal.d.ts.map

package/dist/testing/equal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equal.d.ts","sourceRoot":"","sources":["../../src/testing/equal.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,oBAAmB;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAIhE;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CA2DzD;AAqBD,+FAA+F;AAC/F,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsC3C"}

package/dist/testing/equal.js

@@ -0,0 +1,121 @@
+// Structural equality and printing for test assertions, so /testing depends on no test framework.
+/**
+ * A failed assertion. It carries `actual` and `expected` the way Node's `assert` does, so runners
+ * such as Vitest and Jest show a diff, and `node:test` prints both.
+ */
+export class AssertionError extends Error {
+    name = 'AssertionError';
+    actual;
+    expected;
+    constructor(message, actual, expected) {
+        super(message);
+        this.actual = actual;
+        this.expected = expected;
+    }
+}
+/**
+ * Whether two values have the same structure: objects of the same prototype by their own
+ * enumerable string and symbol keys (a key whose value is `undefined` counts as absent), arrays by
+ * their elements, holes included, `Map`s by their entries and `Set`s by their members, buffers and
+ * typed arrays by their bytes, dates by their time, regular expressions by their source and flags,
+ * and everything else with `Object.is`. `Map` keys and `Set` members match by identity, and
+ * `#private` fields aren't seen.
+ */
+export function deepEqual(a, b) {
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+        return false;
+    }
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
+        return false;
+    }
+    if (Array.isArray(a)) {
+        const other = b;
+        if (a.length !== other.length) {
+            return false;
+        }
+        // An index loop, since every() skips holes.
+        for (let i = 0; i < a.length; i++) {
+            if (i in a !== i in other || !deepEqual(a[i], other[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (a instanceof ArrayBuffer || ArrayBuffer.isView(a)) {
+        const left = bytes(a);
+        const right = bytes(b);
+        return left.length === right.length && left.every((byte, i) => byte === right[i]);
+    }
+    if (a instanceof Map) {
+        const other = b;
+        return (a.size === other.size &&
+            [...a].every(([key, entry]) => other.has(key) && deepEqual(entry, other.get(key))));
+    }
+    if (a instanceof Set) {
+        const other = b;
+        return a.size === other.size && [...a].every((entry) => other.has(entry));
+    }
+    if (a instanceof Date) {
+        return Object.is(a.getTime(), b.getTime());
+    }
+    if (a instanceof RegExp) {
+        return a.source === b.source && a.flags === b.flags;
+    }
+    const left = definedKeys(a);
+    const right = definedKeys(b);
+    return (left.length === right.length &&
+        left.every((key) => Object.hasOwn(b, key) && deepEqual(field(a, key), field(b, key))));
+}
+function bytes(value) {
+    return value instanceof ArrayBuffer
+        ? new Uint8Array(value)
+        : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+// The own enumerable keys, symbols included, whose values aren't undefined.
+function definedKeys(value) {
+    const symbols = Object.getOwnPropertySymbols(value).filter((key) => Object.prototype.propertyIsEnumerable.call(value, key));
+    return [...Object.keys(value), ...symbols].filter((key) => field(value, key) !== undefined);
+}
+function field(value, key) {
+    return value[key];
+}
+/** Prints a value for an assertion message, with `bigint`s, `Map`s and byte arrays legible. */
+export function show(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'bigint') {
+        return `${value}n`;
+    }
+    if (Object.is(value, -0)) {
+        return '-0';
+    }
+    if (typeof value !== 'object' || value === null) {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(show).join(', ')}]`;
+    }
+    if (value instanceof Uint8Array) {
+        return `Uint8Array [${value.join(', ')}]`;
+    }
+    if (value instanceof Map) {
+        const entries = [...value].map(([key, entry]) => `${show(key)} => ${show(entry)}`);
+        return `Map {${entries.join(', ')}}`;
+    }
+    if (value instanceof Set) {
+        return `Set {${[...value].map(show).join(', ')}}`;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? 'Invalid Date' : `Date ${value.toISOString()}`;
+    }
+    if (value instanceof Error) {
+        return `${value.name}: ${value.message}`;
+    }
+    const entries = Object.entries(value).map(([key, entry]) => `${show(key)}: ${show(entry)}`);
+    return `{${entries.join(', ')}}`;
+}
+//# sourceMappingURL=equal.js.map

package/dist/testing/equal.js.map

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

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { AssertionError, deepEqual } from './equal.js';
+export { type Committed, DEFAULT_ENTITY_ID, Fixture, Outcome, Scenario, type ScenarioSetup, When, scenario, } from './scenario.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,cAAc,EAAE,SAAS,EAAC,MAAM,YAAY,CAAA;AACpD,OAAO,EACL,KAAK,SAAS,EACd,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,QAAQ,EACR,KAAK,aAAa,EAClB,IAAI,EACJ,QAAQ,GACT,MAAM,eAAe,CAAA"}

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+// @photon-grove/evt/testing: given/when/then helpers over MemRepository. They throw an
+// AssertionError on failure, so they work in any test runner.
+export { AssertionError, deepEqual } from './equal.js';
+export { DEFAULT_ENTITY_ID, Fixture, Outcome, Scenario, When, scenario, } from './scenario.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,8DAA8D;AAE9D,OAAO,EAAC,cAAc,EAAE,SAAS,EAAC,MAAM,YAAY,CAAA;AACpD,OAAO,EAEL,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,QAAQ,EAER,IAAI,EACJ,QAAQ,GACT,MAAM,eAAe,CAAA"}

package/dist/testing/scenario.d.ts

@@ -0,0 +1,136 @@
+import { type Aggregate, type EventDefinitions, type EventOf, type Rejection } from '../aggregate.js';
+import { type SerializedEvent } from '../event.js';
+import { MemRepository } from '../memory/repository.js';
+import { type Metadata } from '../metadata.js';
+import { type ExecuteResult, type Loaded, Store, type StoreOptions } from '../store.js';
+/** The entity ID a {@link Scenario} runs against unless {@link Scenario.entity} sets one. */
+export declare const DEFAULT_ENTITY_ID = "entity-1";
+/**
+ * A {@link MemRepository} with helpers to seed and read streams of any aggregate. Hand its
+ * `repository` to the code under test, or run several {@link Scenario}s on it with
+ * {@link Scenario.on} so they build on each other.
+ */
+export declare class Fixture {
+    readonly repository: MemRepository;
+    constructor(repository?: MemRepository);
+    /** A store over the fixture's repository. */
+    store(options?: StoreOptions): Store;
+    /**
+     * Appends events to a stream as if earlier commands had committed them. On a stream that
+     * already has events, it continues the sequence from the loaded aggregate, which is where the
+     * snapshot leaves off after a compaction. It writes no snapshot, and its metadata is empty but
+     * for a commit ID.
+     */
+    given<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, events: readonly EventOf<D>[]): Promise<void>;
+    /** The stream's stored events, upcast and decoded, oldest first. */
+    events<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string): Promise<EventOf<D>[]>;
+    /** The aggregate loaded from its stream, from the snapshot like {@link Store.load}. */
+    load<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string): Promise<Loaded<S>>;
+    /** Asserts that the stream holds exactly these events, decoded. */
+    assertEvents<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, expected: readonly EventOf<D>[]): Promise<void>;
+}
+/**
+ * Starts a given/when/then test of one command against one stream:
+ *
+ * ```ts
+ * await scenario(account)
+ *   .given({type: 'account:opened', data: {owner: 'ada'}})
+ *   .when({type: 'deposit', amountCents: 5})
+ *   .thenEvents({type: 'account:deposited', data: {amountCents: 5}})
+ * ```
+ *
+ * Each `then` method runs the command through a real {@link Store} over a {@link MemRepository}
+ * and throws an {@link AssertionError} when the outcome differs, which fails the surrounding test
+ * in any runner. {@link When.run} gives the {@link Outcome} to inspect further.
+ */
+export declare function scenario<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>): Scenario<S, C, D>;
+/** What a {@link Scenario} runs with. Build one with {@link scenario}. */
+export interface ScenarioSetup<D extends EventDefinitions> {
+    readonly fixture: Fixture | null;
+    readonly entityId: string;
+    readonly given: readonly EventOf<D>[];
+    readonly metadata: Partial<Metadata>;
+    readonly options: StoreOptions;
+}
+/**
+ * A command's setting: the aggregate, the stream and its prior events, and how the store runs.
+ * Each method returns a new scenario, so one can be the base of several tests. Without
+ * {@link Scenario.on}, each run gets a fixture of its own.
+ */
+export declare class Scenario<S, C, D extends EventDefinitions> {
+    #private;
+    readonly aggregate: Aggregate<S, C, D>;
+    constructor(aggregate: Aggregate<S, C, D>, setup: ScenarioSetup<D>);
+    /** Adds events the stream holds before the command. */
+    given(...events: EventOf<D>[]): Scenario<S, C, D>;
+    /** Sets the stream's entity ID ({@link DEFAULT_ENTITY_ID} by default). */
+    entity(entityId: string): Scenario<S, C, D>;
+    /** Sets the metadata the command runs with, such as a command ID to test duplicates. */
+    metadata(metadata: Partial<Metadata>): Scenario<S, C, D>;
+    /** Sets the store's options: its clock, region, snapshot interval or commit IDs. */
+    options(options: StoreOptions): Scenario<S, C, D>;
+    /**
+     * Runs on an existing fixture, so the streams it holds are visible and several scenarios build
+     * on each other. Each run seeds the given events and runs the command again, so on a shared
+     * fixture, running a scenario twice writes it twice. Each run gets a new fixture otherwise.
+     */
+    on(fixture: Fixture): Scenario<S, C, D>;
+    /** Names the command to run. */
+    when(command: C): When<S, C, D>;
+}
+/** A {@link Scenario} with its command, ready to run. */
+export declare class When<S, C, D extends EventDefinitions> {
+    #private;
+    constructor(aggregate: Aggregate<S, C, D>, setup: ScenarioSetup<D>, command: C);
+    /**
+     * Seeds the given events, runs the command, and resolves to its {@link Outcome}. Each call does
+     * both again. Invalid store options or a failure to seed throw; a failure of the command is the
+     * outcome's.
+     */
+    run(): Promise<Outcome<S, C, D>>;
+    /** Asserts that the command commits exactly these events. */
+    thenEvents(...expected: EventOf<D>[]): Promise<void>;
+    /** Asserts that the command commits and emits nothing. */
+    thenNoEvents(): Promise<void>;
+    /**
+     * Asserts that the handler rejects the command, with this code or a rejection `matches`
+     * accepts.
+     */
+    thenRejected(matches?: string | ((rejection: Rejection) => boolean)): Promise<void>;
+    /** Asserts that the command is a duplicate of one already in the dedupe window. */
+    thenDuplicate(): Promise<void>;
+    /** Asserts that the store throws, with an error `matches` accepts. */
+    thenError(matches?: (error: unknown) => boolean): Promise<void>;
+    /** Asserts that the command commits, then hands `check` the state after it. */
+    thenState(check: (state: S) => void | Promise<void>): Promise<void>;
+}
+/** The result of a command that committed. */
+export type Committed<S> = Extract<ExecuteResult<S>, {
+    kind: 'committed';
+}>;
+/** What running a {@link Scenario} did. */
+export declare class Outcome<S, C, D extends EventDefinitions> {
+    #private;
+    readonly aggregate: Aggregate<S, C, D>;
+    /** The fixture the scenario ran on, to inspect other streams. */
+    readonly fixture: Fixture;
+    readonly entityId: string;
+    /** What {@link Store.execute} resolved to, or the error it threw. */
+    readonly settled: PromiseSettledResult<ExecuteResult<S>>;
+    constructor(aggregate: Aggregate<S, C, D>, fixture: Fixture, entityId: string, settled: PromiseSettledResult<ExecuteResult<S>>);
+    /** The events as stored, if the command committed. */
+    get storedEvents(): SerializedEvent[] | null;
+    /** The aggregate after the command. Throws unless it committed. */
+    get state(): Loaded<S>;
+    /** Asserts that the command committed, and returns what it did. */
+    assertCommitted(): Committed<S>;
+    /** Asserts that the command committed exactly these events, decoded. */
+    assertEvents(...expected: EventOf<D>[]): void;
+    /** Asserts that the handler rejected the command, with this code or as `matches` accepts. */
+    assertRejected(matches?: string | ((rejection: Rejection) => boolean)): Rejection;
+    /** Asserts that the command was a duplicate, and returns its command ID. */
+    assertDuplicate(): string;
+    /** Asserts that the store threw, with an error `matches` accepts, and returns the error. */
+    assertError(matches?: (error: unknown) => boolean): unknown;
+}
+//# sourceMappingURL=scenario.d.ts.map

package/dist/testing/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/testing/scenario.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,SAAS,EAGf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAC,KAAK,eAAe,EAAU,MAAM,aAAa,CAAA;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAC,KAAK,QAAQ,EAAgB,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAC,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,YAAY,EAAC,MAAM,aAAa,CAAA;AAGrF,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAE3C;;;;GAIG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAElC,YAAY,UAAU,GAAE,aAAmC,EAE1D;IAED,6CAA6C;IAC7C,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAEvC;IAED;;;;;OAKG;IACG,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB,EAC1C,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAyBf;IAED,oEAAoE;IAC9D,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB,EAC3C,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAIvB;IAED,uFAAuF;IACvF,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB,EACnC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAEpB;IAED,mEAAmE;IAC7D,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB,EACjD,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC,CAIf;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB,EACvD,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC5B,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAQnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,gBAAgB;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAC/B;AAED;;;;GAIG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB;;IACpD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAGtC,YAAY,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAGjE;IAED,uDAAuD;IACvD,KAAK,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEhD;IAED,0EAA0E;IAC1E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAE1C;IAED,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEvD;IAED,oFAAoF;IACpF,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEhD;IAED;;;;OAIG;IACH,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEtC;IAED,gCAAgC;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAE9B;CAKF;AAED,yDAAyD;AACzD,qBAAa,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB;;IAKhD,YAAY,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAI7E;IAED;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAerC;IAED,6DAA6D;IACvD,UAAU,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzD;IAED,0DAA0D;IACpD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAGlC;IAED;;;OAGG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxF;IAED,mFAAmF;IAC7E,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAGnC;IAED,sEAAsE;IAChE,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;IAED,+EAA+E;IACzE,SAAS,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxE;CACF;AAED,8CAA8C;AAC9C,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE;IAAC,IAAI,EAAE,WAAW,CAAA;CAAC,CAAC,CAAA;AAEzE,2CAA2C;AAC3C,qBAAa,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,gBAAgB;;IACnD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACtC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IAExD,YACE,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAMhD;IAED,sDAAsD;IACtD,IAAI,YAAY,IAAI,eAAe,EAAE,GAAG,IAAI,CAM3C;IAED,mEAAmE;IACnE,IAAI,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,CAErB;IAED,mEAAmE;IACnE,eAAe,IAAI,SAAS,CAAC,CAAC,CAAC,CAS9B;IAED,wEAAwE;IACxE,YAAY,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAK5C;IAED,6FAA6F;IAC7F,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,GAAG,SAAS,CAoBhF;IAED,4EAA4E;IAC5E,eAAe,IAAI,MAAM,CAOxB;IAED,4FAA4F;IAC5F,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAU1D;CAkBF"}