@kyneta/postgres-store 1.8.0 → 2.0.0

package/src/__tests__/pg-adapter.test.ts

@@ -0,0 +1,112 @@
+// pg-adapter — non-gated unit tests for the fromPool / fromClient adapters.
+//
+// These run without KYNETA_PG_URL: they assert the transaction control flow
+// (checkout / BEGIN / COMMIT / ROLLBACK / release) against lightweight fakes,
+// locking the behaviour that used to live in PostgresStore's connection-type
+// discriminant — now resolved at the call site by which factory is used.
+
+import type { Client, Pool } from "pg"
+import { describe, expect, it, vi } from "vitest"
+import { fromClient, fromPool } from "../index.js"
+
+describe("fromClient", () => {
+  it("runs a transaction inline: BEGIN → fn → COMMIT", async () => {
+    const calls: string[] = []
+    const client = {
+      query: vi.fn(async (text: string) => {
+        calls.push(text)
+        return { rows: [] }
+      }),
+    } as unknown as Client
+
+    const result = await fromClient(client).transaction(async q => {
+      await q.query("INSERT 1")
+      return "done"
+    })
+
+    expect(result).toBe("done")
+    expect(calls).toEqual(["BEGIN", "INSERT 1", "COMMIT"])
+  })
+
+  it("ROLLBACK + rethrow when fn throws", async () => {
+    const calls: string[] = []
+    const client = {
+      query: vi.fn(async (text: string) => {
+        calls.push(text)
+        return { rows: [] }
+      }),
+    } as unknown as Client
+
+    await expect(
+      fromClient(client).transaction(async q => {
+        await q.query("INSERT 1")
+        throw new Error("boom")
+      }),
+    ).rejects.toThrow("boom")
+
+    expect(calls).toEqual(["BEGIN", "INSERT 1", "ROLLBACK"])
+  })
+})
+
+describe("fromPool", () => {
+  it("checks out a client, BEGIN/COMMIT on it, releases in finally", async () => {
+    const calls: string[] = []
+    const release = vi.fn()
+    const poolClient = {
+      query: vi.fn(async (text: string) => {
+        calls.push(text)
+        return { rows: [] }
+      }),
+      release,
+    }
+    const connect = vi.fn(async () => poolClient)
+    const pool = { connect, query: vi.fn() } as unknown as Pool
+
+    const result = await fromPool(pool).transaction(async q => {
+      await q.query("INSERT 1")
+      return 42
+    })
+
+    expect(result).toBe(42)
+    expect(connect).toHaveBeenCalledTimes(1)
+    expect(calls).toEqual(["BEGIN", "INSERT 1", "COMMIT"])
+    expect(release).toHaveBeenCalledTimes(1)
+  })
+
+  it("ROLLBACK + release + rethrow when fn throws", async () => {
+    const calls: string[] = []
+    const release = vi.fn()
+    const poolClient = {
+      query: vi.fn(async (text: string) => {
+        calls.push(text)
+        return { rows: [] }
+      }),
+      release,
+    }
+    const pool = {
+      connect: vi.fn(async () => poolClient),
+      query: vi.fn(),
+    } as unknown as Pool
+
+    await expect(
+      fromPool(pool).transaction(async () => {
+        throw new Error("boom")
+      }),
+    ).rejects.toThrow("boom")
+
+    expect(calls).toEqual(["BEGIN", "ROLLBACK"])
+    expect(release).toHaveBeenCalledTimes(1)
+  })
+
+  it("non-transactional query goes to the pool directly (no checkout)", async () => {
+    const connect = vi.fn()
+    const poolQuery = vi.fn(async () => ({ rows: [{ n: 1 }] }))
+    const pool = { connect, query: poolQuery } as unknown as Pool
+
+    const res = await fromPool(pool).query<{ n: number }>("SELECT 1")
+
+    expect(res.rows).toEqual([{ n: 1 }])
+    expect(poolQuery).toHaveBeenCalledTimes(1)
+    expect(connect).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/postgres-store.test.ts

@@ -5,10 +5,19 @@
 // `KYNETA_PG_URL=postgres://localhost:5432/kyneta_test` (or similar)
 // to run.
 
-import { describeStore, makeMetaRecord } from "@kyneta/exchange/testing"
+import {
+  describeStore,
+  makeArmedFault,
+  makeMetaRecord,
+} from "@kyneta/exchange/testing"
 import { Pool } from "pg"
 import { afterAll, beforeAll, describe, expect, it } from "vitest"
-import { createPostgresStore, PostgresStore } from "../index.js"
+import {
+  createPostgresStore,
+  fromClient,
+  fromPool,
+  PostgresStore,
+} from "../index.js"
 
 const PG_URL = process.env.KYNETA_PG_URL
 const ENABLED = PG_URL !== undefined && PG_URL.length > 0
@@ -20,12 +29,13 @@ const pool: Pool | null = ENABLED
 // Per-test schema namespace via per-test table names. Truncate between
 // tests via DELETE on the canonical tables for the conformance run.
 const SCHEMA_TABLES = {
-  meta: "kyneta_meta",
+  docMeta: "kyneta_doc_meta",
   records: "kyneta_records",
+  storeMeta: "kyneta_store_meta",
 } as const
 
 const SCHEMA_DDL = `
-  CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLES.meta} (
+  CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLES.docMeta} (
     doc_id TEXT  PRIMARY KEY,
     data   JSONB NOT NULL
   );
@@ -37,6 +47,10 @@ const SCHEMA_DDL = `
     blob    BYTEA,
     PRIMARY KEY (doc_id, seq)
   );
+  CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLES.storeMeta} (
+    key   TEXT  PRIMARY KEY,
+    value JSONB NOT NULL
+  );
 `
 
 if (ENABLED && pool !== null) {
@@ -63,93 +77,70 @@ describeIfEnabled("PostgresStore", () => {
     async () => {
       // Truncate before each test for a clean slate.
       await pool.query(
-        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.docMeta}`,
       )
-      return new PostgresStore(pool)
+      return new PostgresStore(fromPool(pool))
     },
     {
       cleanup: async () => {
         await pool.query(
-          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.docMeta}`,
         )
       },
       faultFactory: async () => {
         await pool.query(
-          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+          `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.docMeta}`,
         )
-        // Wrap a single connection (not the pool) so we can intercept
-        // its `query` method to inject failures. The faulty store uses
-        // a Client-shaped wrapper; the fresh store uses a fresh client
-        // checked out from the pool.
+        // Check out a single connection and wrap its `query` with the shared
+        // op-weighted fault primitive. `fromClient` runs transactions inline
+        // on that one connection, so every query (BEGIN/COMMIT/inserts/reads)
+        // is counted — injectFault(2) fires mid-transaction → rollback.
         const client = await pool.connect()
-        // Forward all queries except after arming, when the Nth post-arm
-        // call throws. Schema DDL ran in beforeAll, so we don't need to
-        // protect those calls.
-        let armed: number | null = null
-        let count = 0
-        const realQuery = client.query.bind(client) as (
-          ...args: unknown[]
-        ) => Promise<unknown>
-        const wrappedClient = {
-          query: ((...args: unknown[]) => {
-            if (armed !== null) {
-              count += 1
-              if (count === armed) {
-                return Promise.reject(
-                  new Error(`fault-injected: query call #${count}`),
-                )
-              }
-            }
-            return realQuery(...args)
-          }) as typeof client.query,
-          // Pretend to be a Client (no .connect method).
-        } as unknown as ConstructorParameters<typeof PostgresStore>[0]
-
-        const store = new PostgresStore(wrappedClient)
+        const { proxy, arm } = makeArmedFault(client, { query: 1 })
+        const store = new PostgresStore(fromClient(proxy))
 
         return {
           store,
-          injectFault: n => {
-            armed = n
-            count = 0
-          },
-          freshStore: async () => new PostgresStore(pool),
+          injectFault: arm,
+          freshStore: async () => new PostgresStore(fromPool(pool)),
           cleanup: async () => {
             client.release()
           },
         }
       },
       isolationFactory: async () => {
-        // Two distinct table-name pairs sharing the same Pool.
-        const tablesA = { meta: "iso_a_meta", records: "iso_a_records" }
-        const tablesB = { meta: "iso_b_meta", records: "iso_b_records" }
+        // Two distinct table-name sets sharing the same Pool. These use the
+        // bare `PostgresStore` constructor (no store-format gate), so the
+        // store-metadata table is unused here and not created.
+        const tablesA = { docMeta: "iso_a_meta", records: "iso_a_records" }
+        const tablesB = { docMeta: "iso_b_meta", records: "iso_b_records" }
         await pool.query(`
-          CREATE TABLE IF NOT EXISTS ${tablesA.meta} (
+          CREATE TABLE IF NOT EXISTS ${tablesA.docMeta} (
             doc_id TEXT PRIMARY KEY, data JSONB NOT NULL
           );
           CREATE TABLE IF NOT EXISTS ${tablesA.records} (
             doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
             PRIMARY KEY (doc_id, seq)
           );
-          CREATE TABLE IF NOT EXISTS ${tablesB.meta} (
+          CREATE TABLE IF NOT EXISTS ${tablesB.docMeta} (
             doc_id TEXT PRIMARY KEY, data JSONB NOT NULL
           );
           CREATE TABLE IF NOT EXISTS ${tablesB.records} (
             doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
             PRIMARY KEY (doc_id, seq)
           );
-          TRUNCATE ${tablesA.records}, ${tablesA.meta},
-                   ${tablesB.records}, ${tablesB.meta};
+          TRUNCATE ${tablesA.records}, ${tablesA.docMeta},
+                   ${tablesB.records}, ${tablesB.docMeta};
         `)
         return {
-          storeA: new PostgresStore(pool, { tables: tablesA }),
-          storeB: new PostgresStore(pool, { tables: tablesB }),
+          storeA: new PostgresStore(fromPool(pool), { tables: tablesA }),
+          storeB: new PostgresStore(fromPool(pool), { tables: tablesB }),
           cleanup: async () => {
             await pool.query(`
               DROP TABLE IF EXISTS ${tablesA.records};
-              DROP TABLE IF EXISTS ${tablesA.meta};
+              DROP TABLE IF EXISTS ${tablesA.docMeta};
               DROP TABLE IF EXISTS ${tablesB.records};
-              DROP TABLE IF EXISTS ${tablesB.meta};
+              DROP TABLE IF EXISTS ${tablesB.docMeta};
             `)
           },
         }
@@ -162,37 +153,40 @@ describeIfEnabled("PostgresStore", () => {
   // -------------------------------------------------------------------------
 
   describe("createPostgresStore — schema validation", () => {
-    it("rejects when meta table is missing", async () => {
+    it("rejects when doc-meta table is missing", async () => {
       await expect(
-        createPostgresStore(pool, {
-          tables: { meta: "nonexistent_meta", records: "kyneta_records" },
+        createPostgresStore(fromPool(pool), {
+          tables: { docMeta: "nonexistent_meta", records: "kyneta_records" },
         }),
       ).rejects.toThrow(/nonexistent_meta/)
     })
 
     it("rejects when records table is missing", async () => {
       await expect(
-        createPostgresStore(pool, {
-          tables: { meta: "kyneta_meta", records: "nonexistent_records" },
+        createPostgresStore(fromPool(pool), {
+          tables: {
+            docMeta: "kyneta_doc_meta",
+            records: "nonexistent_records",
+          },
         }),
       ).rejects.toThrow(/nonexistent_records/)
     })
 
     it("returns a ready Store when schema is valid", async () => {
-      const store = await createPostgresStore(pool)
+      const store = await createPostgresStore(fromPool(pool))
       expect(store).toBeDefined()
       await store.close()
     })
 
     it("rejects when a column has the wrong type", async () => {
       const tables = {
-        meta: "wrongtype_meta",
+        docMeta: "wrongtype_meta",
         records: "wrongtype_records",
       }
       await pool.query(`
         DROP TABLE IF EXISTS ${tables.records};
-        DROP TABLE IF EXISTS ${tables.meta};
-        CREATE TABLE ${tables.meta} (
+        DROP TABLE IF EXISTS ${tables.docMeta};
+        CREATE TABLE ${tables.docMeta} (
           doc_id TEXT PRIMARY KEY, data TEXT NOT NULL
         );
         CREATE TABLE ${tables.records} (
@@ -201,13 +195,13 @@ describeIfEnabled("PostgresStore", () => {
         );
       `)
       try {
-        await expect(createPostgresStore(pool, { tables })).rejects.toThrow(
-          /data.*type "text"/,
-        )
+        await expect(
+          createPostgresStore(fromPool(pool), { tables }),
+        ).rejects.toThrow(/data.*type "text"/)
       } finally {
         await pool.query(`
           DROP TABLE IF EXISTS ${tables.records};
-          DROP TABLE IF EXISTS ${tables.meta};
+          DROP TABLE IF EXISTS ${tables.docMeta};
         `)
       }
     })
@@ -220,9 +214,9 @@ describeIfEnabled("PostgresStore", () => {
   describe("listDocIds — range scan vs LIKE-pattern hazards", () => {
     it("prefix containing % and _ matches literally, not as wildcards", async () => {
       await pool.query(
-        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.meta}`,
+        `TRUNCATE ${SCHEMA_TABLES.records}, ${SCHEMA_TABLES.docMeta}`,
       )
-      const store = new PostgresStore(pool)
+      const store = new PostgresStore(fromPool(pool))
 
       await store.append("100%_done", makeMetaRecord())
       await store.append("100_other", makeMetaRecord())
@@ -240,4 +234,61 @@ describeIfEnabled("PostgresStore", () => {
       expect(matched2).toEqual(["100_other"])
     })
   })
+
+  // -------------------------------------------------------------------------
+  // Postgres-specific: store-format gate
+  // -------------------------------------------------------------------------
+
+  describe("createPostgresStore — store-format gate", () => {
+    const tables = {
+      docMeta: "fmt_doc_meta",
+      records: "fmt_records",
+      storeMeta: "fmt_store_meta",
+    }
+    const ddl = `
+      CREATE TABLE IF NOT EXISTS ${tables.docMeta} (
+        doc_id TEXT PRIMARY KEY, data JSONB NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS ${tables.records} (
+        doc_id TEXT, seq INTEGER, kind TEXT, payload TEXT, blob BYTEA,
+        PRIMARY KEY (doc_id, seq)
+      );
+      CREATE TABLE IF NOT EXISTS ${tables.storeMeta} (
+        key TEXT PRIMARY KEY, value JSONB NOT NULL
+      );
+    `
+    const drop = `
+      DROP TABLE IF EXISTS ${tables.records};
+      DROP TABLE IF EXISTS ${tables.docMeta};
+      DROP TABLE IF EXISTS ${tables.storeMeta};
+    `
+
+    it("stamps a fresh store and refuses an incompatible major", async () => {
+      await pool.query(drop)
+      await pool.query(ddl)
+      try {
+        // First open stamps {major:1,minor:0}.
+        const store = await createPostgresStore(fromPool(pool), { tables })
+        await store.close()
+        const stamped = await pool.query<{ value: { major: number } }>(
+          `SELECT value FROM ${tables.storeMeta} WHERE key = 'format'`,
+        )
+        expect(stamped.rows[0]?.value.major).toBe(1)
+
+        // Tamper to a future major → reopen refuses.
+        await pool.query(
+          `UPDATE ${tables.storeMeta} SET value = $1::jsonb WHERE key = 'format'`,
+          [JSON.stringify({ major: 99, minor: 0 })],
+        )
+        await expect(
+          createPostgresStore(fromPool(pool), { tables }),
+        ).rejects.toMatchObject({
+          name: "StoreFormatVersionError",
+          reason: "incompatible-major",
+        })
+      } finally {
+        await pool.query(drop)
+      }
+    })
+  })
 })