Add explicit mode

Author: MelleB

CHANGELOG.md

@@ -1,9 +1,13 @@
 # CHANGELOG
 
-# 0.1.0
+# 0.3.0
 
-- Initial commit
+- Add explicit mode
 
 # 0.2.0
 
 - Add handling of exceptions inside transactions
+
+# 0.1.0
+
+- Initial commit

README.md

@@ -29,9 +29,18 @@ $ npm install pg pgtx
 
 To use pgtx, wrap your PostgreSQL client with `pgtx`. You can then perform transactions as usual, and pgtx will manage savepoints automatically.
 
+`pgtx` has two modes:
+
+1. **Automated mode** runs inside nested functions and commits after the function ends. To roll back call `tx.rollback()` or throw an error.
+2. **Explicit mode** requires the user to call `tx.commit()` or `tx.rollback()` explicitly.
+
+### Usage -- Automated mode
+
+The caller provides an async function to the transaction method and committing happens after completion of this method.
+
 ```typescript
-import pgtx, { PgtxClient } from "pgtx";
-import { Client } from "pg";
+import pgtx, { PgtxClient } from 'pgtx';
+import { Client } from 'pg';
 
 const client = new Client({
   /* connection config */
@@ -40,7 +49,7 @@ const db: PgtxClient = pgtx(client);
 
 await db.transaction(async (tx) => {
   // Your transactional code here, e.g.
-  await db.query("INSERT INTO ...", [value]);
+  await db.query('INSERT INTO ...', [value]);
 
   await trx.transaction(async (nestedTx) => {
     // Nested transaction handled with savepoint
@@ -56,7 +65,7 @@ await db.transaction(async (tx) => {
   // parent transactions can handle the exception as well
   try {
     await tx.transation(async (nestedTx) => {
-      throw new Error("Some issue occured");
+      throw new Error('Some issue occured');
     });
   } catch (e) {
     // Handle recovery scenario
@@ -66,13 +75,35 @@ await db.transaction(async (tx) => {
 });
 ```
 
+### Usage -- Explicit mode
+
+The caller is responsible for calling either `commit()` or `rollback`. Be sure to handle failure scenario's using `try`/`catch`.
+
+```typescript
+const client = new Client({
+  /* connection config */
+});
+const db: PgtxClient = pgtx(client);
+
+const tx = await db.transaction();
+// Other code here, e.g.:
+await tx.query('INSERT INTO ...', [value]);
+
+const txNested = await tx.transaction(); // note the use of `tx` here
+// Other code here, e.g.:
+await txNested.query('INSERT INTO ...', [value]);
+await txNested.rollback();
+
+await tx.commit();
+```
+
 ## API
 
 **`PgtxClient`** extends `pg.Client` and adds:
 
-- `async transaction(tx: PgtxClient => void)`: Begins a new transaction or savepoint if already in a transaction.
-- `async rollback()`: Rolls back the current transaction or savepoint.
-- `async commit()`: Commits the current transaction or releases the savepoint -- although typically you will not use this method
+- `transaction(txFn?: (tx: PgtxClient) => void): Promise<PgtxClient>`: Begins a new transaction or savepoint if already in a transaction. If `txFn` is not defined it sets the client to the child context.
+- `rollback(): Promise<PgtxClient>`: Rolls back the current transaction or savepoint. Returns the client in the parent context.
+- `commit(): Promise<PgtxClient>`: Commits the current transaction or releases the savepoint -- although typically you will not use this method. Returns the client in the parent context.
 
 ## Contributions
 

eslint.config.mjs

@@ -1,12 +1,12 @@
 // @ts-check
 
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 
 export default tseslint.config(
   {
-    ignores: ["dist/*"],
+    ignores: ['dist/*'],
   },
   eslint.configs.recommended,
   ...tseslint.configs.recommended,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgtx",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Simple node-postgres wrapper that abstracts transactions and savepoints",
   "repository": {
     "type": "git",
@@ -51,4 +51,4 @@
   "peerDependencies": {
     "pg": "^8.12.0"
   }
-}
+}

prettier.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  trailingComma: 'all',
+  tabWidth: 2,
+  semi: true,
+  singleQuote: true,
+};

src/index.test.ts

@@ -1,20 +1,20 @@
-import { describe, test, expect } from "vitest";
-import { getClient, createTable, checkRows, insertRow } from "./test/util";
+import { describe, test, expect } from 'vitest';
+import { getClient, createTable, checkRows, insertRow } from './test/util';
 
-describe("happy flows", async () => {
-  test("single level non explicit commit", async () => {
+describe('happy flows', async () => {
+  test('single level non explicit commit', async () => {
     const client = await getClient();
     await client.transaction(async (tx) => {
-      await createTable(tx, "table1");
-      await insertRow(tx, "table1", 1);
+      await createTable(tx, 'table1');
+      await insertRow(tx, 'table1', 1);
     });
 
-    await checkRows(client, "table1", 1);
+    await checkRows(client, 'table1', 1);
   });
 
-  test("nested multiple non explicit commits", async () => {
+  test('nested multiple non explicit commits', async () => {
     const client = await getClient();
-    const tableName = "table2";
+    const tableName = 'table2';
 
     await client.transaction(async (tx) => {
       await createTable(tx, tableName);
@@ -35,8 +35,8 @@ describe("happy flows", async () => {
     await checkRows(client, tableName, 3);
   });
 
-  test("simple rollback", async () => {
-    const tableName = "table3";
+  test('simple rollback', async () => {
+    const tableName = 'table3';
     const client = await getClient();
     await createTable(client, tableName);
 
@@ -48,8 +48,8 @@ describe("happy flows", async () => {
     await checkRows(client, tableName, 0);
   });
 
-  test("nested rollback", async () => {
-    const tableName = "table4";
+  test('nested rollback', async () => {
+    const tableName = 'table4';
     const client = await getClient();
 
     await client.transaction(async (tx) => {
@@ -64,8 +64,8 @@ describe("happy flows", async () => {
     await checkRows(client, tableName, 0);
   });
 
-  test("nested rollback with continuation", async () => {
-    const tableName = "table5";
+  test('nested rollback with continuation', async () => {
+    const tableName = 'table5';
     const client = await getClient();
 
     await client.transaction(async (tx) => {
@@ -85,9 +85,9 @@ describe("happy flows", async () => {
   });
 });
 
-describe("exception handling", async () => {
-  test("exception executes rollback", async () => {
-    const tableName = "table6";
+describe('exception handling', async () => {
+  test('exception executes rollback', async () => {
+    const tableName = 'table6';
     const client = await getClient();
 
     await createTable(client, tableName);
@@ -96,15 +96,15 @@ describe("exception handling", async () => {
         await insertRow(tx, tableName, 1);
         throw new Error();
       });
-    } catch (e) {
+    } catch {
       // catch-all
     }
 
     await checkRows(client, tableName, 0);
   });
 
-  test("nested exception without try/catch rolls back everything", async () => {
-    const tableName = "table7";
+  test('nested exception without try/catch rolls back everything', async () => {
+    const tableName = 'table7';
     const client = await getClient();
 
     try {
@@ -113,7 +113,7 @@ describe("exception handling", async () => {
         await insertRow(tx, tableName, 1);
         await tx.transaction(async (tx2) => {
           await insertRow(tx2, tableName, 2);
-          throw new Error("dummy-msg");
+          throw new Error('dummy-msg');
         });
       });
     } catch (e) {
@@ -123,8 +123,8 @@ describe("exception handling", async () => {
     await checkRows(client, tableName, 0);
   });
 
-  test("nested exception executes rollback to savepoint", async () => {
-    const tableName = "table8";
+  test('nested exception executes rollback to savepoint', async () => {
+    const tableName = 'table8';
     const client = await getClient();
 
     await createTable(client, tableName);
@@ -135,11 +135,65 @@ describe("exception handling", async () => {
           await insertRow(tx2, tableName, 2);
           throw new Error();
         });
-      } catch (e) {
+      } catch {
         // catch error
       }
     });
 
     await checkRows(client, tableName, 1);
   });
 });
+
+describe('explicit mode', async () => {
+  test('unnested transaction - commit', async () => {
+    const tableName = 'table9';
+    const client = await getClient();
+
+    await createTable(client, tableName);
+    const tx = await client.transaction();
+    await insertRow(tx, tableName, 1);
+    await tx.commit();
+
+    await checkRows(client, tableName, 1);
+  });
+
+  test('unnested transaction - rollback', async () => {
+    const tableName = 'table10';
+    const client = await getClient();
+
+    await createTable(client, tableName);
+    const tx = await client.transaction();
+    await insertRow(tx, tableName, 1);
+    await tx.rollback();
+
+    await checkRows(client, tableName, 0);
+  });
+
+  test('nested transaction - commit', async () => {
+    const tableName = 'table11';
+    const client = await getClient();
+
+    await createTable(client, tableName);
+    const tx = await client.transaction();
+    await tx.transaction(async (tx2) => {
+      await insertRow(tx2, tableName, 1);
+    });
+    await tx.commit();
+
+    await checkRows(client, tableName, 1);
+  });
+
+  test('nested transaction - rollback', async () => {
+    const tableName = 'table11';
+    const client = await getClient();
+
+    await createTable(client, tableName);
+    const tx = await client.transaction();
+    await tx.transaction(async (tx2) => {
+      await insertRow(tx2, tableName, 1);
+    });
+    await tx.rollback();
+
+    await checkRows(client, tableName, 0);
+  });
+});

src/index.ts

@@ -1,5 +1,5 @@
-import { Client } from "pg";
-import { randomUUID } from "crypto";
+import { Client } from 'pg';
+import { randomUUID } from 'crypto';
 
 enum TransactionStatus {
   ACTIVE,
@@ -16,24 +16,30 @@ class TransactionContext {
   ) {}
 
   async transaction(
-    childTransaction: (client: PgtxClient) => Promise<void>,
-  ): Promise<void> {
+    childTransaction?: (client: PgtxClient) => Promise<void>,
+  ): Promise<PgtxClient> {
     let activeSavePointName: string | undefined = undefined;
 
     if (this.parentTransaction) {
-      activeSavePointName = "sp_" + randomUUID().replaceAll("-", "_");
+      activeSavePointName = 'sp_' + randomUUID().replaceAll('-', '_');
       await this.client.query(`SAVEPOINT ${activeSavePointName}`);
     } else {
-      await this.client.query("BEGIN");
+      await this.client.query('BEGIN');
     }
 
     const childCtx = new TransactionContext(
       this.client,
       this,
       activeSavePointName,
     );
+
+    const proxy = createProxy(this.client, childCtx);
+    if (!childTransaction) {
+      return proxy;
+    }
+
     try {
-      await childTransaction(createProxy(this.client, childCtx));
+      await childTransaction(proxy);
     } catch (e) {
       await childCtx.rollback();
       throw e;
@@ -42,33 +48,35 @@ class TransactionContext {
     if (childCtx.status === TransactionStatus.ACTIVE) {
       await childCtx.commit();
     }
+
+    return createProxy(this.client, this);
   }
 
   async commit(): Promise<PgtxClient> {
     if (this.status !== TransactionStatus.ACTIVE) {
-      throw new Error("Cannot commit a transaction that is not active");
+      throw new Error('Cannot commit a transaction that is not active');
     }
     if (this.parentTransaction && this.activeSavePoint) {
       await this.client.query(`RELEASE SAVEPOINT ${this.activeSavePoint}`);
       return createProxy(this.client, this.parentTransaction);
     }
 
-    await this.client.query("COMMIT");
+    await this.client.query('COMMIT');
     this.status = TransactionStatus.COMMITTED;
     return createProxy(this.client, this.parentTransaction || this);
   }
 
   async rollback(): Promise<PgtxClient> {
     if (this.status !== TransactionStatus.ACTIVE) {
-      throw new Error("Cannot roll back a transaction that is not active");
+      throw new Error('Cannot roll back a transaction that is not active');
     }
     if (this.activeSavePoint && this.parentTransaction) {
       await this.client.query(`ROLLBACK TO SAVEPOINT ${this.activeSavePoint}`);
       this.status = TransactionStatus.CANCELLED;
       return createProxy(this.client, this.parentTransaction);
     }
 
-    await this.client.query("ROLLBACK");
+    await this.client.query('ROLLBACK');
     this.status = TransactionStatus.CANCELLED;
     return createProxy(this.client, this.parentTransaction || this);
   }