@naturalcycles/db-lib 9.1.1 → 9.2.1

package/dist/adapter/inmemory/inMemory.db.d.ts

@@ -1,6 +1,6 @@
 import { JsonSchemaObject, StringMap, JsonSchemaRootObject, ObjectWithId, CommonLogger } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDB, CommonDBType, DBOperation, DBPatch, DBTransactionFn } from '../..';
+import { CommonDB, CommonDBTransactionOptions, CommonDBType, DBOperation, DBPatch, DBTransactionFn } from '../..';
 import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, DBTransaction, RunQueryResult } from '../../db.model';
 import { DBQuery } from '../../query/dbQuery';
 export interface InMemoryDBCfg {
@@ -12,6 +12,16 @@ export interface InMemoryDBCfg {
      * Reset cache respects this prefix (won't touch other namespaces!)
      */
     tablesPrefix: string;
+    /**
+     * Many DB implementations (e.g Datastore and Firestore) forbid doing
+     * read operations after a write/delete operation was done inside a Transaction.
+     *
+     * To help spot that type of bug - InMemoryDB by default has this setting to `true`,
+     * which will throw on such occasions.
+     *
+     * Defaults to true.
+     */
+    forbidTransactionReadAfterWrite?: boolean;
     /**
      * @default false
      *
@@ -78,7 +88,7 @@ export declare class InMemoryDB implements CommonDB {
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): ReadableTyped<ROW>;
-    runInTransaction(fn: DBTransactionFn): Promise<void>;
+    runInTransaction(fn: DBTransactionFn, opt?: CommonDBTransactionOptions): Promise<void>;
     /**
      * Flushes all tables (all namespaces) at once.
      */
@@ -90,8 +100,10 @@ export declare class InMemoryDB implements CommonDB {
 }
 export declare class InMemoryDBTransaction implements DBTransaction {
     private db;
-    constructor(db: InMemoryDB);
+    private opt;
+    constructor(db: InMemoryDB, opt: Required<CommonDBTransactionOptions>);
     ops: DBOperation[];
+    writeOperationHappened: boolean;
     getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBOptions): Promise<ROW[]>;
     saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number>;

package/dist/adapter/inmemory/inMemory.db.js

@@ -20,6 +20,7 @@ class InMemoryDB {
         this.cfg = {
             // defaults
             tablesPrefix: '',
+            forbidTransactionReadAfterWrite: true,
             persistenceEnabled: false,
             persistZip: true,
             persistentStoragePath: './tmp/inmemorydb',
@@ -146,8 +147,11 @@ class InMemoryDB {
         const table = this.cfg.tablesPrefix + q.table;
         return node_stream_1.Readable.from((0, __1.queryInMemory)(q, Object.values(this.data[table] || {})));
     }
-    async runInTransaction(fn) {
-        const tx = new InMemoryDBTransaction(this);
+    async runInTransaction(fn, opt = {}) {
+        const tx = new InMemoryDBTransaction(this, {
+            readOnly: false,
+            ...opt,
+        });
         try {
             await fn(tx);
             await tx.commit();
@@ -213,14 +217,22 @@ class InMemoryDB {
 }
 exports.InMemoryDB = InMemoryDB;
 class InMemoryDBTransaction {
-    constructor(db) {
+    constructor(db, opt) {
         this.db = db;
+        this.opt = opt;
         this.ops = [];
+        // used to enforce forbidReadAfterWrite setting
+        this.writeOperationHappened = false;
     }
     async getByIds(table, ids, opt) {
+        if (this.db.cfg.forbidTransactionReadAfterWrite) {
+            (0, js_lib_1._assert)(!this.writeOperationHappened, `InMemoryDBTransaction: read operation attempted after write operation`);
+        }
         return await this.db.getByIds(table, ids, opt);
     }
     async saveBatch(table, rows, opt) {
+        (0, js_lib_1._assert)(!this.opt.readOnly, `InMemoryDBTransaction: saveBatch(${table}) called in readOnly mode`);
+        this.writeOperationHappened = true;
         this.ops.push({
             type: 'saveBatch',
             table,
@@ -229,6 +241,8 @@ class InMemoryDBTransaction {
         });
     }
     async deleteByIds(table, ids, opt) {
+        (0, js_lib_1._assert)(!this.opt.readOnly, `InMemoryDBTransaction: deleteByIds(${table}) called in readOnly mode`);
+        this.writeOperationHappened = true;
         this.ops.push({
             type: 'deleteByIds',
             table,

package/dist/base.common.db.d.ts

@@ -1,7 +1,7 @@
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { CommonDB, CommonDBSupport, CommonDBType } from './common.db';
-import { CommonDBOptions, CommonDBSaveOptions, DBPatch, DBTransactionFn, RunQueryResult } from './db.model';
+import { CommonDBOptions, CommonDBSaveOptions, CommonDBTransactionOptions, DBPatch, DBTransactionFn, RunQueryResult } from './db.model';
 import { DBQuery } from './query/dbQuery';
 /**
  * No-op implementation of CommonDB interface.
@@ -22,5 +22,5 @@ export declare class BaseCommonDB implements CommonDB {
     saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): ReadableTyped<ROW>;
     deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number>;
-    runInTransaction(fn: DBTransactionFn): Promise<void>;
+    runInTransaction(fn: DBTransactionFn, opt?: CommonDBTransactionOptions): Promise<void>;
 }

package/dist/base.common.db.js

@@ -49,7 +49,7 @@ class BaseCommonDB {
     async deleteByIds(table, ids, opt) {
         throw new Error('deleteByIds is not implemented');
     }
-    async runInTransaction(fn) {
+    async runInTransaction(fn, opt) {
         const tx = new dbTransaction_util_1.FakeDBTransaction(this);
         await fn(tx);
         // there's no try/catch and rollback, as there's nothing to rollback

package/dist/common.db.d.ts

@@ -1,6 +1,6 @@
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, DBPatch, DBTransactionFn, RunQueryResult } from './db.model';
+import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBTransactionOptions, DBPatch, DBTransactionFn, RunQueryResult } from './db.model';
 import { DBQuery } from './query/dbQuery';
 export declare enum CommonDBType {
     'document' = "document",
@@ -104,8 +104,11 @@ export interface CommonDB {
      * Transaction is automatically committed if fn resolves normally.
      * Transaction is rolled back if fn throws, the error is re-thrown in that case.
      * Graceful rollback is allowed on tx.rollback()
+     *
+     * By default, transaction is read-write,
+     * unless specified as readOnly in CommonDBTransactionOptions.
      */
-    runInTransaction: (fn: DBTransactionFn) => Promise<void>;
+    runInTransaction: (fn: DBTransactionFn, opt?: CommonDBTransactionOptions) => Promise<void>;
 }
 /**
  * Manifest of supported features.

package/dist/commondao/common.dao.d.ts

@@ -2,7 +2,7 @@
 import { Transform } from 'node:stream';
 import { AnyObject, AsyncMapper, CommonLogger, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Saved, UnixTimestampMillisNumber, Unsaved, ZodSchema } from '@naturalcycles/js-lib';
 import { AjvSchema, ObjectSchema, ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { DBModelType, DBPatch, DBTransaction, RunQueryResult } from '../db.model';
+import { CommonDBTransactionOptions, DBModelType, DBPatch, DBTransaction, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
 import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
 /**
@@ -169,7 +169,7 @@ export declare class CommonDao<BM extends Partial<ObjectWithId>, DBM extends Obj
      * Proxy to this.cfg.db.ping
      */
     ping(): Promise<void>;
-    runInTransaction(fn: CommonDaoTransactionFn): Promise<void>;
+    runInTransaction(fn: CommonDaoTransactionFn, opt?: CommonDBTransactionOptions): Promise<void>;
     protected logResult(started: number, op: string, res: any, table: string): void;
     protected logSaveResult(started: number, op: string, table: string): void;
     protected logStarted(op: string, table: string, force?: boolean): UnixTimestampMillisNumber;

package/dist/commondao/common.dao.js

@@ -991,7 +991,7 @@ class CommonDao {
     async ping() {
         await this.cfg.db.ping();
     }
-    async runInTransaction(fn) {
+    async runInTransaction(fn, opt) {
         await this.cfg.db.runInTransaction(async (tx) => {
             const daoTx = new CommonDaoTransaction(tx, this.cfg.logger);
             try {
@@ -1001,7 +1001,7 @@ class CommonDao {
                 await daoTx.rollback();
                 throw err;
             }
-        });
+        }, opt);
     }
     logResult(started, op, res, table) {
         if (!this.cfg.logLevel)

package/dist/db.model.d.ts

@@ -29,6 +29,13 @@ export interface DBTransaction {
      */
     rollback: () => Promise<void>;
 }
+export interface CommonDBTransactionOptions {
+    /**
+     * Default is false.
+     * If set to true - Transaction is created as read-only.
+     */
+    readOnly?: boolean;
+}
 export interface CommonDBOptions {
     /**
      * If passed - the operation will be performed in the context of that DBTransaction.

package/package.json

@@ -40,7 +40,7 @@
   "engines": {
     "node": ">=18.12"
   },
-  "version": "9.1.1",
+  "version": "9.2.1",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/adapter/inmemory/inMemory.db.ts

@@ -32,6 +32,7 @@ import {
 import {
   CommonDB,
   commonDBFullSupport,
+  CommonDBTransactionOptions,
   CommonDBType,
   DBIncrement,
   DBOperation,
@@ -58,6 +59,17 @@ export interface InMemoryDBCfg {
    */
   tablesPrefix: string
 
+  /**
+   * Many DB implementations (e.g Datastore and Firestore) forbid doing
+   * read operations after a write/delete operation was done inside a Transaction.
+   *
+   * To help spot that type of bug - InMemoryDB by default has this setting to `true`,
+   * which will throw on such occasions.
+   *
+   * Defaults to true.
+   */
+  forbidTransactionReadAfterWrite?: boolean
+
   /**
    * @default false
    *
@@ -96,6 +108,7 @@ export class InMemoryDB implements CommonDB {
     this.cfg = {
       // defaults
       tablesPrefix: '',
+      forbidTransactionReadAfterWrite: true,
       persistenceEnabled: false,
       persistZip: true,
       persistentStoragePath: './tmp/inmemorydb',
@@ -273,8 +286,12 @@ export class InMemoryDB implements CommonDB {
     return Readable.from(queryInMemory(q, Object.values(this.data[table] || {}) as ROW[]))
   }
 
-  async runInTransaction(fn: DBTransactionFn): Promise<void> {
-    const tx = new InMemoryDBTransaction(this)
+  async runInTransaction(fn: DBTransactionFn, opt: CommonDBTransactionOptions = {}): Promise<void> {
+    const tx = new InMemoryDBTransaction(this, {
+      readOnly: false,
+      ...opt,
+    })
+
     try {
       await fn(tx)
       await tx.commit()
@@ -361,15 +378,28 @@ export class InMemoryDB implements CommonDB {
 }
 
 export class InMemoryDBTransaction implements DBTransaction {
-  constructor(private db: InMemoryDB) {}
+  constructor(
+    private db: InMemoryDB,
+    private opt: Required<CommonDBTransactionOptions>,
+  ) {}
 
   ops: DBOperation[] = []
 
+  // used to enforce forbidReadAfterWrite setting
+  writeOperationHappened = false
+
   async getByIds<ROW extends ObjectWithId>(
     table: string,
     ids: string[],
     opt?: CommonDBOptions,
   ): Promise<ROW[]> {
+    if (this.db.cfg.forbidTransactionReadAfterWrite) {
+      _assert(
+        !this.writeOperationHappened,
+        `InMemoryDBTransaction: read operation attempted after write operation`,
+      )
+    }
+
     return await this.db.getByIds(table, ids, opt)
   }
 
@@ -378,6 +408,13 @@ export class InMemoryDBTransaction implements DBTransaction {
     rows: ROW[],
     opt?: CommonDBSaveOptions<ROW>,
   ): Promise<void> {
+    _assert(
+      !this.opt.readOnly,
+      `InMemoryDBTransaction: saveBatch(${table}) called in readOnly mode`,
+    )
+
+    this.writeOperationHappened = true
+
     this.ops.push({
       type: 'saveBatch',
       table,
@@ -387,6 +424,13 @@ export class InMemoryDBTransaction implements DBTransaction {
   }
 
   async deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number> {
+    _assert(
+      !this.opt.readOnly,
+      `InMemoryDBTransaction: deleteByIds(${table}) called in readOnly mode`,
+    )
+
+    this.writeOperationHappened = true
+
     this.ops.push({
       type: 'deleteByIds',
       table,

package/src/base.common.db.ts

@@ -4,6 +4,7 @@ import { CommonDB, CommonDBSupport, CommonDBType } from './common.db'
 import {
   CommonDBOptions,
   CommonDBSaveOptions,
+  CommonDBTransactionOptions,
   DBPatch,
   DBTransactionFn,
   RunQueryResult,
@@ -83,7 +84,7 @@ export class BaseCommonDB implements CommonDB {
     throw new Error('deleteByIds is not implemented')
   }
 
-  async runInTransaction(fn: DBTransactionFn): Promise<void> {
+  async runInTransaction(fn: DBTransactionFn, opt?: CommonDBTransactionOptions): Promise<void> {
     const tx = new FakeDBTransaction(this)
     await fn(tx)
     // there's no try/catch and rollback, as there's nothing to rollback

package/src/common.db.ts

@@ -5,6 +5,7 @@ import {
   CommonDBOptions,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
+  CommonDBTransactionOptions,
   DBPatch,
   DBTransactionFn,
   RunQueryResult,
@@ -163,8 +164,11 @@ export interface CommonDB {
    * Transaction is automatically committed if fn resolves normally.
    * Transaction is rolled back if fn throws, the error is re-thrown in that case.
    * Graceful rollback is allowed on tx.rollback()
+   *
+   * By default, transaction is read-write,
+   * unless specified as readOnly in CommonDBTransactionOptions.
    */
-  runInTransaction: (fn: DBTransactionFn) => Promise<void>
+  runInTransaction: (fn: DBTransactionFn, opt?: CommonDBTransactionOptions) => Promise<void>
 }
 
 /**

package/src/commondao/common.dao.ts

@@ -43,7 +43,13 @@ import {
   writableVoid,
 } from '@naturalcycles/nodejs-lib'
 import { DBLibError } from '../cnst'
-import { DBModelType, DBPatch, DBTransaction, RunQueryResult } from '../db.model'
+import {
+  CommonDBTransactionOptions,
+  DBModelType,
+  DBPatch,
+  DBTransaction,
+  RunQueryResult,
+} from '../db.model'
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery'
 import {
   CommonDaoCfg,
@@ -1331,7 +1337,10 @@ export class CommonDao<
     await this.cfg.db.ping()
   }
 
-  async runInTransaction(fn: CommonDaoTransactionFn): Promise<void> {
+  async runInTransaction(
+    fn: CommonDaoTransactionFn,
+    opt?: CommonDBTransactionOptions,
+  ): Promise<void> {
     await this.cfg.db.runInTransaction(async tx => {
       const daoTx = new CommonDaoTransaction(tx, this.cfg.logger!)
 
@@ -1341,7 +1350,7 @@ export class CommonDao<
         await daoTx.rollback()
         throw err
       }
-    })
+    }, opt)
   }
 
   protected logResult(started: number, op: string, res: any, table: string): void {

package/src/db.model.ts

@@ -34,6 +34,14 @@ export interface DBTransaction {
   rollback: () => Promise<void>
 }
 
+export interface CommonDBTransactionOptions {
+  /**
+   * Default is false.
+   * If set to true - Transaction is created as read-only.
+   */
+  readOnly?: boolean
+}
+
 export interface CommonDBOptions {
   /**
    * If passed - the operation will be performed in the context of that DBTransaction.