@zukhruf/sqlite-transaction 0.0.0-stage → 0.3.32

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-transaction
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`node:sqlite` has no function that runs work in a transaction. Thus each store writes `BEGIN`, `COMMIT` and `ROLLBACK` itself. After some errors, SQLite ends the transaction itself. Then a `ROLLBACK` fails with `cannot rollback - no transaction is active`, and that error replaces the original error. This package gives one function that runs work in a transaction, and that keeps the original error. This function is also known as a transaction function or a transaction wrapper.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Use it
+
+This project is an experiment. It uses only `node:sqlite`.
+
+```sh
+npm install @zukhruf/sqlite-transaction
+```
+
+```ts
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { transaction } from '@zukhruf/sqlite-transaction';
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'transaction-'));
+using database = new DatabaseSync(join(scratch.path, 'app.sqlite'));
+database.exec('CREATE TABLE notes (body TEXT) STRICT');
+
+const rows = transaction(
+  database,
+  () => {
+    database.exec("INSERT INTO notes VALUES ('kept')");
+    try {
+      transaction(
+        database,
+        () => {
+          database.exec("INSERT INTO notes VALUES ('undone')");
+          throw new Error('stop');
+        },
+        { mode: 'immediate' },
+      );
+    } catch (error) {
+      console.log((error as Error).message);
+    }
+    return database.prepare('SELECT body FROM notes').all().length;
+  },
+  { mode: 'immediate' },
+);
+console.log(rows);
+```
+
+Output:
+
+```
+stop
+1
+```
+
+## The rules
+
+- `transaction(database, work, { mode })` runs `work`. When `work` returns, the transaction commits, and `transaction` gives the value of `work`. When `work` throws, the transaction rolls back, and `transaction` throws the same error.
+- When the connection has no transaction, the call is the owner. It starts the transaction with `BEGIN DEFERRED`, `BEGIN IMMEDIATE` or `BEGIN EXCLUSIVE`, as `mode` tells.
+- When the connection has a transaction, the call works in a savepoint. When `work` throws, only the changes of `work` are undone, and the outer transaction continues. The mode does not apply.
+- The rollback runs only while SQLite holds the transaction. When SQLite ended the transaction itself, `transaction` throws the original error. [ADR 0001](./docs/adr/0001-roll-back-only-while-sqlite-holds-the-transaction.md) tells why.
+- `work` must be synchronous. `node:sqlite` is synchronous, and a transaction cannot stay open across an `await`.
+- `transaction` does not wait for a lock, and it does not try again. The busy timeout of the connection sets how long SQLite waits.
+
+## Errors
+
+| Error                | When                                                                                                                  |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `TypeError`          | `work` gives a promise. The transaction rolls back. TypeScript also refuses an `async` function.                      |
+| The original error   | `work` throws. The transaction rolls back, or SQLite ended it before.                                                 |
+| `database is locked` | `BEGIN IMMEDIATE` or `BEGIN EXCLUSIVE` waits for the busy timeout of the connection, then fails. `work` does not run. |
+
+## The same concepts in other systems
+
+| System                    | What it does                                                                                                                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| better-sqlite3            | `db.transaction(fn)` gives a function that runs `fn` in a transaction. A call inside a transaction uses a savepoint. `.deferred`, `.immediate` and `.exclusive` set the mode. It refuses a function that gives a promise. |
+| Python `sqlite3`          | `with conn:` commits when the block ends, and rolls back when the block raises an exception.                                                                                                                              |
+| SQLite automatic rollback | After some errors, for example `SQLITE_IOERR` or `RAISE(ROLLBACK)` in a trigger, SQLite rolls back the transaction itself. See "Response To Errors Within A Transaction" in the SQLite documentation.                     |
+
+## Documentation
+
+- [0001 Roll back only while SQLite holds the transaction](./docs/adr/0001-roll-back-only-while-sqlite-holds-the-transaction.md)
+
+## Development
+
+This package is part of the [zukhruf](../../../README.md) workspace. Run the commands from the workspace root.
+
+```sh
+npm install
+npx nx run sqlite-transaction:test        # builds, then runs the tests in src/
+npx nx run sqlite-transaction:typecheck   # formats, lints, then type checks
+npx nx run sqlite-transaction:build       # compiles src/ to dist/
+```
+
+```
+src/
+  index.ts               the exports
+  transaction.ts         transaction and TransactionMode
+  transaction.test.ts    the tests, on real SQLite files
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { transaction, type TransactionMode } from './transaction.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { transaction } from "./transaction.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAC"}

package/dist/transaction.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseSync } from 'node:sqlite';
+export type TransactionMode = 'deferred' | 'immediate' | 'exclusive';
+export declare function transaction<T>(database: Pick<DatabaseSync, 'exec' | 'isTransaction'>, work: () => T extends PromiseLike<unknown> ? never : T, options: {
+    readonly mode: TransactionMode;
+}): T;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;AAUrE,wBAAgB,WAAW,CAAC,CAAC,EAC3B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAAC,EACtD,IAAI,EAAE,MAAM,CAAC,SAAS,WAAW,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,EACtD,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC1C,CAAC,CAkBH"}

package/dist/transaction.js

@@ -0,0 +1,30 @@
+// SQLite lets one name nest: ROLLBACK TO and RELEASE find the innermost.
+const SAVEPOINT = 'zukhruf_transaction';
+// Runs work in a transaction: commits when it returns, rolls back when it
+// throws. Inside a transaction, work runs in a savepoint and the mode does not
+// apply. The rollback runs only while SQLite still holds the transaction:
+// after some errors SQLite ends the transaction itself, and a ROLLBACK then
+// would replace the original error.
+export function transaction(database, work, options) {
+    const owns = !database.isTransaction;
+    database.exec(owns ? `BEGIN ${options.mode.toUpperCase()}` : `SAVEPOINT ${SAVEPOINT}`);
+    try {
+        const result = work();
+        if (thenable(result))
+            throw new TypeError('A transaction function cannot return a promise');
+        database.exec(owns ? 'COMMIT' : `RELEASE ${SAVEPOINT}`);
+        return result;
+    }
+    catch (error) {
+        if (database.isTransaction)
+            database.exec(owns ? 'ROLLBACK' : `ROLLBACK TO ${SAVEPOINT}; RELEASE ${SAVEPOINT}`);
+        throw error;
+    }
+}
+function thenable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAKA,yEAAyE;AACzE,MAAM,SAAS,GAAG,qBAAqB,CAAC;AAExC,0EAA0E;AAC1E,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,oCAAoC;AACpC,MAAM,UAAU,WAAW,CACzB,QAAsD,EACtD,IAAsD,EACtD,OAA2C;IAE3C,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC;IACrC,QAAQ,CAAC,IAAI,CACX,IAAI,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,SAAS,EAAE,CACxE,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,EAAE,CAAC;QACtB,IAAI,QAAQ,CAAC,MAAM,CAAC;YAClB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;QACxE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,SAAS,EAAE,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,QAAQ,CAAC,aAAa;YACxB,QAAQ,CAAC,IAAI,CACX,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,SAAS,aAAa,SAAS,EAAE,CACrE,CAAC;QACJ,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,CACjC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zukhruf/sqlite-transaction",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.32",
+  "description": "A transaction function for node:sqlite. It runs a function in a transaction, commits when the function returns, and rolls back when it throws. A call inside a transaction works in a savepoint. After SQLite ends the transaction itself, the caller gets the original error, not \"cannot rollback\".",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/transaction"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/transaction#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "transaction",
+    "savepoint",
+    "rollback",
+    "nested-transaction"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}