inibase 2.0.0 → 3.0.0

package/dist/index.js

@@ -1,11 +1,12 @@
 import "dotenv/config";
-import { randomBytes, scryptSync } from "node:crypto";
+import { randomBytes, randomUUID, scryptSync } from "node:crypto";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
-import { glob, mkdir, readdir, readFile, rename, rm, unlink, writeFile, } from "node:fs/promises";
-import { join, parse } from "node:path";
+import { glob, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
+import { basename, join, parse, resolve } from "node:path";
 import { inspect } from "node:util";
 import Inison from "inison";
 import * as File from "./file.js";
+import { DatabaseJournal, Journal } from "./journal.js";
 import * as Utils from "./utils.js";
 import * as UtilsServer from "./utils.server.js";
 export const ERROR_CODES = [
@@ -48,6 +49,13 @@ export default class Inibase {
     databasePath;
     uniqueMap;
     schemaFileExtension = process.env.INIBASE_SCHEMA_EXTENSION ?? "json";
+    /**
+     * Open database transaction (see begin/commit/rollback). Holds the
+     * database lock (`<db>/.tmp/.locked`) for its whole lifetime and the
+     * per-table writer lock of every table it mutates, so mutations stage into
+     * the database journal and publish only on commit().
+     */
+    transaction = null;
     constructor(database, mainFolder = ".", language = "en") {
         this.language = language;
         this.validateName(database);
@@ -128,6 +136,11 @@ export default class Inibase {
      */
     async createTable(tableName, schema, config) {
         this.validateName(tableName);
+        // DDL does not participate in the write-ahead journal: schema surgery
+        // inside a transaction would escape the atomic publish/rollback scope.
+        if (this.transaction)
+            throw this.createError("INVALID_PARAMETERS");
+        await this.ensureDatabaseRecovered();
         if (schema)
             this.validateSchema(schema);
         const tablePath = join(this.databasePath, tableName);
@@ -145,24 +158,27 @@ export default class Inibase {
             };
         if (config) {
             if (config.compression)
-                await writeFile(join(tablePath, ".compression.config"), "");
+                await File.write(join(tablePath, ".compression.config"), "");
             if (config.cache)
-                await writeFile(join(tablePath, ".cache.config"), "");
+                await File.write(join(tablePath, ".cache.config"), "");
             if (config.prepend)
-                await writeFile(join(tablePath, ".prepend.config"), "");
+                await File.write(join(tablePath, ".prepend.config"), "");
             if (config.decodeID)
-                await writeFile(join(tablePath, ".decodeID.config"), "");
+                await File.write(join(tablePath, ".decodeID.config"), "");
         }
         if (schema) {
             const lastSchemaID = { value: 0 };
-            await writeFile(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
+            await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
                 ? JSON.stringify(Utils.addIdToSchema(schema, lastSchemaID), null, 2)
                 : Inison.stringify(Utils.addIdToSchema(schema, lastSchemaID)));
-            await writeFile(join(tablePath, `${lastSchemaID.value}.schema`), "");
+            await File.write(join(tablePath, `${lastSchemaID.value}.schema`), "");
         }
         else
-            await writeFile(join(tablePath, "0.schema"), "");
-        await writeFile(join(tablePath, "0-0.pagination"), "");
+            await File.write(join(tablePath, "0.schema"), "");
+        await File.write(join(tablePath, "0-0.pagination"), "");
+        // Make the new table's metadata durable before acknowledging creation.
+        await File.syncDir(tablePath);
+        await File.syncDir(join(tablePath, ".tmp"));
         this.idDensity.set(tableName, true);
     }
     // Function to replace the string in one schema file
@@ -170,7 +186,9 @@ export default class Inibase {
         const data = await readFile(filePath, "utf8");
         if (data.includes(targetString)) {
             const updatedContent = data.replaceAll(targetString, replaceString);
-            await writeFile(filePath, updatedContent, "utf8");
+            // File.write fsyncs the replacement so a link-update after a table
+            // rename survives a crash.
+            await File.write(filePath, updatedContent);
         }
     }
     /**
@@ -182,12 +200,35 @@ export default class Inibase {
      */
     async updateTable(tableName, schema, config) {
         this.validateName(tableName);
+        // DDL does not participate in the write-ahead journal: schema surgery
+        // inside a transaction would escape the atomic publish/rollback scope.
+        if (this.transaction)
+            throw this.createError("INVALID_PARAMETERS");
+        await this.ensureDatabaseRecovered();
         if (config?.name)
             this.validateName(config.name);
         const table = await this.getTable(tableName);
         if (!table)
             return;
         const tablePath = join(this.databasePath, tableName);
+        // DDL is serialized with DML writers on the same per-table lock, so a
+        // post/put/delete can never interleave with schema/file surgery.
+        try {
+            await File.lock(join(tablePath, ".tmp"));
+            await this.updateTableLocked(tableName, table, tablePath, schema, config);
+        }
+        finally {
+            await File.unlock(join(tablePath, ".tmp"));
+            // Renaming the table moves its .tmp (and with it the lock file)
+            // to the new directory, so the unlock above only released the old
+            // path. Release the lock at its new location too, or the renamed
+            // table is left with a perpetual live-owner lock no writer can
+            // steal.
+            if (config?.name && config.name !== tableName)
+                await File.unlock(join(join(this.databasePath, config.name), ".tmp"));
+        }
+    }
+    async updateTableLocked(tableName, table, tablePath, schema, config) {
         if (schema) {
             this.validateSchema(schema);
             // remove id from schema
@@ -214,13 +255,15 @@ export default class Inibase {
                         }
                     }));
             }
-            await writeFile(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
+            // Data-bearing schema writes go through File.write so they are
+            // fsynced before updateTable returns.
+            await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
                 ? JSON.stringify(schema, null, 2)
                 : Inison.stringify(schema));
             if (schemaIdFilePath)
                 await rename(schemaIdFilePath, join(tablePath, `${lastSchemaID.value}.schema`));
             else
-                await writeFile(join(tablePath, `${lastSchemaID.value}.schema`), "");
+                await File.write(join(tablePath, `${lastSchemaID.value}.schema`), "");
             // Fields added by this migration have no backing file yet. If the
             // first post after the migration writes such a file from scratch it
             // starts at line 1 and every existing row becomes misaligned (the
@@ -242,26 +285,31 @@ export default class Inibase {
         if (config) {
             if (config.compression !== undefined &&
                 config.compression !== table.config.compression) {
-                await UtilsServer.execFile("find", [
-                    tableName,
-                    "-type",
-                    "f",
-                    "-name",
-                    `*${this.fileExtension}${config.compression ? "" : ".gz"}`,
-                    "-exec",
-                    config.compression ? "gzip" : "gunzip",
-                    "-f",
-                    "{}",
-                    "+",
-                ], { cwd: this.databasePath });
+                // Toggle compression crash-safely: the shell only decompresses
+                // to a temp file (streamed), the publish step fsyncs each temp
+                // before renaming it over the original, then the config marker
+                // is fsynced. A crash mid-toggle leaves valid (uncompressed or
+                // compressed) files, never a truncated one.
+                const toggleFiles = (await readdir(tablePath)).filter((name) => config.compression
+                    ? name.endsWith(this.fileExtension) &&
+                        !name.endsWith(`${this.fileExtension}.gz`)
+                    : name.endsWith(`${this.fileExtension}.gz`));
+                for (const name of toggleFiles) {
+                    const src = join(tablePath, name);
+                    const tmp = `${src}.recompressed`;
+                    const target = config.compression ? `${src}.gz` : src.slice(0, -3); // strip ".gz"
+                    await UtilsServer.exec(`${config.compression ? "gzip" : "gunzip"} -c ${File.escapeShellPath(src)} > ${File.escapeShellPath(tmp)}`);
+                    await File.syncFile(tmp);
+                    await rename(tmp, target);
+                }
                 if (config.compression)
-                    await writeFile(join(tablePath, ".compression.config"), "");
+                    await File.write(join(tablePath, ".compression.config"), "");
                 else
                     await unlink(join(tablePath, ".compression.config"));
             }
             if (config.cache !== undefined && config.cache !== table.config.cache) {
                 if (config.cache)
-                    await writeFile(join(tablePath, ".cache.config"), "");
+                    await File.write(join(tablePath, ".cache.config"), "");
                 else {
                     await this.clearCache(tableName);
                     await unlink(join(tablePath, ".cache.config"));
@@ -270,12 +318,17 @@ export default class Inibase {
             if (config.decodeID !== undefined &&
                 config.decodeID !== table.config.decodeID) {
                 if (config.decodeID)
-                    await writeFile(join(tablePath, ".decodeID.config"), "");
+                    await File.write(join(tablePath, ".decodeID.config"), "");
                 else
                     await unlink(join(tablePath, ".decodeID.config"));
             }
             if (config.prepend !== undefined &&
                 config.prepend !== table.config.prepend) {
+                // Reverse every column file so the "first" row stays first after
+                // toggling prepend. The (streaming) shell only writes `<file>.reversed`
+                // temp files; the publish step below fsyncs each temp before renaming
+                // it into place, so a crash mid-toggle never leaves a half-reversed
+                // live file (the old file stays valid until the rename).
                 await UtilsServer.execFile("find", [
                     tableName,
                     "-type",
@@ -286,24 +339,34 @@ export default class Inibase {
                     "sh",
                     "-c",
                     `for file; do ${config.compression
-                        ? `zcat "$file" | ${process.platform === "darwin" ? "tail -r" : "tac"} | gzip > "$file.reversed" && mv "$file.reversed" "$file"`
-                        : `${process.platform === "darwin" ? "tail -r" : "tac"} "$file" > "$file.reversed" && mv "$file.reversed" "$file"`}; done`,
+                        ? `zcat "$file" | ${process.platform === "darwin" ? "tail -r" : "tac"} | gzip > "$file.reversed"`
+                        : `${process.platform === "darwin" ? "tail -r" : "tac"} "$file" > "$file.reversed"`}; done`,
                     "_",
                     "{}",
                     "+",
                 ], { cwd: this.databasePath });
+                const reversedSuffix = `${this.fileExtension}${config.compression ? ".gz" : ""}.reversed`;
+                for (const fileName of await readdir(tablePath)) {
+                    if (!fileName.endsWith(reversedSuffix))
+                        continue;
+                    const reversedPath = join(tablePath, fileName);
+                    await File.syncFile(reversedPath);
+                    await rename(reversedPath, join(tablePath, fileName.slice(0, -".reversed".length)));
+                }
                 if (config.prepend)
-                    await writeFile(join(tablePath, ".prepend.config"), "");
+                    await File.write(join(tablePath, ".prepend.config"), "");
                 else
                     await unlink(join(tablePath, ".prepend.config"));
             }
             if (config.name) {
                 await rename(tablePath, join(this.databasePath, config.name));
-                // replace table name in other linked tables (relationship)
+                // replace table name in other linked tables (relationship).
+                // glob() returns paths relative to `cwd`, so resolve them
+                // against the database path before touching the files.
                 for await (const schemaPath of glob(`**/schema.${this.schemaFileExtension}`, {
                     cwd: this.databasePath,
                 }))
-                    await this.replaceStringInFile(schemaPath, 
+                    await this.replaceStringInFile(resolve(this.databasePath, schemaPath), 
                     // TODO: escape caracters in table name
                     this.schemaFileExtension === "json"
                         ? `"table": "${tableName}"`
@@ -312,6 +375,10 @@ export default class Inibase {
                         : `table:${config.name}`);
             }
         }
+        // Flush the directory entries touched by this DDL (renames, unlinks,
+        // fresh config markers) before updateTable returns so the schema/config
+        // change survives a crash.
+        await File.syncDir(config?.name ? this.databasePath : tablePath);
         globalConfig[this.databasePath].tables?.delete(tableName);
     }
     /**
@@ -356,10 +423,14 @@ export default class Inibase {
                 otherSchemaFileExtension === "json"
                     ? JSON.parse(schemaFile)
                     : Inison.unstringify(schemaFile);
-            await writeFile(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
+            // Mirror the legacy schema file into the preferred extension and
+            // drop the old one (fsync-backed; this read-path migration must
+            // survive a crash).
+            await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
                 ? JSON.stringify(schema, null, 2)
                 : Inison.stringify(schema));
             await unlink(join(tablePath, `schema.${otherSchemaFileExtension}`));
+            await File.syncDir(tablePath);
         }
         else
             schemaFile = await readFile(join(tablePath, `schema.${this.schemaFileExtension}`), "utf8");
@@ -536,6 +607,8 @@ export default class Inibase {
                         ? value
                         : Number(value.trim())
                     : 0;
+            case "date":
+                return Utils.dateToTimestamp(value);
             case "id":
                 return Utils.isNumber(value)
                     ? value
@@ -842,9 +915,7 @@ export default class Inibase {
                 key: field.key,
                 config: {
                     ...field,
-                    type: field.key === "id" && decodeID
-                        ? "number"
-                        : field.type,
+                    type: field.key === "id" && decodeID ? "number" : field.type,
                     databasePath: this.databasePath,
                 },
             });
@@ -1264,11 +1335,387 @@ export default class Inibase {
         await rm(cacheFolderPath, { recursive: true, force: true });
         await mkdir(cacheFolderPath);
     }
+    /**
+     * Commit a multi-file mutation crash-atomically:
+     * 1. fsync every freshly-written temp file;
+     * 2. write the journal `begin` entry and fsync it;
+     * 3. rename the pagination metadata file first (atomic publication point:
+     *    the row count flips in a single rename, which is what lock-free
+     *    readers observe) and then swap each live file aside (backup) and
+     *    rename the temp into place;
+     * 4. write the journal `commit` marker and fsync it;
+     * 5. discard backups/temps + the journal, fsync the directories.
+     *
+     * On any failure before `commit`, the journal is rolled back so the table
+     * is left exactly as it was. `renameList` entries are [tempPath, livePath]
+     * pairs; a null tempPath means a pure removal (live file taken out).
+     */
+    async commitFiles(tablePath, renameList, pagination) {
+        const txn = randomUUID();
+        const ops = [];
+        // Backups are parked in a per-transaction subdirectory
+        // (.tmp/backup/<txn>/), so a later transaction can never collide with
+        // the leftovers of an earlier crashed one.
+        const backupDir = join(tablePath, ".tmp", "backup", txn);
+        await mkdir(backupDir, { recursive: true });
+        for (const [tmp, live] of renameList) {
+            if (!live)
+                continue;
+            ops.push({
+                live,
+                backup: join(backupDir, basename(live)),
+                tmp,
+                existed: await File.isExists(live),
+            });
+        }
+        const journal = new Journal(tablePath, txn);
+        try {
+            // Make every replacement durable before it can be published.
+            await Promise.allSettled(ops
+                .filter((op) => op.tmp)
+                .map(async (op) => File.syncFile(op.tmp)));
+            await journal.begin(ops, pagination);
+            // Publish: the pagination rename is the atomic publication point
+            // (row count flips in one rename) and MUST come first — readers
+            // that snapshot file identities detect the flip and retry. Then
+            // park each original and move the replacement in.
+            if (pagination)
+                await rename(pagination.from, pagination.to);
+            for (const op of ops) {
+                if (op.existed)
+                    await rename(op.live, op.backup);
+                if (op.tmp)
+                    await rename(op.tmp, op.live);
+            }
+            await journal.commit();
+        }
+        catch (error) {
+            await journal.rollback().catch(() => { });
+            throw error;
+        }
+        finally {
+            await Promise.allSettled(ops.map((op) => unlink(op.backup).catch(() => { })));
+            await rm(backupDir, { recursive: true, force: true }).catch(() => { });
+            await journal.dispose();
+            await unlink(journal.path).catch(() => { });
+            // Make the renames durable before acknowledging the commit.
+            await File.syncDir(join(tablePath, ".tmp"));
+            await File.syncDir(tablePath);
+        }
+    }
+    /**
+     * Runs crash recovery for a table (and any crashed database transaction)
+     * before a read. Mutation paths get the same guarantee implicitly (the
+     * writer lock runs recovery on acquire); reads call this explicitly
+     * because they never take the table lock.
+     */
+    async ensureTableRecovered(tableName) {
+        const tablePath = join(this.databasePath, tableName);
+        if (await File.isExists(join(tablePath, ".tmp", "journal.jsonl"))) {
+            await File.lock(join(tablePath, ".tmp"));
+            await File.unlock(join(tablePath, ".tmp"));
+        }
+        // A database journal exists only while a live transaction holds the
+        // database lock, or after one crashed. Recovery must never roll back a
+        // live transaction, so acquire the database lock non-blocking here:
+        // on success the previous owner is gone (recovery ran); on failure a
+        // live transaction owns the lock across processes and readers simply
+        // proceed against the committed state.
+        const dbTmp = join(this.databasePath, ".tmp");
+        if (await File.isExists(join(dbTmp, "journal.jsonl"))) {
+            if (await File.tryLock(dbTmp))
+                await File.unlock(dbTmp);
+        }
+    }
+    /**
+     * Blocking database-journal recovery, used by mutation paths (writers are
+     * serialized with live transactions on the database lock anyway).
+     */
+    async ensureDatabaseRecovered() {
+        const dbTmp = join(this.databasePath, ".tmp");
+        if (await File.isExists(join(dbTmp, "journal.jsonl"))) {
+            await File.lock(dbTmp);
+            await File.unlock(dbTmp);
+        }
+    }
+    async ensureDatabaseTmpDir() {
+        await mkdir(join(this.databasePath, ".tmp"), { recursive: true });
+    }
+    /** Staged per-table entry of the open transaction, or null when none. */
+    txnTableEntry(tableName) {
+        const txn = this.transaction;
+        if (!txn)
+            return null;
+        let entry = txn.tables.get(tableName);
+        if (!entry) {
+            entry = {
+                locked: false,
+                paginationFrom: "",
+                lastId: 0,
+                total: 0,
+                staged: [],
+            };
+            txn.tables.set(tableName, entry);
+        }
+        return entry;
+    }
+    /** Lock a table for the open transaction (idempotent per transaction). */
+    async ensureTxnLock(tableName) {
+        const entry = this.txnTableEntry(tableName);
+        if (!entry || entry.locked)
+            return;
+        await File.lock(join(this.databasePath, tableName, ".tmp"));
+        entry.locked = true;
+    }
+    /**
+     * Resolve the pagination state a DML op should build on. Outside a
+     * transaction this reads the live pagination file (as before); inside a
+     * transaction the first touch reads it once and the entry keeps the staged
+     * id/count so chained ops (guarded to one per table) and commit() stay
+     * consistent without publishing anything early.
+     */
+    async resolvePagination(tableName) {
+        const tablePath = join(this.databasePath, tableName);
+        const entry = this.txnTableEntry(tableName);
+        if (entry?.paginationFrom) {
+            return {
+                filePath: entry.paginationFrom,
+                lastId: entry.lastId,
+                total: entry.total,
+            };
+        }
+        let paginationFilePath = "";
+        for await (const fileName of glob("*.pagination", { cwd: tablePath }))
+            paginationFilePath = join(tablePath, fileName);
+        const [lastId, total] = parse(paginationFilePath)
+            .name.split("-")
+            .map(Number);
+        if (entry) {
+            entry.paginationFrom = paginationFilePath;
+            entry.lastId = lastId;
+            entry.total = total;
+        }
+        return { filePath: paginationFilePath, lastId, total };
+    }
+    /**
+     * Stage one table mutation into the open transaction: fsync its temps and
+     * append an `op` entry to the database journal (no live file is touched;
+     * commit() performs the actual renames). One staged mutation per table per
+     * transaction (multi-table atomicity; a second touch of the same table
+     * would need read-your-writes composition).
+     */
+    async stageTxnOp(tableName, renameList, pagination) {
+        const txn = this.transaction;
+        const entry = this.txnTableEntry(tableName);
+        if (!txn || !entry)
+            throw this.createError("INVALID_PARAMETERS");
+        if (entry.staged.length)
+            throw this.createError("INVALID_PARAMETERS");
+        const backupDir = join(this.databasePath, ".tmp", "backup", txn.id);
+        await mkdir(backupDir, { recursive: true });
+        const ops = [];
+        for (const [tmp, live] of renameList) {
+            if (!live)
+                continue;
+            // Benchmarks must be unique within the whole transaction: the same
+            // column basename can exist in several tables, and rollback
+            // restores by path. Namespace per table (one staged op per table).
+            ops.push({
+                live,
+                backup: join(backupDir, `${entry.staged.length}-${tableName}-${basename(live)}`),
+                tmp,
+                existed: await File.isExists(live),
+            });
+        }
+        // Make every replacement durable before the journal records intent.
+        await Promise.allSettled(ops
+            .filter((op) => op.tmp)
+            .map(async (op) => File.syncFile(op.tmp)));
+        await txn.journal.op(ops, pagination);
+        entry.staged.push({ ops, pagination });
+        if (pagination)
+            entry.paginationFrom = pagination.to;
+    }
+    /**
+     * Begin a database transaction. Mutations issued while the transaction is
+     * open (post/put/delete, including cascade deletes) are staged into the
+     * database journal and published atomically at commit(); rollback()
+     * discards them without touching any live file.
+     *
+     * @param tables Optional table names to pre-lock at begin() in sorted
+     * order (the deadlock-free way to span tables). Tables not listed are
+     * locked on first touch, in first-touch order.
+     */
+    async begin(tables = []) {
+        if (this.transaction)
+            throw this.createError("INVALID_PARAMETERS");
+        await this.ensureDatabaseTmpDir();
+        // The database lock is the transaction mutex: it serializes
+        // transactions and its acquisition runs crash recovery on any journal
+        // left behind by a crashed transaction.
+        await File.lock(join(this.databasePath, ".tmp"));
+        const uniqueTables = [...new Set(tables)].sort();
+        const acquired = [];
+        try {
+            // Validate every listed table before locking anything.
+            for (const name of uniqueTables) {
+                this.validateName(name);
+                await this.getTable(name); // throws TABLE_NOT_EXISTS
+            }
+            const id = randomUUID();
+            this.transaction = {
+                id,
+                journal: new DatabaseJournal(this.databasePath, id),
+                tables: new Map(),
+            };
+            await this.transaction.journal.begin(uniqueTables);
+            for (const name of uniqueTables) {
+                await File.lock(join(this.databasePath, name, ".tmp"));
+                acquired.push(name);
+                this.transaction.tables.set(name, {
+                    locked: true,
+                    paginationFrom: "",
+                    lastId: 0,
+                    total: 0,
+                    staged: [],
+                });
+            }
+        }
+        catch (error) {
+            // Release only the table locks this process actually took (an
+            // unlock of a never-acquired path could unlink another process's
+            // lock file).
+            for (const name of acquired)
+                await File.unlock(join(this.databasePath, name, ".tmp")).catch(() => { });
+            this.transaction = null;
+            await File.unlock(join(this.databasePath, ".tmp")).catch(() => { });
+            throw error;
+        }
+    }
+    /**
+     * Publish every staged mutation atomically: per table (sorted), the
+     * pagination rename comes first (the atomic publication point readers
+     * observe) and then live->backup + tmp->live swaps, before a single fsynced
+     * `commit` marker makes the whole transaction durable. A crash at any
+     * point is recovered by the journal rule (no marker -> roll back all
+     * tables, marker -> roll forward all tables).
+     */
+    async commit() {
+        const txn = this.transaction;
+        if (!txn)
+            throw this.createError("INVALID_PARAMETERS");
+        try {
+            for (const tableName of [...txn.tables.keys()].sort()) {
+                const entry = txn.tables.get(tableName);
+                if (!entry)
+                    continue;
+                for (const { ops, pagination } of entry.staged) {
+                    if (pagination)
+                        await rename(pagination.from, pagination.to);
+                    for (const op of ops) {
+                        if (op.existed)
+                            await rename(op.live, op.backup);
+                        if (op.tmp)
+                            await rename(op.tmp, op.live);
+                    }
+                }
+            }
+            await txn.journal.commit();
+            // Clean the fast-path leftovers; recovery owns any crash leftovers.
+            await txn.journal.dispose();
+            await unlink(txn.journal.path).catch(() => { });
+            await rm(join(this.databasePath, ".tmp", "backup", txn.id), {
+                recursive: true,
+                force: true,
+            }).catch(() => { });
+            await File.syncDir(join(this.databasePath, ".tmp"));
+            await File.syncDir(this.databasePath);
+            for (const tableName of txn.tables.keys()) {
+                await File.syncDir(join(this.databasePath, tableName));
+                await File.syncDir(join(this.databasePath, tableName, ".tmp"));
+            }
+        }
+        catch (error) {
+            await txn.journal.rollback().catch(() => { });
+            throw error;
+        }
+        finally {
+            for (const tableName of [...txn.tables.keys()].sort().reverse())
+                await File.unlock(join(this.databasePath, tableName, ".tmp"));
+            await File.unlock(join(this.databasePath, ".tmp"));
+            this.transaction = null;
+        }
+    }
+    /**
+     * Discard the open transaction: temps and the journal are removed and no
+     * live file is touched (nothing is published before commit()).
+     */
+    async rollback() {
+        const txn = this.transaction;
+        if (!txn)
+            throw this.createError("INVALID_PARAMETERS");
+        try {
+            await txn.journal.rollback().catch(() => { });
+        }
+        finally {
+            for (const tableName of [...txn.tables.keys()].sort().reverse())
+                await File.unlock(join(this.databasePath, tableName, ".tmp"));
+            await File.unlock(join(this.databasePath, ".tmp"));
+            this.transaction = null;
+        }
+    }
+    /**
+     * Snapshot the identity (dev:inode:mtime:size) of every column file and
+     * the pagination file. Reading data and then re-verifying this snapshot
+     * lets lock-free readers detect an in-flight writer commit and retry
+     * instead of returning a torn row set.
+     */
+    async snapshotTableFiles(tableName) {
+        const tablePath = join(this.databasePath, tableName);
+        const extension = this.getFileExtension(tableName);
+        const snapshot = new Map();
+        for (const fileName of await readdir(tablePath).catch(() => [])) {
+            if (!fileName.endsWith(extension) && !fileName.endsWith(".pagination"))
+                continue;
+            const filePath = join(tablePath, fileName);
+            const fileStat = await stat(filePath).catch(() => null);
+            if (fileStat)
+                snapshot.set(filePath, `${fileStat.dev}:${fileStat.ino}:${fileStat.mtimeMs}:${fileStat.size}`);
+        }
+        return snapshot;
+    }
+    /** True when every snapshotted file is still present and unchanged. */
+    async verifyTableFiles(snapshot) {
+        for (const [filePath, identity] of snapshot) {
+            const fileStat = await stat(filePath).catch(() => null);
+            if (!fileStat ||
+                `${fileStat.dev}:${fileStat.ino}:${fileStat.mtimeMs}:${fileStat.size}` !==
+                    identity)
+                return false;
+        }
+        return true;
+    }
     async get(tableName, where, options = {
         page: 1,
         perPage: 15,
     }, onlyOne, onlyLinesNumbers, _whereIsLinesNumbers) {
         this.validateName(tableName);
+        await this.ensureTableRecovered(tableName);
+        // Lock-free reads with optimistic retry: snapshot the identity of every
+        // column + pagination file, run the read, then verify nothing changed
+        // mid-scan. A writer commit flips at least one file identity, so a torn
+        // read is detected and re-run instead of being returned.
+        for (let attempt = 0;; attempt++) {
+            const snapshot = await this.snapshotTableFiles(tableName);
+            const result = await this.getOnce(tableName, where, options, onlyOne, onlyLinesNumbers, _whereIsLinesNumbers);
+            if (attempt === 2 || (await this.verifyTableFiles(snapshot)))
+                return result;
+        }
+    }
+    async getOnce(tableName, where, options = {
+        page: 1,
+        perPage: 15,
+    }, onlyOne, onlyLinesNumbers, _whereIsLinesNumbers) {
         const tablePath = join(this.databasePath, tableName);
         // Ensure options.columns is an array
         if (options.columns) {
@@ -1316,9 +1763,11 @@ export default class Inibase {
                     .concat(options.sort)
                     .map((column) => [column, true]);
             let cacheKey = "";
-            // Criteria
+            // Criteria. The sort cache is versioned by the pagination row count
+            // (see the criteria-cache note) so stale sorted line numbers from
+            // before a post/delete are never replayed.
             if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
-                cacheKey = UtilsServer.hashString(inspect(sortArray, { sorted: true }));
+                cacheKey = UtilsServer.hashString(inspect([sortArray, pagination[1]], { sorted: true }));
             if (where) {
                 const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
                 if (!lineNumbers?.length)
@@ -1326,16 +1775,15 @@ export default class Inibase {
                 const itemsIDs = Object.values((await File.get(join(tablePath, `id${this.getFileExtension(tableName)}`), lineNumbers, { key: "BLABLA", type: "number" })) ?? {}).map(Number);
                 awkCommand = `awk '${itemsIDs.map((id) => `$1 == ${id}`).join(" || ")}'`;
             }
+            // perPage < 0 means "no limit": select every line instead of
+            // generating an empty awk window (with perPage -1 the old code
+            // produced `awk ''`, which prints nothing and the empty stdout
+            // decoded into a single hollow row).
             else
-                // perPage < 0 means "no limit": select every line instead of
-                // generating an empty awk window (with perPage -1 the old code
-                // produced `awk ''`, which prints nothing and the empty stdout
-                // decoded into a single hollow row).
                 awkCommand =
                     options.perPage < 0
                         ? "awk '1'"
-                        : `awk '${Array.from({ length: options.perPage }, (_, index) => (options.page - 1) *
-                            options.perPage +
+                        : `awk '${Array.from({ length: options.perPage }, (_, index) => (options.page - 1) * options.perPage +
                             index +
                             1)
                             .map((lineNumber) => `NR==${lineNumber}`)
@@ -1455,8 +1903,7 @@ export default class Inibase {
             let countItems = 0;
             const isDecodeID = globalConfig[this.databasePath].tables?.get(tableName)?.config
                 .decodeID === true &&
-                !globalConfig[this.databasePath].tables?.get(tableName)?.config
-                    .prepend;
+                !globalConfig[this.databasePath].tables?.get(tableName)?.config.prepend;
             if (isDecodeID &&
                 this.idDensity.get(tableName) &&
                 Ids.every(Utils.isNumber)) {
@@ -1509,7 +1956,11 @@ export default class Inibase {
             let cachedFilePath = "";
             // Criteria
             if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache) {
-                cachedFilePath = join(tablePath, ".cache", `${UtilsServer.hashString(inspect(where, { sorted: true }))}${this.fileExtension}`);
+                // Cache entries are versioned by the pagination row count so a
+                // stale cache written before a post/delete (in this process or
+                // another) is detectable: the candidate filename simply stops
+                // matching and the cache is rebuilt.
+                cachedFilePath = join(tablePath, ".cache", `${UtilsServer.hashString(inspect(where, { sorted: true }))}-${pagination[1]}${this.fileExtension}`);
                 if (await File.isExists(cachedFilePath)) {
                     const cachedItems = (await readFile(cachedFilePath, "utf8")).split(",");
                     if (!this.totalItems.has(`${tableName}-*`))
@@ -1573,33 +2024,37 @@ export default class Inibase {
                 ? options.columns
                 : [options.columns]));
         const tablePath = join(this.databasePath, tableName);
+        if (!this.transaction)
+            await this.ensureDatabaseRecovered();
         await this.getTable(tableName);
         if (!globalConfig[this.databasePath].tables?.get(tableName)?.schema)
             throw this.createError("NO_SCHEMA", tableName);
         if (!returnPostedData)
             returnPostedData = false;
         let clonedData = structuredClone(data);
-        const keys = UtilsServer.hashString(Object.keys(Array.isArray(clonedData) ? clonedData[0] : clonedData).join("."));
         await this.validateTableData(tableName, clonedData);
         const renameList = [];
+        let txnStaged = false;
         try {
-            await File.lock(join(tablePath, ".tmp"), keys);
-            let paginationFilePath = "";
-            for await (const fileName of glob("*.pagination", { cwd: tablePath }))
-                paginationFilePath = join(tablePath, fileName);
-            let [lastId, _totalItems] = parse(paginationFilePath)
-                .name.split("-")
-                .map(Number);
-            this.totalItems.set(`${tableName}-*`, _totalItems);
+            // Inside a transaction the table lock is taken once per txn (and
+            // held until commit/rollback); otherwise the usual writer lock.
+            if (this.transaction)
+                await this.ensureTxnLock(tableName);
+            else
+                await File.lock(join(tablePath, ".tmp"));
+            const { filePath: paginationFilePath, lastId, total: _totalItems, } = await this.resolvePagination(tableName);
+            let lastIdValue = lastId;
+            if (!this.transaction)
+                this.totalItems.set(`${tableName}-*`, _totalItems);
             if (Utils.isArrayOfObjects(clonedData))
                 for (let index = 0; index < clonedData.length; index++) {
                     const element = clonedData[index];
-                    element.id = ++lastId;
+                    element.id = ++lastIdValue;
                     element.createdAt = Date.now();
                     element.updatedAt = undefined;
                 }
             else {
-                clonedData.id = ++lastId;
+                clonedData.id = ++lastIdValue;
                 clonedData.createdAt = Date.now();
                 clonedData.updatedAt = undefined;
             }
@@ -1613,15 +2068,34 @@ export default class Inibase {
                 .prepend
                 ? await File.prepend(path, content)
                 : await File.append(path, content))));
-            await Promise.allSettled(renameList
-                .filter((pair) => Boolean(pair[1]))
-                .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
-            if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
-                await this.clearCache(tableName);
-            const currentValue = this.totalItems.get(`${tableName}-*`) || 0;
-            this.totalItems.set(`${tableName}-*`, currentValue + (Array.isArray(data) ? data.length : 1));
-            await rename(paginationFilePath, join(tablePath, `${lastId}-${this.totalItems.get(`${tableName}-*`)}.pagination`));
-            if (returnPostedData)
+            const newTotal = _totalItems + (Array.isArray(data) ? data.length : 1);
+            const pagination = {
+                from: paginationFilePath,
+                to: join(tablePath, `${lastIdValue}-${newTotal}.pagination`),
+            };
+            if (this.transaction) {
+                // Stage: journal the intent (fsynced op entry); the live files
+                // only change when commit() publishes.
+                await this.stageTxnOp(tableName, renameList, pagination);
+                txnStaged = true;
+                const stagedEntry = this.txnTableEntry(tableName);
+                if (stagedEntry) {
+                    stagedEntry.lastId = lastIdValue;
+                    stagedEntry.total = newTotal;
+                }
+            }
+            else {
+                // Crash-atomic commit: journal + backup swap + pagination rename.
+                await this.commitFiles(tablePath, renameList, pagination);
+                this.totalItems.set(`${tableName}-*`, newTotal);
+                if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                    await this.clearCache(tableName);
+            }
+            if (returnPostedData) {
+                if (this.transaction)
+                    // No read-your-writes yet: return the formatted staged rows
+                    // (ids + defaults) instead of a committed-state read.
+                    return (Array.isArray(clonedData) ? clonedData : clonedData);
                 return this.get(tableName, globalConfig[this.databasePath].tables?.get(tableName)?.config.prepend
                     ? Array.isArray(clonedData)
                         ? clonedData.map((_, index) => index + 1).toReversed()
@@ -1632,6 +2106,7 @@ export default class Inibase {
                             .toReversed()
                         : this.totalItems.get(`${tableName}-*`), options, !Utils.isArrayOfObjects(clonedData), // return only one item if data is not array of objects
                 undefined, true);
+            }
             return Array.isArray(clonedData)
                 ? (globalConfig[this.databasePath].tables?.get(tableName)?.config
                     .prepend
@@ -1640,11 +2115,22 @@ export default class Inibase {
                 : UtilsServer.encodeID(clonedData.id);
         }
         finally {
-            if (renameList.length)
-                await Promise.allSettled(renameList
-                    .filter((pair) => Boolean(pair[1]))
-                    .map(async ([tempPath, _]) => unlink(tempPath)));
-            await File.unlock(join(tablePath, ".tmp"), keys);
+            if (this.transaction) {
+                // Staged temps belong to the journal op; commit()/rollback()
+                // owns them. Temps from a failed pre-stage attempt are cleaned
+                // here so nothing leaks.
+                if (!txnStaged && renameList.length)
+                    await Promise.allSettled(renameList
+                        .filter((pair) => Boolean(pair[1]))
+                        .map(async ([tempPath, _]) => unlink(tempPath)));
+            }
+            else {
+                if (renameList.length)
+                    await Promise.allSettled(renameList
+                        .filter((pair) => Boolean(pair[1]))
+                        .map(async ([tempPath, _]) => unlink(tempPath)));
+                await File.unlock(join(tablePath, ".tmp"));
+            }
         }
     }
     async put(tableName, data, where, options = {
@@ -1652,12 +2138,15 @@ export default class Inibase {
         perPage: 15,
     }, returnUpdatedData, _whereIsLinesNumbers) {
         const renameList = [];
+        let txnStaged = false;
         this.validateName(tableName);
         if (options.columns)
             this.validateColumns((Array.isArray(options.columns)
                 ? options.columns
                 : [options.columns]));
         const tablePath = join(this.databasePath, tableName);
+        if (!this.transaction)
+            await this.ensureDatabaseRecovered();
         await this.throwErrorIfTableEmpty(tableName);
         let clonedData = structuredClone(data);
         if (!where) {
@@ -1680,26 +2169,48 @@ export default class Inibase {
                 updatedAt: Date.now(),
             });
             try {
-                await File.lock(join(tablePath, ".tmp"));
-                for await (const paginationFileName of glob("*.pagination", {
-                    cwd: tablePath,
-                }))
-                    this.totalItems.set(`${tableName}-*`, parse(paginationFileName).name.split("-").map(Number)[1]);
-                await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content, this.totalItems.get(`${tableName}-*`)))));
-                await Promise.allSettled(renameList
-                    .filter((pair) => Boolean(pair[1]))
-                    .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
-                if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
-                    await this.clearCache(join(tablePath, ".cache"));
-                if (returnUpdatedData)
+                if (this.transaction)
+                    await this.ensureTxnLock(tableName);
+                else
+                    await File.lock(join(tablePath, ".tmp"));
+                const { total } = await this.resolvePagination(tableName);
+                await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content, total))));
+                if (this.transaction) {
+                    // Stage instead of publishing: row count is unchanged so
+                    // there is no pagination rename to journal.
+                    await this.stageTxnOp(tableName, renameList, null);
+                    txnStaged = true;
+                }
+                else {
+                    // Crash-atomic commit (row count unchanged -> no pagination rename).
+                    await this.commitFiles(tablePath, renameList, null);
+                    if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                        await this.clearCache(tableName);
+                }
+                if (returnUpdatedData) {
+                    if (this.transaction)
+                        // Reading the committed state would miss the staged
+                        // write (no read-your-writes yet).
+                        throw this.createError("INVALID_PARAMETERS");
                     return await this.get(tableName, undefined, options);
+                }
             }
             finally {
-                if (renameList.length)
-                    await Promise.allSettled(renameList
-                        .filter((pair) => Boolean(pair[1]))
-                        .map(async ([tempPath, _]) => unlink(tempPath)));
-                await File.unlock(join(tablePath, ".tmp"));
+                if (this.transaction) {
+                    // Staged temps belong to the journal op; commit()/rollback()
+                    // owns them.
+                    if (!txnStaged && renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                }
+                else {
+                    if (renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                    await File.unlock(join(tablePath, ".tmp"));
+                }
             }
         }
         else if (((Array.isArray(where) && where.every(Utils.isNumber)) ||
@@ -1722,26 +2233,43 @@ export default class Inibase {
                     return obj;
                 }, {}),
             ]));
-            const keys = UtilsServer.hashString(Object.keys(pathesContents)
-                .map((path) => path.replaceAll(this.getFileExtension(tableName), ""))
-                .join("."));
             try {
-                await File.lock(join(tablePath, ".tmp"), keys);
+                // One global lock per table serializes every writer; inside a
+                // transaction the lock is held for the whole txn.
+                if (this.transaction)
+                    await this.ensureTxnLock(tableName);
+                else
+                    await File.lock(join(tablePath, ".tmp"));
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content))));
-                await Promise.allSettled(renameList
-                    .filter((pair) => Boolean(pair[1]))
-                    .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
-                if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
-                    await this.clearCache(tableName);
-                if (returnUpdatedData)
+                if (this.transaction) {
+                    await this.stageTxnOp(tableName, renameList, null);
+                    txnStaged = true;
+                }
+                else {
+                    await this.commitFiles(tablePath, renameList, null);
+                    if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                        await this.clearCache(tableName);
+                }
+                if (returnUpdatedData) {
+                    if (this.transaction)
+                        throw this.createError("INVALID_PARAMETERS");
                     return this.get(tableName, where, options, !Array.isArray(where), undefined, true);
+                }
             }
             finally {
-                if (renameList.length)
-                    await Promise.allSettled(renameList
-                        .filter((pair) => Boolean(pair[1]))
-                        .map(async ([tempPath, _]) => unlink(tempPath)));
-                await File.unlock(join(tablePath, ".tmp"), keys);
+                if (this.transaction) {
+                    if (!txnStaged && renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                }
+                else {
+                    if (renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                    await File.unlock(join(tablePath, ".tmp"));
+                }
             }
         }
         else if ((!_whereIsLinesNumbers &&
@@ -1779,37 +2307,63 @@ export default class Inibase {
      */
     async delete(tableName, where, _whereIsLinesNumbers, _cascadeGuard) {
         this.validateName(tableName);
+        if (!this.transaction)
+            await this.ensureDatabaseRecovered();
         const tablePath = join(this.databasePath, tableName);
         await this.throwErrorIfTableEmpty(tableName);
         if (!where) {
+            let txnStaged = false;
+            // Crash-atomic truncate: park every column file (pure removal
+            // ops) and publish the empty row count in one journaled commit.
+            const renameList = [];
             try {
-                await File.lock(join(tablePath, ".tmp"));
-                let paginationFilePath = "";
-                let pagination = [0, 0];
-                for await (const paginationFileName of glob("*.pagination", {
-                    cwd: tablePath,
-                })) {
-                    paginationFilePath = join(tablePath, paginationFileName);
-                    pagination = parse(paginationFileName)
-                        .name.split("-")
-                        .map(Number);
+                if (this.transaction)
+                    await this.ensureTxnLock(tableName);
+                else
+                    await File.lock(join(tablePath, ".tmp"));
+                const files = (await readdir(tablePath)) ?? [];
+                renameList.push(...files
+                    .filter((fileName) => fileName.endsWith(this.getFileExtension(tableName)))
+                    .map((file) => [null, join(tablePath, file)]));
+                const { filePath: paginationFilePath, lastId, total, } = await this.resolvePagination(tableName);
+                const pagination = {
+                    from: paginationFilePath,
+                    to: join(tablePath, `${lastId}-0.pagination`),
+                };
+                if (this.transaction) {
+                    await this.stageTxnOp(tableName, renameList, pagination);
+                    txnStaged = true;
+                    const stagedEntry = this.txnTableEntry(tableName);
+                    if (stagedEntry)
+                        stagedEntry.total = 0;
+                }
+                else {
+                    await this.commitFiles(tablePath, renameList, pagination);
+                    if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                        await this.clearCache(tableName);
                 }
-                await Promise.allSettled((await readdir(tablePath))
-                    ?.filter((fileName) => fileName.endsWith(this.getFileExtension(tableName)))
-                    .map(async (file) => unlink(join(tablePath, file))));
-                if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
-                    await this.clearCache(tableName);
-                await rename(paginationFilePath, join(tablePath, `${pagination[0]}-0.pagination`));
                 this.idDensity.set(tableName, true);
                 // Deleting every row must also delete rows that reference them.
-                if (pagination[1]) {
-                    const allLines = Array.from({ length: pagination[1] }, (_, i) => i + 1);
+                if (total) {
+                    const allLines = Array.from({ length: total }, (_, i) => i + 1);
                     await this.cascadeDelete(tableName, allLines, new Set());
                 }
                 return true;
             }
             finally {
-                await File.unlock(join(tablePath, ".tmp"));
+                if (this.transaction) {
+                    if (!txnStaged && renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                }
+                else {
+                    if (renameList.length)
+                        await Promise.allSettled(renameList
+                            .filter((pair) => Boolean(pair[1]))
+                            .map(async ([tempPath, _]) => unlink(tempPath)));
+                    await File.unlock(join(tablePath, ".tmp"));
+                }
             }
         }
         if (((Array.isArray(where) && where.every(Utils.isNumber)) ||
@@ -1821,46 +2375,77 @@ export default class Inibase {
             const files = (await readdir(tablePath))?.filter((fileName) => fileName.endsWith(this.getFileExtension(tableName)));
             if (files.length) {
                 const renameList = [];
+                let txnStaged = false;
                 try {
-                    await File.lock(join(tablePath, ".tmp"));
-                    let paginationFilePath = "";
-                    let pagination = [0, 0];
-                    for await (const paginationFileName of glob("*.pagination", {
-                        cwd: tablePath,
-                    })) {
-                        paginationFilePath = join(tablePath, paginationFileName);
-                        pagination = parse(paginationFileName)
-                            .name.split("-")
-                            .map(Number);
-                    }
-                    if (pagination[1] &&
-                        pagination[1] - (Array.isArray(where) ? where.length : 1) > 0) {
+                    if (this.transaction)
+                        await this.ensureTxnLock(tableName);
+                    else
+                        await File.lock(join(tablePath, ".tmp"));
+                    const { filePath: paginationFilePath, lastId, total, } = await this.resolvePagination(tableName);
+                    const remaining = total - (Array.isArray(where) ? where.length : 1);
+                    if (total && remaining > 0) {
                         this.idDensity.set(tableName, false);
                         await Promise.allSettled(files.map(async (file) => renameList.push(await File.remove(join(tablePath, file), where))));
-                        await Promise.allSettled(renameList
-                            .filter((pair) => Boolean(pair[1]))
-                            .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
+                        const pagination = {
+                            from: paginationFilePath,
+                            to: join(tablePath, `${lastId}-${remaining}.pagination`),
+                        };
+                        if (this.transaction) {
+                            await this.stageTxnOp(tableName, renameList, pagination);
+                            txnStaged = true;
+                            const stagedEntry = this.txnTableEntry(tableName);
+                            if (stagedEntry)
+                                stagedEntry.total = remaining;
+                        }
+                        else {
+                            await this.commitFiles(tablePath, renameList, pagination);
+                        }
                     }
                     else {
                         this.idDensity.set(tableName, true);
-                        await Promise.allSettled((await readdir(tablePath))
+                        // Deleting every remaining row: pure removals.
+                        const truncateList = (await readdir(tablePath))
                             ?.filter((fileName) => fileName.endsWith(this.getFileExtension(tableName)))
-                            .map(async (file) => unlink(join(tablePath, file))));
+                            .map((file) => [null, join(tablePath, file)]);
+                        const pagination = {
+                            from: paginationFilePath,
+                            to: join(tablePath, `${lastId}-0.pagination`),
+                        };
+                        if (this.transaction) {
+                            await this.stageTxnOp(tableName, truncateList, pagination);
+                            txnStaged = true;
+                            const stagedEntry = this.txnTableEntry(tableName);
+                            if (stagedEntry)
+                                stagedEntry.total = 0;
+                        }
+                        else {
+                            await this.commitFiles(tablePath, truncateList, pagination);
+                        }
                     }
-                    if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                    // Cache still describes the committed state while a
+                    // transaction is open, so only clear it outside one.
+                    if (!this.transaction &&
+                        globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                         await this.clearCache(tableName);
-                    await rename(paginationFilePath, join(tablePath, `${pagination[0]}-${pagination[1] - (Array.isArray(where) ? where.length : 1)}.pagination`));
                     // Cascade: rows in other tables referencing the deleted rows
                     // (via `table`-typed fields) are removed too.
                     await this.cascadeDelete(tableName, Array.isArray(where) ? where : [where], _cascadeGuard ?? new Set());
                     return true;
                 }
                 finally {
-                    if (renameList.length)
-                        await Promise.allSettled(renameList
-                            .filter((pair) => Boolean(pair[1]))
-                            .map(async ([tempPath, _]) => unlink(tempPath)));
-                    await File.unlock(join(tablePath, ".tmp"));
+                    if (this.transaction) {
+                        if (!txnStaged && renameList.length)
+                            await Promise.allSettled(renameList
+                                .filter((pair) => Boolean(pair[1]))
+                                .map(async ([tempPath, _]) => unlink(tempPath)));
+                    }
+                    else {
+                        if (renameList.length)
+                            await Promise.allSettled(renameList
+                                .filter((pair) => Boolean(pair[1]))
+                                .map(async ([tempPath, _]) => unlink(tempPath)));
+                        await File.unlock(join(tablePath, ".tmp"));
+                    }
                 }
             }
         }
@@ -1930,8 +2515,12 @@ export default class Inibase {
                             for (const l of found)
                                 matching.add(l);
                     }
-                    catch {
+                    catch (error) {
                         // Unreadable/unsupported column -> skip this reference.
+                        // Inside a transaction a broken reference must abort the
+                        // whole cascade (all-or-nothing).
+                        if (this.transaction)
+                            throw error;
                     }
                 }
                 const toDelete = [...matching].filter((line) => {
@@ -1946,8 +2535,12 @@ export default class Inibase {
                 try {
                     await this.delete(candidateName, toDelete, true, guard);
                 }
-                catch {
-                    // Cascade is best-effort: never break the parent delete.
+                catch (error) {
+                    // Cascade is best-effort outside a transaction: never break
+                    // the parent delete. Inside a transaction a cascade failure
+                    // must abort the whole txn (all-or-nothing).
+                    if (this.transaction)
+                        throw error;
                 }
             }
         }
@@ -1976,6 +2569,30 @@ export default class Inibase {
         }
         return columns.length > 1 ? RETURN : Object.values(RETURN)[0];
     }
+    async avg(tableName, columns, where) {
+        this.validateName(tableName);
+        if (!Array.isArray(columns))
+            columns = [columns];
+        for (const column of columns)
+            this.validateName(column);
+        await this.throwErrorIfTableEmpty(tableName);
+        const RETURN = {};
+        const tablePath = join(this.databasePath, tableName);
+        for await (const column of columns) {
+            const columnPath = join(tablePath, `${column}${this.getFileExtension(tableName)}`);
+            if (await File.isExists(columnPath)) {
+                if (where) {
+                    const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
+                    RETURN[column] = lineNumbers
+                        ? await File.avg(columnPath, lineNumbers)
+                        : 0;
+                }
+                else
+                    RETURN[column] = await File.avg(columnPath);
+            }
+        }
+        return columns.length > 1 ? RETURN : Object.values(RETURN)[0];
+    }
     async max(tableName, columns, where) {
         this.validateName(tableName);
         if (!Array.isArray(columns))