inibase 3.5.0 → 3.6.0

package/dist/index.d.ts

@@ -130,7 +130,7 @@ export default class Inibase {
      * per-table writer lock of every table it mutates, so mutations stage into
      * the database journal and publish only on commit().
      */
-    private transaction;
+    private activeTransaction;
     constructor(database: string, mainFolder?: string, language?: ErrorLang);
     createError(name: ErrorCode, variable?: string | number | (string | number)[]): Error;
     private validateName;
@@ -350,6 +350,20 @@ export default class Inibase {
      * live file is touched (nothing is published before commit()).
      */
     rollback(): Promise<void>;
+    /**
+     * Run `callback` inside a transaction, committing when it resolves and
+     * rolling back when it throws. Prefer this over a bare begin/commit pair:
+     * the database lock taken by begin() is held for the transaction's whole
+     * lifetime, so an exception between begin() and commit() would otherwise
+     * block every later write on this database for the full lock-wait timeout.
+     *
+     * @param tablesOrCallback Pre-lock list (sorted, deadlock-free) or the callback
+     * @param maybeCallback The callback, when tables were passed first
+     * @param tables Pre-lock list when the callback was passed first
+     * @return {*} Whatever the callback resolves to
+     */
+    transaction<T>(tablesOrCallback: string[] | ((db: Inibase) => Promise<T>), maybeCallback?: (db: Inibase) => Promise<T>, tables?: string[]): Promise<T>;
+    private _transaction;
     /**
      * Snapshot the identity (dev:inode:mtime:size) of every column file and
      * the pagination file. Reading data and then re-verifying this snapshot

package/dist/index.js

@@ -140,7 +140,7 @@ export default class Inibase {
      * per-table writer lock of every table it mutates, so mutations stage into
      * the database journal and publish only on commit().
      */
-    transaction = null;
+    activeTransaction = null;
     constructor(database, mainFolder = ".", language = "en") {
         this.language = language;
         this.validateName(database);
@@ -226,7 +226,7 @@ export default class Inibase {
         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)
+        if (this.activeTransaction)
             throw this.createError("INVALID_PARAMETERS");
         await this.ensureDatabaseRecovered();
         if (schema)
@@ -300,7 +300,7 @@ export default class Inibase {
         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)
+        if (this.activeTransaction)
             throw this.createError("INVALID_PARAMETERS");
         await this.ensureDatabaseRecovered();
         if (config?.name)
@@ -1428,7 +1428,7 @@ export default class Inibase {
                     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))
+                if (this.activeTransaction?.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
@@ -2210,7 +2210,7 @@ export default class Inibase {
     }
     /** Staged per-table entry of the open transaction, or null when none. */
     txnTableEntry(tableName) {
-        const txn = this.transaction;
+        const txn = this.activeTransaction;
         if (!txn)
             return null;
         let entry = txn.tables.get(tableName);
@@ -2272,7 +2272,7 @@ export default class Inibase {
      * would need read-your-writes composition).
      */
     async stageTxnOp(tableName, renameList, pagination) {
-        const txn = this.transaction;
+        const txn = this.activeTransaction;
         const entry = this.txnTableEntry(tableName);
         if (!txn || !entry)
             throw this.createError("INVALID_PARAMETERS");
@@ -2317,7 +2317,7 @@ export default class Inibase {
         return File.runWithLockStore(() => this._begin(tables));
     }
     async _begin(tables = []) {
-        if (this.transaction)
+        if (this.activeTransaction)
             throw this.createError("INVALID_PARAMETERS");
         await this.ensureDatabaseTmpDir();
         // The database lock is the transaction mutex: it serializes
@@ -2333,16 +2333,16 @@ export default class Inibase {
                 await this.getTable(name); // throws TABLE_NOT_EXISTS
             }
             const id = randomUUID();
-            this.transaction = {
+            this.activeTransaction = {
                 id,
                 journal: new DatabaseJournal(this.databasePath, id),
                 tables: new Map(),
             };
-            await this.transaction.journal.begin(uniqueTables);
+            await this.activeTransaction.journal.begin(uniqueTables);
             for (const name of uniqueTables) {
                 await File.lock(join(this.databasePath, name, ".tmp"));
                 acquired.push(name);
-                this.transaction.tables.set(name, {
+                this.activeTransaction.tables.set(name, {
                     locked: true,
                     paginationFrom: "",
                     lastId: 0,
@@ -2357,7 +2357,7 @@ export default class Inibase {
             // lock file).
             for (const name of acquired)
                 await File.unlock(join(this.databasePath, name, ".tmp")).catch(() => { });
-            this.transaction = null;
+            this.activeTransaction = null;
             await File.unlock(join(this.databasePath, ".tmp")).catch(() => { });
             throw error;
         }
@@ -2371,7 +2371,7 @@ export default class Inibase {
      * tables, marker -> roll forward all tables).
      */
     async commit() {
-        const txn = this.transaction;
+        const txn = this.activeTransaction;
         if (!txn)
             throw this.createError("INVALID_PARAMETERS");
         try {
@@ -2404,6 +2404,25 @@ export default class Inibase {
                 await File.syncDir(join(this.databasePath, tableName));
                 await File.syncDir(join(this.databasePath, tableName, ".tmp"));
             }
+            // A staged table's row count and derived caches were deliberately
+            // left untouched while the transaction was open (nothing is
+            // published before commit), so they must be refreshed here — the
+            // single-table fast path does the same right after commitFiles().
+            // Without this a committed `put` (row count unchanged) would keep
+            // serving sorted/criteria .cache entries built before the write.
+            for (const tableName of txn.tables.keys()) {
+                const entry = txn.tables.get(tableName);
+                if (!entry?.staged.length)
+                    continue; // pre-locked but untouched
+                // Only trust entry.total when resolvePagination() recorded it.
+                // A `put` selected by `where` never reads the pagination file
+                // (its row count cannot change), so entry.total is still its
+                // initial 0 — publishing that would corrupt the live counter.
+                if (entry.paginationFrom)
+                    this.totalItems.set(`${tableName}-*`, entry.total);
+                if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
+                    await this.clearCache(tableName);
+            }
         }
         catch (error) {
             await txn.journal.rollback().catch(() => { });
@@ -2413,7 +2432,7 @@ export default class Inibase {
             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;
+            this.activeTransaction = null;
         }
     }
     /**
@@ -2421,7 +2440,7 @@ export default class Inibase {
      * live file is touched (nothing is published before commit()).
      */
     async rollback() {
-        const txn = this.transaction;
+        const txn = this.activeTransaction;
         if (!txn)
             throw this.createError("INVALID_PARAMETERS");
         try {
@@ -2431,7 +2450,44 @@ export default class Inibase {
             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;
+            this.activeTransaction = null;
+        }
+    }
+    /**
+     * Run `callback` inside a transaction, committing when it resolves and
+     * rolling back when it throws. Prefer this over a bare begin/commit pair:
+     * the database lock taken by begin() is held for the transaction's whole
+     * lifetime, so an exception between begin() and commit() would otherwise
+     * block every later write on this database for the full lock-wait timeout.
+     *
+     * @param tablesOrCallback Pre-lock list (sorted, deadlock-free) or the callback
+     * @param maybeCallback The callback, when tables were passed first
+     * @param tables Pre-lock list when the callback was passed first
+     * @return {*} Whatever the callback resolves to
+     */
+    async transaction(tablesOrCallback, maybeCallback, tables = []) {
+        return File.runWithLockStore(() => this._transaction(tablesOrCallback, maybeCallback, tables));
+    }
+    async _transaction(tablesOrCallback, maybeCallback, tables = []) {
+        const callback = typeof tablesOrCallback === "function" ? tablesOrCallback : maybeCallback;
+        if (!callback)
+            throw this.createError("INVALID_PARAMETERS");
+        if (Array.isArray(tablesOrCallback))
+            tables = tablesOrCallback;
+        await this.begin(tables);
+        let committed = false;
+        try {
+            const result = await callback(this);
+            await this.commit();
+            committed = true;
+            return result;
+        }
+        finally {
+            // commit() already rolled back and cleared the transaction when it
+            // failed, so this only fires for a throwing callback (or one that
+            // never committed) — the case that would otherwise leak the lock.
+            if (!committed && this.activeTransaction)
+                await this.rollback().catch(() => { });
         }
     }
     /**
@@ -2805,7 +2861,7 @@ export default class Inibase {
                 ? options.columns
                 : [options.columns]));
         const tablePath = join(this.databasePath, tableName);
-        if (!this.transaction)
+        if (!this.activeTransaction)
             await this.ensureDatabaseRecovered();
         await this.getTable(tableName);
         if (!globalConfig[this.databasePath].tables?.get(tableName)?.schema)
@@ -2819,13 +2875,13 @@ export default class Inibase {
         try {
             // Inside a transaction the table lock is taken once per txn (and
             // held until commit/rollback); otherwise the usual writer lock.
-            if (this.transaction)
+            if (this.activeTransaction)
                 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)
+            if (!this.activeTransaction)
                 this.totalItems.set(`${tableName}-*`, _totalItems);
             if (Utils.isArrayOfObjects(clonedData))
                 for (let index = 0; index < clonedData.length; index++) {
@@ -2868,7 +2924,7 @@ export default class Inibase {
                 from: paginationFilePath,
                 to: join(tablePath, `${lastIdValue}-${newTotal}.pagination`),
             };
-            if (this.transaction) {
+            if (this.activeTransaction) {
                 // Stage: journal the intent (fsynced op entry); the live files
                 // only change when commit() publishes.
                 await this.stageTxnOp(tableName, renameList, pagination);
@@ -2887,7 +2943,7 @@ export default class Inibase {
                     await this.clearCache(tableName);
             }
             if (returnPostedData) {
-                if (this.transaction)
+                if (this.activeTransaction)
                     // No read-your-writes yet: return the formatted staged rows
                     // (ids + defaults) instead of a committed-state read.
                     return (Array.isArray(clonedData) ? clonedData : clonedData);
@@ -2908,15 +2964,13 @@ export default class Inibase {
             // not encode it here. Every other table keeps returning the
             // encrypted id.
             const tableConfig = globalConfig[this.databasePath].tables?.get(tableName)?.config;
-            const postedID = (id) => tableConfig?.decodeID === true
-                ? Number(id)
-                : UtilsServer.encodeID(id);
+            const postedID = (id) => tableConfig?.decodeID === true ? Number(id) : UtilsServer.encodeID(id);
             return Array.isArray(clonedData)
                 ? (tableConfig?.prepend ? clonedData.toReversed() : clonedData).map(({ id }) => postedID(id))
                 : postedID(clonedData.id);
         }
         finally {
-            if (this.transaction) {
+            if (this.activeTransaction) {
                 // Staged temps belong to the journal op; commit()/rollback()
                 // owns them. Temps from a failed pre-stage attempt are cleaned
                 // here so nothing leaks.
@@ -2952,7 +3006,7 @@ export default class Inibase {
                 ? options.columns
                 : [options.columns]));
         const tablePath = join(this.databasePath, tableName);
-        if (!this.transaction)
+        if (!this.activeTransaction)
             await this.ensureDatabaseRecovered();
         await this.throwErrorIfTableEmpty(tableName);
         let clonedData = structuredClone(data);
@@ -2980,7 +3034,7 @@ export default class Inibase {
             // row overlaid with the payload. The plan itself is schema-only.
             const computedPlan = await this.buildComputedPlan(tableName);
             try {
-                if (this.transaction)
+                if (this.activeTransaction)
                     await this.ensureTxnLock(tableName);
                 else
                     await File.lock(join(tablePath, ".tmp"));
@@ -3007,7 +3061,7 @@ export default class Inibase {
                     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) {
+                if (this.activeTransaction) {
                     // Stage instead of publishing: row count is unchanged so
                     // there is no pagination rename to journal.
                     await this.stageTxnOp(tableName, renameList, null);
@@ -3020,7 +3074,7 @@ export default class Inibase {
                         await this.clearCache(tableName);
                 }
                 if (returnUpdatedData) {
-                    if (this.transaction)
+                    if (this.activeTransaction)
                         // Reading the committed state would miss the staged
                         // write (no read-your-writes yet).
                         throw this.createError("INVALID_PARAMETERS");
@@ -3028,7 +3082,7 @@ export default class Inibase {
                 }
             }
             finally {
-                if (this.transaction) {
+                if (this.activeTransaction) {
                     // Staged temps belong to the journal op; commit()/rollback()
                     // owns them.
                     if (!txnStaged && renameList.length)
@@ -3075,7 +3129,7 @@ export default class Inibase {
             try {
                 // One global lock per table serializes every writer; inside a
                 // transaction the lock is held for the whole txn.
-                if (this.transaction)
+                if (this.activeTransaction)
                     await this.ensureTxnLock(tableName);
                 else
                     await File.lock(join(tablePath, ".tmp"));
@@ -3104,7 +3158,7 @@ export default class Inibase {
                     this.mergeComputedLineRecords(tableName, computedPlan, evaluated, pathesContents, existing);
                 }
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content))));
-                if (this.transaction) {
+                if (this.activeTransaction) {
                     await this.stageTxnOp(tableName, renameList, null);
                     txnStaged = true;
                 }
@@ -3114,7 +3168,7 @@ export default class Inibase {
                         await this.clearCache(tableName);
                 }
                 if (returnUpdatedData) {
-                    if (this.transaction)
+                    if (this.activeTransaction)
                         throw this.createError("INVALID_PARAMETERS");
                     // AWAITED readback: must complete inside the writer lock. An
                     // async-tail `return this.get(...)` lets the finally below
@@ -3123,7 +3177,7 @@ export default class Inibase {
                 }
             }
             finally {
-                if (this.transaction) {
+                if (this.activeTransaction) {
                     if (!txnStaged && renameList.length)
                         await Promise.allSettled(renameList
                             .filter((pair) => Boolean(pair[0]))
@@ -3150,7 +3204,7 @@ export default class Inibase {
             // the lock is held continuously from resolution to publish.
             let inlineLock = false;
             try {
-                if (this.transaction)
+                if (this.activeTransaction)
                     await this.ensureTxnLock(tableName);
                 else {
                     await File.lock(join(tablePath, ".tmp"));
@@ -3194,7 +3248,7 @@ export default class Inibase {
     }
     async _delete(tableName, where, _whereIsLinesNumbers, _cascadeGuard) {
         this.validateName(tableName);
-        if (!this.transaction)
+        if (!this.activeTransaction)
             await this.ensureDatabaseRecovered();
         const tablePath = join(this.databasePath, tableName);
         await this.throwErrorIfTableEmpty(tableName);
@@ -3204,7 +3258,7 @@ export default class Inibase {
             // ops) and publish the empty row count in one journaled commit.
             const renameList = [];
             try {
-                if (this.transaction)
+                if (this.activeTransaction)
                     await this.ensureTxnLock(tableName);
                 else
                     await File.lock(join(tablePath, ".tmp"));
@@ -3217,7 +3271,7 @@ export default class Inibase {
                     from: paginationFilePath,
                     to: join(tablePath, `${lastId}-0.pagination`),
                 };
-                if (this.transaction) {
+                if (this.activeTransaction) {
                     await this.stageTxnOp(tableName, renameList, pagination);
                     txnStaged = true;
                     const stagedEntry = this.txnTableEntry(tableName);
@@ -3238,7 +3292,7 @@ export default class Inibase {
                 return true;
             }
             finally {
-                if (this.transaction) {
+                if (this.activeTransaction) {
                     if (!txnStaged && renameList.length)
                         await Promise.allSettled(renameList
                             .filter((pair) => Boolean(pair[0]))
@@ -3268,7 +3322,7 @@ export default class Inibase {
                 const renameList = [];
                 let txnStaged = false;
                 try {
-                    if (this.transaction)
+                    if (this.activeTransaction)
                         await this.ensureTxnLock(tableName);
                     else
                         await File.lock(join(tablePath, ".tmp"));
@@ -3281,7 +3335,7 @@ export default class Inibase {
                             from: paginationFilePath,
                             to: join(tablePath, `${lastId}-${remaining}.pagination`),
                         };
-                        if (this.transaction) {
+                        if (this.activeTransaction) {
                             await this.stageTxnOp(tableName, renameList, pagination);
                             txnStaged = true;
                             const stagedEntry = this.txnTableEntry(tableName);
@@ -3302,7 +3356,7 @@ export default class Inibase {
                             from: paginationFilePath,
                             to: join(tablePath, `${lastId}-0.pagination`),
                         };
-                        if (this.transaction) {
+                        if (this.activeTransaction) {
                             await this.stageTxnOp(tableName, truncateList, pagination);
                             txnStaged = true;
                             const stagedEntry = this.txnTableEntry(tableName);
@@ -3315,7 +3369,7 @@ export default class Inibase {
                     }
                     // Cache still describes the committed state while a
                     // transaction is open, so only clear it outside one.
-                    if (!this.transaction &&
+                    if (!this.activeTransaction &&
                         globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                         await this.clearCache(tableName);
                     // Cascade: rows in other tables referencing the deleted rows
@@ -3324,7 +3378,7 @@ export default class Inibase {
                     return true;
                 }
                 finally {
-                    if (this.transaction) {
+                    if (this.activeTransaction) {
                         if (!txnStaged && renameList.length)
                             await Promise.allSettled(renameList
                                 .filter((pair) => Boolean(pair[0]))
@@ -3350,7 +3404,7 @@ export default class Inibase {
             // lines of a prepend table and remove the wrong row).
             let inlineLock = false;
             try {
-                if (this.transaction)
+                if (this.activeTransaction)
                     await this.ensureTxnLock(tableName);
                 else {
                     await File.lock(join(tablePath, ".tmp"));
@@ -3424,7 +3478,7 @@ export default class Inibase {
                         // Unreadable/unsupported column -> skip this reference.
                         // Inside a transaction a broken reference must abort the
                         // whole cascade (all-or-nothing).
-                        if (this.transaction)
+                        if (this.activeTransaction)
                             throw error;
                     }
                 }
@@ -3444,7 +3498,7 @@ export default class Inibase {
                     // 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)
+                    if (this.activeTransaction)
                         throw error;
                 }
             }
@@ -3503,7 +3557,9 @@ export default class Inibase {
         const targetFields = new Map();
         for (const column of columns) {
             const dot = column.indexOf(".");
-            if (dot <= 0 || dot === column.length - 1 || column.indexOf(".", dot + 1) !== -1)
+            if (dot <= 0 ||
+                dot === column.length - 1 ||
+                column.indexOf(".", dot + 1) !== -1)
                 throw this.createError("INVALID_PARAMETERS", [
                     `sum nested: '${column}' must be a single-level child path of an array-of-objects column`,
                 ]);
@@ -3629,7 +3685,8 @@ export default class Inibase {
                     let matches = true;
                     for (const p of elementPredicates) {
                         const pv = predCells.get(p.field.key)?.[Number(lineStr)]?.[i];
-                        if (pv === undefined || !UtilsServer.compare(p.operator, pv, p.comparedValue, p.field.type)) {
+                        if (pv === undefined ||
+                            !UtilsServer.compare(p.operator, pv, p.comparedValue, p.field.type)) {
                             matches = false;
                             break;
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "type": "module",
   "author": {
     "name": "Karim Amahtil",