@spine-event-engine/storage-postgres 2.0.0-snapshot.24 → 2.0.0-snapshot.25

package/dist/postgres/record-storage.d.ts

@@ -4,10 +4,46 @@ import { RecordQuery, RecordStorage, type NormalizedQueryPlan, type RecordEntry,
 import type { PoolClient } from "pg";
 import type { PostgresParameter } from "./parameter.js";
 import type { PostgresTableSpec } from "./storage-factory.js";
+/**
+ * Admits one complete public provider operation before application callbacks run.
+ * @internal
+ * @typeParam T The operation result.
+ * @param work The admitted operation.
+ * @returns The operation outcome.
+ */
+export type OnPublicOperation = <T>(work: () => Promise<T>) => Promise<T>;
 /**
  * Manages PostgreSQL clients for one record-family handle.
  */
 export interface PostgresRecordLifecycle {
+    /**
+     * Resolves the selected database and its server-selected schema.
+     *
+     * @returns Completion after binding.
+     */
+    resolve(): Promise<void>;
+    /**
+     * Prepares factory-shared physical readiness for the resolved table.
+     *
+     * @param table The canonical physical table definition.
+     * @param customCreate Optional custom create SQL producer.
+     * @returns Completion after creation or remembered compatible readiness.
+     */
+    prepare(table: PostgresTableSpec<unknown, never>, customCreate?: () => string): Promise<void>;
+    /**
+     * Records one admitted asynchronous operation through factory close.
+     *
+     * @typeParam T The operation result.
+     * @param work The admitted operation promise.
+     * @returns The same operation outcome.
+     */
+    track<T>(work: Promise<T>): Promise<T>;
+    /**
+     * Checks the factory fence for public record operations.
+     *
+     * @returns Whether a new public operation may start.
+     */
+    publicOpen(): boolean;
     /**
      * Names the selected database for advisory coordination.
      */
@@ -55,14 +91,6 @@ export interface PostgresRecordExecutor<I, R extends Message> {
      * @returns Stored record when present.
      */
     read(client: PoolClient, id: I, lock?: "for-update"): Promise<R | undefined>;
-    /**
-     * Checks an immutable record on the Agent transaction client.
-     *
-     * @param client Active transaction client.
-     * @param record Proposed immutable record.
-     * @returns Completion after collision validation.
-     */
-    assertImmutable(client: PoolClient, record: R): Promise<void>;
     /**
      * Writes an immutable record on the Agent transaction client.
      *
@@ -124,9 +152,11 @@ export interface PostgresRecordExecutor<I, R extends Message> {
  */
 export declare class PostgresRecordStorage<I, R extends Message> extends RecordStorage<I, R> {
     #private;
-    private readonly table;
+    private readonly tableNameValue;
+    private readonly onSchema;
     private readonly lifecycle;
     private readonly onClose;
+    private readonly create?;
     /**
      * Reports that compare-and-set uses a conditional SQL mutation.
      */
@@ -136,13 +166,20 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      *
      * @param context Identifies the storage boundary for this handle.
      * @param spec Defines the record type, ID type, and declared columns.
-     * @param table Supplies the resolved physical table layout.
+     * @param tableNameValue Supplies the locally resolved physical table name.
+     * @param onSchema Builds the physical layout after schema resolution.
      * @param lifecycle Acquires clients for the selected database and schema.
      * @param onClose Removes this handle from the factory's live set.
      * @param create Optionally supplies custom create-table SQL.
      * @param stringifiers Converts message IDs and columns reversibly.
      */
-    constructor(context: StorageContext, spec: RecordSpec<I, R>, table: PostgresTableSpec<I, R>, lifecycle: PostgresRecordLifecycle, onClose: () => void, create?: () => string, stringifiers?: StringifierRegistry);
+    constructor(context: StorageContext, spec: RecordSpec<I, R>, tableNameValue: string, onSchema: (schema: string) => PostgresTableSpec<I, R>, lifecycle: PostgresRecordLifecycle, onClose: () => void, create?: ((table: PostgresTableSpec<I, R>) => string) | undefined, stringifiers?: StringifierRegistry);
+    /**
+     * Returns the bound layout after preparation.
+     *
+     * @returns The resolved physical layout.
+     */
+    private get table();
     /**
      * Returns the resolved physical table name.
      *
@@ -155,6 +192,24 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      * @returns A promise that resolves after compatible initialization.
      */
     prepare(): Promise<void>;
+    /**
+     * Prepares an already admitted operation, including after the factory fence.
+     *
+     * @returns Completion after table preparation.
+     */
+    private prepareInternal;
+    /**
+     * Binds the destination and prepares its physical table.
+     *
+     * @returns Completion after physical table preparation.
+     */
+    private prepareBound;
+    /**
+     * Resolves the database before constructing the schema-bound initializer.
+     *
+     * @returns Completion after the initializer is available.
+     */
+    private bind;
     /**
      * Opens package-local bounded history operations for this record family.
      *
@@ -166,6 +221,64 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      * Closes this handle and unregisters it from the factory.
      */
     close(): void;
+    /**
+     * Registers a complete public operation before invoking record callbacks.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the public record operation.
+     * @returns The complete admitted outcome.
+     */
+    private admit;
+    /**
+     * Deletes one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    delete(id: I): Promise<boolean>;
+    /**
+     * Reads one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    read(id: I): Promise<R | undefined>;
+    /**
+     * Indexes public records under the factory admission fence.
+     * @inheritdoc
+     */
+    index(query?: RecordQuery<I>): Promise<readonly I[]>;
+    /**
+     * Queries public records under the factory admission fence.
+     * @inheritdoc
+     */
+    query(query?: RecordQuery<I>): Promise<readonly R[]>;
+    /**
+     * Queries public record entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryEntries(query?: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Queries a normalized plan under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlan(plan: NormalizedQueryPlan<I>): Promise<readonly R[]>;
+    /**
+     * Queries normalized entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlanEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Writes a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    write(record: R): Promise<void>;
+    /**
+     * Compares and sets a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    compareAndSet(id: I, expected: R | undefined, next: R | undefined): Promise<boolean>;
+    /**
+     * Writes a public batch under the factory admission fence.
+     * @inheritdoc
+     */
+    writeAll(records: Iterable<R>): Promise<void>;
     /**
      * Writes an immutable record or confirms an identical existing payload.
      *
@@ -214,6 +327,12 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      * @returns The decoded records admitted by the plan.
      */
     protected queryPlanRecordEntries(plan: NormalizedQueryPlan<I>): Promise<readonly RecordEntry<I, R>[]>;
+    /**
+     * Checks plan columns and bind count before connecting to PostgreSQL.
+     *
+     * @param plan The normalized query definition.
+     */
+    private validatePlan;
     /**
      * Compares and conditionally mutates one row with a raw-byte SQL guard.
      *
@@ -273,6 +392,14 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      * @returns The value returned by the work.
      */
     private using;
+    /**
+     * Executes one prepared record operation on a released client.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the client operation.
+     * @returns The operation result.
+     */
+    private usePrepared;
     /**
      * Executes Agent-scoped record work under one PostgreSQL transaction.
      *
@@ -281,6 +408,14 @@ export declare class PostgresRecordStorage<I, R extends Message> extends RecordS
      * @returns Result after commit.
      */
     private transaction;
+    /**
+     * Executes one prepared Agent transaction on a released client.
+     *
+     * @typeParam T The transaction result.
+     * @param work Performs work on the transaction client.
+     * @returns The committed result.
+     */
+    private transactionPrepared;
     /**
      * Calculates a stable Agent advisory key in this database and schema.
      *

package/dist/postgres/record-storage.d.ts.map

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

package/dist/postgres/record-storage.js

@@ -12,13 +12,12 @@
  * the License.
  */
 import { fromBinary, ScalarType, toBinary } from "@bufbuild/protobuf";
-import { StringifierRegistry } from "@spine-event-engine/core";
+import { defaultStringifierRegistry, StringifierRegistry } from "@spine-event-engine/core";
 import { ColumnMappings, defaultQueryCandidateLimit, RecordQuery, RecordStorage, } from "@spine-event-engine/storage";
 import { createHash } from "node:crypto";
 import { PostgresColumnMapping } from "./column-mapping.js";
 import { PostgresStorageDataError, PostgresStorageOperationError, PostgresClientDisposal, } from "./errors.js";
 import { PostgresIdColumn } from "./id-column.js";
-import { PostgresTableInitializer } from "./table-initializer.js";
 const maximumNormalizedPlanBinds = 1_000;
 /**
  * Stores one record family in one qualified PostgreSQL table.
@@ -27,35 +26,50 @@ const maximumNormalizedPlanBinds = 1_000;
  * @typeParam R The stored Protobuf record type.
  */
 export class PostgresRecordStorage extends RecordStorage {
-    table;
+    tableNameValue;
+    onSchema;
     lifecycle;
     onClose;
+    create;
     /**
      * Reports that compare-and-set uses a conditional SQL mutation.
      */
     atomicCompareAndSet = true;
     #idColumn;
     #columns;
-    #initializer;
+    #binding;
+    #table;
     /**
      * Creates a PostgreSQL record-family handle.
      *
      * @param context Identifies the storage boundary for this handle.
      * @param spec Defines the record type, ID type, and declared columns.
-     * @param table Supplies the resolved physical table layout.
+     * @param tableNameValue Supplies the locally resolved physical table name.
+     * @param onSchema Builds the physical layout after schema resolution.
      * @param lifecycle Acquires clients for the selected database and schema.
      * @param onClose Removes this handle from the factory's live set.
      * @param create Optionally supplies custom create-table SQL.
      * @param stringifiers Converts message IDs and columns reversibly.
      */
-    constructor(context, spec, table, lifecycle, onClose, create, stringifiers = new StringifierRegistry()) {
+    constructor(context, spec, tableNameValue, onSchema, lifecycle, onClose, create, stringifiers = defaultStringifierRegistry) {
         super(context, spec);
-        this.table = table;
+        this.tableNameValue = tableNameValue;
+        this.onSchema = onSchema;
         this.lifecycle = lifecycle;
         this.onClose = onClose;
+        this.create = create;
         this.#idColumn = new PostgresIdColumn(spec.idType, stringifiers);
         this.#columns = new PostgresColumnMapping(stringifiers);
-        this.#initializer = new PostgresTableInitializer(lifecycle, table.schema, table, create);
+    }
+    /**
+     * Returns the bound layout after preparation.
+     *
+     * @returns The resolved physical layout.
+     */
+    get table() {
+        if (this.#table === undefined)
+            throw new Error("PostgreSQL record table is not bound.");
+        return this.#table;
     }
     /**
      * Returns the resolved physical table name.
@@ -63,7 +77,7 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns The physical table name without its schema.
      */
     get tableName() {
-        return this.table.tableName;
+        return this.tableNameValue;
     }
     /**
      * Prepares this table before a record operation.
@@ -71,7 +85,39 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns A promise that resolves after compatible initialization.
      */
     prepare() {
-        return this.#initializer.prepare();
+        return this.admit(() => this.prepareInternal());
+    }
+    /**
+     * Prepares an already admitted operation, including after the factory fence.
+     *
+     * @returns Completion after table preparation.
+     */
+    prepareInternal() {
+        return this.lifecycle.track(Promise.resolve().then(() => this.prepareBound()));
+    }
+    /**
+     * Binds the destination and prepares its physical table.
+     *
+     * @returns Completion after physical table preparation.
+     */
+    async prepareBound() {
+        this.#binding ??= this.bind().catch((error) => {
+            this.#binding = undefined;
+            throw error;
+        });
+        await this.#binding;
+        const create = this.create;
+        await this.lifecycle.prepare(this.table, create === undefined ? undefined : () => create(this.table));
+    }
+    /**
+     * Resolves the database before constructing the schema-bound initializer.
+     *
+     * @returns Completion after the initializer is available.
+     */
+    async bind() {
+        await this.lifecycle.resolve();
+        const table = this.onSchema(this.lifecycle.schema);
+        this.#table = table;
     }
     /**
      * Opens package-local bounded history operations for this record family.
@@ -85,11 +131,6 @@ export class PostgresRecordStorage extends RecordStorage {
             transaction: (work) => this.transaction(work),
             using: (work) => this.using(work),
             read: (client, id, lock) => this.readOn(client, id, lock === "for-update"),
-            assertImmutable: async (client, record) => {
-                const existing = await this.readOn(client, this.recordSpec.idValueIn(record));
-                if (existing !== undefined && !this.same(existing, record))
-                    throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
-            },
             appendImmutable: (client, record) => this.appendImmutableOn(client, record),
             write: (client, record) => this.writeOn(client, record),
             query: (client, sql, values) => this.historyEntries(client, sql, values),
@@ -107,14 +148,104 @@ export class PostgresRecordStorage extends RecordStorage {
         super.close();
         this.onClose();
     }
+    /**
+     * Registers a complete public operation before invoking record callbacks.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the public record operation.
+     * @returns The complete admitted outcome.
+     */
+    admit(work) {
+        if (!this.isOpen() || !this.lifecycle.publicOpen())
+            return Promise.reject(new Error("PostgreSQL record storage is closed."));
+        const { promise, resolve, reject } = Promise.withResolvers();
+        void this.lifecycle.track(promise);
+        try {
+            void work().then(resolve, reject);
+        }
+        catch (error) {
+            reject(error);
+        }
+        return promise;
+    }
+    /**
+     * Deletes one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    delete(id) {
+        return this.admit(() => super.delete(id));
+    }
+    /**
+     * Reads one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    read(id) {
+        return this.admit(() => super.read(id));
+    }
+    /**
+     * Indexes public records under the factory admission fence.
+     * @inheritdoc
+     */
+    index(query = {}) {
+        return this.admit(() => super.index(query));
+    }
+    /**
+     * Queries public records under the factory admission fence.
+     * @inheritdoc
+     */
+    query(query = {}) {
+        return this.admit(() => super.query(query));
+    }
+    /**
+     * Queries public record entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryEntries(query = {}) {
+        return this.admit(() => super.queryEntries(query));
+    }
+    /**
+     * Queries a normalized plan under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlan(plan) {
+        return this.admit(async () => (await super.queryPlanEntries(plan)).map((entry) => entry.record));
+    }
+    /**
+     * Queries normalized entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlanEntries(plan) {
+        return this.admit(() => super.queryPlanEntries(plan));
+    }
+    /**
+     * Writes a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    write(record) {
+        return this.admit(() => super.write(record));
+    }
+    /**
+     * Compares and sets a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    compareAndSet(id, expected, next) {
+        return this.admit(() => super.compareAndSet(id, expected, next));
+    }
+    /**
+     * Writes a public batch under the factory admission fence.
+     * @inheritdoc
+     */
+    writeAll(records) {
+        return this.admit(() => super.writeAll(records));
+    }
     /**
      * Writes an immutable record or confirms an identical existing payload.
      *
      * @param record Provides the immutable record to store.
      * @returns A promise that resolves when the payload is stored or confirmed.
      */
-    async writeImmutable(record) {
-        await this.using((client) => this.appendImmutableOn(client, record)).catch((error) => {
+    writeImmutable(record) {
+        return this.admit(() => this.using((client) => this.appendImmutableOn(client, record))).catch((error) => {
             throw operationError(error);
         });
     }
@@ -125,7 +256,7 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns A promise that rejects when the stored payload differs.
      */
     async assertImmutable(record) {
-        const existing = await this.read(this.recordSpec.idValueIn(record));
+        const existing = await this.admit(() => super.read(this.recordSpec.idValueIn(record)));
         if (existing === undefined || this.same(existing, record))
             return;
         throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
@@ -159,8 +290,7 @@ export class PostgresRecordStorage extends RecordStorage {
     async queryRecordEntries(query) {
         if (query.ids?.length === 0)
             return [];
-        const compiled = this.recordQuery(query);
-        return this.using((client) => this.entries(client, compiled));
+        return this.using((client) => this.entries(client, this.recordQuery(query)));
     }
     /**
      * Returns complete normalized-plan pushdown capabilities.
@@ -180,8 +310,28 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns The decoded records admitted by the plan.
      */
     async queryPlanRecordEntries(plan) {
-        const compiled = this.planQuery(plan);
-        return this.using((client) => this.entries(client, compiled));
+        this.validatePlan(plan);
+        return this.using((client) => this.entries(client, this.planQuery(plan)));
+    }
+    /**
+     * Checks plan columns and bind count before connecting to PostgreSQL.
+     *
+     * @param plan The normalized query definition.
+     */
+    validatePlan(plan) {
+        for (const item of plan.order ?? [])
+            this.column(item.column);
+        const visit = (predicate) => {
+            if (predicate.kind === "comparison")
+                this.column(predicate.column);
+            if (predicate.kind === "all" || predicate.kind === "either")
+                for (const child of predicate.predicates)
+                    visit(child);
+        };
+        if (plan.predicate !== undefined)
+            visit(plan.predicate);
+        if (!plan.exhaustive && this.predicateBindCount(plan.predicate) >= maximumNormalizedPlanBinds)
+            throw new PostgresStorageOperationError("PostgreSQL normalized query exceeds the 1000-parameter bind budget.");
     }
     /**
      * Compares and conditionally mutates one row with a raw-byte SQL guard.
@@ -294,8 +444,18 @@ export class PostgresRecordStorage extends RecordStorage {
      * @param work Performs the client work.
      * @returns The value returned by the work.
      */
-    async using(work) {
-        await this.prepare();
+    using(work) {
+        return this.lifecycle.track(this.usePrepared(work));
+    }
+    /**
+     * Executes one prepared record operation on a released client.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the client operation.
+     * @returns The operation result.
+     */
+    async usePrepared(work) {
+        await this.prepareInternal();
         const client = await this.lifecycle.acquire();
         let discard = false;
         try {
@@ -316,8 +476,18 @@ export class PostgresRecordStorage extends RecordStorage {
      * @param work Operations to run on the acquired client.
      * @returns Result after commit.
      */
-    async transaction(work) {
-        await this.prepare();
+    transaction(work) {
+        return this.lifecycle.track(this.transactionPrepared(work));
+    }
+    /**
+     * Executes one prepared Agent transaction on a released client.
+     *
+     * @typeParam T The transaction result.
+     * @param work Performs work on the transaction client.
+     * @returns The committed result.
+     */
+    async transactionPrepared(work) {
+        await this.prepareInternal();
         const client = await this.lifecycle.acquire();
         let releaseFailure;
         try {
@@ -721,7 +891,10 @@ export class PostgresRecordStorage extends RecordStorage {
     afterTerm(column, direction, value, bind) {
         if (value === null)
             return direction === "desc" ? "FALSE" : `${column} IS NOT NULL`;
-        return `(${column} IS NOT NULL AND ${column} ${direction === "desc" ? "<" : ">"} ${bind.add(value)})`;
+        const comparison = `(${column} IS NOT NULL AND ${column} ${direction === "desc" ? "<" : ">"} ${bind.add(value)})`;
+        return direction === "desc" && column !== '"ID"'
+            ? `(${comparison} OR ${column} IS NULL)`
+            : comparison;
     }
     /**
      * Builds SQL for one normalized query predicate recursively.