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

package/dist/entity/entity-transaction.d.ts

@@ -0,0 +1,372 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type ConstraintViolation } from "@spine-event-engine/proto";
+import type { DescriptorMessageSchema } from "./entity-metadata.js";
+import { type StateTransitionResult } from "./entity-transition-validation.js";
+/**
+ * Lifecycle flags carried by an entity transaction draft and result.
+ */
+export interface EntityTransactionLifecycleFlags {
+    /**
+     * Whether the draft entity state is archived.
+     */
+    readonly archived: boolean;
+    /**
+     * Whether the draft entity state is deleted.
+     */
+    readonly deleted: boolean;
+}
+/**
+ * Explicit version metadata carried by an entity transaction draft.
+ */
+export interface EntityTransactionVersionMetadata<Version = unknown> {
+    /**
+     * Caller-supplied previous committed version metadata.
+     */
+    readonly previous: Version;
+    /**
+     * Caller-supplied draft version metadata.
+     */
+    readonly draft: Version;
+}
+/**
+ * Explicit version metadata returned by an accepted commit.
+ */
+export interface CommittedVersionMetadata<Version = unknown> {
+    /**
+     * Caller-supplied previous committed version metadata.
+     */
+    readonly previous: Version;
+    /**
+     * Draft metadata accepted by the commit boundary.
+     */
+    readonly committed: Version;
+}
+/**
+ * Visible lifecycle status of an entity transaction.
+ */
+export type EntityTransactionStatus = "active" | "committed" | "rolled-back";
+/**
+ * Transaction operation guarded by active-status checks.
+ */
+export type EntityTransactionOperation = "archive" | "commit" | "markDeleted" | "requireActive" | "restore" | "rollback" | "tryUpdate" | "unarchive" | "update" | "updateVersionMetadata";
+/**
+ * Draft lifecycle reason that prevents active-only entity state mutation.
+ */
+export type DraftStateReason = "archived" | "deleted";
+/**
+ * Updates an entity-state draft in place.
+ *
+ * @param draft Live or scratch state draft to mutate synchronously.
+ */
+export type EntityTransactionMutator<Schema extends DescriptorMessageSchema> = (draft: MessageShape<Schema>) => void;
+/**
+ * Options for creating an {@link EntityTransaction}.
+ */
+export interface EntityTransactionOptions<Schema extends DescriptorMessageSchema, Version = unknown> {
+    /**
+     * Generated Protobuf-ES schema describing the entity state.
+     */
+    readonly schema: Schema;
+    /**
+     * Previous committed entity state, absent for creation transactions.
+     */
+    readonly previous: MessageShape<Schema> | undefined;
+    /**
+     * Initial draft state. Defaults to a clone of `previous`, or an empty state for creations.
+     */
+    readonly draft?: MessageShape<Schema>;
+    /**
+     * Explicit version metadata to carry through draft, commit, and rollback results.
+     */
+    readonly version: EntityTransactionVersionMetadata<Version>;
+    /**
+     * Draft lifecycle flags. Defaults to active, not deleted.
+     */
+    readonly lifecycle?: Partial<EntityTransactionLifecycleFlags>;
+}
+/**
+ * Result returned when a transaction commit is accepted.
+ */
+export interface EntityTransactionAcceptedCommit<Schema extends DescriptorMessageSchema, Version = unknown> {
+    /**
+     * Commit result discriminator.
+     */
+    readonly status: "accepted";
+    /**
+     * Previous committed state snapshot.
+     */
+    readonly previous: MessageShape<Schema> | undefined;
+    /**
+     * Accepted next state snapshot.
+     */
+    readonly next: MessageShape<Schema>;
+    /**
+     * Accepted commit version metadata.
+     */
+    readonly version: CommittedVersionMetadata<Version>;
+    /**
+     * Lifecycle flags accepted with the committed state.
+     */
+    readonly lifecycle: EntityTransactionLifecycleFlags;
+    /**
+     * Successful transition validation result.
+     */
+    readonly validation: StateTransitionResult & {
+        readonly valid: true;
+    };
+}
+/**
+ * Result returned when a transaction commit is rejected by validation.
+ */
+export interface EntityTransactionRejectedCommit<Schema extends DescriptorMessageSchema, Version = unknown> {
+    /**
+     * Commit result discriminator.
+     */
+    readonly status: "rejected";
+    /**
+     * Previous committed state snapshot.
+     */
+    readonly previous: MessageShape<Schema> | undefined;
+    /**
+     * Rejected draft state snapshot.
+     */
+    readonly next: MessageShape<Schema>;
+    /**
+     * Draft version metadata that was not accepted.
+     */
+    readonly version: EntityTransactionVersionMetadata<Version>;
+    /**
+     * Lifecycle flags that were not accepted.
+     */
+    readonly lifecycle: EntityTransactionLifecycleFlags;
+    /**
+     * Failed transition validation result with validator violations.
+     */
+    readonly validation: StateTransitionResult & {
+        readonly valid: false;
+    };
+}
+/**
+ * Structured result returned by {@link EntityTransaction.commit}.
+ */
+export type EntityTransactionCommitResult<Schema extends DescriptorMessageSchema, Version = unknown> = EntityTransactionAcceptedCommit<Schema, Version> | EntityTransactionRejectedCommit<Schema, Version>;
+/**
+ * Structured result returned by {@link EntityTransaction.rollback}.
+ */
+export interface EntityTransactionRollbackResult<Schema extends DescriptorMessageSchema, Version = unknown> {
+    /**
+     * Rollback result discriminator.
+     */
+    readonly status: "rolled-back";
+    /**
+     * Previous committed state snapshot.
+     */
+    readonly previous: MessageShape<Schema> | undefined;
+    /**
+     * Draft state snapshot that was discarded.
+     */
+    readonly draft: MessageShape<Schema>;
+    /**
+     * Draft version metadata that was discarded.
+     */
+    readonly version: EntityTransactionVersionMetadata<Version>;
+    /**
+     * Lifecycle flags that were discarded.
+     */
+    readonly lifecycle: EntityTransactionLifecycleFlags;
+}
+/**
+ * Error thrown when transaction methods are called after commit or rollback.
+ */
+export declare class EntityTransactionStateError extends Error {
+    /**
+     * Transaction status that rejected the operation.
+     */
+    readonly status: EntityTransactionStatus;
+    /**
+     * Operation rejected by the transaction status.
+     */
+    readonly operation: EntityTransactionOperation;
+    /**
+     * Creates a deterministic closed-transaction error.
+     *
+     * @param status Status that made the operation unavailable.
+     * @param operation Operation that was rejected.
+     */
+    constructor(status: EntityTransactionStatus, operation: EntityTransactionOperation);
+}
+/**
+ * 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 declare class DraftStateError extends Error {
+    /**
+     * Draft lifecycle reason that rejected active-only mutation.
+     */
+    readonly reason: DraftStateReason;
+    /**
+     * Creates a deterministic draft lifecycle guard error.
+     *
+     * @param reason Draft lifecycle reason that prevented mutation.
+     */
+    constructor(reason: DraftStateReason);
+}
+/**
+ * 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 declare class EntityTransaction<Schema extends DescriptorMessageSchema, Version = unknown> {
+    #private;
+    /**
+     * Creates a transaction over previous state and a buffered draft.
+     *
+     * @param options State, version, and lifecycle inputs for the transaction.
+     */
+    constructor(options: EntityTransactionOptions<Schema, Version>);
+    /**
+     * Gets the current lifecycle status of the transaction.
+     *
+     * @returns The active, committed, or rolled-back status.
+     */
+    get status(): EntityTransactionStatus;
+    /**
+     * Gets the previous committed state snapshot, absent for creation transactions.
+     *
+     * @returns A cloned prior state, if one exists.
+     */
+    get previous(): MessageShape<Schema> | undefined;
+    /**
+     * Gets the current draft state snapshot.
+     *
+     * @returns A cloned draft state.
+     */
+    get currentDraft(): MessageShape<Schema>;
+    /**
+     * Gets explicit version metadata carried by the current draft.
+     *
+     * @returns The previous and draft version metadata.
+     */
+    get version(): EntityTransactionVersionMetadata<Version>;
+    /**
+     * Gets lifecycle flags carried by the current draft.
+     *
+     * @returns The current archived and deleted flags.
+     */
+    get lifecycle(): EntityTransactionLifecycleFlags;
+    /**
+     * 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(): void;
+    /**
+     * 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: EntityTransactionMutator<Schema>): MessageShape<Schema>;
+    /**
+     * 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: EntityTransactionMutator<Schema>): readonly ConstraintViolation[];
+    /**
+     * 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(): EntityTransactionLifecycleFlags;
+    /**
+     * 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(): EntityTransactionLifecycleFlags;
+    /**
+     * 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(): EntityTransactionLifecycleFlags;
+    /**
+     * 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(): EntityTransactionLifecycleFlags;
+    /**
+     * 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: Version): EntityTransactionVersionMetadata<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(): EntityTransactionCommitResult<Schema, Version>;
+    /**
+     * 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(): EntityTransactionRollbackResult<Schema, Version>;
+}
+/**
+ * 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 declare function createEntityTransaction<Schema extends DescriptorMessageSchema, Version = unknown>(options: EntityTransactionOptions<Schema, Version>): EntityTransaction<Schema, Version>;
+//# sourceMappingURL=entity-transaction.d.ts.map

package/dist/entity/entity-transaction.d.ts.map

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