@zeroxsolutions/db 10.3.0 → 10.4.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 10.4.0 (2026-10-28)
+
+### 🚀 Features
+
+- **db:** wait on a named blocking backend ([e241940](https://github.com/zeroxsolutions/zeroxsolutions/commit/e241940))
+
+### ❤️ Thank You
+
+- luongvantuit
+
+## 10.3.1 (2026-10-21)
+
+This was a version bump only for @zeroxsolutions/db to align it with other projects, there were no code changes.
+
 ## 10.3.0 (2026-10-20)
 
 ### 🚀 Features

package/README.md

@@ -40,7 +40,7 @@ declares `"."`, but no `src/index.ts` exists for the build to emit it from, so
 | `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                                              |
 | `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                                   |
 | `@zeroxsolutions/db/utils`      | `defineReads`, `relationsOf`, `withoutRelation`, the read and order types, the filter-value schema + operator enum, the refusals, omit masks |
-| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7                   |
+| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, the container timeout, a fake uuid v7, and a wait on a lock     |
 | `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                                           |
 
 ---
@@ -519,6 +519,33 @@ typecheck failure rather than a suite that quietly passed on a major you do not
 | `CONTAINER_TIMEOUT_MS`                   | 180s, for the hook that starts a container: an image pull on a cold machine outruns vitest's 5s default                                                                                                                                                    |
 | `fakeUuidV7`                             | Random bits in a v7 layout: it passes a v7 check, and is not time-ordered like a minted id                                                                                                                                                                 |
 
+### Waiting until one backend blocks another
+
+A spec proving that a second transaction waits on a lock the first one holds runs each on its own
+backend with `runOnBackend`, then waits for that pair with `waitUntilBlockedBy`:
+
+```ts
+import { runOnBackend, waitUntilBlockedBy } from '@zeroxsolutions/db/testing';
+
+const holder = runOnBackend(database.db, async (tx) => {
+  await tx.select().from(notes).where(eq(notes.id, id)).for('update');
+  await released;
+});
+await holder.pid;
+const waiter = runOnBackend(database.db, (tx) => tx.select().from(notes).where(eq(notes.id, id)).for('update'));
+
+await waitUntilBlockedBy(database.db, waiter, holder);
+```
+
+Counting the sessions `pg_stat_activity` lists as waiting on a lock does not do this job: every spec
+file sharing the server adds its own waiters to the count, so a wait for one passes before your
+session blocks, and a wait for an exact number never passes.
+
+| Export                                             | What it is                                                                                                                                                                                                               |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `runOnBackend(db, work)`                           | Opens a transaction, reads its backend's pid, then runs `work` in it. Returns `{ pid, result }`: the pid once the transaction has started, and `work`'s own result                                                       |
+| `waitUntilBlockedBy(db, waiter, holder, options?)` | Resolves once `holder` is among the backends `waiter` waits on. Each is a `runOnBackend` handle or a bare pid. Rejects when `waiter`'s result settles first, and after `timeoutMs` (5000; polled every `intervalMs`, 20) |
+
 ### A container you started yourself
 
 A global setup that starts its own container, to migrate a template or several databases, tears it down

package/dist/testing/blocking-backend.d.ts

@@ -0,0 +1,35 @@
+import { type ExtractTablesWithRelations } from 'drizzle-orm';
+import type { PgDatabase, PgQueryResultHKT, PgTransaction } from 'drizzle-orm/pg-core';
+/** Work running in its own transaction, on a backend a spec can name in a lock wait. */
+export interface BackendRun<T> {
+    /** The backend the work runs on, known once its transaction has started. */
+    pid: Promise<number>;
+    /** The work's own result. */
+    result: Promise<T>;
+}
+/** How long {@link waitUntilBlockedBy} polls, and how often. */
+export interface BlockedWaitOptions {
+    /** Milliseconds before the wait rejects; 5000 when omitted. */
+    timeoutMs?: number;
+    /** Milliseconds between two polls; 20 when omitted. */
+    intervalMs?: number;
+}
+/**
+ * Opens a transaction on `db`, reads the backend it runs on, then runs `work` inside it.
+ *
+ * The transaction holds one pooled connection until `work` settles, so a spec can hold a lock on one
+ * backend and queue a second backend behind it. `pid` rejects with `result` when the transaction
+ * cannot start.
+ */
+export declare function runOnBackend<TSchema extends Record<string, unknown>, T>(db: PgDatabase<PgQueryResultHKT, TSchema>, work: (tx: PgTransaction<PgQueryResultHKT, TSchema, ExtractTablesWithRelations<TSchema>>) => Promise<T>): BackendRun<T>;
+/**
+ * Resolves once backend `holder` is among the backends `waiter` waits on for a lock.
+ *
+ * Only that pair counts: another backend queued behind `holder`, from this spec or from another file
+ * sharing the server, never satisfies the wait. Each argument is a {@link BackendRun} or a bare pid.
+ *
+ * @throws Error when `waiter`'s result settles before `holder` blocks it, which means the lock was
+ * never contended, or when `timeoutMs` passes; both messages name the two pids.
+ */
+export declare function waitUntilBlockedBy(db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>, waiter: BackendRun<unknown> | number, holder: BackendRun<unknown> | number, options?: BlockedWaitOptions): Promise<void>;
+//# sourceMappingURL=blocking-backend.d.ts.map

package/dist/testing/blocking-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocking-backend.d.ts","sourceRoot":"","sources":["../../src/testing/blocking-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAO,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvF,wFAAwF;AACxF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,6BAA6B;IAC7B,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACrE,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,OAAO,CAAC,EACzC,IAAI,EAAE,CAAC,EAAE,EAAE,aAAa,CAAC,gBAAgB,EAAE,OAAO,EAAE,0BAA0B,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACtG,UAAU,CAAC,CAAC,CAAC,CAkBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzD,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,EACpC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,EACpC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/testing/blocking-backend.js

@@ -0,0 +1,60 @@
+import { sql } from 'drizzle-orm';
+/**
+ * Opens a transaction on `db`, reads the backend it runs on, then runs `work` inside it.
+ *
+ * The transaction holds one pooled connection until `work` settles, so a spec can hold a lock on one
+ * backend and queue a second backend behind it. `pid` rejects with `result` when the transaction
+ * cannot start.
+ */
+export function runOnBackend(db, work) {
+    let resolvePid = (_pid) => undefined;
+    let rejectPid = (_reason) => undefined;
+    const pid = new Promise((resolve, reject) => {
+        resolvePid = resolve;
+        rejectPid = reject;
+    });
+    // A caller that awaits only `result` still hears a failed start through it, so the copy of that
+    // failure on `pid` must not also surface as an unhandled rejection.
+    pid.catch(() => undefined);
+    const result = db.transaction(async (tx) => {
+        const [backend] = await tx.select({ pid: sql `pid` }).from(sql `pg_backend_pid() as pid`);
+        if (backend === undefined)
+            throw new Error('pg_backend_pid() returned no row');
+        resolvePid(backend.pid);
+        return work(tx);
+    });
+    result.catch(rejectPid);
+    return { pid, result };
+}
+/**
+ * Resolves once backend `holder` is among the backends `waiter` waits on for a lock.
+ *
+ * Only that pair counts: another backend queued behind `holder`, from this spec or from another file
+ * sharing the server, never satisfies the wait. Each argument is a {@link BackendRun} or a bare pid.
+ *
+ * @throws Error when `waiter`'s result settles before `holder` blocks it, which means the lock was
+ * never contended, or when `timeoutMs` passes; both messages name the two pids.
+ */
+export async function waitUntilBlockedBy(db, waiter, holder, options = {}) {
+    const { timeoutMs = 5000, intervalMs = 20 } = options;
+    const deadline = Date.now() + timeoutMs;
+    let waiterEnded = false;
+    if (typeof waiter !== 'number') {
+        waiter.result.then(() => (waiterEnded = true), () => (waiterEnded = true));
+    }
+    const waiterPid = typeof waiter === 'number' ? waiter : await waiter.pid;
+    const holderPid = typeof holder === 'number' ? holder : await holder.pid;
+    for (;;) {
+        const [row] = await db
+            .select({ blocked: sql `${holderPid} = any(blockers)` })
+            .from(sql `pg_blocking_pids(${waiterPid}) as blockers`);
+        if (row?.blocked === true)
+            return;
+        if (waiterEnded)
+            throw new Error(`backend ${waiterPid} ended before backend ${holderPid} blocked it`);
+        if (Date.now() >= deadline) {
+            throw new Error(`timed out after ${timeoutMs} ms waiting for backend ${holderPid} to block backend ${waiterPid}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}

package/dist/testing/index.d.ts

@@ -1,3 +1,4 @@
+export * from './blocking-backend.js';
 export * from './disposable-postgres.js';
 export * from './fake-uuid-v7.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC"}

package/dist/testing/index.js

@@ -1,2 +1,3 @@
+export * from './blocking-backend.js';
 export * from './disposable-postgres.js';
 export * from './fake-uuid-v7.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/db",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "Generic Drizzle toolkit - the id column and audit timestamps a table takes, a base repository, the unit-of-work and transactional outbox impls, and the filter/sort/pagination query helpers, for PostgreSQL (postgres-js) and Cloudflare D1; ships no domain schema. Shared across ZeroXSolutions services.",
   "private": false,
   "type": "module",
@@ -43,7 +43,7 @@
     "tslib": "^2.3.0",
     "uuid": "^14.0.1",
     "@zeroxsolutions/cosmic": "0.3.4",
-    "@zeroxsolutions/query": "0.7.4"
+    "@zeroxsolutions/query": "0.7.5"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",