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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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
+
+       http://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.

package/README.md

@@ -0,0 +1,102 @@
+# PostgreSQL storage for Spine TS
+
+`@spine-event-engine/storage-postgres` stores Spine TS records in PostgreSQL.
+It is a separate provider package; the existing `storage-rdbms` package remains
+the MySQL provider. PostgreSQL support currently targets PostgreSQL 16 or newer,
+with live acceptance recorded against PostgreSQL 16.15 and 18.6.
+
+This is an experimental snapshot package. Use Node 24 or newer. For the precise
+public API and operational rules, see the [coding-agent reference](REFERENCE.md).
+
+## Install
+
+```sh
+pnpm add @spine-event-engine/storage-postgres@snapshot @spine-event-engine/storage@snapshot @bufbuild/protobuf
+```
+
+Create the database and schema before starting the application. The adapter
+creates and checks its private tables; it does not create databases or schemas.
+
+## First write and read
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { StringValueSchema } from "@bufbuild/protobuf/wkt";
+import { RecordSpec } from "@spine-event-engine/storage";
+import { PostgresStorageFactory } from "@spine-event-engine/storage-postgres";
+
+const factory = await PostgresStorageFactory.newBuilder()
+  .setOptions({ url: "postgresql://user:password@127.0.0.1:5432/spine_app" })
+  .build();
+const records = factory.createRecordStorage(
+  { name: "Tasks", multitenant: false },
+  new RecordSpec({
+    recordType: StringValueSchema,
+    idKind: "string",
+    extractId: (record) => record.value,
+  }),
+);
+
+try {
+  await records.write(create(StringValueSchema, { value: "task-42" }));
+  const stored = await records.read("task-42");
+  if (stored?.value !== "task-42") throw new Error("The record was not stored.");
+} finally {
+  records.close();
+  factory.close();
+}
+```
+
+The URL must include a database name. Use `postgres:` or `postgresql:` URLs;
+credentials should come from the deployment environment. TLS options, pool
+limits, connection timeout, and an explicit schema are configured through the
+factory options. When no schema is supplied, the factory resolves
+`current_schema()` once and uses that validated schema for all later operations.
+
+For multitenancy, configure one database and pool per complete generated
+`TenantId`. A schema is not a substitute for the database boundary. Duplicate
+tenant or database targets are rejected during construction.
+
+## Lifecycle and operations
+
+Tables are initialized lazily and checked against the expected PostgreSQL
+layout. Each acquired client is released and each transaction is completed or
+rolled back. Call `factory.close()` when the application stops; it is
+idempotent and drains live handles and pools. A closed factory cannot create new
+handles.
+
+The provider supports record CRUD, compare-and-set, immutable append, Entity
+state and event history, delivery cleanup, declared-column filtering, sorting,
+limits, offsets, and continuations through the common storage API. It uses
+PostgreSQL `BYTEA`, parameterized `$1`-style values, and PostgreSQL's configured
+text collation. Collation ordering can differ from JavaScript ordering, so
+applications should choose and document their database collation deliberately.
+
+`google.protobuf.Timestamp` columns are epoch nanoseconds in `BIGINT`, and
+`spine.core.Version` columns are numeric `INT`. Generated names use the JVM
+physical-name renderer: ASCII unquoted spelling folds to lowercase, names are
+limited to 63 UTF-8 bytes, and case-folded or byte-limit collisions are rejected
+before the database is accessed.
+
+## Live integration checks
+
+The live suite is opt-in and requires an already running PostgreSQL service.
+No container or database is started automatically:
+
+```sh
+SPINE_TS_POSTGRESQL_URL='postgresql://user:password@127.0.0.1:5432/spine_test' \
+SPINE_TS_POSTGRESQL_TENANT_A_URL='postgresql://user:password@127.0.0.1:5432/spine_tenant_a' \
+SPINE_TS_POSTGRESQL_TENANT_B_URL='postgresql://user:password@127.0.0.1:5432/spine_tenant_b' \
+  pnpm --filter @spine-event-engine/storage-postgres test:postgresql
+```
+
+The tenant URLs must name two distinct databases; separate schemas in one
+database do not prove the multitenant boundary.
+
+Use `test:postgresql:16` or `test:postgresql:18` when the URL points to the
+corresponding server major. The repository's initial acceptance ran both
+commands successfully against PostgreSQL 16.15 and 18.6.
+
+Use a dedicated database account with DDL, metadata, and DML permissions. Keep
+URLs and credentials out of source control, configure TLS for production, and
+plan backups, monitoring, and migrations separately.

package/REFERENCE.md

@@ -0,0 +1,85 @@
+# @spine-event-engine/storage-postgres reference
+
+This reference describes the public PostgreSQL adapter contract for coding
+agents and maintainers.
+
+## Public entry point
+
+Import `PostgresStorageFactory`, `PostgresStorageFactoryBuilder`,
+`PostgresStorageFactoryOptions`, `PostgresTenantStorageOptions`,
+`PostgresEntityStorageHandle`, `PostgresTableSpec`,
+`PostgresCreateOperation`, `PostgresCreateOperationFactory`, and
+`PostgresColumnSpec` from the package root. Provider errors are
+`PostgresStorageConfigurationError`, `PostgresStorageConnectionError`,
+`PostgresStorageSchemaError`, `PostgresStorageDataError`, and
+`PostgresStorageOperationError`.
+
+## Configuration
+
+`PostgresStorageFactory.newBuilder().setOptions(options).build()` configures a
+single database and schema. `setTenantOptions(entries)` configures one database
+and pool per complete generated `TenantId`; every operation selects its tenant
+pool before table, metadata, transaction, lock, or data work. Options include a
+PostgreSQL URL, pool maximum, connection timeout, TLS CA/certificate/key,
+server-certificate verification, and optional schema name. URLs must include a
+database and cannot bypass the explicit options model with fragments or driver
+parameters. The factory proves configured connections during build and
+sanitizes provider errors.
+
+PostgreSQL creates tables but not databases or schemas. A missing schema is a
+configuration error. Without an explicit schema, `current_schema()` is resolved
+once while building the target and the validated result is qualified into every
+table and metadata statement.
+
+## Physical layout and queries
+
+Family tables contain `ID`, `bytes`, declared native columns, and the Entity
+framework columns where applicable. `ID` is the primary key. Payloads and byte
+columns use `BYTEA`; text IDs use `VARCHAR(512)`; ordinary text uses `TEXT`;
+integer, boolean, timestamp, version, `REAL`, and `DOUBLE PRECISION` values use
+their PostgreSQL-native mappings. Existing tables are inspected and never
+altered. Missing, extra, or incompatible columns, defaults, nullability,
+primary keys, or unique constraints reject with `PostgresStorageSchemaError`.
+
+The adapter uses `$1` parameters, `IS NOT DISTINCT FROM`, PostgreSQL upsert,
+transaction advisory locks, and a bounded normalized query plan. It preserves
+the common 1,000-bind plan budget and 10,000-row default with one
+overflow lookahead row. The database collation controls text ordering; the
+provider does not invent a JavaScript-compatible collation.
+
+Normalized plans support IDs; equal, greater-than, less-than, greater-or-equal,
+and less-or-equal comparisons; nested all/either predicates; declared-column
+ordering; masks; and finite limits. They do not support normalized offsets:
+`RecordQuery.offset` is the separate provider-side pagination feature.
+
+`Timestamp` values are stored as epoch nanoseconds in `BIGINT`; `Version` is
+stored as numeric `INT`. The JVM-compatible physical-name renderer folds plain,
+non-reserved ASCII identifiers only. Reserved and quoted-required names preserve
+their spelling; all names reject NUL, unsafe values, 63-byte overflow, and
+collisions before DDL, DML, or catalog inspection.
+
+## Lifecycle and errors
+
+`factory.close()` is idempotent, closes registered handles, prevents new handle
+creation, and drains pools. Record and Entity handles can close independently.
+Acquired clients are released in `finally` blocks and transactions are always
+committed or rolled back before release. Errors do not include URLs,
+credentials, SQL text, or driver internals.
+
+Custom table creation may use `useOperationFactory(factory)` with the exported
+`PostgresTableSpec`, `PostgresCreateOperation`, and
+`PostgresCreateOperationFactory` types. The resolved `table.schema` and
+`table.tableName` identify the target; custom SQL must safely quote both
+identifiers and remain idempotent. Do not import pool, client, catalog, or
+compiler internals.
+
+## Live verification
+
+The infrastructure suite is intentionally excluded from ordinary CI. Supply
+explicit `SPINE_TS_POSTGRESQL_URL`, `SPINE_TS_POSTGRESQL_TENANT_A_URL`, and
+`SPINE_TS_POSTGRESQL_TENANT_B_URL` values naming three test databases, then run
+the package's `test:postgresql:16`
+or `test:postgresql:18` command against a matching service. The repository
+records successful live acceptance against PostgreSQL 16.15 and 18.6. The four
+skipped cases in each run are the MySQL and Datastore variants in the shared
+Inbox test file; both PostgreSQL Inbox cases run.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { PostgresStorageFactory, type PostgresCreateOperation, type PostgresCreateOperationFactory, type PostgresColumnSpec, type PostgresStorageFactoryBuilder, type PostgresStorageFactoryOptions, type PostgresTableSpec, type PostgresTenantStorageOptions, } from "./postgres/storage-factory.js";
+export type { PostgresDdlType } from "./postgres/data-type.js";
+export { PostgresStorageConfigurationError, PostgresStorageConnectionError, PostgresStorageDataError, PostgresStorageOperationError, PostgresStorageSchemaError, } from "./postgres/errors.js";
+export type { PostgresEntityStorageHandle } from "./postgres/entity-history.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,GAClC,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,wBAAwB,EACxB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/*
+ * 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.
+ */
+export { PostgresStorageFactory, } from "./postgres/storage-factory.js";
+export { PostgresStorageConfigurationError, PostgresStorageConnectionError, PostgresStorageDataError, PostgresStorageOperationError, PostgresStorageSchemaError, } from "./postgres/errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,sBAAsB,GAQvB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,wBAAwB,EACxB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC"}

package/dist/postgres/column-mapping.d.ts

@@ -0,0 +1,33 @@
+import { StringifierRegistry } from "@spine-event-engine/core";
+import type { ColumnMapping, ColumnTypeMapping, RecordColumnType } from "@spine-event-engine/storage";
+import type { PostgresParameter } from "./parameter.js";
+/**
+ * Converts typed Protobuf columns to PostgreSQL-native parameters.
+ *
+ * The result union lists every JavaScript value produced for a `pg` bind
+ * parameter while each conversion preserves its typed Protobuf input.
+ */
+export declare class PostgresColumnMapping implements ColumnMapping<PostgresParameter> {
+    #private;
+    /**
+     * Creates a PostgreSQL-native column mapping.
+     *
+     * @param stringifiers Provides schema-bound message stringifiers.
+     */
+    constructor(stringifiers?: StringifierRegistry);
+    /**
+     * Returns the native conversion for one declared column type.
+     *
+     * @typeParam V Protobuf value accepted by the declared column.
+     * @param type Identifies the declared Protobuf value type.
+     * @returns The PostgreSQL parameter conversion.
+     */
+    of<V>(type: RecordColumnType<V>): ColumnTypeMapping<V, PostgresParameter>;
+    /**
+     * Returns a conversion that preserves SQL null values.
+     *
+     * @returns The null conversion.
+     */
+    ofNull(): ColumnTypeMapping<null, PostgresParameter>;
+}
+//# sourceMappingURL=column-mapping.d.ts.map

package/dist/postgres/column-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.d.ts","sourceRoot":"","sources":["../../src/postgres/column-mapping.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAKxD;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,aAAa,CAAC,iBAAiB,CAAC;;IAG5E;;;;OAIG;gBACS,YAAY,GAAE,mBAA+C;IAIzE;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,CAAC;IAWzE;;;;OAIG;IACH,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC;CAGrD"}

package/dist/postgres/column-mapping.js

@@ -0,0 +1,93 @@
+/*
+ * 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 { ScalarType } from "@bufbuild/protobuf";
+import { StringifierRegistry } from "@spine-event-engine/core";
+const timestampType = "google.protobuf.Timestamp";
+const versionType = "spine.core.Version";
+/**
+ * Converts typed Protobuf columns to PostgreSQL-native parameters.
+ *
+ * The result union lists every JavaScript value produced for a `pg` bind
+ * parameter while each conversion preserves its typed Protobuf input.
+ */
+export class PostgresColumnMapping {
+    #stringifiers;
+    /**
+     * Creates a PostgreSQL-native column mapping.
+     *
+     * @param stringifiers Provides schema-bound message stringifiers.
+     */
+    constructor(stringifiers = new StringifierRegistry()) {
+        this.#stringifiers = new StringifierRegistry(stringifiers);
+    }
+    /**
+     * Returns the native conversion for one declared column type.
+     *
+     * @typeParam V Protobuf value accepted by the declared column.
+     * @param type Identifies the declared Protobuf value type.
+     * @returns The PostgreSQL parameter conversion.
+     */
+    of(type) {
+        if (type.kind === "scalar")
+            return PostgresColumnMappings.scalar(type.scalar);
+        if (type.kind === "enum")
+            return (value) => value;
+        if (type.message.typeName === timestampType)
+            return (value) => PostgresColumnMappings.timestamp(value);
+        if (type.message.typeName === versionType)
+            return (value) => PostgresColumnMappings.version(value);
+        return (value) => this.#stringifiers.forMessage(type.message).toString(value);
+    }
+    /**
+     * Returns a conversion that preserves SQL null values.
+     *
+     * @returns The null conversion.
+     */
+    ofNull() {
+        return (value) => value;
+    }
+}
+const PostgresColumnMappings = Object.freeze({
+    /**
+     * Maps a Protobuf scalar to the same value for the PostgreSQL driver.
+     *
+     * @typeParam V Scalar value accepted by the declared column.
+     * @param type Identifies the Protobuf scalar kind.
+     * @returns A conversion that preserves the scalar value.
+     */
+    scalar(type) {
+        void type;
+        return (value) => value;
+    },
+    /**
+     * Converts a Protobuf timestamp to epoch nanoseconds.
+     *
+     * @param value Protobuf timestamp value.
+     * @returns Epoch nanoseconds stored in PostgreSQL.
+     */
+    timestamp(value) {
+        const timestamp = value;
+        return timestamp.seconds * 1000000000n + BigInt(timestamp.nanos);
+    },
+    /**
+     * Reads the integer value from a Spine version message.
+     *
+     * @param value Spine version message.
+     * @returns Version number stored in PostgreSQL.
+     */
+    version(value) {
+        return value.number;
+    },
+});
+//# sourceMappingURL=column-mapping.js.map

package/dist/postgres/column-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.js","sourceRoot":"","sources":["../../src/postgres/column-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAgB,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAS/D,MAAM,aAAa,GAAG,2BAA2B,CAAC;AAClD,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,qBAAqB;IACvB,aAAa,CAAsB;IAE5C;;;;OAIG;IACH,YAAY,eAAoC,IAAI,mBAAmB,EAAE;QACvE,IAAI,CAAC,aAAa,GAAG,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,EAAE,CAAI,IAAyB;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9E,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAA0B,CAAC;QACvE,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,aAAa;YACzC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,WAAW;YACvC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC1D,OAAO,CAAC,KAAK,EAAE,EAAE,CACf,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,OAA8B,CAAC,CAAC,QAAQ,CAAC,KAAgB,CAAC,CAAC;IAClG,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3C;;;;;;OAMG;IACH,MAAM,CAAI,IAAgB;QACxB,KAAK,IAAI,CAAC;QACV,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAA0B,CAAC;IAC/C,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,KAAc;QACtB,MAAM,SAAS,GAAG,KAA6D,CAAC;QAChF,OAAO,SAAS,CAAC,OAAO,GAAG,WAAc,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAc;QACpB,OAAQ,KAAqC,CAAC,MAAM,CAAC;IACvD,CAAC;CACF,CAAC,CAAC"}

package/dist/postgres/data-type.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Describes SQL type names emitted by the PostgreSQL storage provider.
+ */
+interface PostgresDataTypeNames {
+    readonly bigInt: "BIGINT";
+    readonly boolean: "BOOLEAN";
+    readonly bytea: "BYTEA";
+    readonly doublePrecision: "DOUBLE PRECISION";
+    readonly integer: "INT";
+    readonly real: "REAL";
+    readonly text: "TEXT";
+    readonly varchar512: "VARCHAR(512)";
+}
+/**
+ * Lists SQL type names emitted by the PostgreSQL storage provider.
+ *
+ * The `pg` package exposes numeric wire OIDs, not SQL DDL type names.
+ */
+export declare const PostgresDataTypes: Readonly<PostgresDataTypeNames>;
+/**
+ * Lists the DDL type declarations supported by this provider.
+ */
+export type PostgresDdlType = (typeof PostgresDataTypes)[keyof typeof PostgresDataTypes];
+export {};
+//# sourceMappingURL=data-type.d.ts.map

package/dist/postgres/data-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-type.d.ts","sourceRoot":"","sources":["../../src/postgres/data-type.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,qBAAqB,CAS5D,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/postgres/data-type.js

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ */
+/**
+ * Lists SQL type names emitted by the PostgreSQL storage provider.
+ *
+ * The `pg` package exposes numeric wire OIDs, not SQL DDL type names.
+ */
+export const PostgresDataTypes = Object.freeze({
+    bigInt: "BIGINT",
+    boolean: "BOOLEAN",
+    bytea: "BYTEA",
+    doublePrecision: "DOUBLE PRECISION",
+    integer: "INT",
+    real: "REAL",
+    text: "TEXT",
+    varchar512: "VARCHAR(512)",
+});
+//# sourceMappingURL=data-type.js.map

package/dist/postgres/data-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-type.js","sourceRoot":"","sources":["../../src/postgres/data-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAoC,MAAM,CAAC,MAAM,CAAC;IAC9E,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,cAAc;CAC3B,CAAC,CAAC"}