@spine-event-engine/storage-postgres 2.0.0-snapshot.13

package/dist/postgres/entity-commit.js

@@ -0,0 +1,385 @@
+/*
+ * 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 { toBinary } from "@bufbuild/protobuf";
+import { EntityRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
+import {} from "@spine-event-engine/storage";
+import { TenantBoundary, eventHistorySpec, eventStoreRecordSpec, stateHistorySpec, } from "@spine-event-engine/storage/provider";
+import { PostgresRollbackErrors, PostgresStorageOperationError, PostgresTransactionErrors, } from "./errors.js";
+import { PostgresRecordStorage, } from "./record-storage.js";
+/**
+ * Acquires fresh clients for a complete Entity transaction and one safe retry.
+ */
+class PostgresEntityCommitCoordinator {
+    lifecycle;
+    /**
+     * Creates a coordinator for one tenant-bound record lifecycle.
+     *
+     * @param lifecycle Acquires transaction clients for the selected database.
+     */
+    constructor(lifecycle) {
+        this.lifecycle = lifecycle;
+    }
+    /**
+     * Commits one complete Entity change with one serialization retry.
+     *
+     * @typeParam T Result returned by the transaction work.
+     * @param work Applies the Entity commit on an acquired client.
+     * @returns The committed work result.
+     */
+    async commit(work) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const client = await this.lifecycle.acquire();
+            let discard;
+            try {
+                await client.query("BEGIN");
+                const result = await work(client);
+                await client.query("COMMIT");
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch {
+                    discard = PostgresRollbackErrors.discard(error);
+                }
+                if (attempt === 0 && PostgresTransactionErrors.retryable(error))
+                    continue;
+                throw PostgresCommitErrors.operation(error);
+            }
+            finally {
+                client.release(discard);
+            }
+        }
+        throw new Error("Unreachable PostgreSQL Entity commit retry.");
+    }
+}
+/**
+ * Opens and closes the exact record families participating in one commit.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
+class PostgresCommitRecords {
+    current;
+    states;
+    diagnostics;
+    events;
+    #handles;
+    /**
+     * Opens the current record family and each enabled immutable family.
+     *
+     * @param input Describes the Entity commit and enabled histories.
+     * @param open Opens one record family.
+     */
+    constructor(input, open) {
+        const current = open(input.entity.recordSpec);
+        const handles = [current];
+        this.current = current.historyExecutor();
+        this.states = input.states?.length ? this.openState(input, open, handles) : undefined;
+        this.diagnostics = input.diagnostics?.length
+            ? this.openDiagnostic(input, open, handles)
+            : undefined;
+        this.events = input.events?.length ? this.openEvents(open, handles) : undefined;
+        this.#handles = handles;
+    }
+    /**
+     * Prepares every record family before the transaction begins.
+     *
+     * @returns Completion after all required tables are ready.
+     */
+    async prepare() {
+        for (const handle of this.#handles)
+            await handle.prepare();
+    }
+    /**
+     * Closes every temporary record-family handle.
+     */
+    close() {
+        for (const handle of this.#handles)
+            handle.close();
+    }
+    /**
+     * Opens the Entity state-history record family.
+     *
+     * @param input Describes the Entity state schema.
+     * @param open Opens one record family.
+     * @param handles Collects handles that must close after the commit.
+     * @returns The state-history transaction executor.
+     */
+    openState(input, open, handles) {
+        const layout = stateHistorySpec(input.entity.stateSchema);
+        const handle = open(layout.spec, layout.group);
+        handles.push(handle);
+        return handle.historyExecutor();
+    }
+    /**
+     * Opens the Entity diagnostic-event history record family.
+     *
+     * @param input Describes the Entity state schema.
+     * @param open Opens one record family.
+     * @param handles Collects handles that must close after the commit.
+     * @returns The diagnostic-history transaction executor.
+     */
+    openDiagnostic(input, open, handles) {
+        const layout = eventHistorySpec(input.entity.stateSchema);
+        const handle = open(layout.spec, layout.group);
+        handles.push(handle);
+        return handle.historyExecutor();
+    }
+    /**
+     * Opens the shared event-store record family.
+     *
+     * @param open Opens one record family.
+     * @param handles Collects handles that must close after the commit.
+     * @returns The event-store transaction executor.
+     */
+    openEvents(open, handles) {
+        const handle = open(eventStoreRecordSpec);
+        handles.push(handle);
+        return handle.historyExecutor();
+    }
+}
+/**
+ * Represents a factory-tracked PostgreSQL Entity commit handle.
+ *
+ * @typeParam I Entity identifier type captured by this handle.
+ * @typeParam S Entity state message type captured by this handle.
+ */
+export class PostgresEntityCommitStorage {
+    entity;
+    open;
+    onClose;
+    #open = true;
+    #coordinator;
+    /**
+     * Creates a PostgreSQL Entity commit handle for one Entity storage boundary.
+     *
+     * @param entity Defines the captured Entity source, state, and tenant scope.
+     * @param open Opens temporary current and history record-family handles.
+     * @param lifecycle Acquires transaction clients for the captured database.
+     * @param onClose Removes this handle from the factory's live-handle set.
+     */
+    constructor(entity, open, lifecycle, onClose) {
+        this.entity = entity;
+        this.open = open;
+        this.onClose = onClose;
+        this.#coordinator = new PostgresEntityCommitCoordinator(lifecycle);
+    }
+    /**
+     * Commits one current Entity record and its optional immutable records.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param input Defines the expected and next current records plus histories.
+     * @returns Whether PostgreSQL committed the mutation or found a conflict.
+     */
+    async commit(input) {
+        this.validate(input);
+        const records = new PostgresCommitRecords(input, this.open);
+        try {
+            await records.prepare();
+            return await this.#coordinator.commit((client) => this.apply(client, input, records));
+        }
+        finally {
+            records.close();
+        }
+    }
+    /**
+     * Closes this handle to new commits while allowing started work to settle.
+     */
+    close() {
+        if (this.#open) {
+            this.#open = false;
+            this.onClose();
+        }
+    }
+    /**
+     * Applies one validated Entity commit on an active transaction.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param client PostgreSQL transaction client.
+     * @param input Defines the Entity records to commit.
+     * @param records Provides the prepared record families.
+     * @returns Whether records were committed or conflicted.
+     */
+    async apply(client, input, records) {
+        await this.locks(client, input, records);
+        const current = await records.current.read(client, input.entityId, "for-update");
+        if (!PostgresCommitValues.same(current, input.expected) &&
+            !PostgresCommitValues.same(current, input.next))
+            return "conflict";
+        await this.preflight(client, input, records);
+        await this.append(client, input, records);
+        if (!PostgresCommitValues.same(current, input.next))
+            await records.current.write(client, input.next);
+        return "committed";
+    }
+    /**
+     * Acquires locks for each mutable or append-only family in the commit.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param client PostgreSQL transaction client.
+     * @param input Defines the Entity records to commit.
+     * @param records Provides the prepared record families.
+     * @returns Completion after all transaction locks are acquired.
+     */
+    async locks(client, input, records) {
+        if (records.states)
+            await client.query("SELECT pg_advisory_xact_lock_shared($1)", [
+                records.states.lock("history-family", records.states.table()),
+            ]);
+        if (records.diagnostics)
+            await client.query("SELECT pg_advisory_xact_lock_shared($1)", [
+                records.diagnostics.lock("history-family", records.diagnostics.table()),
+            ]);
+        await client.query("SELECT pg_advisory_xact_lock($1)", [
+            records.current.lock("entity-mutation", input.entity.sourceType.typeName, this.entity.id.key(input.entityId)),
+        ]);
+    }
+    /**
+     * Verifies that every immutable record can be appended.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param client PostgreSQL transaction client.
+     * @param input Defines the immutable records to verify.
+     * @param records Provides the prepared record families.
+     * @returns Completion after all immutable checks pass.
+     */
+    async preflight(client, input, records) {
+        for (const record of input.states ?? [])
+            await records.states?.assertImmutable(client, record);
+        for (const record of input.diagnostics ?? [])
+            await records.diagnostics?.assertImmutable(client, record);
+        for (const record of input.events ?? [])
+            await records.events?.assertImmutable(client, record);
+    }
+    /**
+     * Stores every immutable history and event-store record.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param client PostgreSQL transaction client.
+     * @param input Defines the immutable records to append.
+     * @param records Provides the prepared record families.
+     * @returns Completion after all records are appended.
+     */
+    async append(client, input, records) {
+        for (const record of input.states ?? [])
+            await records.states?.appendImmutable(client, record);
+        for (const record of input.diagnostics ?? [])
+            await records.diagnostics?.appendImmutable(client, record);
+        for (const record of input.events ?? [])
+            await records.events?.appendImmutable(client, record);
+    }
+    /**
+     * Validates the commit against the Entity boundary captured by this handle.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param input Defines the Entity records to validate.
+     */
+    validate(input) {
+        if (!this.#open)
+            throw new PostgresStorageOperationError("Entity commit storage is closed.");
+        if (input.entity.sourceType.typeName !== this.entity.sourceType.typeName)
+            throw new PostgresStorageOperationError("Entity commit source type is incompatible.");
+        if (input.entity.stateSchema.typeName !== this.entity.stateSchema.typeName)
+            throw new PostgresStorageOperationError("Entity commit state schema is incompatible.");
+        if (!PostgresCommitValues.sameBoundary(input.context, this.entity.context) ||
+            !PostgresCommitValues.sameBoundary(input.entity.context, this.entity.context))
+            throw new PostgresStorageOperationError("Entity commit context is incompatible.");
+        if (input.states?.length && !this.entity.stateHistory)
+            throw new PostgresStorageOperationError("Entity state history is disabled.");
+        if (input.diagnostics?.length && !this.entity.eventHistory)
+            throw new PostgresStorageOperationError("Entity event history is disabled.");
+        this.validateRows(input);
+    }
+    /**
+     * Validates record identifiers inside one Entity commit.
+     *
+     * @typeParam Id Entity identifier type supplied by the commit.
+     * @typeParam State Entity state message type supplied by the commit.
+     * @param input Defines current and historical records to validate.
+     */
+    validateRows(input) {
+        for (const record of [input.expected, input.next, ...(input.states ?? [])]) {
+            if (record === undefined)
+                continue;
+            const decoded = this.entity.id.unpack(record.entityId ?? {});
+            if (decoded === undefined ||
+                this.entity.id.key(decoded) !== this.entity.id.key(input.entityId))
+                throw new PostgresStorageOperationError("Entity commit record does not identify the requested Entity.");
+        }
+        this.validateEventIds(input.diagnostics, "diagnostic");
+        this.validateEventIds(input.events, "delivery");
+    }
+    /**
+     * Validates event identifiers for one immutable event family.
+     *
+     * @param events Events to validate when the family is enabled.
+     * @param family Names the event family in validation errors.
+     */
+    validateEventIds(events, family) {
+        const ids = events?.map((event) => event.id?.value) ?? [];
+        if (ids.some((id) => id === undefined))
+            throw new PostgresStorageOperationError(`Entity commit requires ${family} event IDs.`);
+        if (ids.some((id) => id?.trim() === ""))
+            throw new PostgresStorageOperationError(`Entity commit rejects blank ${family} event IDs.`);
+        if (new Set(ids).size !== ids.length)
+            throw new PostgresStorageOperationError(`Entity commit rejects duplicate ${family} event IDs.`);
+    }
+}
+const PostgresCommitValues = Object.freeze({
+    /**
+     * Compares two Entity records through their Protobuf wire representation.
+     *
+     * @param left Stored Entity record.
+     * @param right Expected Entity record.
+     * @returns Whether both records are absent or have identical wire bytes.
+     */
+    same(left, right) {
+        return left === undefined || right === undefined
+            ? left === right
+            : Buffer.compare(toBinary(EntityRecordSchema, left), toBinary(EntityRecordSchema, right)) ===
+                0;
+    },
+    /**
+     * Compares two complete storage tenant boundaries.
+     *
+     * @param left First storage context.
+     * @param right Second storage context.
+     * @returns Whether both contexts select the same tenant boundary.
+     */
+    sameBoundary(left, right) {
+        return TenantBoundary.of(left).key === TenantBoundary.of(right).key;
+    },
+});
+const PostgresCommitErrors = Object.freeze({
+    /**
+     * Converts an internal commit failure to the stable provider error.
+     *
+     * @param error Failure raised during the Entity commit.
+     * @returns Stable public commit error.
+     */
+    operation(error) {
+        return error instanceof PostgresStorageOperationError
+            ? error
+            : new PostgresStorageOperationError("PostgreSQL Entity commit failed.");
+    },
+});
+//# sourceMappingURL=entity-commit.js.map

package/dist/postgres/entity-commit.js.map

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

package/dist/postgres/entity-history.d.ts

@@ -0,0 +1,85 @@
+import { type Message } from "@bufbuild/protobuf";
+import type { EntityRecord } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
+import type { EntityEventHistoryPort, EntityRecordStorage, EntityStateHistoryPort, EntityStorageInput } from "@spine-event-engine/storage/provider";
+import { PostgresRecordStorage } from "./record-storage.js";
+/**
+ * Opens one grouped PostgreSQL record family for an Entity history.
+ *
+ * @typeParam I Record identifier type.
+ * @typeParam R Stored Protobuf record type.
+ */
+type OpenRecords = <I, R extends Message>(spec: import("@spine-event-engine/storage").RecordSpec<I, R>, group?: import("@spine-event-engine/storage").StorageGroup) => PostgresRecordStorage<I, R>;
+/**
+ * Describes PostgreSQL-backed Entity record-family handles.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
+export interface PostgresEntityStorageHandle<I, S extends Message> {
+    /**
+     * Exposes current Entity records.
+     */
+    readonly current: EntityRecordStorage<I>;
+    /**
+     * Exposes Entity state history records.
+     */
+    readonly states: EntityStateHistoryPort<I, S>;
+    /**
+     * Exposes Entity event history records.
+     */
+    readonly events: EntityEventHistoryPort<I>;
+    /**
+     * Returns whether this Entity storage handle accepts operations.
+     *
+     * @returns Whether the handle is open.
+     */
+    isOpen(): boolean;
+    /**
+     * Closes the Entity record-family handles.
+     */
+    close(): void;
+}
+/**
+ * Provides PostgreSQL-backed current Entity storage and optional disabled history ports.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
+export declare class PostgresEntityStorage<I, S extends Message> implements PostgresEntityStorageHandle<I, S> {
+    #private;
+    private readonly records;
+    private readonly onClose;
+    /**
+     * Exposes current Entity records.
+     */
+    readonly current: EntityRecordStorage<I>;
+    /**
+     * Exposes optional Entity state history.
+     */
+    readonly states: EntityStateHistoryPort<I, S>;
+    /**
+     * Exposes optional Entity event history.
+     */
+    readonly events: EntityEventHistoryPort<I>;
+    /**
+     * Creates Entity ports around one current-record handle.
+     *
+     * @param input Supplies Entity identity and materialized column definitions.
+     * @param records Stores current Entity record envelopes.
+     * @param open Opens grouped PostgreSQL record families.
+     * @param onClose Unregisters this Entity handle from its factory.
+     */
+    constructor(input: EntityStorageInput<I, S>, records: PostgresRecordStorage<I, EntityRecord>, open: OpenRecords, onClose: () => void);
+    /**
+     * Returns whether this Entity handle accepts operations.
+     *
+     * @returns Whether this handle remains open.
+     */
+    isOpen(): boolean;
+    /**
+     * Closes the current-record handle and unregisters this Entity handle.
+     */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=entity-history.d.ts.map

package/dist/postgres/entity-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-history.d.ts","sourceRoot":"","sources":["../../src/postgres/entity-history.ts"],"names":[],"mappings":"AAcA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sEAAsE,CAAC;AAEzG,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,sCAAsC,CAAC;AAmB9C,OAAO,EAAE,qBAAqB,EAA+B,MAAM,qBAAqB,CAAC;AAGzF;;;;;GAKG;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACtC,IAAI,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5D,KAAK,CAAC,EAAE,OAAO,6BAA6B,EAAE,YAAY,KACvD,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;IAG/D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAE3C;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC;IAElB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAE,YAAW,2BAA2B,CAC7F,CAAC,EACD,CAAC,CACF;;IA4BG,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA7B1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAI3C;;;;;;;OAOG;gBAED,KAAK,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EACd,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,YAAY,CAAC,EAChE,IAAI,EAAE,WAAW,EACA,OAAO,EAAE,MAAM,IAAI;IAetC;;;;OAIG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,KAAK,IAAI,IAAI;CAQd"}