Add pg-transaction module

Author: brianc

packages/pg-transaction/.eslintrc

@@ -0,0 +1,7 @@
+{
+  "ignorePatterns": [
+    "/dist/*{js,ts,map}",
+    "/src",
+    "/esm"
+  ]
+}

packages/pg-transaction/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pg-transaction",
+  "version": "2.0.0",
+  "main": "dist/index.js",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "pretest": "tsc",
+    "test": "mocha dist/**/*.test.js"
+  },
+  "dependencies": {
+    "@types/node": "^24.0.14",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/mocha": "^10.0.10",
+    "@types/pg": "^8.10.9",
+    "mocha": "^10.8.2",
+    "pg": "^8.11.3"
+  }
+}

packages/pg-transaction/src/index.test.ts

@@ -0,0 +1,78 @@
+import { strict as assert } from 'assert';
+import { Client } from 'pg';
+import { transaction } from '.';
+
+class DisposableClient extends Client {
+  // overwrite the query method and log the arguments and then dispatch to the original method
+  override query(queryText: string, values?: any[]): Promise<any>;
+  override query(queryConfig: any): Promise<any>;
+  override query(queryStream: any): any;
+  override query(...args: any[]): any {
+    // console.log('Executing query:', ...args);
+    // @ts-ignore
+    return super.query(...args);
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.end();
+  }
+}
+
+async function getClient(): Promise<DisposableClient> {
+  const client = new DisposableClient()
+  await client.connect();
+  await client.query('CREATE TEMP TABLE test_table (id SERIAL PRIMARY KEY, name TEXT)');
+  return client
+}
+
+
+describe('transaction', () => {
+  it('should create a client with an empty temp table', async () => {
+    await using client = await getClient();
+    const { rowCount } = await client.query('SELECT * FROM test_table');
+    assert.equal(rowCount, 0, 'Temp table should be empty on creation');
+  });
+
+  it('automatically commits on success', async () => {
+    await using client = await getClient();
+    
+    const result = await transaction(client, async () => {
+      await client.query('INSERT INTO test_table (name) VALUES ($1)', ['test']);
+      const { rows } = await client.query('SELECT * FROM test_table');
+      return rows[0].name; // Should return 'test'
+    });
+    
+    assert.equal(result, 'test');
+  });
+
+  it('automatically rolls back on error', async () => {
+    await using client = await getClient();
+    
+    // Assert that the transaction function rejects with the expected error
+    await assert.rejects(
+      async () => {
+        await transaction(client, async () => {
+          await client.query('INSERT INTO test_table (name) VALUES ($1)', ['test']);
+          const { rows } = await client.query('SELECT * FROM test_table');
+          throw new Error('Simulated error'); // This will trigger a rollback
+        });
+      },
+      {
+        name: 'Error',
+        message: 'Simulated error'
+      }
+    );
+
+    // Verify that the transaction rolled back
+    const { rowCount } = await client.query('SELECT * FROM test_table');
+    assert.equal(rowCount, 0, 'Table should be empty after rollback');
+  });
+
+  it('can return nothing from the transaction with correct type', async () => {
+    await using client = await getClient();
+    
+    const _nothing: void = await transaction(client, async () => {
+      await client.query('INSERT INTO test_table (name) VALUES ($1)', ['test']);
+    });
+  });
+});

packages/pg-transaction/src/index.ts

@@ -0,0 +1,42 @@
+import { Client } from 'pg';
+
+async function doTransaction(client: Client) {
+  await client.query('BEGIN');
+  
+  let shouldRollback = false;
+  let disposed = false;
+  
+  return {
+    async [Symbol.asyncDispose]() {
+      if (disposed) return;
+      disposed = true;
+      
+      if (shouldRollback) {
+        await client.query('ROLLBACK');
+      } else {
+        await client.query('COMMIT');
+      }
+    },
+    
+    rollback() {
+      shouldRollback = true;
+    }
+  };
+}
+
+// Auto-rollback wrapper that catches errors automatically
+async function transaction<T>(client: Client, fn: () => Promise<T>): Promise<T> {
+  await using txn = await doTransaction(client);
+  
+  try {
+    const result = await fn();
+    // If we get here, success - transaction will auto-commit
+    return result;
+  } catch (error) {
+    // If error occurs, mark for rollback
+    txn.rollback();
+    throw error;
+  }
+}
+
+export { transaction as transaction };

packages/pg-transaction/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "commonjs",
+    "lib": ["es2022", "ESNext.Disposable"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}