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

package/dist/stand/stand.js

@@ -0,0 +1,681 @@
+/*
+ * 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.
+ */
+var _a;
+import { clone, create } from "@bufbuild/protobuf";
+import { TypeUrls } from "@spine-event-engine/core";
+import { TenantIdSchema, VersionSchema, } from "@spine-event-engine/proto";
+import { ColumnTypes, RecordColumn, RecordMask, RecordQuery, } from "@spine-event-engine/storage";
+import { TenantBoundary } from "@spine-event-engine/storage/provider";
+import { EntityRecords, standEntityStorageDescriptor, } from "../entity/entity-storage-descriptor.js";
+import { SubscriptionObservers } from "./subscription-observer.js";
+const HANDLE_CLOSE_ERROR_LIMIT = 16;
+/**
+ * Error thrown when direct Stand access targets an unregistered state type.
+ */
+export class StandStateTypeError extends Error {
+    // prettier-ignore
+    /**
+     * Rejected state type URL.
+     */
+    typeUrl;
+    /**
+     * Stand operation that required a known state type.
+     */
+    operation;
+    /**
+     * Creates an error for an operation targeting an unknown state type.
+     *
+     * @param typeUrl The rejected state type URL.
+     * @param operation The operation requiring a registered state type.
+     */
+    constructor(typeUrl, operation) {
+        super(`Stand cannot ${operation} unknown entity state type "${typeUrl}".`);
+        this.name = "StandStateTypeError";
+        this.typeUrl = typeUrl;
+        this.operation = operation;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Direct read-side access point for storage-backed entity states and updates.
+ *
+ * Entity states are queried through the shared durable current-record seam.
+ */
+export class Stand {
+    #context;
+    #storageFactory;
+    #registrations = new Map();
+    #entityHandles = new Map();
+    #handleCloseErrors = [];
+    #omittedHandleCloseErrors = 0;
+    #inFlight = new Set();
+    #closing = false;
+    #closed = false;
+    #closedPromise;
+    /**
+     * Creates a direct read-side Stand.
+     *
+     * @param options The storage context and factory used for state records.
+     */
+    constructor(options) {
+        this.#context = _a.#cloneContext(options.context);
+        this.#storageFactory = options.storageFactory;
+        deferredUpdates.set(this, (schema, state, updateOptions) => this.#deferUpdate(schema, state, updateOptions));
+        currentReads.set(this, (schema, id, readOptions) => this.#readCurrent(schema, id, readOptions));
+    }
+    /**
+     * Registers one entity state schema. Re-registering the same schema is idempotent.
+     *
+     * @param schema The entity state schema to register.
+     * @param options The materialized columns for the state type.
+     */
+    register(schema, options = {}) {
+        this.#requireOpen();
+        const typeUrl = TypeUrls.derive(schema);
+        if (this.#registrations.has(typeUrl)) {
+            return;
+        }
+        const idField = schema.fields[0]?.localName;
+        if (idField === undefined || idField.trim().length === 0) {
+            throw new Error(`Stand state "${schema.typeName}" requires an entity ID field.`);
+        }
+        this.#registrations.set(typeUrl, Object.freeze({
+            schema,
+            typeUrl,
+            idField,
+            columns: options.columns ??
+                schema.fields.map((field) => new RecordColumn(field.localName, ColumnTypes.fromField(field), (state) => state[field.localName])),
+            subscribers: new Set(),
+        }));
+    }
+    /**
+     * Returns known state type URLs in registration order.
+     *
+     * @returns The registered state type URLs.
+     */
+    stateTypes() {
+        this.#requireOpen();
+        return Object.freeze([...this.#registrations.keys()]);
+    }
+    /**
+     * Finds state-observer metadata for one type URL.
+     *
+     * @param typeUrl Identifies the candidate entity state type.
+     * @returns Returns observer metadata when the state is registered.
+     * @internal
+     */
+    observedState(typeUrl) {
+        const registration = this.#registrations.get(typeUrl);
+        return registration === undefined
+            ? undefined
+            : Object.freeze({ schema: registration.schema, idField: registration.idField });
+    }
+    /**
+     * Reads the latest state for one entity ID.
+     *
+     * @param schema The registered entity state schema.
+     * @param id The entity ID to read.
+     * @param options The tenant slice to read.
+     * @returns The latest state, or undefined when no live record exists.
+     */
+    async read(schema, id, options = {}) {
+        const result = await this.readVersioned(schema, id, options);
+        return result?.state;
+    }
+    /**
+     * Reads the latest state and its supplied version metadata for one entity ID.
+     *
+     * @param schema The registered entity state schema.
+     * @param id The entity ID to read.
+     * @param options The tenant slice to read.
+     * @returns The current state and version, or undefined when no live record exists.
+     */
+    async readVersioned(schema, id, options = {}) {
+        const finish = this.#beginOperation();
+        try {
+            const registration = this.#registration(schema, "read");
+            const tenantId = this.#tenantId(options.tenantId);
+            const storage = this.#leaseCurrent(registration, tenantId);
+            try {
+                const stored = await storage.current.read(id);
+                if (stored === undefined || EntityRecords.unpack(registration.schema, stored).deleted) {
+                    return undefined;
+                }
+                return this.#currentResult(registration, stored);
+            }
+            finally {
+                storage.release();
+            }
+        }
+        finally {
+            finish();
+        }
+    }
+    /**
+     * Reads all latest states and version metadata in storage query order.
+     *
+     * @param schema The registered entity state schema.
+     * @param options The tenant slice to read.
+     * @returns The current states and versions in query order.
+     */
+    async readAllVersioned(schema, options = {}) {
+        return this.queryVersioned(schema, {}, options);
+    }
+    /**
+     * Finds latest states and version metadata in storage query order.
+     *
+     * @param schema The registered entity state schema.
+     * @param query The legacy record query to apply.
+     * @param options The tenant slice to read.
+     * @returns The matching current states and versions.
+     */
+    async queryVersioned(schema, query = {}, options = {}) {
+        const finish = this.#beginOperation();
+        try {
+            const registration = this.#registration(schema, "read");
+            const tenantId = this.#tenantId(options.tenantId);
+            const storage = this.#leaseCurrent(registration, tenantId);
+            try {
+                const stored = await storage.current.query(_a.#legacyPlan(query));
+                const results = stored.map((entry) => this.#entryResult(registration, entry.record, query.mask));
+                return results.filter((result) => result !== undefined);
+            }
+            finally {
+                storage.release();
+            }
+        }
+        finally {
+            finish();
+        }
+    }
+    /**
+     * Finds latest states through a normalized plan and retains versions.
+     *
+     * @param schema The registered entity state schema.
+     * @param plan The normalized storage query plan to apply.
+     * @param options The tenant slice to read.
+     * @returns The matching current states and versions.
+     */
+    async queryPlanVersioned(schema, plan, options = {}) {
+        const finish = this.#beginOperation();
+        try {
+            const registration = this.#registration(schema, "read");
+            const tenantId = this.#tenantId(options.tenantId);
+            const storage = this.#leaseCurrent(registration, tenantId);
+            try {
+                const stored = await storage.current.query(plan);
+                const results = stored.map((entry) => this.#entryResult(registration, entry.record, plan.mask?.paths));
+                return results.filter((result) => result !== undefined);
+            }
+            finally {
+                storage.release();
+            }
+        }
+        finally {
+            finish();
+        }
+    }
+    /**
+     * Clears all stored states and durable version metadata for one known state schema.
+     *
+     * The legacy-named local `BoundedContext.catchUpReadSide()` reset/replay
+     * helper uses this to reset one Projection state type for the selected tenant
+     * slice.
+     *
+     * @param schema The registered entity state schema to clear.
+     * @param options The tenant slice to clear.
+     * @returns The number of state records marked deleted.
+     */
+    async clear(schema, options = {}) {
+        const finish = this.#beginOperation();
+        try {
+            const registration = this.#registration(schema, "clear");
+            const tenantId = this.#tenantId(options.tenantId);
+            const storage = this.#leaseCurrent(registration, tenantId);
+            try {
+                const entries = await storage.current.query({
+                    candidateLimit: 10_000,
+                });
+                const ids = entries.map((entry) => entry.id);
+                for (const id of ids) {
+                    const stored = await storage.current.read(id);
+                    if (stored !== undefined) {
+                        const value = EntityRecords.unpack(registration.schema, stored);
+                        await storage.current.write(EntityRecords.pack(registration.schema, id, value.state, value.versionMessage, {
+                            archived: value.archived,
+                            deleted: true,
+                        }));
+                    }
+                }
+                return ids.length;
+            }
+            finally {
+                storage.release();
+            }
+        }
+        finally {
+            finish();
+        }
+    }
+    /**
+     * Records one latest entity state and delivers an update to matching subscribers.
+     *
+     * @param schema The registered entity state schema.
+     * @param state The latest entity state to store.
+     * @param options The tenant, version, and lifecycle metadata to store.
+     * @returns A promise that resolves after the state update is stored.
+     */
+    async update(schema, state, options = {}) {
+        const prepared = await this.#prepareUpdate(schema, state, options);
+        try {
+            await prepared.write();
+            prepared.notify();
+        }
+        catch (error) {
+            prepared.cancel();
+            throw error;
+        }
+    }
+    async #deferUpdate(schema, state, options) {
+        return await this.#prepareUpdate(schema, state, options);
+    }
+    async #prepareUpdate(schema, state, options) {
+        const finish = this.#beginOperation();
+        let storage;
+        try {
+            const registration = this.#registration(schema, "update");
+            const tenantId = this.#tenantId(options.tenantId);
+            const stateCopy = clone(schema, state);
+            const id = _a.#readStateId(stateCopy, registration);
+            storage = this.#leaseCurrent(registration, tenantId);
+            const currentStorage = storage;
+            const previous = this.#hasTenantSubscribers(registration, tenantId)
+                ? await currentStorage.current.read(id)
+                : undefined;
+            const previousState = previous === undefined
+                ? undefined
+                : EntityRecords.unpack(registration.schema, previous).state;
+            const subscribers = [...this.#tenantSubscribers(registration, this.#tenantKey(tenantId))];
+            const record = EntityRecords.pack(registration.schema, id, stateCopy, options.version ?? 0n, options.lifecycle ?? { archived: false, deleted: false });
+            let settled = false;
+            const settle = () => {
+                if (!settled) {
+                    settled = true;
+                    currentStorage.release();
+                    finish();
+                }
+            };
+            return Object.freeze({
+                cancel: settle,
+                write: () => currentStorage.current.write(record),
+                notify: () => {
+                    try {
+                        this.#notify(registration, {
+                            id,
+                            previousState,
+                            state: stateCopy,
+                            tenantId,
+                            version: options.version,
+                        }, subscribers);
+                    }
+                    finally {
+                        settle();
+                    }
+                },
+            });
+        }
+        catch (error) {
+            storage?.release();
+            finish();
+            throw error;
+        }
+    }
+    /**
+     * Repository-only full current-record read, including lifecycle metadata.
+     */
+    async #readCurrent(schema, id, options) {
+        const finish = this.#beginOperation();
+        try {
+            const registration = this.#registration(schema, "read");
+            const tenantId = this.#tenantId(options.tenantId);
+            const storage = this.#leaseCurrent(registration, tenantId);
+            try {
+                const stored = await storage.current.read(id);
+                if (stored === undefined)
+                    return undefined;
+                const value = EntityRecords.unpack(registration.schema, stored);
+                return Object.freeze({
+                    state: clone(schema, value.state),
+                    versionMessage: clone(VersionSchema, value.versionMessage),
+                    version: value.version,
+                    archived: value.archived,
+                    deleted: value.deleted,
+                });
+            }
+            finally {
+                storage.release();
+            }
+        }
+        finally {
+            finish();
+        }
+    }
+    /**
+     * Subscribes to in-process updates for one registered state schema.
+     *
+     * @param schema The registered entity state schema.
+     * @param callback The function receiving matching state updates.
+     * @param options The tenant slice to subscribe to.
+     * @returns A handle that stops future callback delivery.
+     */
+    subscribe(schema, callback, options = {}) {
+        this.#requireOpen();
+        const registration = this.#registration(schema, "subscribe");
+        const tenantKey = this.#tenantKey(options.tenantId);
+        const subscriber = Object.freeze({ tenantKey, callback });
+        let closed = false;
+        registration.subscribers.add(subscriber);
+        return Object.freeze({
+            get closed() {
+                return closed;
+            },
+            unsubscribe() {
+                if (!closed) {
+                    closed = true;
+                    registration.subscribers.delete(subscriber);
+                }
+            },
+        });
+    }
+    /**
+     * Closes direct subscriptions and rejects later Stand operations.
+     *
+     * Close is idempotent. New operations are rejected once close begins, and the
+     * close promise waits for already accepted direct reads/updates to finish
+     * before clearing subscriptions and version metadata.
+     *
+     * @returns A promise that settles after the stand closes.
+     *
+     */
+    close() {
+        this.#closedPromise ??= this.#closeOnce();
+        return this.#closedPromise;
+    }
+    async #closeOnce() {
+        this.#closing = true;
+        await Promise.all([...this.#inFlight]);
+        for (const registration of this.#registrations.values()) {
+            registration.subscribers.clear();
+        }
+        const errors = this.#handleCloseErrors.splice(0);
+        let omittedErrors = this.#omittedHandleCloseErrors;
+        this.#omittedHandleCloseErrors = 0;
+        for (const handle of this.#entityHandles.values()) {
+            try {
+                handle.close();
+            }
+            catch (error) {
+                if (errors.length < HANDLE_CLOSE_ERROR_LIMIT)
+                    errors.push(error);
+                else
+                    omittedErrors++;
+            }
+        }
+        this.#entityHandles.clear();
+        this.#closed = true;
+        if (omittedErrors > 0) {
+            errors.push(new Error(`${String(omittedErrors)} additional entity handle close failures.`));
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, "Stand close failed.");
+    }
+    #registration(schema, operation) {
+        this.#requireOpen();
+        const typeUrl = TypeUrls.derive(schema);
+        const registration = this.#registrations.get(typeUrl);
+        if (registration === undefined) {
+            throw new StandStateTypeError(typeUrl, operation);
+        }
+        return registration;
+    }
+    #leaseCurrent(registration, tenantId) {
+        if (this.#context.multitenant) {
+            return this.#lease(_a.#openStorage(this.#storageFactory, standEntityStorageDescriptor(this.#storageContext(tenantId), registration.schema, registration.columns)), true);
+        }
+        const key = registration.typeUrl;
+        const existing = this.#entityHandles.get(key);
+        if (existing !== undefined)
+            return this.#lease(existing, false);
+        const handle = _a.#openStorage(this.#storageFactory, standEntityStorageDescriptor(this.#storageContext(tenantId), registration.schema, registration.columns));
+        this.#entityHandles.set(key, handle);
+        return this.#lease(handle, false);
+    }
+    #lease(handle, releaseAfterOperation) {
+        let released = false;
+        return {
+            current: handle.current,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (releaseAfterOperation) {
+                    try {
+                        handle.close();
+                    }
+                    catch (error) {
+                        if (this.#handleCloseErrors.length < HANDLE_CLOSE_ERROR_LIMIT) {
+                            this.#handleCloseErrors.push(error);
+                        }
+                        else {
+                            this.#omittedHandleCloseErrors++;
+                        }
+                    }
+                }
+            },
+        };
+    }
+    #entryResult(registration, current, maskPaths) {
+        const value = EntityRecords.unpack(registration.schema, current);
+        if (value.deleted)
+            return undefined;
+        const version = value.version === 0n && value.versionMessage.timestamp === undefined
+            ? undefined
+            : value.versionMessage;
+        return Object.freeze({
+            state: Object.assign(create(registration.schema), RecordMask.apply(clone(registration.schema, value.state), maskPaths)),
+            ...(version === undefined ? {} : { version: clone(VersionSchema, version) }),
+        });
+    }
+    #currentResult(registration, current) {
+        return this.#entryResult(registration, current);
+    }
+    #notify(registration, input, captured) {
+        const errors = [];
+        const tenantKey = this.#tenantKey(input.tenantId);
+        const subscribers = captured ?? this.#tenantSubscribers(registration, tenantKey);
+        for (const subscriber of subscribers) {
+            try {
+                subscriber.callback(_a.#createUpdate(registration, input));
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        if (errors.length > 1) {
+            throw new AggregateError(errors, "Stand subscriber delivery failed.");
+        }
+    }
+    #tenantKey(tenantId) {
+        const selected = this.#tenantId(tenantId);
+        return selected === undefined ? "__single__" : String(TenantBoundary.from(selected).key);
+    }
+    #hasTenantSubscribers(registration, tenantId) {
+        const tenantKey = this.#tenantKey(tenantId);
+        for (const subscriber of registration.subscribers) {
+            if (subscriber.tenantKey === tenantKey) {
+                return true;
+            }
+        }
+        return false;
+    }
+    #tenantSubscribers(registration, tenantKey) {
+        return [...registration.subscribers].filter((subscriber) => subscriber.tenantKey === tenantKey);
+    }
+    #tenantId(tenantId) {
+        if (!this.#context.multitenant) {
+            if (tenantId !== undefined) {
+                throw new Error(`Single-tenant Stand "${this.#context.name}" does not accept tenantId.`);
+            }
+            return undefined;
+        }
+        if (tenantId === undefined) {
+            throw new Error(`Multitenant Stand "${this.#context.name}" requires tenantId.`);
+        }
+        return TenantBoundary.from(tenantId).tenantId;
+    }
+    #storageContext(tenantId) {
+        if (!this.#context.multitenant) {
+            this.#tenantId(tenantId);
+            return Object.freeze({ name: this.#context.name, multitenant: false });
+        }
+        if (tenantId === undefined) {
+            throw new Error(`Multitenant Stand "${this.#context.name}" requires tenantId.`);
+        }
+        return Object.freeze({
+            name: this.#context.name,
+            multitenant: true,
+            tenantId: TenantBoundary.from(tenantId).tenantId,
+        });
+    }
+    #requireOpen() {
+        if (this.#closing || this.#closed) {
+            throw new Error("Stand is closed.");
+        }
+    }
+    #beginOperation() {
+        this.#requireOpen();
+        let finish;
+        const operation = new Promise((resolve) => {
+            finish = resolve;
+        });
+        this.#inFlight.add(operation);
+        return () => {
+            this.#inFlight.delete(operation);
+            finish?.();
+        };
+    }
+    static #createUpdate(registration, input) {
+        const version = input.version === undefined ? undefined : clone(VersionSchema, input.version);
+        return Object.freeze({
+            typeUrl: registration.typeUrl,
+            id: _a.#cloneValue(input.id),
+            ...(input.previousState === undefined
+                ? {}
+                : { previousState: clone(registration.schema, input.previousState) }),
+            state: clone(registration.schema, input.state),
+            ...(version === undefined ? {} : { version }),
+            ...(input.tenantId === undefined ? {} : { tenantId: clone(TenantIdSchema, input.tenantId) }),
+        });
+    }
+    static #readStateId(state, registration) {
+        const id = state[registration.idField];
+        if (id === undefined || id === null) {
+            throw new Error(`Stand state "${registration.schema.typeName}" requires ID field.`);
+        }
+        return id;
+    }
+    static #cloneValue(value) {
+        return typeof value === "object" && value !== null ? globalThis.structuredClone(value) : value;
+    }
+    static #legacyPlan(query) {
+        RecordQuery.validate(query);
+        if (query.after !== undefined) {
+            throw new Error("Stand query continuations require the normalized entity query API.");
+        }
+        const predicates = [
+            ...(query.ids === undefined ? [] : [{ kind: "ids", ids: query.ids }]),
+            ...(query.filters ?? []).map((filter) => ({
+                kind: "comparison",
+                column: filter.column,
+                operator: "equal",
+                value: filter.value,
+            })),
+        ];
+        return {
+            ...(predicates.length === 0
+                ? {}
+                : {
+                    predicate: predicates.length === 1 ? predicates[0] : { kind: "all", predicates },
+                }),
+            ...(query.sort === undefined
+                ? {}
+                : {
+                    order: query.sort
+                        .map((sort) => ({ field: sort.field, direction: sort.direction ?? "asc" }))
+                        .map(({ field, direction }) => ({ column: field, direction })),
+                }),
+            ...(query.mask === undefined ? {} : { mask: { paths: query.mask } }),
+            ...(query.limit === undefined ? {} : { limit: query.limit }),
+            candidateLimit: 10_000,
+        };
+    }
+    static #openStorage(factory, input) {
+        const candidate = factory;
+        if (candidate.createEntityStorage === undefined) {
+            throw new Error("StorageFactory does not provide the required entity-record storage seam.");
+        }
+        return candidate.createEntityStorage(input);
+    }
+    static #cloneContext(context) {
+        return Object.freeze({ name: context.name, multitenant: context.multitenant });
+    }
+}
+_a = Stand;
+/**
+ * Defines the repository-only persistence seam that defers subscriber delivery.
+ *
+ * @internal
+ */
+export const standAccess = Object.freeze({
+    observedState(stand, typeUrl) {
+        if (!(stand instanceof Stand))
+            throw new TypeError("State observation requires a Stand instance.");
+        if (typeUrl === undefined)
+            return undefined;
+        return stand.observedState(typeUrl);
+    },
+    observeState(stand, subscription, state, systemEventBus, onUpdate) {
+        if (!(stand instanceof Stand))
+            throw new TypeError("State observation requires a Stand instance.");
+        return SubscriptionObservers.observeState(subscription, state, systemEventBus, onUpdate);
+    },
+    readCurrent(stand, schema, id, options) {
+        const read = currentReads.get(stand);
+        if (read === undefined)
+            throw new TypeError("Stand current read requires a Stand instance.");
+        return read(schema, id, options);
+    },
+    deferUpdate(stand, schema, state, options) {
+        const deferred = deferredUpdates.get(stand);
+        if (deferred === undefined)
+            throw new TypeError("Stand deferred update requires a Stand instance.");
+        return deferred(schema, state, options);
+    },
+});
+const deferredUpdates = new WeakMap();
+const currentReads = new WeakMap();
+//# sourceMappingURL=stand.js.map