@relaybus/postgres 0.3.1 → 0.4.0

package/README.md

@@ -102,15 +102,29 @@ Where the budget lives depends on who owns the pool:
 - **A pool or executor you pass in**: the budget is transaction-scoped (`SET LOCAL` semantics), set with `BEGIN` by
   `PgExecutor` and by its own statement for the other adapters. Session settings of your pool are never changed.
 
-**Prisma is not integration-tested yet.** The adapter is typed structurally (no Prisma dependency) and unit-tested
-against a fake client only. Prisma interactive transactions default to a 5 s timeout, so pass
-`createPrismaExecutor(prisma, { timeout, maxWait })` if handlers run longer.
+**Prisma** is integration-tested with a generated Prisma Client 7.10 (and 6.19 in CI) on the `@prisma/adapter-pg`
+driver adapter: the full event store contract, publishing in `prisma.$transaction`, rollback and concurrent
+transactions. The adapter is typed structurally, so the package has no Prisma dependency. Prisma interactive
+transactions default to a 5 s timeout, so pass `createPrismaExecutor(prisma, { timeout, maxWait })` if handlers run
+longer.
+
+**Give an ORM store the `pg` pool too.** ORMs send raw statements unprepared and offer no connection to `LISTEN` on.
+Pass the `pg` pool your ORM's driver uses as `pool` next to `executor`: the statements the store sends outside your
+transactions (the dispatcher's claims, completions and renewals) then run on it as prepared statements, and the
+store listens for wake-ups, so an event published in your ORM transaction is dispatched right after that
+transaction commits. Your transactions still go through the ORM, and the store never closes the pool.
+
+```ts
+const pool = new Pool({ connectionString });
+const prisma = new PrismaClient({ adapter: new PrismaPg(pool) });
+const store = new PostgresEventStore({ executor: createPrismaExecutor(prisma), pool });
+```
 
 ## Options
 
 | Option                                   | Default               | Meaning                                                                                                            |
 | ---------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `pool` / `connectionString` / `executor` | required, exactly one | How to reach the database.                                                                                         |
+| `pool` / `connectionString` / `executor` | required, exactly one | How to reach the database. With `executor`, `pool` may be given too (see above).                                   |
 | `poolConfig`                             | none                  | Extra `pg` pool settings when `connectionString` is used.                                                          |
 | `schema`                                 | `'public'`            | Schema of the tables. Created by `setup()` when it is not `public`.                                                |
 | `tablePrefix`                            | `'relaybus_'`         | Tables are `<prefix>events`, `<prefix>deliveries`, `<prefix>key_sequences`, `<prefix>lanes`.                       |
@@ -274,11 +288,16 @@ tool, run it as one transaction with the workers stopped. Running 0.1.0 and the
   that channel (`<schema>.<prefix>deliveries`, hashed when longer than 63 characters) on one connection of its own,
   opened with the pool's settings outside the pool, so an event published by any process runs within milliseconds
   instead of at the next poll. A lost listening connection is replaced after a second; polling remains the safety
-  net, so a missed notification only costs latency. A store built on an `executor` cannot listen and relies on
-  polling (and on the wake-up of its own process after a publish). `wakeUp: 'poll'` sends and listens for nothing.
+  net, so a missed notification only costs latency. The notification of a publish in your own transaction is sent
+  by PostgreSQL at its commit, however late that is, so the handler starts within milliseconds of the commit
+  (`wake-after-commit.integration.test.ts`). A store built on an `executor` listens only when it is given `pool`
+  as well; without it, it relies on polling and on the wake-ups of its own process after a publish (see
+  `bus.wake()`). `wakeUp: 'poll'` sends and listens for nothing.
 - **Prepared statements.** With `preparedStatements: true` (the default) the publish, claim, completion and renewal
   statements are named prepared statements: each connection parses and plans them once. Only `PgExecutor` (the
-  default `pool` / `connectionString` path) prepares; the library adapters send every statement unprepared. See
+  default `pool` / `connectionString` path, and the `pool` given next to an `executor`) prepares; the library
+  adapters send the statements of your transactions unprepared (a dispatch batch on an ORM store parses 2 statements
+  without `pool`, 0 with it: `perf-design-orm-executors.integration.test.ts`). See
   `docs/performance/publish-path.md` for what that saves.
 - **Pooling.** Claim, complete, extend and purge need a free connection besides your transactions; size the pool for
   `dispatcher.concurrency` plus publishers; the listening connection comes on top of the pool's `max`. Listening and
@@ -310,12 +329,12 @@ tool, run it as one transaction with the workers stopped. Running 0.1.0 and the
 ## Testing
 
 Integration tests use Testcontainers against `postgres:17-alpine` and `postgres:13-alpine` (override with
-`RELAYBUS_POSTGRES_IMAGES`). Every adapter except Prisma runs the full `@relaybus/testing` event store contract plus
-transaction tests against the real database.
+`RELAYBUS_POSTGRES_IMAGES`). Every adapter (Kysely, Knex, TypeORM, Drizzle, Prisma with and without `pool`) runs the
+full `@relaybus/testing` event store contract plus transaction tests against the real database.
 
 ## When to use @relaybus/postgres, and when not to
 
-Use it when your data lives in PostgreSQL 13 or newer and events must commit or roll back with it. It is not for MySQL or MongoDB (see `@relaybus/mongodb` for MongoDB), and the Prisma adapter is typed and unit-tested but not yet integration-tested.
+Use it when your data lives in PostgreSQL 13 or newer and events must commit or roll back with it. It is not for MySQL or MongoDB (see `@relaybus/mongodb` for MongoDB).
 
 Documentation: <https://berkcansavur.github.io/relaybus/packages/postgres>
 

package/dist/drizzle.d.cts

@@ -1,5 +1,5 @@
 import { SQL } from 'drizzle-orm';
-import { P as PostgresExecutor } from './executor-CfJgktC6.cjs';
+import { PostgresExecutor } from './index.cjs';
 
 /** What a Drizzle database and a Drizzle transaction have in common. */
 interface DrizzleQueryable {
@@ -17,4 +17,5 @@ interface DrizzleLike extends DrizzleQueryable {
  */
 declare function createDrizzleExecutor(database: DrizzleLike): PostgresExecutor<DrizzleQueryable>;
 
-export { type DrizzleLike, type DrizzleQueryable, createDrizzleExecutor };
+export { createDrizzleExecutor };
+export type { DrizzleLike, DrizzleQueryable };

package/dist/drizzle.d.ts

@@ -1,5 +1,5 @@
 import { SQL } from 'drizzle-orm';
-import { P as PostgresExecutor } from './executor-CfJgktC6.js';
+import { PostgresExecutor } from './index.js';
 
 /** What a Drizzle database and a Drizzle transaction have in common. */
 interface DrizzleQueryable {
@@ -17,4 +17,5 @@ interface DrizzleLike extends DrizzleQueryable {
  */
 declare function createDrizzleExecutor(database: DrizzleLike): PostgresExecutor<DrizzleQueryable>;
 
-export { type DrizzleLike, type DrizzleQueryable, createDrizzleExecutor };
+export { createDrizzleExecutor };
+export type { DrizzleLike, DrizzleQueryable };

package/dist/index.cjs

@@ -493,6 +493,19 @@ var NotificationListener = class {
     await drop?.();
   }
 };
+
+// src/root-pool-executor.ts
+function withRootPool(executor, root) {
+  return {
+    ...executor.sessionTimeouts === void 0 ? {} : { sessionTimeouts: executor.sessionTimeouts },
+    transaction: (work) => executor.transaction(work),
+    ...executor.transactionWithBudget === void 0 ? {} : {
+      transactionWithBudget: (work, timeoutMs) => executor.transactionWithBudget(work, timeoutMs)
+    },
+    // eslint-disable-next-line relaybus/max-two-params -- PostgresExecutor port signature
+    query: (sql, parameters, transaction, options) => transaction === void 0 ? root.query(sql, parameters, void 0, options) : executor.query(sql, parameters, transaction, options)
+  };
+}
 function text(row, column) {
   return row[column];
 }
@@ -1436,7 +1449,7 @@ var PostgresMaintenance = class {
 var WAKE_UPS = ["notify", "poll"];
 var DEFAULT_PURGE_BATCH_SIZE = 1e3;
 function resolveStoreSettings(options) {
-  const sources = [options.pool, options.connectionString, options.executor].filter(
+  const sources = [options.executor ?? options.pool, options.connectionString].filter(
     (source) => source !== void 0
   );
   if (sources.length !== 1) {
@@ -1542,9 +1555,13 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
   RETURNING available_at
 )`;
   }
-  /** One wake-up notification on {@link PostgresNames.notificationChannel}, outside any publishing transaction. */
+  /**
+   * One wake-up notification on {@link PostgresNames.notificationChannel}, outside any publishing
+   * transaction. Returns a boolean column rather than the `void` of `pg_notify`, which some libraries
+   * cannot read (Prisma's raw queries reject a `void` column).
+   */
   get notify() {
-    return `SELECT pg_notify('${this.#names.notificationChannel}', '')`;
+    return `SELECT true AS notified FROM pg_notify('${this.#names.notificationChannel}', '')`;
   }
   /**
    * A CTE `woken` that sends one notification on {@link PostgresNames.notificationChannel} when a row of
@@ -2834,8 +2851,12 @@ var SetupStatements = class {
   WHERE n.nspname = '${this.#names.schema}' AND c.relname = '${this.#names.lanesTableName}' AND d.description = $1::text
 ) AS current`;
   }
+  /**
+   * Takes the setup lock. Returns a boolean column rather than the `void` of the lock function, which
+   * some libraries cannot read (Prisma's raw queries reject a `void` column).
+   */
   get setupLock() {
-    return "SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))";
+    return "SELECT true AS locked FROM pg_advisory_xact_lock(hashtextextended($1::text, 0))";
   }
 };
 
@@ -3104,7 +3125,12 @@ var PostgresEventStore = class {
 };
 function connect(options, { logger, owned }) {
   if (options.executor !== void 0) {
-    return { executor: options.executor, pool: void 0, ownedPool: void 0 };
+    const { executor: executor2, pool: pool2 } = options;
+    return {
+      executor: pool2 === void 0 ? executor2 : withRootPool(executor2, new PgExecutor(pool2, { logger })),
+      pool: pool2,
+      ownedPool: void 0
+    };
   }
   const pool = options.pool ?? new pg.Pool({
     ...options.poolConfig,