@spine-event-engine/server 2.0.0-snapshot.2

package/dist/bus/command-bus.js

@@ -0,0 +1,201 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { clone } from "@bufbuild/protobuf";
+import { ValidationException, Validate, AnyMessages } from "@spine-event-engine/core";
+import { CommandSchema } from "@spine-event-engine/proto";
+import { runtimeAccess, ServerRuntimeStateError, SingleProcessServerRuntime, } from "../runtime/runtime.js";
+import { CommandValidationError } from "./command-errors.js";
+import { ImplicitRequiredIds } from "../entity/implicit-required-id.js";
+import { CommandDispatcherRegistry } from "./command-dispatcher-registry.js";
+const internalCommandPosters = new WeakMap();
+const commandBusCloseStarters = new WeakMap();
+const commandBusDrainers = new WeakMap();
+const commandBusCloseFinishers = new WeakMap();
+const commandBusWorkCounters = new WeakMap();
+/**
+ * Small single-process unicast command bus.
+ *
+ * Commands are accepted asynchronously through `post()` and routed by enclosed
+ * message type URL to exactly one registered dispatcher.
+ */
+export class CommandBus {
+    #registry = new CommandDispatcherRegistry();
+    #runtime = new SingleProcessServerRuntime();
+    #started;
+    #intakeState = "open";
+    #acceptedWorkCount = 0;
+    #closed;
+    /**
+     * Creates a bus and registers its initial dispatchers.
+     *
+     * @param dispatchers the dispatchers to register.
+     */
+    constructor(dispatchers = []) {
+        this.#started = this.#runtime.start();
+        internalCommandPosters.set(this, (command) => this.#postInternal(command));
+        commandBusCloseStarters.set(this, () => {
+            this.#beginClose();
+        });
+        commandBusDrainers.set(this, () => this.#drain());
+        commandBusCloseFinishers.set(this, () => this.#finishClose());
+        commandBusWorkCounters.set(this, () => this.#acceptedWorkCount);
+        for (const dispatcher of dispatchers) {
+            this.register(dispatcher);
+        }
+    }
+    /**
+     * Registers a dispatcher.
+     *
+     * @param dispatcher the dispatcher to register.
+     * @returns the registered dispatcher.
+     */
+    register(dispatcher) {
+        this.#registry.register(dispatcher);
+        return dispatcher;
+    }
+    /**
+     * Lists command type URLs accepted by registered dispatchers.
+     *
+     * @returns the accepted command type URLs.
+     */
+    acceptedCommandTypes() {
+        return this.#registry.acceptedTypeUrls();
+    }
+    /**
+     * Posts a command for asynchronous dispatch.
+     *
+     * @param command the command envelope to post.
+     * @returns A promise that settles after queued command dispatch completes and may reject.
+     */
+    post(command) {
+        const accepted = clone(CommandSchema, command);
+        if (this.#intakeState !== "open") {
+            return Promise.reject(new ServerRuntimeStateError("enqueue", this.#intakeState));
+        }
+        return this.#enqueueAccepted(accepted);
+    }
+    /**
+     * Stops accepting new command work and waits for accepted work to settle.
+     *
+     * Close is idempotent and returns the same close outcome on repeated calls.
+     * Runtime close failures reject the returned promise.
+     * @returns A promise that settles after the command bus closes.
+     *
+     */
+    close() {
+        this.#closed ??= this.#closeOnce();
+        return this.#closed;
+    }
+    #postInternal(command) {
+        const accepted = clone(CommandSchema, command);
+        if (this.#intakeState === "closed") {
+            return Promise.reject(new ServerRuntimeStateError("enqueue", "closed"));
+        }
+        return this.#enqueueAccepted(accepted);
+    }
+    #enqueueAccepted(command) {
+        this.#acceptedWorkCount++;
+        return this.#started.then(() => this.#runtime.enqueue(() => this.#dispatch(command)));
+    }
+    #beginClose() {
+        if (this.#intakeState === "open") {
+            this.#intakeState = "closing";
+        }
+    }
+    #drain() {
+        return this.#started.then(() => runtimeAccess.drain(this.#runtime));
+    }
+    #finishClose() {
+        this.#closed ??= this.#closeOnce();
+        return this.#closed;
+    }
+    async #closeOnce() {
+        this.#beginClose();
+        await this.#started;
+        await this.#runtime.close();
+        this.#intakeState = "closed";
+    }
+    async #dispatch(command) {
+        const packed = command.message;
+        if (packed === undefined || packed.typeUrl === "") {
+            throw new Error("CommandBus requires command.message.typeUrl.");
+        }
+        const typeUrl = packed.typeUrl;
+        const registration = this.#registry.find(typeUrl);
+        if (registration === undefined) {
+            throw new Error(`No command dispatcher registered for "${typeUrl}".`);
+        }
+        const message = AnyMessages.unpack(packed, registration.schema);
+        if (message === undefined) {
+            throw CommandValidationError.invalidPayload();
+        }
+        try {
+            Validate.check(registration.schema, message);
+        }
+        catch (error) {
+            if (error instanceof ValidationException) {
+                throw new CommandValidationError(error.asMessage());
+            }
+            throw error;
+        }
+        const implicitId = ImplicitRequiredIds.validateCommand(registration.schema, message);
+        if (!implicitId.valid) {
+            throw new CommandValidationError(implicitId.error);
+        }
+        await registration.dispatcher.dispatch(clone(CommandSchema, command));
+    }
+}
+/**
+ * Provides framework-owned command posting and coordinated close access.
+ *
+ * @internal
+ */
+export const commandBusAccess = Object.freeze({
+    postInternal(commandBus, command) {
+        const postInternal = internalCommandPosters.get(commandBus);
+        if (postInternal === undefined) {
+            throw new TypeError("Internal command post requires a CommandBus instance.");
+        }
+        return postInternal(command);
+    },
+    beginClose(commandBus) {
+        const beginClose = commandBusCloseStarters.get(commandBus);
+        if (beginClose === undefined) {
+            throw new TypeError("Command-bus close coordination requires a CommandBus instance.");
+        }
+        beginClose();
+    },
+    drain(commandBus) {
+        const drain = commandBusDrainers.get(commandBus);
+        if (drain === undefined) {
+            throw new TypeError("Command-bus drain requires a CommandBus instance.");
+        }
+        return drain();
+    },
+    finishClose(commandBus) {
+        const finishClose = commandBusCloseFinishers.get(commandBus);
+        if (finishClose === undefined) {
+            throw new TypeError("Command-bus close completion requires a CommandBus instance.");
+        }
+        return finishClose();
+    },
+    acceptedWorkCount(commandBus) {
+        const acceptedWorkCount = commandBusWorkCounters.get(commandBus);
+        if (acceptedWorkCount === undefined) {
+            throw new TypeError("Command-bus work counting requires a CommandBus instance.");
+        }
+        return acceptedWorkCount();
+    },
+});
+//# sourceMappingURL=command-bus.js.map

package/dist/bus/command-bus.js.map

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

package/dist/bus/command-dispatcher-registry.d.ts

@@ -0,0 +1,33 @@
+import { type MessageSchema } from "@spine-event-engine/core";
+import type { CommandDispatcher } from "./command-dispatcher.js";
+interface RegisteredCommandDispatcher {
+    readonly dispatcher: CommandDispatcher;
+    readonly schema: MessageSchema;
+}
+/**
+ * Internal unicast registry keyed by canonical Spine command type URL.
+ */
+export declare class CommandDispatcherRegistry {
+    #private;
+    /**
+     * Registers a dispatcher and all of its distinct command schemas.
+     *
+     * @param dispatcher the dispatcher to register.
+     */
+    register(dispatcher: CommandDispatcher): void;
+    /**
+     * Finds the dispatcher registered for a canonical command type URL.
+     *
+     * @param typeUrl the canonical command type URL.
+     * @returns the registration, when one exists.
+     */
+    find(typeUrl: string): RegisteredCommandDispatcher | undefined;
+    /**
+     * Lists the canonical command type URLs accepted by this registry.
+     *
+     * @returns the registered type URLs.
+     */
+    acceptedTypeUrls(): readonly string[];
+}
+export {};
+//# sourceMappingURL=command-dispatcher-registry.d.ts.map

package/dist/bus/command-dispatcher-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatcher-registry.d.ts","sourceRoot":"","sources":["../../src/bus/command-dispatcher-registry.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,aAAa,EAAY,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,UAAU,2BAA2B;IACnC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,yBAAyB;;IAIpC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAyB7C;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,2BAA2B,GAAG,SAAS;IAI9D;;;;OAIG;IACH,gBAAgB,IAAI,SAAS,MAAM,EAAE;CAoBtC"}

package/dist/bus/command-dispatcher-registry.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { TypeUrls } from "@spine-event-engine/core";
+/**
+ * Internal unicast registry keyed by canonical Spine command type URL.
+ */
+export class CommandDispatcherRegistry {
+    #dispatchers = new Set();
+    #byTypeUrl = new Map();
+    /**
+     * Registers a dispatcher and all of its distinct command schemas.
+     *
+     * @param dispatcher the dispatcher to register.
+     */
+    register(dispatcher) {
+        if (this.#dispatchers.has(dispatcher)) {
+            return;
+        }
+        const registrations = CommandDispatcherRegistry.#registrations(dispatcher);
+        for (const registration of registrations) {
+            const registered = this.#byTypeUrl.get(registration.typeUrl);
+            if (registered !== undefined && registered.dispatcher !== dispatcher) {
+                throw new Error(`Duplicate command dispatcher for "${registration.typeUrl}".`);
+            }
+        }
+        this.#dispatchers.add(dispatcher);
+        for (const registration of registrations) {
+            this.#byTypeUrl.set(registration.typeUrl, {
+                dispatcher,
+                schema: registration.schema,
+            });
+        }
+    }
+    /**
+     * Finds the dispatcher registered for a canonical command type URL.
+     *
+     * @param typeUrl the canonical command type URL.
+     * @returns the registration, when one exists.
+     */
+    find(typeUrl) {
+        return this.#byTypeUrl.get(typeUrl);
+    }
+    /**
+     * Lists the canonical command type URLs accepted by this registry.
+     *
+     * @returns the registered type URLs.
+     */
+    acceptedTypeUrls() {
+        return Object.freeze([...this.#byTypeUrl.keys()]);
+    }
+    static #registrations(dispatcher) {
+        const registrations = [];
+        const seen = new Set();
+        for (const schema of dispatcher.messageSchemas()) {
+            const typeUrl = TypeUrls.derive(schema);
+            if (!seen.has(typeUrl)) {
+                seen.add(typeUrl);
+                registrations.push({ typeUrl, schema });
+            }
+        }
+        return Object.freeze(registrations);
+    }
+}
+//# sourceMappingURL=command-dispatcher-registry.js.map

package/dist/bus/command-dispatcher-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatcher-registry.js","sourceRoot":"","sources":["../../src/bus/command-dispatcher-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAsB,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AASxE;;GAEG;AACH,MAAM,OAAO,yBAAyB;IAC3B,YAAY,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC5C,UAAU,GAAG,IAAI,GAAG,EAAuC,CAAC;IAErE;;;;OAIG;IACH,QAAQ,CAAC,UAA6B;QACpC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACtC,OAAO;QACT,CAAC;QAED,MAAM,aAAa,GAAG,yBAAyB,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAE3E,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YAE7D,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBACrE,MAAM,IAAI,KAAK,CAAC,qCAAqC,YAAY,CAAC,OAAO,IAAI,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;QAED,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAElC,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE;gBACxC,UAAU;gBACV,MAAM,EAAE,YAAY,CAAC,MAAM;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,CAAC,cAAc,CACnB,UAA6B;QAE7B,MAAM,aAAa,GAAiD,EAAE,CAAC;QACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAE/B,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAExC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACvB,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAClB,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/bus/command-dispatcher.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from "@spine-event-engine/proto";
+import type { MessageSchema } from "@spine-event-engine/core";
+/**
+ * Small unicast command-dispatch seam for bus and repository adapters.
+ *
+ * Dispatchers declare the command message schemas they accept and perform
+ * handling behind the bus seam. Repository-backed adapters own entity loading
+ * and method invocation; the bus only routes accepted command envelopes.
+ */
+export interface CommandDispatcher {
+    /**
+     * Lists generated command message schemas accepted by this dispatcher.
+     *
+     * @returns the accepted message schemas.
+     */
+    messageSchemas(): readonly MessageSchema[];
+    /**
+     * Dispatches one generated Spine command envelope.
+     *
+     * @param command the command envelope to dispatch.
+     * @returns A promise that resolves after the command is dispatched.
+     */
+    dispatch(command: Command): Promise<void>;
+}
+//# sourceMappingURL=command-dispatcher.d.ts.map

package/dist/bus/command-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatcher.d.ts","sourceRoot":"","sources":["../../src/bus/command-dispatcher.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;;;OAIG;IACH,cAAc,IAAI,SAAS,aAAa,EAAE,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C"}

package/dist/bus/command-dispatcher.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+export {};
+//# sourceMappingURL=command-dispatcher.js.map

package/dist/bus/command-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-dispatcher.js","sourceRoot":"","sources":["../../src/bus/command-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/bus/command-errors.d.ts

@@ -0,0 +1,23 @@
+import { type ValidationError } from "@spine-event-engine/proto";
+/**
+ * Error raised when a command envelope payload fails command-bus validation.
+ */
+export declare class CommandValidationError extends Error {
+    /**
+     * Structured payload validation details from the command-bus boundary.
+     */
+    readonly validationError: ValidationError;
+    /**
+     * Creates a command-bus validation error with structured details.
+     *
+     * @param validationError the structured payload validation details.
+     */
+    constructor(validationError: ValidationError);
+    /**
+     * Creates a validation error for payloads that cannot be unpacked as the registered type.
+     *
+     * @returns the invalid-payload error.
+     */
+    static invalidPayload(): CommandValidationError;
+}
+//# sourceMappingURL=command-errors.d.ts.map

package/dist/bus/command-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-errors.d.ts","sourceRoot":"","sources":["../../src/bus/command-errors.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,2BAA2B,CAAC;AAEnC;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAG/C;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;OAIG;gBACS,eAAe,EAAE,eAAe;IAO5C;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,sBAAsB;CAWhD"}

package/dist/bus/command-errors.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Validate } from "@spine-event-engine/core";
+import { ConstraintViolationSchema, TemplateStringSchema, } from "@spine-event-engine/proto";
+/**
+ * Error raised when a command envelope payload fails command-bus validation.
+ */
+export class CommandValidationError extends Error {
+    // prettier-ignore
+    /**
+     * Structured payload validation details from the command-bus boundary.
+     */
+    validationError;
+    /**
+     * Creates a command-bus validation error with structured details.
+     *
+     * @param validationError the structured payload validation details.
+     */
+    constructor(validationError) {
+        super("Command payload validation failed.");
+        this.name = "CommandValidationError";
+        this.validationError = validationError;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Creates a validation error for payloads that cannot be unpacked as the registered type.
+     *
+     * @returns the invalid-payload error.
+     */
+    static invalidPayload() {
+        return new CommandValidationError(Validate.createError([
+            create(ConstraintViolationSchema, {
+                message: create(TemplateStringSchema, {
+                    withPlaceholders: "Command payload could not be decoded as the registered type.",
+                }),
+            }),
+        ]));
+    }
+}
+//# sourceMappingURL=command-errors.js.map

package/dist/bus/command-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-errors.js","sourceRoot":"","sources":["../../src/bus/command-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAErB,MAAM,2BAA2B,CAAC;AAEnC;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,kBAAkB;IAElB;;OAEG;IACM,eAAe,CAAkB;IAE1C;;;;OAIG;IACH,YAAY,eAAgC;QAC1C,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,cAAc;QACnB,OAAO,IAAI,sBAAsB,CAC/B,QAAQ,CAAC,WAAW,CAAC;YACnB,MAAM,CAAC,yBAAyB,EAAE;gBAChC,OAAO,EAAE,MAAM,CAAC,oBAAoB,EAAE;oBACpC,gBAAgB,EAAE,8DAA8D;iBACjF,CAAC;aACH,CAAC;SACH,CAAC,CACH,CAAC;IACJ,CAAC;CACF"}

package/dist/bus/event-bus.d.ts

@@ -0,0 +1,113 @@
+import { type MessageSchema } from "@spine-event-engine/core";
+import { type Event } from "@spine-event-engine/proto";
+import type { EventStore } from "@spine-event-engine/storage";
+import type { ILogLayer } from "loglayer";
+import type { EventDispatcher } from "./event-dispatcher.js";
+interface EventBusAccess {
+    /**
+     * Assembles a package-internal bus that owns no event store.
+     *
+     * @param dispatchers the initial dispatchers to register.
+     * @returns the assembled forgetting bus.
+     */
+    createForgettingBus(dispatchers?: Iterable<EventDispatcher>): EventBus;
+    createSystemBus(eventStore: EventStore | undefined, dispatchers?: Iterable<EventDispatcher>): EventBus;
+    postStored(eventBus: EventBus, event: Event): Promise<void>;
+    postStoredFollowUp(eventBus: EventBus, event: Event): Promise<void>;
+    postFollowUp(eventBus: EventBus, event: Event): Promise<void>;
+    runExclusive<Result>(eventBus: EventBus, work: () => Result | Promise<Result>): Promise<Result>;
+    subscribe(eventBus: EventBus, typeUrl: string, subscriber: EventSubscriber): EventSubscription;
+    eventSchemas(eventBus: EventBus): readonly MessageSchema[];
+    registerSchemas(eventBus: EventBus, schemas: Iterable<MessageSchema>): void;
+    unregister(eventBus: EventBus, dispatcher: EventDispatcher): void;
+    schema(eventBus: EventBus, typeUrl: string): MessageSchema | undefined;
+    beginClose(eventBus: EventBus): void;
+    drain(eventBus: EventBus): Promise<void>;
+    finishClose(eventBus: EventBus): Promise<void>;
+    abortClose(eventBus: EventBus): void;
+    acceptedWorkCount(eventBus: EventBus): number;
+    installLogger(eventBus: EventBus, logger: ILogLayer): void;
+    clearLogger(eventBus: EventBus): void;
+}
+/**
+ * Small single-process multicast event bus.
+ *
+ * Public construction creates a domain-only bus that stores domain events and
+ * rejects System schemas, dispatchers, and events. Internally assembled
+ * forgetting and System buses own no `EventStore` unless explicitly given one.
+ * Events with no matching dispatcher resolve without dispatch. Events with no
+ * registered schema reject deterministically before storage or dispatch.
+ */
+export declare class EventBus {
+    #private;
+    /**
+     * Creates a domain-only bus backed by an event store and initial dispatchers.
+     * System schemas and dispatchers are rejected; framework System events use
+     * the package-internal System-bus factory instead.
+     *
+     * @param eventStore the store that persists accepted events.
+     * @param dispatchers the dispatchers to register.
+     */
+    constructor(eventStore: EventStore, dispatchers?: Iterable<EventDispatcher>);
+    /**
+     * Registers an event dispatcher.
+     *
+     * @param dispatcher the dispatcher to register.
+     * @returns the registered dispatcher.
+     */
+    register<Dispatcher extends EventDispatcher>(dispatcher: Dispatcher): Dispatcher;
+    /**
+     * Posts an event for asynchronous dispatch.
+     *
+     * @param event the event envelope to post.
+     * @returns A promise that settles after admission and dispatch complete and may reject.
+     */
+    post(event: Event): Promise<void>;
+    /**
+     * Stops accepting new event work, drains accepted work, and closes an owned event store.
+     *
+     * Close is idempotent and returns the same close outcome on repeated calls.
+     * Runtime and event-store close hooks are both attempted; failures reject as
+     * an `AggregateError`.
+     *
+     * @returns A promise that settles after the event bus closes.
+     *
+     */
+    close(): Promise<void>;
+}
+/**
+ * Accepts events for framework service adapters.
+ *
+ * @internal
+ */
+export interface EventSubscriber {
+    /**
+     * Accepts a cloned dispatched event.
+     *
+     * @param event the event received by the subscription.
+     */
+    onEvent(event: Event): void;
+}
+/**
+ * Represents an explicit cleanup handle for framework event subscriptions.
+ *
+ * @internal
+ */
+export interface EventSubscription {
+    /**
+     * Indicates whether the subscription no longer receives events.
+     */
+    readonly closed: boolean;
+    /**
+     * Stops this subscription from receiving events.
+     */
+    unsubscribe(): void;
+}
+/**
+ * Provides package-internal EventBus access and assembly.
+ *
+ * @internal
+ */
+export declare const eventBusAccess: EventBusAccess;
+export {};
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/bus/event-bus.d.ts.map

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