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

package/dist/entity/entity-transaction.js

@@ -0,0 +1,413 @@
+/*
+ * 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, create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { ConstraintViolationSchema } from "@spine-event-engine/proto";
+import { validateEntityStateTransition, } from "./entity-transition-validation.js";
+const noConstraintViolations = Object.freeze([]);
+/**
+ * Error thrown when transaction methods are called after commit or rollback.
+ */
+export class EntityTransactionStateError extends Error {
+    // prettier-ignore
+    /**
+     * Transaction status that rejected the operation.
+     */
+    status;
+    /**
+     * Operation rejected by the transaction status.
+     */
+    operation;
+    /**
+     * Creates a deterministic closed-transaction error.
+     *
+     * @param status Status that made the operation unavailable.
+     * @param operation Operation that was rejected.
+     */
+    constructor(status, operation) {
+        super(`Cannot ${operation} an entity transaction with status "${status}".`);
+        this.name = "EntityTransactionStateError";
+        this.status = status;
+        this.operation = operation;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Error thrown when active-only state mutation is attempted for an archived or
+ * deleted draft.
+ *
+ * The error exposes only the deterministic draft lifecycle reason. It does not
+ * include entity state payloads, IDs, or previous/draft values.
+ */
+export class DraftStateError extends Error {
+    // prettier-ignore
+    /**
+     * Draft lifecycle reason that rejected active-only mutation.
+     */
+    reason;
+    /**
+     * Creates a deterministic draft lifecycle guard error.
+     *
+     * @param reason Draft lifecycle reason that prevented mutation.
+     */
+    constructor(reason) {
+        super(`Cannot mutate active entity state while the draft is ${reason}.`);
+        this.name = "DraftStateError";
+        this.reason = reason;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Framework-owned buffered transaction over one entity state draft.
+ *
+ * The transaction owns only in-memory draft/result data. It does not invoke
+ * handlers, write repositories, apply snapshots, dispatch messages, start
+ * buses, or participate in async-local/global transaction state.
+ */
+export class EntityTransaction {
+    #schema;
+    #previous;
+    #draft;
+    #status = "active";
+    #version;
+    #lifecycle;
+    /**
+     * Creates a transaction over previous state and a buffered draft.
+     *
+     * @param options State, version, and lifecycle inputs for the transaction.
+     */
+    constructor(options) {
+        this.#schema = options.schema;
+        this.#previous =
+            options.previous === undefined
+                ? undefined
+                : TransactionDrafts.clone(options.schema, options.previous);
+        this.#draft = TransactionDrafts.clone(options.schema, options.draft ?? options.previous ?? create(options.schema));
+        this.#version = {
+            previous: options.version.previous,
+            draft: options.version.draft,
+        };
+        this.#lifecycle = {
+            archived: options.lifecycle?.archived ?? false,
+            deleted: options.lifecycle?.deleted ?? false,
+        };
+    }
+    /**
+     * Gets the current lifecycle status of the transaction.
+     *
+     * @returns The active, committed, or rolled-back status.
+     */
+    get status() {
+        return this.#status;
+    }
+    /**
+     * Gets the previous committed state snapshot, absent for creation transactions.
+     *
+     * @returns A cloned prior state, if one exists.
+     */
+    get previous() {
+        return this.#previous === undefined
+            ? undefined
+            : TransactionDrafts.clone(this.#schema, this.#previous);
+    }
+    /**
+     * Gets the current draft state snapshot.
+     *
+     * @returns A cloned draft state.
+     */
+    get currentDraft() {
+        return TransactionDrafts.clone(this.#schema, this.#draft);
+    }
+    /**
+     * Gets explicit version metadata carried by the current draft.
+     *
+     * @returns The previous and draft version metadata.
+     */
+    get version() {
+        return { previous: this.#version.previous, draft: this.#version.draft };
+    }
+    /**
+     * Gets lifecycle flags carried by the current draft.
+     *
+     * @returns The current archived and deleted flags.
+     */
+    get lifecycle() {
+        return { archived: this.#lifecycle.archived, deleted: this.#lifecycle.deleted };
+    }
+    /**
+     * Ensures an active, non-archived, non-deleted draft for entity state mutation.
+     *
+     * This guard is intentionally local to the buffered transaction draft. It
+     * does not query repositories, filter read-side results, or inspect storage.
+     *
+     * @throws {@link EntityTransactionStateError} when the transaction was already
+     * committed or rolled back.
+     * @throws {@link DraftStateError} when the active draft is
+     * archived or deleted.
+     */
+    requireActive() {
+        this.#requireActiveStatus("requireActive");
+        this.#requireDraftAllowsStateMutation();
+    }
+    /**
+     * Updates the buffered draft in place.
+     *
+     * The mutator receives the live draft. The previous committed state is never
+     * exposed as mutable transaction storage. Mutators must complete
+     * synchronously; a returned thenable is rejected and cannot later mutate the
+     * live draft. If a synchronous mutator throws after changing the draft, its
+     * partial changes remain visible.
+     *
+     * @param mutator Synchronous operation that changes the live draft.
+     * @returns A cloned snapshot of the changed draft.
+     */
+    update(mutator) {
+        this.#requireActiveForStateMutation("update");
+        const before = TransactionDrafts.clone(this.#schema, this.#draft);
+        try {
+            TransactionDrafts.invoke(mutator, this.#draft);
+        }
+        catch (error) {
+            if (error instanceof AsyncMutatorError) {
+                this.#draft = before;
+            }
+            throw error;
+        }
+        return this.currentDraft;
+    }
+    /**
+     * Validates and applies a scratch draft only when it is valid.
+     *
+     * Validation failures are returned as an immutable violations list. Errors
+     * thrown by the mutator propagate and leave the live draft unchanged.
+     * Mutators must complete synchronously; returned thenables are rejected.
+     *
+     * @param mutator Synchronous operation that changes a scratch draft.
+     * @returns An empty frozen list when applied, or validation violations.
+     */
+    tryUpdate(mutator) {
+        this.#requireActiveForStateMutation("tryUpdate");
+        const candidate = TransactionDrafts.clone(this.#schema, this.#draft);
+        TransactionDrafts.invoke(mutator, candidate);
+        const validation = validateEntityStateTransition({
+            schema: this.#schema,
+            previous: this.#previous,
+            next: candidate,
+        });
+        if (!validation.valid) {
+            return Object.freeze(validation.violations.map((violation) => TransactionDrafts.freeze(clone(ConstraintViolationSchema, violation))));
+        }
+        this.#draft = TransactionDrafts.clone(this.#schema, candidate);
+        return noConstraintViolations;
+    }
+    /**
+     * Updates the buffered draft to archived.
+     *
+     * The helper changes only in-memory draft lifecycle metadata. It does not
+     * persist lifecycle state, emit lifecycle events, or filter queries.
+     *
+     * @returns The changed lifecycle flags.
+     */
+    archive() {
+        this.#replaceLifecycle("archive", { archived: true });
+        return this.lifecycle;
+    }
+    /**
+     * Updates the buffered draft to not archived.
+     *
+     * The helper changes only in-memory draft lifecycle metadata. It does not
+     * persist lifecycle state, emit lifecycle events, or filter queries.
+     *
+     * @returns The changed lifecycle flags.
+     */
+    unarchive() {
+        this.#replaceLifecycle("unarchive", { archived: false });
+        return this.lifecycle;
+    }
+    /**
+     * Updates the buffered draft to deleted.
+     *
+     * The helper changes only in-memory draft lifecycle metadata. It does not
+     * persist lifecycle state, emit lifecycle events, or filter queries.
+     *
+     * @returns The changed lifecycle flags.
+     */
+    markDeleted() {
+        this.#replaceLifecycle("markDeleted", { deleted: true });
+        return this.lifecycle;
+    }
+    /**
+     * Updates the buffered draft to not deleted.
+     *
+     * The helper changes only in-memory draft lifecycle metadata. It does not
+     * persist lifecycle state, emit lifecycle events, or filter queries.
+     *
+     * @returns The changed lifecycle flags.
+     */
+    restore() {
+        this.#replaceLifecycle("restore", { deleted: false });
+        return this.lifecycle;
+    }
+    /**
+     * Updates caller-owned explicit draft version metadata.
+     *
+     * This helper does not compute version increments, timestamps, producer
+     * metadata, or event versions. It preserves the transaction's `Version`
+     * generic and returns a snapshot of the previous/draft metadata pair.
+     *
+     * @param draft Replacement caller-owned draft version metadata.
+     * @returns The updated previous and draft metadata.
+     */
+    updateVersionMetadata(draft) {
+        this.#requireActiveStatus("updateVersionMetadata");
+        this.#version = {
+            previous: this.#version.previous,
+            draft,
+        };
+        return this.version;
+    }
+    /**
+     * Validates and commits the current draft at this transaction boundary.
+     *
+     * Ordinary entity state validation failures are returned as rejected commit
+     * results with validator violations. They do not throw and do not mark the
+     * transaction committed.
+     *
+     * @returns An accepted commit or a validation-rejected result.
+     */
+    commit() {
+        this.#requireActiveStatus("commit");
+        const previous = this.previous;
+        const next = this.currentDraft;
+        const validation = validateEntityStateTransition({
+            schema: this.#schema,
+            previous,
+            next,
+        });
+        if (!validation.valid) {
+            return {
+                status: "rejected",
+                previous,
+                next,
+                version: this.version,
+                lifecycle: this.lifecycle,
+                validation,
+            };
+        }
+        this.#status = "committed";
+        return {
+            status: "accepted",
+            previous,
+            next,
+            version: {
+                previous: this.#version.previous,
+                committed: this.#version.draft,
+            },
+            lifecycle: this.lifecycle,
+            validation,
+        };
+    }
+    /**
+     * Returns unaccepted draft evidence and closes the transaction.
+     *
+     * Rollback does not validate or accept state. It only closes this in-memory
+     * transaction so future updates or commits are rejected deterministically.
+     *
+     * @returns The discarded draft and prior-state evidence.
+     */
+    rollback() {
+        this.#requireActiveStatus("rollback");
+        this.#status = "rolled-back";
+        return {
+            status: "rolled-back",
+            previous: this.previous,
+            draft: this.currentDraft,
+            version: this.version,
+            lifecycle: this.lifecycle,
+        };
+    }
+    #replaceLifecycle(operation, updates) {
+        this.#requireActiveStatus(operation);
+        this.#lifecycle = {
+            archived: updates.archived ?? this.#lifecycle.archived,
+            deleted: updates.deleted ?? this.#lifecycle.deleted,
+        };
+    }
+    #requireActiveForStateMutation(operation) {
+        this.#requireActiveStatus(operation);
+        this.#requireDraftAllowsStateMutation();
+    }
+    #requireActiveStatus(operation) {
+        if (this.#status !== "active") {
+            throw new EntityTransactionStateError(this.#status, operation);
+        }
+    }
+    #requireDraftAllowsStateMutation() {
+        if (this.#lifecycle.archived) {
+            throw new DraftStateError("archived");
+        }
+        if (this.#lifecycle.deleted) {
+            throw new DraftStateError("deleted");
+        }
+    }
+}
+class AsyncMutatorError extends TypeError {
+    constructor() {
+        super("Entity state mutators must be synchronous.");
+        this.name = "AsyncMutatorError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Clones transaction state, applies synchronous mutation, and captures immutable validation snapshots.
+ */
+const TransactionDrafts = Object.freeze({
+    clone(schema, state) {
+        return fromBinary(schema, toBinary(schema, state, { writeUnknownFields: false }));
+    },
+    invoke(mutator, draft) {
+        const result = mutator(draft);
+        if (!this.isThenable(result)) {
+            return;
+        }
+        void Promise.resolve(result).catch(() => undefined);
+        throw new AsyncMutatorError();
+    },
+    isThenable(value) {
+        return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+            typeof value.then === "function");
+    },
+    freeze(value, seen = new WeakSet()) {
+        if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+            return value;
+        }
+        if (seen.has(value)) {
+            return value;
+        }
+        seen.add(value);
+        for (const child of Object.values(value)) {
+            this.freeze(child, seen);
+        }
+        return Object.freeze(value);
+    },
+});
+/**
+ * Creates a transaction with inferred schema state typing.
+ *
+ * @param options State, version, and lifecycle inputs for the transaction.
+ * @returns A new isolated entity transaction.
+ */
+export function createEntityTransaction(options) {
+    return new EntityTransaction(options);
+}
+//# sourceMappingURL=entity-transaction.js.map

package/dist/entity/entity-transaction.js.map

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

package/dist/entity/entity-transition-validation.d.ts

@@ -0,0 +1,47 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type TransitionValidationResult } from "@spine-event-engine/core";
+import { type DescriptorMessageSchema } from "./entity-metadata.js";
+/**
+ * Request for built-in server entity state transition validation.
+ *
+ * The built-in rules derive Spine `(set_once)` semantics from descriptor-backed
+ * entity metadata. Creation transitions with `previous === undefined` may
+ * establish supported set-once values; unsupported repeated, map-valued, and
+ * explicit optional set-once declarations fail closed even on creation.
+ */
+export interface StateTransitionRequest<Schema extends DescriptorMessageSchema = DescriptorMessageSchema> {
+    /**
+     * Generated Protobuf-ES schema describing the entity state.
+     */
+    readonly schema: Schema;
+    /**
+     * Previous committed entity state, absent when creating the entity state.
+     */
+    readonly previous: MessageShape<Schema> | undefined;
+    /**
+     * Proposed next entity state to validate before commit.
+     */
+    readonly next: MessageShape<Schema>;
+}
+/**
+ * Structured, sanitized result returned by {@link validateEntityStateTransition}.
+ */
+export type StateTransitionResult = TransitionValidationResult;
+/**
+ * Returns the built-in validation result for a proposed entity state transition.
+ *
+ * The validator first applies ordinary message validation, then enforces an
+ * implicit required declaration-first Entity ID when no explicit `(required)`
+ * option is present, and finally enforces descriptor-derived `(set_once)`
+ * fields. It delegates result shaping to `@spine-event-engine/core` and does
+ * not instantiate entities, dispatch handlers, touch repositories, or perform
+ * runtime I/O. Repeated, map-valued, and explicit optional `(set_once)` fields
+ * are rejected with field-specific violations.
+ * Non-entity schemas still fail through `DescriptorMetadataError` from
+ * `describeEntityMetadata()`.
+ *
+ * @param request Schema and previous/next state values to validate.
+ * @returns Sanitized validation result with any message or transition violations.
+ */
+export declare function validateEntityStateTransition<Schema extends DescriptorMessageSchema>(request: StateTransitionRequest<Schema>): StateTransitionResult;
+//# sourceMappingURL=entity-transition-validation.d.ts.map

package/dist/entity/entity-transition-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-transition-validation.d.ts","sourceRoot":"","sources":["../../src/entity/entity-transition-validation.ts"],"names":[],"mappings":"AAcA,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjG,OAAO,EACL,KAAK,0BAA0B,EAGhC,MAAM,0BAA0B,CAAC;AAQlC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CACrC,MAAM,SAAS,uBAAuB,GAAG,uBAAuB;IAIhE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAO/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,uBAAuB,EAClF,OAAO,EAAE,sBAAsB,CAAC,MAAM,CAAC,GACtC,qBAAqB,CAIvB"}