inibase 2.0.1 → 3.1.0

package/dist/index.js

@@ -1,11 +1,13 @@
 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 { buildFieldIndex, collectFieldDeps, parseExpression, resolveExpression, resolveFramePath, topoSortComputedFields, } from "./expression.js";
 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 = [
@@ -22,6 +24,15 @@ export const ERROR_CODES = [
     "TABLE_NOT_EXISTS",
     "INVALID_REGEX_MATCH",
     "INVALID_NAME",
+    "COMPUTED_FIELD_SYNTAX",
+    "COMPUTED_FIELD_UNKNOWN_FIELD",
+    "COMPUTED_FIELD_INVALID_LINK",
+    "COMPUTED_FIELD_INVALID_TARGET",
+    "COMPUTED_FIELD_CONFLICT",
+    "COMPUTED_FIELD_CYCLE",
+    "COMPUTED_FIELD_SETTABLE",
+    "COMPUTED_FIELD_DANGLING_LINK",
+    "COMPUTED_FIELD_ARITHMETIC",
 ];
 // hide ExperimentalWarning glob()
 // Guard against non-Node environments (e.g. accidental import in a browser bundle)
@@ -30,6 +41,75 @@ if (typeof process !== "undefined" &&
     process.removeAllListeners("warning");
 }
 export const globalConfig = {};
+/**
+ * Batch-scoped link-hop reader for computed-field evaluation: a dry pass
+ * records every (table, column, id) triple the expressions need, each
+ * distinct triple is resolved exactly once by the engine's `readLinkedRow`
+ * (deduplicated across rows and fields of the batch), and subsequent passes
+ * are served from a warm per-(table, column) cache.
+ */
+class LinkedRowReader {
+    readRow;
+    pending = new Map();
+    cache = new Map();
+    constructor(readRow) {
+        this.readRow = readRow;
+    }
+    get hasPending() {
+        return this.pending.size > 0;
+    }
+    record(table, column, id) {
+        const key = `${table}\u0000${column}`;
+        let ids = this.pending.get(key);
+        if (!ids)
+            this.pending.set(key, (ids = new Set()));
+        ids.add(id);
+    }
+    async read(table, column, id) {
+        const key = `${table}\u0000${column}`;
+        let map = this.cache.get(key);
+        if (!map) {
+            map = await this.resolve(key, this.pending.get(key) ?? new Set());
+            this.pending.delete(key);
+            this.cache.set(key, map);
+        }
+        return map.get(id) ?? null;
+    }
+    /** Resolve every pending bucket now (called between the collection pass
+     *  and the real evaluation pass). */
+    async resolveAll() {
+        for (const [key, ids] of this.pending)
+            this.cache.set(key, await this.resolve(key, ids));
+        this.pending.clear();
+    }
+    async resolve(key, ids) {
+        const separator = key.indexOf("\u0000");
+        const table = key.slice(0, separator);
+        const column = key.slice(separator + 1);
+        const map = new Map();
+        // One engine read per distinct triple; the buckets' triples are
+        // independent so they resolve concurrently. A missing row caches as
+        // null so repeated dangling hops fail once, exactly like a direct
+        // readLinkedRow would per hop.
+        await Promise.all(Array.from(ids).map(async (id) => {
+            map.set(id, await this.readRow(table, column, id));
+        }));
+        return map;
+    }
+}
+/** True when an expression tree contains any link hop (multi-segment path). */
+function astHasHops(node) {
+    switch (node.kind) {
+        case "num":
+            return false;
+        case "path":
+            return node.ids.length > 1;
+        case "bin":
+            return astHasHops(node.left) || astHasHops(node.right);
+        case "fn":
+            return astHasHops(node.arg);
+    }
+}
 /**
  * @param {string} database - Database name
  * @param {string} [mainFolder="."] - Main folder path
@@ -45,9 +125,22 @@ export default class Inibase {
      *  resolve numeric ids to line numbers arithmetically instead of scanning
      *  the id file. Set false by any partial row deletion. */
     idDensity = new Map();
+    /** Per-table computed-plan cache (null = table has no computed fields).
+     *  A plan depends only on the table's persisted schema (compiled ASTs are
+     *  id-based and rename-proof), so it is rebuilt only when the schema
+     *  changes: see the invalidation in `getTable`'s reload branch,
+     *  `createTable` and `updateTableLocked`. Bounded by the number of tables. */
+    computedPlanCache = new Map();
     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 +221,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,32 +243,44 @@ 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"
-                ? JSON.stringify(Utils.addIdToSchema(schema, lastSchemaID), null, 2)
-                : Inison.stringify(Utils.addIdToSchema(schema, lastSchemaID)));
-            await writeFile(join(tablePath, `${lastSchemaID.value}.schema`), "");
+            // Compile computed expressions only after ids are assigned (the
+            // persisted AST carries ids, making it rename-proof), and before
+            // the schema is written so a bad expression never lands on disk.
+            schema = await this.compileComputedFields(Utils.addIdToSchema(schema, lastSchemaID));
+            await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
+                ? JSON.stringify(schema, null, 2)
+                : Inison.stringify(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);
+        // Defensive: a table of the same name may have had a cached plan from
+        // before a delete+recreate.
+        this.computedPlanCache.delete(tableName);
     }
     // Function to replace the string in one schema file
     async replaceStringInFile(filePath, targetString, replaceString) {
         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 +292,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
@@ -199,6 +332,18 @@ export default class Inibase {
                 value: schemaIdFilePath ? Number(parse(schemaIdFilePath).name) : 0,
             };
             schema = Utils.addIdToSchema(schema, lastSchemaID);
+            // Compile computed expressions now that ids are assigned (the
+            // persisted AST only stores ids, so later renames never retarget
+            // an expression). Compilation happens before any file surgery so
+            // a bad expression aborts the migration cleanly.
+            schema = await this.compileComputedFields(schema);
+            // Row count is needed for the computed backfill below, so read the
+            // pagination before the schema is rewritten.
+            let totalLines = 0;
+            for await (const paginationFileName of glob("*.pagination", {
+                cwd: tablePath,
+            }))
+                totalLines = parse(paginationFileName).name.split("-").map(Number)[1];
             // if schema file exists, update columns files names based on field id
             if ((await File.isExists(join(tablePath, `schema.${this.schemaFileExtension}`))) &&
                 table.schema?.length) {
@@ -214,13 +359,55 @@ export default class Inibase {
                         }
                     }));
             }
-            await writeFile(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
+            // Computed-field backfill: a computed expression that is added or
+            // changed by this migration must be (re)derived for every existing
+            // row. Evaluation happens BEFORE the schema is rewritten, so a
+            // failed migration (dangling link, arithmetic error, unknown
+            // field, ...) leaves the old schema and column values untouched.
+            const oldComputed = new Map((table.schema ?? [])
+                .filter((field) => typeof field.computed !== "undefined")
+                .map((field) => [field.key, this.computedExprOf(field)]));
+            const changedComputedKeys = new Set(totalLines > 0
+                ? schema
+                    .filter((field) => typeof field.computed !== "undefined" &&
+                    oldComputed.get(field.key) !== this.computedExprOf(field))
+                    .map((field) => field.key)
+                : []);
+            const backfillReplacers = changedComputedKeys.size
+                ? await (async () => {
+                    const plan = await this.buildComputedPlan(tableName, schema);
+                    if (!plan)
+                        return undefined;
+                    const lineNumbers = Array.from({ length: totalLines }, (_, index) => index + 1);
+                    const existing = await this.processSchemaData(tableName, schema.filter((field) => typeof field.computed === "undefined"), lineNumbers);
+                    return this.evaluateComputedRows(tableName, plan, existing);
+                })()
+                : undefined;
+            // Publish the backfilled values before the schema write.
+            if (backfillReplacers) {
+                const backfillRenameList = [];
+                for (const key of changedComputedKeys) {
+                    const lines = {};
+                    for (const [line, values] of Object.entries(backfillReplacers))
+                        if (Object.hasOwn(values, key))
+                            lines[Number(line)] = File.encode(values[key]);
+                    if (!Object.keys(lines).length)
+                        continue;
+                    backfillRenameList.push(await File.replace(join(tablePath, `${key}${this.getFileExtension(tableName)}`), lines));
+                }
+                for (const [tmp, live] of backfillRenameList)
+                    if (tmp && live)
+                        await rename(tmp, live);
+            }
+            // 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
@@ -228,11 +415,6 @@ export default class Inibase {
             // files padded with one empty line per existing row so appends keep
             // line-aligned with the other column files (decode("") is
             // undefined/null, matching the "no value yet" semantics).
-            let totalLines = 0;
-            for await (const paginationFileName of glob("*.pagination", {
-                cwd: tablePath,
-            }))
-                totalLines = parse(paginationFileName).name.split("-").map(Number)[1];
             await Promise.allSettled(schema.map(async ({ key }) => {
                 const filePath = join(tablePath, `${key}${this.getFileExtension(tableName)}`);
                 if (!(await File.isExists(filePath)))
@@ -242,26 +424,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 +457,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 +478,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,7 +514,17 @@ 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);
+        // The schema on disk changed under the DDL lock: drop the cached plan
+        // (also under the old name when the table was renamed) so the next DML
+        // rebuilds from the reloaded schema.
+        this.computedPlanCache.delete(tableName);
+        if (config?.name && config.name !== tableName)
+            this.computedPlanCache.delete(config.name);
     }
     /**
      * Get table schema and config
@@ -338,6 +550,9 @@ export default class Inibase {
                 },
                 timestamp: await File.getFileDate(join(tablePath, `schema.${this.schemaFileExtension}`)),
             });
+        // A reload means the on-disk schema changed (create/update/external
+        // edit): the cached computed plan is derived from it.
+        this.computedPlanCache.delete(tableName);
         return globalConfig[this.databasePath].tables?.get(tableName);
     }
     async getTableSchema(tableName) {
@@ -356,10 +571,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");
@@ -406,6 +625,13 @@ export default class Inibase {
         }
         if (Utils.isObject(data)) {
             for (const field of schema) {
+                // Computed columns are never user-settable: their value is
+                // always derived by the engine at write time.
+                if (typeof field.computed !== "undefined") {
+                    if (Object.hasOwn(data, field.key))
+                        throw this.createError("COMPUTED_FIELD_SETTABLE", field.key);
+                    continue;
+                }
                 if (!Object.hasOwn(data, field.key) ||
                     data[field.key] === null ||
                     data[field.key] === undefined ||
@@ -789,6 +1015,454 @@ export default class Inibase {
         }
         return RETURN;
     }
+    /* -----------------------------------------------------------------------
+     * Computed fields
+     * --------------------------------------------------------------------- */
+    /**
+     * Extract the raw expression from a field's `computed` property (string or
+     * persisted `{ expr, ast }` spec).
+     */
+    computedExprOf(field) {
+        const computed = field.computed;
+        return typeof computed === "string" ? computed : (computed?.expr ?? "");
+    }
+    /**
+     * Compile every `computed` expression of a schema (which must already have
+     * ids assigned) into its persisted `{ expr, ast }` form, in dependency
+     * order. Throws `COMPUTED_FIELD_CYCLE` on cyclic fields. Used by DDL so the
+     * on-disk schema always carries compiled ASTs.
+     */
+    async compileComputedFields(schema) {
+        const computedFields = schema.filter((field) => typeof field.computed !== "undefined");
+        if (!computedFields.length)
+            return schema;
+        const index = buildFieldIndex(schema);
+        const ctx = {
+            language: this.language,
+            ownKey: "",
+            index,
+            getTableIndex: async (target) => this.tableFieldIndex(target),
+        };
+        const resolved = [];
+        for (const field of computedFields) {
+            // Computed fields are evaluated from the row of the table they
+            // belong to, so v1 restricts them to top-level schema fields.
+            const ref = index.get(field.id);
+            if (!ref || ref.arrayAncestor)
+                throw this.createError("COMPUTED_FIELD_INVALID_TARGET", field.key);
+            ctx.ownKey = field.key;
+            const raw = parseExpression(this.computedExprOf(field), this.language, field.key);
+            const { ast, deps } = await resolveExpression(raw, ctx);
+            resolved.push({ field, ast, deps });
+        }
+        const ordered = topoSortComputedFields(resolved.map(({ field, deps }) => ({
+            id: field.id,
+            key: field.key,
+            deps,
+        })), this.language);
+        const specByKey = new Map();
+        for (const meta of ordered) {
+            const entry = resolved.find(({ field }) => field.id === meta.id);
+            if (!entry)
+                continue;
+            specByKey.set(meta.key, {
+                expr: this.computedExprOf(entry.field),
+                ast: entry.ast,
+            });
+        }
+        return schema.map((field) => typeof field.computed !== "undefined"
+            ? { ...field, computed: specByKey.get(field.key) }
+            : field);
+    }
+    /**
+     * Build the evaluation plan (topological order + id index) for a table's
+     * computed fields. Throws on cycles or unresolvable expressions.
+     */
+    async buildComputedPlan(tableName, schema) {
+        // Plans only depend on the persisted schema (compiled, id-based ASTs),
+        // so cache per table and invalidate on schema changes. The explicit
+        // `schema` argument (backfill during updateTable) always bypasses the
+        // cache — the caller owns that freshly-migrated schema.
+        if (schema === undefined) {
+            const cached = this.computedPlanCache.get(tableName);
+            if (cached !== undefined)
+                return cached;
+        }
+        const s = schema ?? globalConfig[this.databasePath].tables?.get(tableName)?.schema;
+        if (!s)
+            return null;
+        const index = buildFieldIndex(s);
+        const fields = [];
+        const indexCache = new Map();
+        const ctx = {
+            language: this.language,
+            ownKey: "",
+            index,
+            getTableIndex: async (target) => {
+                let cached = indexCache.get(target);
+                if (!cached) {
+                    cached = await this.tableFieldIndex(target);
+                    if (cached)
+                        indexCache.set(target, cached);
+                }
+                return cached;
+            },
+        };
+        for (const field of s) {
+            if (typeof field.computed === "undefined")
+                continue;
+            const computed = field.computed;
+            if (typeof computed === "string") {
+                ctx.ownKey = field.key;
+                const raw = parseExpression(computed, this.language, field.key);
+                const { ast, deps } = await resolveExpression(raw, ctx);
+                fields.push({
+                    id: field.id,
+                    key: field.key,
+                    ast,
+                    deps,
+                });
+            }
+            else
+                fields.push({
+                    id: field.id,
+                    key: field.key,
+                    ast: computed.ast,
+                    deps: collectFieldDeps(computed.ast),
+                });
+        }
+        if (!fields.length) {
+            if (schema === undefined)
+                this.computedPlanCache.set(tableName, null);
+            return null;
+        }
+        const ordered = topoSortComputedFields(fields.map(({ id, key, deps }) => ({ id, key, deps })), this.language);
+        const byId = new Map(fields.map((f) => [f.id, f]));
+        const planFields = ordered.map((meta) => byId.get(meta.id));
+        const plan = {
+            fields: planFields,
+            index,
+            hasHops: planFields.some((field) => astHasHops(field.ast)),
+        };
+        if (schema === undefined)
+            this.computedPlanCache.set(tableName, plan);
+        return plan;
+    }
+    /** Id index of a table's schema (link targets are re-resolved at write
+     *  time, so renames never retarget a compiled expression). */
+    async tableFieldIndex(tableName) {
+        const schema = await this.getTableSchema(tableName);
+        return schema ? buildFieldIndex(schema) : undefined;
+    }
+    /**
+     * Evaluate a batch of (merged) rows against the table's computed fields.
+     * Returns `lineNo -> { computedKey -> value }` in dependency order.
+     *
+     * Batched link-hop reads: when the plan contains any link hop, a dry
+     * collection pass records every (table, column, id) triple the rows'
+     * expressions need (no file I/O), each distinct triple is then resolved
+     * exactly once — deduplicated across rows and fields — and a final pass
+     * evaluates against the warm cache. Plans without hops run the single
+     * evaluation pass unchanged.
+     */
+    async evaluateComputedRows(tableName, plan, rows) {
+        const out = {};
+        const indexCache = new Map([
+            [tableName, plan.index],
+        ]);
+        const entries = Object.entries(rows);
+        const reader = plan.hasHops ? this.createLinkReader() : null;
+        if (reader) {
+            for (const [, row] of entries)
+                await this.evaluateRowComputed(tableName, plan, row, indexCache, reader, true);
+            if (reader.hasPending)
+                await reader.resolveAll();
+        }
+        for (const [line, row] of entries)
+            out[Number(line)] = await this.evaluateRowComputed(tableName, plan, row, indexCache, reader ?? undefined);
+        return out;
+    }
+    createLinkReader() {
+        return new LinkedRowReader((table, column, id) => this.readLinkedRow(table, id, column));
+    }
+    /** Evaluate every computed field of one row (topological order) and merge
+     *  the results back into the row so dependent fields see them. */
+    async evaluateRowComputed(tableName, plan, row, indexCache, links, collect = false) {
+        const out = {};
+        // One structured frame per row, shared by every computed field: paths
+        // resolve against the row in place (direct key-path reads), so no
+        // flattened copy is ever built. Freshly evaluated values are written
+        // back into the row — computed fields are top-level keys, so dependent
+        // fields see earlier results through the same key-path reads.
+        const env = {
+            table: tableName,
+            index: plan.index,
+            frame: row,
+            row,
+            strip: "",
+            ownKey: "",
+            indexCache,
+            links,
+            collect,
+        };
+        for (const field of plan.fields) {
+            env.strip = "";
+            env.ownKey = field.key;
+            const value = await this.evaluateNode(field.ast, env);
+            out[field.key] = value;
+            row[field.key] = value;
+        }
+        return out;
+    }
+    async evaluateNode(node, env) {
+        switch (node.kind) {
+            case "num":
+                return node.value;
+            case "path":
+                return this.evaluatePath(node, env);
+            case "bin": {
+                const a = await this.evaluateNode(node.left, env);
+                const b = await this.evaluateNode(node.right, env);
+                return this.applyBinaryOp(node.op, a, b, env.ownKey, env.collect);
+            }
+            case "fn": {
+                const arrayRef = env.index.get(node.arrayFieldId);
+                const arrayKey = arrayRef?.key;
+                const raw = arrayKey ? env.row[arrayKey] : undefined;
+                // formatData turns a missing/empty array-of-objects into `{}`;
+                // treat anything that is not an actual array as empty.
+                const elements = Array.isArray(raw) ? raw : [];
+                const values = [];
+                // Reuse the env object across elements (only frame/strip
+                // change) to avoid allocating a frame per element. Elements
+                // are walked in place via direct key-path reads, so nothing is
+                // flattened or cached.
+                const savedFrame = env.frame;
+                const savedStrip = env.strip;
+                const stripPrefix = arrayKey ? `${arrayKey}.` : "";
+                for (const element of elements) {
+                    if (!Utils.isObject(element))
+                        continue;
+                    env.frame = element;
+                    env.strip = stripPrefix;
+                    const value = await this.evaluateNode(node.arg, env);
+                    if (value === null || value === undefined)
+                        continue;
+                    const num = this.coerceNumber(value, env.ownKey);
+                    values.push(num);
+                }
+                env.frame = savedFrame;
+                env.strip = savedStrip;
+                return this.aggregate(node.name, values, elements.length, env.ownKey, env.collect);
+            }
+        }
+    }
+    /** Evaluate a path (`ids`, dot-separated link hops) against the current
+     *  frame. Returns `null` when an intermediate link value is missing. */
+    async evaluatePath(node, env) {
+        const ids = node.ids;
+        let table = env.table;
+        let index = env.index;
+        let frame = env.frame;
+        let strip = env.strip;
+        let value;
+        let ref;
+        for (let i = 0; i < ids.length; i++) {
+            ref = index.get(ids[i]);
+            if (!ref)
+                throw this.createError("COMPUTED_FIELD_UNKNOWN_FIELD", [
+                    env.ownKey,
+                    ids[i],
+                ]);
+            const key = strip && ref.key.startsWith(strip)
+                ? ref.key.slice(strip.length)
+                : ref.key;
+            if (i === 0) {
+                // Direct key-path read: walk the structured frame in place.
+                value = resolveFramePath(frame, key);
+                strip = "";
+            }
+            else {
+                // `value` is the id of the row this hop lives in.
+                if (value === undefined ||
+                    value === null ||
+                    value === "" ||
+                    (typeof value === "object" && value !== null))
+                    return null;
+                // A transaction cannot read a dependency table it has already
+                // staged (no read-your-writes past its commit point).
+                if (this.transaction?.tables.has(table))
+                    throw this.createError("INVALID_PARAMETERS");
+                // Batched link-hop reads: during the collection pass a hop
+                // only records its (table, column, id) triple; the real pass
+                // is served from the reader's warm cache. Without a reader
+                // this is the plain per-hop engine read.
+                const row = env.links
+                    ? env.collect
+                        ? (env.links.record(table, ref.key, value), null)
+                        : await env.links.read(table, ref.key, value)
+                    : await this.readLinkedRow(table, value, ref.key);
+                if (!env.collect &&
+                    (row === undefined || row === null))
+                    throw this.createError("COMPUTED_FIELD_DANGLING_LINK", [
+                        env.ownKey,
+                        table,
+                    ]);
+                // The linked row is the next frame, walked in place (no
+                // flattened copy). readLinkedRow already fetched only the
+                // `ref.key` column, so the frame is minimal.
+                frame = row;
+                value = row ? resolveFramePath(frame, ref.key) : null;
+                index = (await this.indexFor(table, env.indexCache)) ?? index;
+            }
+            if (i < ids.length - 1) {
+                if (ref.field.type !== "table" || typeof ref.field.table !== "string")
+                    throw this.createError("COMPUTED_FIELD_INVALID_LINK", [
+                        env.ownKey,
+                        ids[i + 1],
+                    ]);
+                table = ref.field.table;
+                index = (await this.indexFor(table, env.indexCache)) ?? index;
+            }
+        }
+        return value === undefined ? null : value;
+    }
+    /** Id index lookup with a shared per-evaluation cache. */
+    async indexFor(tableName, cache) {
+        const cached = cache.get(tableName);
+        if (cached)
+            return cached;
+        const index = await this.tableFieldIndex(tableName);
+        if (index)
+            cache.set(tableName, index);
+        return index;
+    }
+    /** Read a single column of one linked row via `get`, or null when the
+     *  row does not exist (dangling link). */
+    async readLinkedRow(tableName, id, column) {
+        const row = await this.get(tableName, id, { columns: [column] }, true);
+        return row ?? null;
+    }
+    coerceNumber(value, ownKey) {
+        const num = Number(value);
+        if (!Number.isFinite(num))
+            throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                ownKey,
+                `non-numeric value '${String(value)}'`,
+            ]);
+        return num;
+    }
+    applyBinaryOp(op, a, b, ownKey, collect = false) {
+        if (a === null || a === undefined || b === null || b === undefined) {
+            // Collection passes must tolerate unresolved (null) link hops:
+            // the pass only discovers which links are needed, so a neutral
+            // result is fine. Real evaluation still throws.
+            if (collect)
+                return 0;
+            throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                ownKey,
+                "missing or null operand",
+            ]);
+        }
+        const an = this.coerceNumber(a, ownKey);
+        const bn = this.coerceNumber(b, ownKey);
+        switch (op) {
+            case "add":
+                return an + bn;
+            case "sub":
+                return an - bn;
+            case "mul":
+                return an * bn;
+            case "div":
+                if (bn === 0)
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "division by zero",
+                    ]);
+                return an / bn;
+            case "mod":
+                if (bn === 0)
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "modulo by zero",
+                    ]);
+                return an % bn;
+        }
+    }
+    aggregate(name, values, elementCount, ownKey, collect = false) {
+        switch (name) {
+            case "count":
+                // Aggregates iterate the row's actual array, so count is the
+                // element count (regardless of value presence).
+                return elementCount;
+            case "sum":
+                return values.reduce((acc, v) => acc + v, 0);
+            case "avg": {
+                if (!values.length) {
+                    // Collection passes may have skipped every value of an
+                    // array whose elements only held unresolved link hops.
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "average over no values",
+                    ]);
+                }
+                return values.reduce((acc, v) => acc + v, 0) / values.length;
+            }
+            case "min": {
+                if (!values.length) {
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "min over no values",
+                    ]);
+                }
+                return Math.min(...values);
+            }
+            case "max": {
+                if (!values.length) {
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "max over no values",
+                    ]);
+                }
+                return Math.max(...values);
+            }
+        }
+    }
+    /** Merge evaluated per-line computed values into a `pathesContents` map
+     *  as line-numbered replace records (encoded cells). */
+    mergeComputedLineRecords(tableName, plan, evaluated, pathesContents, existing) {
+        for (const field of plan.fields) {
+            const path = join(this.databasePath, tableName, `${field.key}${this.getFileExtension(tableName)}`);
+            const entries = Object.entries(evaluated);
+            // When the pre-update rows are available, compare each column's
+            // re-evaluated line values against the stored ones (deterministic
+            // encode). A column that is identical for every evaluated line is
+            // left untouched — no content buffer, no File.replace, no fsync.
+            if (existing) {
+                let matches = true;
+                for (const [line, values] of entries) {
+                    const old = existing[Number(line)]?.[field.key];
+                    const fresh = File.encode(values[field.key]);
+                    if (old === undefined || File.encode(old) !== fresh) {
+                        matches = false;
+                        break;
+                    }
+                }
+                if (matches)
+                    continue;
+            }
+            const content = pathesContents[path] ?? {};
+            for (const [line, values] of entries)
+                content[Number(line)] = File.encode(values[field.key]);
+            pathesContents[path] = content;
+        }
+    }
     // Helper function to determine if a field is simple
     isSimpleField(fieldType) {
         const complexTypes = ["array", "object", "table"];
@@ -1264,11 +1938,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 +2366,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)
@@ -1507,7 +2559,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}-*`))
@@ -1571,37 +2627,55 @@ 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;
             }
             clonedData = this.formatData(clonedData, globalConfig[this.databasePath].tables?.get(tableName)?.schema ?? [], false);
+            // Derived columns: evaluate every computed expression against the
+            // final formatted row (the row is pieced back in place so helpers
+            // iterate the real array values and dependent fields see each
+            // other). Evaluation happens before any file is touched.
+            const computedPlan = await this.buildComputedPlan(tableName);
+            if (computedPlan) {
+                const rows = Array.isArray(clonedData)
+                    ? clonedData
+                    : [clonedData];
+                // Evaluate every row against the shared plan in one batch:
+                // link hops are read once per distinct (table, column, id)
+                // across the whole post instead of once per hop.
+                await this.evaluateComputedRows(tableName, computedPlan, Object.fromEntries(rows.map((row, index) => [index, row])));
+            }
             const pathesContents = this.joinPathesContents(tableName, globalConfig[this.databasePath].tables?.get(tableName)?.config.prepend
                 ? Array.isArray(clonedData)
                     ? clonedData.toReversed()
@@ -1611,15 +2685,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()
@@ -1630,6 +2723,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
@@ -1638,11 +2732,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 = {
@@ -1650,12 +2755,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) {
@@ -1677,27 +2785,74 @@ export default class Inibase {
                 ...(({ id, ...restOfData }) => restOfData)(clonedData),
                 updatedAt: Date.now(),
             });
+            // Derived columns: a where-less put rewrites every row, so each
+            // computed expression must be re-evaluated against the existing
+            // row overlaid with the payload. The plan itself is schema-only.
+            const computedPlan = await this.buildComputedPlan(tableName);
             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);
+                if (computedPlan) {
+                    const lineNumbers = Array.from({ length: total }, (_, index) => index + 1);
+                    const schema = globalConfig[this.databasePath].tables?.get(tableName)?.schema ??
+                        [];
+                    // Read every stored column (computed ones included) so the
+                    // merge can skip columns whose re-evaluated values are
+                    // unchanged — no rewrite, no fsync for them.
+                    const existing = await this.processSchemaData(tableName, schema, lineNumbers);
+                    const payloadRows = (Array.isArray(clonedData) ? clonedData : [clonedData]).map((row) => Object.fromEntries(Object.entries(row).filter(([, v]) => v !== "undefined")));
+                    const mergedRows = {};
+                    for (let index = 0; index < lineNumbers.length; index++) {
+                        const line = lineNumbers[index];
+                        mergedRows[line] = {
+                            ...(existing[line] ?? {}),
+                            ...(payloadRows[index % payloadRows.length] ?? {}),
+                            updatedAt: Date.now(),
+                        };
+                    }
+                    const evaluated = await this.evaluateComputedRows(tableName, computedPlan, mergedRows);
+                    this.mergeComputedLineRecords(tableName, computedPlan, evaluated, pathesContents, existing);
+                }
+                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)) ||
@@ -1720,26 +2875,70 @@ export default class Inibase {
                     return obj;
                 }, {}),
             ]));
-            const keys = UtilsServer.hashString(Object.keys(pathesContents)
-                .map((path) => path.replaceAll(this.getFileExtension(tableName), ""))
-                .join("."));
+            // Derived columns re-evaluate the target lines: existing values +
+            // payload overlay feed the expressions, results go back per line.
+            const computedPlan = await this.buildComputedPlan(tableName);
             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"));
+                if (computedPlan) {
+                    const whereLines = Array.isArray(where) ? where : [where];
+                    const schema = globalConfig[this.databasePath].tables?.get(tableName)?.schema ??
+                        [];
+                    // Read every stored column (computed ones included) so the
+                    // merge can skip columns whose re-evaluated values are
+                    // unchanged — no rewrite, no fsync for them.
+                    const existing = await this.processSchemaData(tableName, schema, whereLines);
+                    const payloadRows = (Array.isArray(clonedData) ? clonedData : [clonedData]).map((row) => Object.fromEntries(Object.entries(row).filter(([, v]) => v !== "undefined")));
+                    const evaluated = {};
+                    const indexCache = new Map([
+                        [tableName, computedPlan.index],
+                    ]);
+                    for (let index = 0; index < whereLines.length; index++) {
+                        const line = whereLines[index];
+                        const merged = {
+                            ...(existing[line] ?? {}),
+                            ...(payloadRows[index] ?? {}),
+                            updatedAt: Date.now(),
+                        };
+                        evaluated[line] = await this.evaluateRowComputed(tableName, computedPlan, merged, indexCache);
+                    }
+                    this.mergeComputedLineRecords(tableName, computedPlan, evaluated, pathesContents, existing);
+                }
                 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 &&
@@ -1777,37 +2976,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);
-                }
-                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`));
+                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);
+                }
                 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)) ||
@@ -1819,46 +3044,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"));
+                    }
                 }
             }
         }
@@ -1928,8 +3184,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) => {
@@ -1944,8 +3204,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;
                 }
             }
         }