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

package/dist/handler/generated-registry-discovery.d.ts

@@ -0,0 +1,94 @@
+import { HandlerRegistryIngestor } from "./generated-handler-registry.js";
+import { HandlerMetadataRegistry } from "./handler-metadata.js";
+/**
+ * Stable error code for generated registry discovery failures.
+ */
+export type RegistryDiscoveryErrorCode = "MODULE_IMPORT_FAILED" | "MISSING_REGISTRY_EXPORT" | "INVALID_REGISTRY_MODULE" | "REGISTRY_INGESTION_FAILED" | "UNSUPPORTED_MODULE_SCHEME" | "INVALID_MODULE_REF" | "DUPLICATE_REGISTRY_MODULE";
+/**
+ * Options for loading one or more generated registry modules.
+ */
+export interface GeneratedRegistryDiscoveryOptions {
+    /**
+     * Explicit filesystem paths or file: URLs to load.
+     */
+    readonly modules: readonly (string | URL)[];
+    /**
+     * Export name expected from each generated module.
+     */
+    readonly exportName?: string;
+    /**
+     * Optional retry token used to bypass Node's dynamic import cache for canonical modules.
+     */
+    readonly cacheBust?: string;
+}
+/**
+ * Error thrown when generated registry discovery or loading fails.
+ */
+export declare class GeneratedRegistryDiscoveryError extends Error {
+    /**
+     * Stable code for callers/tests that need structured failure handling.
+     */
+    readonly code: RegistryDiscoveryErrorCode;
+    /**
+     * Normalized imported module identifier.
+     */
+    readonly moduleId: string;
+    /**
+     * Optional underlying import or ingestion error.
+     */
+    readonly cause: unknown;
+    /**
+     * Creates a registry discovery error.
+     *
+     * @param code Stable code that identifies the failed operation.
+     * @param message Human-readable failure description.
+     * @param moduleId Normalized identifier of the affected module.
+     * @param cause Underlying import or ingestion failure.
+     */
+    constructor(code: RegistryDiscoveryErrorCode, message: string, moduleId: string, cause?: unknown);
+}
+/**
+ * Framework-owned runtime loader for generated handler registry modules.
+ */
+export declare class GeneratedRegistryDiscovery {
+    #private;
+    /**
+     * Creates a generated-registry loader.
+     *
+     * @param ingestor Adapter that validates and registers loaded metadata.
+     */
+    constructor(ingestor?: HandlerRegistryIngestor);
+    /**
+     * Builds the conventional generated registry module path for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns Absolute path to the conventional registry module.
+     */
+    static conventionalModulePath(root: string): string;
+    /**
+     * Builds the conventional generated registry module URL for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns File URL for the conventional registry module.
+     */
+    static conventionalModuleUrl(root: string): URL;
+    /**
+     * Loads generated handler registries from explicit filesystem paths or file URLs.
+     *
+     * @param options Module references and optional load configuration.
+     * @returns Frozen loaded registry values in module order.
+     */
+    load(options: GeneratedRegistryDiscoveryOptions): Promise<readonly unknown[]>;
+    /**
+     * Loads generated handler registries and ingests them into a caller-owned metadata registry.
+     *
+     * Registration stages all new metadata before mutating the caller-owned registry.
+     *
+     * @param options Module references and optional load configuration.
+     * @param registry Metadata registry to update, if one already exists.
+     * @returns Registry containing the loaded generated metadata.
+     */
+    register(options: GeneratedRegistryDiscoveryOptions, registry?: HandlerMetadataRegistry): Promise<HandlerMetadataRegistry>;
+    private loadModules;
+}
+//# sourceMappingURL=generated-registry-discovery.d.ts.map

package/dist/handler/generated-registry-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-registry-discovery.d.ts","sourceRoot":"","sources":["../../src/handler/generated-registry-discovery.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAMhE;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,yBAAyB,GACzB,yBAAyB,GACzB,2BAA2B,GAC3B,2BAA2B,GAC3B,oBAAoB,GACpB,2BAA2B,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAGhD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IAGxD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,SAAkB,KAAK,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;gBAED,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO;CASlB;AAED;;GAEG;AACH,qBAAa,0BAA0B;;IAGrC;;;;OAIG;gBACS,QAAQ,GAAE,uBAAuD;IAI7E;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAInD;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAI/C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,iCAAiC,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC;IAMnF;;;;;;;;OAQG;IACG,QAAQ,CACZ,OAAO,EAAE,iCAAiC,EAC1C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,OAAO,CAAC,uBAAuB,CAAC;YA8BrB,WAAW;CAqB1B"}

package/dist/handler/generated-registry-discovery.js

@@ -0,0 +1,226 @@
+/*
+ * 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 { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HandlerRegistryIngestor, } from "./generated-handler-registry.js";
+import { HandlerMetadataRegistry } from "./handler-metadata.js";
+const defaultExportName = "generatedHandlerRegistry";
+const generatedRegistryFile = "generated/handler/generated-handler-registry.js";
+const moduleSchemeRe = /^[A-Za-z][A-Za-z\d+.-]*:/;
+/**
+ * Error thrown when generated registry discovery or loading fails.
+ */
+export class GeneratedRegistryDiscoveryError extends Error {
+    // prettier-ignore
+    /**
+     * Stable code for callers/tests that need structured failure handling.
+     */
+    code;
+    /**
+     * Normalized imported module identifier.
+     */
+    moduleId;
+    /**
+     * Optional underlying import or ingestion error.
+     */
+    cause;
+    /**
+     * Creates a registry discovery error.
+     *
+     * @param code Stable code that identifies the failed operation.
+     * @param message Human-readable failure description.
+     * @param moduleId Normalized identifier of the affected module.
+     * @param cause Underlying import or ingestion failure.
+     */
+    constructor(code, message, moduleId, cause) {
+        super(message);
+        this.name = "GeneratedRegistryDiscoveryError";
+        this.code = code;
+        this.moduleId = moduleId;
+        this.cause = cause;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Framework-owned runtime loader for generated handler registry modules.
+ */
+export class GeneratedRegistryDiscovery {
+    #ingestor;
+    /**
+     * Creates a generated-registry loader.
+     *
+     * @param ingestor Adapter that validates and registers loaded metadata.
+     */
+    constructor(ingestor = new HandlerRegistryIngestor()) {
+        this.#ingestor = ingestor;
+    }
+    /**
+     * Builds the conventional generated registry module path for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns Absolute path to the conventional registry module.
+     */
+    static conventionalModulePath(root) {
+        return resolve(root, generatedRegistryFile);
+    }
+    /**
+     * Builds the conventional generated registry module URL for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns File URL for the conventional registry module.
+     */
+    static conventionalModuleUrl(root) {
+        return pathToFileURL(GeneratedRegistryDiscovery.conventionalModulePath(root));
+    }
+    /**
+     * Loads generated handler registries from explicit filesystem paths or file URLs.
+     *
+     * @param options Module references and optional load configuration.
+     * @returns Frozen loaded registry values in module order.
+     */
+    async load(options) {
+        const loaded = await this.loadModules(options);
+        return Object.freeze(loaded.map((entry) => entry.registry));
+    }
+    /**
+     * Loads generated handler registries and ingests them into a caller-owned metadata registry.
+     *
+     * Registration stages all new metadata before mutating the caller-owned registry.
+     *
+     * @param options Module references and optional load configuration.
+     * @param registry Metadata registry to update, if one already exists.
+     * @returns Registry containing the loaded generated metadata.
+     */
+    async register(options, registry) {
+        const loaded = await this.loadModules(options);
+        const target = registry ?? new HandlerMetadataRegistry();
+        const existing = target.listEntityHandlers();
+        const staged = new HandlerMetadataRegistry(existing);
+        for (const entry of loaded) {
+            try {
+                this.#ingestor.register(entry.registry, staged);
+            }
+            catch (error) {
+                throw new GeneratedRegistryDiscoveryError("REGISTRY_INGESTION_FAILED", `Generated handler registry module "${entry.moduleId}" could not be ingested.`, entry.moduleId, error);
+            }
+        }
+        if (registry === undefined) {
+            return staged;
+        }
+        for (const metadata of staged.listEntityHandlers().slice(existing.length)) {
+            registry.register(metadata);
+        }
+        return registry;
+    }
+    async loadModules(options) {
+        const exportName = options.exportName ?? defaultExportName;
+        const moduleRefs = [...options.modules];
+        const moduleIds = moduleRefs.map((moduleRef) => RegistryModules.normalize(moduleRef));
+        const loaded = [];
+        RegistryModules.assertUnique(moduleIds);
+        for (const moduleId of moduleIds) {
+            const exports = await RegistryModules.import(RegistryModules.cacheable(moduleId, options));
+            loaded.push({
+                moduleId,
+                registry: RegistryModules.registry(exports, moduleId, exportName),
+            });
+        }
+        return Object.freeze(loaded);
+    }
+}
+const RegistryModules = Object.freeze({
+    async import(moduleId) {
+        try {
+            return await import(moduleId);
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("MODULE_IMPORT_FAILED", `Could not import generated handler registry module "${moduleId}".`, moduleId, error);
+        }
+    },
+    cacheable(moduleId, options) {
+        if (options.cacheBust === undefined || options.cacheBust.length === 0) {
+            return moduleId;
+        }
+        const moduleUrl = new URL(moduleId);
+        moduleUrl.searchParams.set("spine-registry-cache", options.cacheBust);
+        return moduleUrl.href;
+    },
+    registry(exports, moduleId, exportName) {
+        const value = RegistryModules.export(exports, exportName);
+        if (value === undefined) {
+            throw new GeneratedRegistryDiscoveryError("MISSING_REGISTRY_EXPORT", `Generated handler registry module "${moduleId}" does not export "${exportName}".`, moduleId);
+        }
+        if (RegistryModules.isRegistry(value)) {
+            return value;
+        }
+        throw new GeneratedRegistryDiscoveryError("INVALID_REGISTRY_MODULE", `Generated handler registry module "${moduleId}" exports invalid "${exportName}" metadata.`, moduleId);
+    },
+    export(exports, exportName) {
+        if (exports === null || typeof exports !== "object") {
+            return undefined;
+        }
+        return exports[exportName];
+    },
+    isRegistry(value) {
+        if (value === null || typeof value !== "object") {
+            return false;
+        }
+        const receivers = value.receivers;
+        return Array.isArray(receivers);
+    },
+    normalize(moduleRef) {
+        if (moduleRef instanceof URL) {
+            return RegistryModules.url(moduleRef);
+        }
+        if (RegistryModules.isUrl(moduleRef)) {
+            return RegistryModules.url(RegistryModules.parse(moduleRef));
+        }
+        return pathToFileURL(resolve(moduleRef)).href;
+    },
+    url(moduleUrl) {
+        if (moduleUrl.protocol !== "file:") {
+            throw new GeneratedRegistryDiscoveryError("UNSUPPORTED_MODULE_SCHEME", `Generated handler registry module "${moduleUrl.href}" must use the file: URL scheme.`, moduleUrl.href);
+        }
+        if (moduleUrl.search.length > 0 || moduleUrl.hash.length > 0) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleUrl.href}" must not include a query or hash.`, moduleUrl.href);
+        }
+        try {
+            return pathToFileURL(resolve(fileURLToPath(moduleUrl))).href;
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleUrl.href}" is not a valid file URL.`, moduleUrl.href, error);
+        }
+    },
+    isUrl(moduleRef) {
+        return moduleSchemeRe.test(moduleRef) && !/^[A-Za-z]:[\\/]/.test(moduleRef);
+    },
+    parse(moduleRef) {
+        try {
+            return new URL(moduleRef);
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleRef}" is not a valid URL.`, moduleRef, error);
+        }
+    },
+    assertUnique(moduleIds) {
+        const seen = new Set();
+        for (const moduleId of moduleIds) {
+            if (seen.has(moduleId)) {
+                throw new GeneratedRegistryDiscoveryError("DUPLICATE_REGISTRY_MODULE", `Generated handler registry module "${moduleId}" was listed more than once.`, moduleId);
+            }
+            seen.add(moduleId);
+        }
+    },
+});
+//# sourceMappingURL=generated-registry-discovery.js.map

package/dist/handler/generated-registry-discovery.js.map

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

package/dist/handler/handler-decorators.d.ts

@@ -0,0 +1,151 @@
+import type { DescriptorMessageSchema } from "../entity/entity-metadata.js";
+import { type EntityClass, type EntityHandlersMetadata, type EventApplicationOptions, type WhereOptions } from "./handler-metadata.js";
+export type { WhereOptions } from "./handler-metadata.js";
+/**
+ * Describes the standard TypeScript method decorator accepted by Spine handler declarations.
+ *
+ * @typeParam This - Entity instance that owns the decorated method.
+ * @typeParam Parameters - Parameters accepted by the decorated method.
+ * @typeParam Return - Result returned by the decorated method.
+ * @param value Decorated method implementation.
+ * @param context Standard TypeScript decorator context.
+ */
+export type HandlerMethodDecorator = <This extends object, Parameters extends readonly unknown[], Return>(value: HandlerMethodValue<This, Parameters, Return>, context: ClassMethodDecoratorContext<This, HandlerMethodValue<This, Parameters, Return>>) => void;
+/**
+ * Describes an instance method shape accepted by public handler decorators.
+ *
+ * @typeParam This - Entity instance that owns the method.
+ * @typeParam Parameters - Parameters accepted by the method.
+ * @typeParam Return - Result returned by the method.
+ * @param this Entity instance that receives the invocation.
+ * @param parameters Arguments supplied to the handler.
+ * @returns Handler result.
+ */
+export type HandlerMethodValue<This extends object = object, Parameters extends readonly unknown[] = readonly unknown[], Return = unknown> = (this: This, ...parameters: Parameters) => Return;
+/**
+ * Generated companion declaration for a rejection that a command receptor may throw.
+ */
+export interface RejectionDeclaration {
+    /**
+     * Generated Protobuf schema of the declared rejection.
+     */
+    readonly schema: DescriptorMessageSchema;
+}
+/**
+ * Records the generated domain rejections a command-accepting handler may throw.
+ *
+ * @param declarations Generated rejection companions.
+ * @returns A method decorator that records the declared rejection schemas.
+ */
+export declare function Throws(...declarations: readonly RejectionDeclaration[]): HandlerMethodDecorator;
+/**
+ * Creates a command-assignee declaration.
+ *
+ * Bare `@Assign` is the ordinary application form. Generated handler
+ * registries require a command input and normal event output; a rejection is
+ * valid in neither role, but the handler may throw a generated rejection
+ * throwable. The decorator records metadata only; it does not register the
+ * handler, instantiate the entity, or invoke the method.
+ *
+ * @typeParam This - Entity instance that owns the method.
+ * @typeParam Parameters - Parameters accepted by the method.
+ * @typeParam Return - Result returned by the method.
+ * @param value Decorated method implementation or command schema.
+ * @param context Standard decorator context for bare usage.
+ */
+export declare function Assign<This extends object, Parameters extends readonly unknown[], Return>(value: HandlerMethodValue<This, Parameters, Return>, context: ClassMethodDecoratorContext<This, HandlerMethodValue<This, Parameters, Return>>): void;
+/**
+ * Creates a command handler declaration.
+ *
+ * Bare `@Command` accepts a generated Command, Event, or rejection input.
+ * A Command input is the unique command-substitution receptor for its type and
+ * substitutes it with one or more Commands. `@Command` handlers are supported only by Process
+ * Manager repositories; Aggregate and Projection repositories reject them.
+ * Event and rejection inputs are Event Bus reactions that may return Commands.
+ * Rejections are thrown, not returned.
+ *
+ * @typeParam This - Entity instance that owns the method.
+ * @typeParam Parameters - Parameters accepted by the method.
+ * @typeParam Return - Result returned by the method.
+ * @param value Decorated method implementation or command schema.
+ * @param context Standard decorator context for bare usage.
+ */
+export declare function Command<This extends object, Parameters extends readonly unknown[], Return>(value: HandlerMethodValue<This, Parameters, Return>, context: ClassMethodDecoratorContext<This, HandlerMethodValue<This, Parameters, Return>>): void;
+/**
+ * Creates an Event/rejection or Entity-state subscriber declaration.
+ *
+ * Bare `@Subscribe` accepts generated Event/rejection or descriptor-marked
+ * Entity-state inputs and returns `void`. Event/rejection inputs produce
+ * event-subscription metadata; Entity state inputs produce state-subscription
+ * metadata. Subscribers are metadata-only declarations bridged by generated
+ * registry and runtime metadata.
+ *
+ * @typeParam This - Entity instance that owns the method.
+ * @typeParam Parameters - Parameters accepted by the method.
+ * @typeParam Return - Result returned by the method.
+ * @param value Decorated method implementation.
+ * @param context Standard decorator context for bare usage.
+ */
+export declare function Subscribe<This extends object, Parameters extends readonly unknown[], Return>(value: HandlerMethodValue<This, Parameters, Return>, context: ClassMethodDecoratorContext<This, HandlerMethodValue<This, Parameters, Return>>): void;
+/**
+ * Creates an event-reactor declaration.
+ *
+ * Bare `@React` accepts generated event or rejection inputs and returns normal
+ * events or explicit `void`; rejections are thrown, not returned. Reactors are
+ * collected as class-owned metadata and may fan out through the caller-owned
+ * handler registry.
+ *
+ * @typeParam This - Entity instance that owns the method.
+ * @typeParam Parameters - Parameters accepted by the method.
+ * @typeParam Return - Result returned by the method.
+ * @param value Decorated method implementation or event schema.
+ * @param context Standard decorator context for bare usage.
+ */
+export declare function React<This extends object, Parameters extends readonly unknown[], Return>(value: HandlerMethodValue<This, Parameters, Return>, context: ClassMethodDecoratorContext<This, HandlerMethodValue<This, Parameters, Return>>): void;
+/**
+ * Creates one Event field equality filter for an Event-consuming handler.
+ *
+ * Generated handler analysis validates the declaration and carries it into
+ * immutable repository metadata. The decorator itself does not inspect or
+ * invoke the handler.
+ *
+ * @param options Event source field and canonical expected value.
+ * @returns Decorator for a public instance handler method.
+ */
+export declare function Where(options: WhereOptions): HandlerMethodDecorator;
+/**
+ * Creates legacy framework event-application metadata.
+ *
+ * New application aggregates must not use `@Apply`; managed aggregates are no
+ * longer event-sourced and the framework owns state transactions. This
+ * decorator is kept only for compatibility code that still needs explicit
+ * schema-bearing event application metadata. The optional `allowImport` flag
+ * is preserved only as part of that legacy metadata shape.
+ *
+ * @param schema Event schema accepted by the decorated method.
+ * @param options Legacy event-application metadata options.
+ * @returns Decorator that records the application metadata.
+ */
+export declare function Apply(schema: DescriptorMessageSchema, options?: EventApplicationOptions): HandlerMethodDecorator;
+/**
+ * Builds schema-bearing decorator declarations for framework compatibility.
+ *
+ * The returned object is the same frozen `EntityHandlersMetadata` contract
+ * produced by `EntityHandlers.define()` and accepted by
+ * `HandlerMetadataRegistry`. Only own prototype methods of `entityType` are
+ * inspected; inherited decorated methods are intentionally not materialized by
+ * this class-owned adapter.
+ *
+ * Application code must not call this function and must not provide its own
+ * handler discovery/materialization. Generated framework registries own schema
+ * inference for bare decorators; this adapter only supports legacy
+ * schema-bearing decorator metadata.
+ *
+ * @typeParam Instance - Entity instance that owns the handlers.
+ * @typeParam StateSchema - Schema that describes the entity state.
+ * @param entityType Entity class whose own decorated methods are read.
+ * @param stateSchema Schema that describes the entity state.
+ * @returns Frozen handler metadata for the decorated methods.
+ */
+export declare function materializeDecoratedEntityHandlers<Instance extends object, StateSchema extends DescriptorMessageSchema>(entityType: EntityClass<Instance>, stateSchema: StateSchema): EntityHandlersMetadata<Instance, StateSchema>;
+//# sourceMappingURL=handler-decorators.d.ts.map

package/dist/handler/handler-decorators.d.ts.map

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