@byline/db-postgres 3.8.0 → 3.9.0

package/dist/index.js

@@ -8,6 +8,7 @@
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
+import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
 import { createCommandBuilders, } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -19,7 +20,14 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
         connectionTimeoutMillis,
     });
     const db = drizzle(pool, { schema });
-    const commandBuilders = createCommandBuilders(db, defaultContentLocale);
+    // Request-scoped transaction propagation (docs/TRANSACTIONS.md). The command
+    // builders run on the DBManager — each `this.db` access resolves to the
+    // ambient transaction when a `withTransaction` boundary is open, else the
+    // pool. Queries and counters stay on the raw `db` for now (reads don't need
+    // to join the audit transaction); they migrate opportunistically.
+    const dbManager = new DBManagerImpl({ dbPool: db });
+    const txManager = new TXManagerImpl({ db: dbManager });
+    const commandBuilders = createCommandBuilders(dbManager, defaultContentLocale);
     const queryBuilders = createQueryBuilders(db, collections, defaultContentLocale);
     const counterCommands = createCounterCommands(db);
     return {
@@ -28,6 +36,7 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
             counters: counterCommands,
         },
         queries: queryBuilders,
+        withTransaction: (fn) => txManager.withTransaction(fn),
         drizzle: db,
         pool,
         backfillVersionLocales: () => commandBuilders.documents.backfillVersionLocales(),

package/dist/lib/db-manager.d.ts

@@ -0,0 +1,61 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Ported from the Modulus project (`db-manager.ts`) — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../database/schema/index.js';
+/**
+ * The executor every storage command runs on: either the connection pool
+ * (autonomous, statement-at-a-time) or — when a `withTransaction` boundary is
+ * open in the current async context — that transaction. Commands obtain it via
+ * `DBManager.get()` and never thread a transaction handle through their
+ * signatures.
+ */
+export type DBExecutor = NodePgDatabase<typeof schema>;
+export interface DBManager {
+    /**
+     * The current executor: the ambient transaction when a `withTransaction`
+     * boundary is open in this async context, otherwise the pool.
+     */
+    get(): DBExecutor;
+}
+export declare class DBManagerImpl implements DBManager {
+    private readonly dbPool;
+    constructor(deps: {
+        dbPool: DBExecutor;
+    });
+    get(): DBExecutor;
+}
+export interface TXManager {
+    /**
+     * Run `fn` inside a single database transaction. Every `DBManager.get()`
+     * call made during `fn` (transitively, across `await`s) returns that
+     * transaction, so the commands `fn` invokes commit or roll back together.
+     *
+     * Nesting: when already inside a `withTransaction`, the inner call opens a
+     * SAVEPOINT (Drizzle nested transaction) — an inner throw rolls back to the
+     * savepoint, an outer throw rolls back everything.
+     */
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class TXManagerImpl implements TXManager {
+    private readonly db;
+    constructor(deps: {
+        db: DBManager;
+    });
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/lib/db-manager.js

@@ -0,0 +1,43 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Ported from the Modulus project (`db-manager.ts`) — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const transactionALS = new AsyncLocalStorage();
+export class DBManagerImpl {
+    dbPool;
+    constructor(deps) {
+        this.dbPool = deps.dbPool;
+    }
+    get() {
+        return transactionALS.getStore() ?? this.dbPool;
+    }
+}
+export class TXManagerImpl {
+    db;
+    constructor(deps) {
+        this.db = deps.db;
+    }
+    withTransaction(fn) {
+        return this.db.get().transaction((tx) => 
+        // `tx` is Drizzle's PgTransaction; it carries the full query-builder
+        // surface every command uses. The cast bridges the one structural gap
+        // to NodePgDatabase — the transaction lacks `$client`, which no command
+        // touches. See docs/TRANSACTIONS.md.
+        transactionALS.run(tx, fn));
+    }
+}

package/dist/lib/test-helper.d.ts

@@ -1,9 +1,12 @@
 import type { CollectionDefinition } from '@byline/core';
 import { type NodePgDatabase } from 'drizzle-orm/node-postgres';
 import * as schema from '../database/schema/index.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
 export declare function setupTestDB(collections?: CollectionDefinition[]): {
     pool: import("pg").Pool;
     db: NodePgDatabase<typeof schema>;
+    dbManager: DBManagerImpl;
+    txManager: TXManagerImpl;
     commandBuilders: {
         collections: import("../modules/storage/storage-commands.js").CollectionCommands;
         documents: import("../modules/storage/storage-commands.js").DocumentCommands;

package/dist/lib/test-helper.js

@@ -3,9 +3,12 @@ import pg from 'pg';
 import * as schema from '../database/schema/index.js';
 import { createCommandBuilders } from '../modules/storage/storage-commands.js';
 import { createQueryBuilders } from '../modules/storage/storage-queries.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
 import { assertTestDatabase } from './test-db.js';
 let pool;
 let db;
+let dbManager;
+let txManager;
 let commandBuilders;
 let queryBuilders;
 export function setupTestDB(collections = []) {
@@ -26,19 +29,25 @@ export function setupTestDB(collections = []) {
     if (!db) {
         db = drizzle(pool, { schema });
     }
+    if (!dbManager) {
+        dbManager = new DBManagerImpl({ dbPool: db });
+        txManager = new TXManagerImpl({ db: dbManager });
+    }
     if (!commandBuilders) {
-        commandBuilders = createCommandBuilders(db, 'en');
+        commandBuilders = createCommandBuilders(dbManager, 'en');
     }
     // Recreate queryBuilders when collections are provided so that
     // DocumentQueries can resolve collection definitions by path.
     queryBuilders = createQueryBuilders(db, collections, 'en');
-    return { pool, db, commandBuilders, queryBuilders };
+    return { pool, db, dbManager, txManager, commandBuilders, queryBuilders };
 }
 export async function teardownTestDB() {
     if (pool) {
         await pool.end();
         pool = undefined;
         db = undefined;
+        dbManager = undefined;
+        txManager = undefined;
         commandBuilders = undefined;
         queryBuilders = undefined;
     }

package/dist/modules/storage/storage-commands.d.ts

@@ -6,9 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { CollectionDefinition, ICollectionCommands, IDocumentCommands } from '@byline/core';
-import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import type * as schema from '../../database/schema/index.js';
-type DatabaseConnection = NodePgDatabase<typeof schema>;
+import type { DBManager } from '../../lib/db-manager.js';
 /** Outcome of re-anchoring a single document's content source locale. */
 export type ReAnchorStatus = 'reanchored' | 'skipped-incomplete' | 'already-anchored' | 'not-found';
 export interface ReAnchorResult {
@@ -36,8 +34,15 @@ export interface ReAnchorReport {
  * CollectionCommands
  */
 export declare class CollectionCommands implements ICollectionCommands {
-    private db;
-    constructor(db: DatabaseConnection);
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    private get db();
     create(path: string, config: CollectionDefinition, opts?: {
         version?: number;
         schemaHash?: string;
@@ -73,9 +78,16 @@ export declare class CollectionCommands implements ICollectionCommands {
  * DocumentCommands
  */
 export declare class DocumentCommands implements IDocumentCommands {
-    private db;
+    private dbManager;
     private defaultContentLocale;
-    constructor(db: DatabaseConnection, defaultContentLocale: string);
+    constructor(dbManager: DBManager, defaultContentLocale: string);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    private get db();
     /**
      * createDocumentVersion
      *
@@ -379,8 +391,7 @@ export declare class DocumentCommands implements IDocumentCommands {
         order_key: string;
     }): Promise<void>;
 }
-export declare function createCommandBuilders(db: DatabaseConnection, defaultContentLocale: string): {
+export declare function createCommandBuilders(dbManager: DBManager, defaultContentLocale: string): {
     collections: CollectionCommands;
     documents: DocumentCommands;
 };
-export {};

package/dist/modules/storage/storage-commands.js

@@ -15,9 +15,18 @@ import { getFirstOrThrow } from './storage-utils.js';
  * CollectionCommands
  */
 export class CollectionCommands {
-    db;
-    constructor(db) {
-        this.db = db;
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    get db() {
+        return this.dbManager.get();
     }
     async create(path, config, opts) {
         return await this.db
@@ -51,12 +60,21 @@ export class CollectionCommands {
  * DocumentCommands
  */
 export class DocumentCommands {
-    db;
+    dbManager;
     defaultContentLocale;
-    constructor(db, defaultContentLocale) {
-        this.db = db;
+    constructor(dbManager, defaultContentLocale) {
+        this.dbManager = dbManager;
         this.defaultContentLocale = defaultContentLocale;
     }
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    get db() {
+        return this.dbManager.get();
+    }
     /**
      * createDocumentVersion
      *
@@ -836,9 +854,9 @@ export class DocumentCommands {
             .where(eq(documents.id, params.document_id));
     }
 }
-export function createCommandBuilders(db, defaultContentLocale) {
+export function createCommandBuilders(dbManager, defaultContentLocale) {
     return {
-        collections: new CollectionCommands(db),
-        documents: new DocumentCommands(db, defaultContentLocale),
+        collections: new CollectionCommands(dbManager),
+        documents: new DocumentCommands(dbManager, defaultContentLocale),
     };
 }

package/dist/modules/storage/tests/storage-transactions.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/storage/tests/storage-transactions.test.js

@@ -0,0 +1,108 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Integration tests for request-scoped transaction propagation
+ * (`withTransaction` / DBManager / TXManager — see docs/TRANSACTIONS.md).
+ *
+ * Proves the load-bearing guarantee the audit log depends on: multiple
+ * `commands.*` calls wrapped in one `withTransaction` commit or roll back
+ * **together**, with no transaction handle threaded through their signatures.
+ * The commands join the ambient transaction purely via the AsyncLocalStorage
+ * propagation in DBManager.get().
+ */
+import { eq } from 'drizzle-orm';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { collections } from '../../../database/schema/index.js';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+let db;
+let dbManager;
+let txManager;
+let commandBuilders;
+const ts = Date.now();
+const createdPaths = [];
+async function collectionExists(path) {
+    const rows = await db
+        .select({ id: collections.id })
+        .from(collections)
+        .where(eq(collections.path, path));
+    return rows.length > 0;
+}
+describe('withTransaction propagation + atomicity', () => {
+    beforeAll(() => {
+        const testDB = setupTestDB([]);
+        db = testDB.db;
+        dbManager = testDB.dbManager;
+        txManager = testDB.txManager;
+        commandBuilders = testDB.commandBuilders;
+    });
+    afterAll(async () => {
+        for (const path of createdPaths) {
+            try {
+                const rows = await db
+                    .select({ id: collections.id })
+                    .from(collections)
+                    .where(eq(collections.path, path));
+                if (rows[0])
+                    await commandBuilders.collections.delete(rows[0].id);
+            }
+            catch (error) {
+                console.error('cleanup failed for', path, error);
+            }
+        }
+        await teardownTestDB();
+    });
+    it('get() returns the pool outside a transaction and the tx inside it', async () => {
+        // Outside any boundary, the executor is the pool itself.
+        expect(dbManager.get()).toBe(db);
+        let insideExecutor;
+        await txManager.withTransaction(async () => {
+            insideExecutor = dbManager.get();
+        });
+        // Inside the boundary it is the ambient transaction — a different handle.
+        expect(insideExecutor).not.toBe(db);
+    });
+    it('commits every command in the boundary together', async () => {
+        const a = `tx-commit-a-${ts}`;
+        const b = `tx-commit-b-${ts}`;
+        createdPaths.push(a, b);
+        await txManager.withTransaction(async () => {
+            await commandBuilders.collections.create(a, {
+                path: a,
+                labels: { singular: 'A', plural: 'As' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+            await commandBuilders.collections.create(b, {
+                path: b,
+                labels: { singular: 'B', plural: 'Bs' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+        });
+        expect(await collectionExists(a)).toBe(true);
+        expect(await collectionExists(b)).toBe(true);
+    });
+    it('rolls back every command in the boundary when it throws', async () => {
+        const a = `tx-rollback-a-${ts}`;
+        const b = `tx-rollback-b-${ts}`;
+        const boom = new Error('boom');
+        await expect(txManager.withTransaction(async () => {
+            // First write succeeds...
+            await commandBuilders.collections.create(a, {
+                path: a,
+                labels: { singular: 'A', plural: 'As' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+            // ...then the unit of work fails after it. If the first write ran on
+            // the pool rather than the ambient tx, it would survive this throw.
+            throw boom;
+        })).rejects.toThrow('boom');
+        // Atomicity: the successful-looking first write was rolled back with the
+        // failing transaction. Neither collection exists.
+        expect(await collectionExists(a)).toBe(false);
+        expect(await collectionExists(b)).toBe(false);
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/admin": "3.8.0",
-    "@byline/auth": "3.8.0",
-    "@byline/core": "3.8.0"
+    "@byline/auth": "3.9.0",
+    "@byline/admin": "3.9.0",
+    "@byline/core": "3.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",