@naturalcycles/firestore-lib 1.5.0 → 1.6.0

package/dist/firestore.db.d.ts

@@ -1,5 +1,5 @@
-import { Firestore, Query } from '@google-cloud/firestore';
-import { BaseCommonDB, CommonDB, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, DBQuery, DBTransaction, RunQueryResult } from '@naturalcycles/db-lib';
+import { Firestore, Query, Transaction } from '@google-cloud/firestore';
+import { BaseCommonDB, CommonDB, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBSupport, DBQuery, DBTransaction, RunQueryResult } from '@naturalcycles/db-lib';
 import { ObjectWithId, AnyObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
 export interface FirestoreDBCfg {
@@ -12,16 +12,38 @@ export interface FirestoreDBSaveOptions<ROW extends Partial<ObjectWithId> = AnyO
 export declare class FirestoreDB extends BaseCommonDB implements CommonDB {
     cfg: FirestoreDBCfg;
     constructor(cfg: FirestoreDBCfg);
-    getByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], _opt?: FirestoreDBOptions): Promise<ROW[]>;
+    support: CommonDBSupport;
+    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], _opt?: FirestoreDBOptions): Promise<ROW[]>;
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBOptions): Promise<RunQueryResult<ROW>>;
     runFirestoreQuery<ROW extends ObjectWithId>(q: Query, _opt?: FirestoreDBOptions): Promise<ROW[]>;
     runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: FirestoreDBOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBStreamOptions): ReadableTyped<ROW>;
     saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: FirestoreDBSaveOptions<ROW>): Promise<void>;
     deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBOptions): Promise<number>;
-    deleteByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], _opt?: FirestoreDBOptions): Promise<number>;
+    deleteByIds(table: string, ids: string[], opt?: FirestoreDBOptions): Promise<number>;
     private querySnapshotToArray;
-    commitTransaction(tx: DBTransaction, _opt?: CommonDBSaveOptions): Promise<void>;
+    createTransaction(): Promise<FirestoreDBTransaction>;
     ping(): Promise<void>;
     getTables(): Promise<string[]>;
 }
+/**
+ * https://firebase.google.com/docs/firestore/manage-data/transactions
+ */
+export declare class FirestoreDBTransaction implements DBTransaction {
+    db: FirestoreDB;
+    tx: Transaction;
+    private txPendingDefer;
+    private txCompletedDefer;
+    /**
+     * This defer is held during Transaction and
+     * is released when it's ready to be committed or rolled back.
+     */
+    /**
+     * This is resolved after Transaction is committed or rolled back.
+     * On error - it rejects with that error.
+     */
+    private constructor();
+    static create(db: FirestoreDB): Promise<FirestoreDBTransaction>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}

package/dist/firestore.db.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirestoreDB = void 0;
+exports.FirestoreDBTransaction = exports.FirestoreDB = void 0;
 const db_lib_1 = require("@naturalcycles/db-lib");
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
@@ -15,6 +15,11 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
     constructor(cfg) {
         super();
         this.cfg = cfg;
+        this.support = {
+            ...db_lib_1.commonDBFullSupport,
+            updateByQuery: false,
+            tableSchemas: false,
+        };
     }
     // GET
     async getByIds(table, ids, _opt) {
@@ -79,13 +84,23 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
     }
     // SAVE
     async saveBatch(table, rows, opt = {}) {
+        const { firestore } = this.cfg;
+        const col = firestore.collection(table);
         const method = methodMap[opt.saveMethod] || 'set';
+        if (opt.tx) {
+            const { tx } = opt.tx;
+            rows.forEach(row => {
+                (0, js_lib_1._assert)(row.id, `firestore-db doesn't support id auto-generation, but empty id was provided in saveBatch`);
+                tx[method](col.doc((0, firestore_util_1.escapeDocId)(row.id)), (0, js_lib_1._filterUndefinedValues)(row));
+            });
+            return;
+        }
         // Firestore allows max 500 items in one batch
         await (0, js_lib_1.pMap)((0, js_lib_1._chunk)(rows, 500), async (chunk) => {
-            const batch = this.cfg.firestore.batch();
+            const batch = firestore.batch();
             chunk.forEach(row => {
                 (0, js_lib_1._assert)(row.id, `firestore-db doesn't support id auto-generation, but empty id was provided in saveBatch`);
-                batch[method](this.cfg.firestore.collection(table).doc((0, firestore_util_1.escapeDocId)(row.id)), (0, js_lib_1._filterUndefinedValues)(row));
+                batch[method](col.doc((0, firestore_util_1.escapeDocId)(row.id)), (0, js_lib_1._filterUndefinedValues)(row));
             });
             await batch.commit();
         }, { concurrency: 1 });
@@ -104,11 +119,20 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
         await this.deleteByIds(q.table, ids, opt);
         return ids.length;
     }
-    async deleteByIds(table, ids, _opt) {
+    async deleteByIds(table, ids, opt = {}) {
+        const { firestore } = this.cfg;
+        const col = firestore.collection(table);
+        if (opt.tx) {
+            const { tx } = opt.tx;
+            ids.forEach(id => {
+                tx.delete(col.doc((0, firestore_util_1.escapeDocId)(id)));
+            });
+            return ids.length;
+        }
         await (0, js_lib_1.pMap)((0, js_lib_1._chunk)(ids, 500), async (chunk) => {
-            const batch = this.cfg.firestore.batch();
+            const batch = firestore.batch();
             chunk.forEach(id => {
-                batch.delete(this.cfg.firestore.collection(table).doc((0, firestore_util_1.escapeDocId)(id)));
+                batch.delete(col.doc((0, firestore_util_1.escapeDocId)(id)));
             });
             await batch.commit();
         });
@@ -124,25 +148,30 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
         });
         return rows;
     }
-    async commitTransaction(tx, _opt) {
-        const { firestore } = this.cfg;
-        await firestore.runTransaction(async (tr) => {
-            for (const op of tx.ops) {
-                if (op.type === 'saveBatch') {
-                    op.rows.forEach(row => {
-                        tr.set(firestore.collection(op.table).doc((0, firestore_util_1.escapeDocId)(row.id)), (0, js_lib_1._filterUndefinedValues)(row));
-                    });
-                }
-                else if (op.type === 'deleteByIds') {
-                    op.ids.forEach(id => {
-                        tr.delete(firestore.collection(op.table).doc((0, firestore_util_1.escapeDocId)(id)));
-                    });
-                }
-                else {
-                    throw new Error(`DBOperation not supported: ${op.type}`);
-                }
-            }
-        });
+    // override async commitTransaction(tx: DBTransaction, _opt?: CommonDBSaveOptions): Promise<void> {
+    //   const { firestore } = this.cfg
+    //
+    //   await firestore.runTransaction(async tr => {
+    //     for (const op of tx.ops) {
+    //       if (op.type === 'saveBatch') {
+    //         op.rows.forEach(row => {
+    //           tr.set(
+    //             firestore.collection(op.table).doc(escapeDocId(row.id)),
+    //             _filterUndefinedValues(row),
+    //           )
+    //         })
+    //       } else if (op.type === 'deleteByIds') {
+    //         op.ids.forEach(id => {
+    //           tr.delete(firestore.collection(op.table).doc(escapeDocId(id)))
+    //         })
+    //       } else {
+    //         throw new Error(`DBOperation not supported: ${(op as any).type}`)
+    //       }
+    //     }
+    //   })
+    // }
+    async createTransaction() {
+        return await FirestoreDBTransaction.create(this);
     }
     async ping() {
         // no-op now
@@ -152,3 +181,53 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
     }
 }
 exports.FirestoreDB = FirestoreDB;
+/**
+ * https://firebase.google.com/docs/firestore/manage-data/transactions
+ */
+class FirestoreDBTransaction {
+    /**
+     * This defer is held during Transaction and
+     * is released when it's ready to be committed or rolled back.
+     */
+    // private txPendingDefer = pDefer()
+    /**
+     * This is resolved after Transaction is committed or rolled back.
+     * On error - it rejects with that error.
+     */
+    // private txCompletedDefer = pDefer()
+    constructor(db, tx, txPendingDefer, txCompletedDefer) {
+        this.db = db;
+        this.tx = tx;
+        this.txPendingDefer = txPendingDefer;
+        this.txCompletedDefer = txCompletedDefer;
+    }
+    static async create(db) {
+        const txCreated = (0, js_lib_1.pDefer)();
+        const txPendingDefer = (0, js_lib_1.pDefer)();
+        const txCompletedDefer = (0, js_lib_1.pDefer)();
+        db.cfg.firestore
+            .runTransaction(async (tx) => {
+            txCreated.resolve(tx);
+            // Now we pause and let consumers to use the Transaction,
+            // until commit/rollback is called
+            await txPendingDefer;
+        })
+            .then(() => {
+            txCompletedDefer.resolve();
+        })
+            .catch(err => {
+            txCompletedDefer.reject(err);
+        });
+        const tx = await txCreated;
+        return new FirestoreDBTransaction(db, tx, txPendingDefer, txCompletedDefer);
+    }
+    async commit() {
+        this.txPendingDefer.resolve();
+        await this.txCompletedDefer;
+    }
+    async rollback() {
+        this.txPendingDefer.reject(new Error('rollback'));
+        await this.txCompletedDefer;
+    }
+}
+exports.FirestoreDBTransaction = FirestoreDBTransaction;

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { Firestore } from '@google-cloud/firestore';
-import { FirestoreDB, FirestoreDBCfg, FirestoreDBOptions, FirestoreDBSaveOptions } from './firestore.db';
-import { dbQueryToFirestoreQuery } from './query.util';
-export type { FirestoreDBCfg, FirestoreDBOptions, FirestoreDBSaveOptions };
-export { Firestore, FirestoreDB, dbQueryToFirestoreQuery };
+export * from './firestore.db';
+export * from './query.util';
+export { Firestore };

package/dist/index.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dbQueryToFirestoreQuery = exports.FirestoreDB = exports.Firestore = void 0;
+exports.Firestore = void 0;
+const tslib_1 = require("tslib");
 const firestore_1 = require("@google-cloud/firestore");
 Object.defineProperty(exports, "Firestore", { enumerable: true, get: function () { return firestore_1.Firestore; } });
-const firestore_db_1 = require("./firestore.db");
-Object.defineProperty(exports, "FirestoreDB", { enumerable: true, get: function () { return firestore_db_1.FirestoreDB; } });
-const query_util_1 = require("./query.util");
-Object.defineProperty(exports, "dbQueryToFirestoreQuery", { enumerable: true, get: function () { return query_util_1.dbQueryToFirestoreQuery; } });
+tslib_1.__exportStar(require("./firestore.db"), exports);
+tslib_1.__exportStar(require("./query.util"), exports);

package/package.json

@@ -5,7 +5,7 @@
   },
   "dependencies": {
     "@google-cloud/firestore": "^7.0.0",
-    "@naturalcycles/db-lib": "^8.2.0",
+    "@naturalcycles/db-lib": "^9.0.0",
     "@naturalcycles/js-lib": "^14.6.0",
     "@naturalcycles/nodejs-lib": "^13.1.0"
   },
@@ -14,12 +14,9 @@
     "@naturalcycles/test-lib": "^1.0.3",
     "@types/node": "^20.1.2",
     "dotenv": "^16.0.0",
-    "firebase-admin": "^11.0.0",
+    "firebase-admin": "^12.0.0",
     "jest": "^29.1.2"
   },
-  "resolutions": {
-    "@google-cloud/firestore": "^7.0.0"
-  },
   "files": [
     "dist",
     "src",
@@ -40,7 +37,7 @@
   "engines": {
     "node": ">=18.12.0"
   },
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Firestore implementation of CommonDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT"

package/src/firestore.db.ts

@@ -1,11 +1,19 @@
-import { Firestore, Query, QueryDocumentSnapshot, QuerySnapshot } from '@google-cloud/firestore'
+import {
+  Firestore,
+  Query,
+  QueryDocumentSnapshot,
+  QuerySnapshot,
+  Transaction,
+} from '@google-cloud/firestore'
 import {
   BaseCommonDB,
   CommonDB,
+  commonDBFullSupport,
   CommonDBOptions,
   CommonDBSaveMethod,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
+  CommonDBSupport,
   DBQuery,
   DBTransaction,
   RunQueryResult,
@@ -20,6 +28,8 @@ import {
   AnyObjectWithId,
   _assert,
   _isTruthy,
+  pDefer,
+  DeferredPromise,
 } from '@naturalcycles/js-lib'
 import { ReadableTyped, transformMapSimple } from '@naturalcycles/nodejs-lib'
 import { escapeDocId, unescapeDocId } from './firestore.util'
@@ -33,7 +43,9 @@ export interface FirestoreDBOptions extends CommonDBOptions {}
 export interface FirestoreDBSaveOptions<ROW extends Partial<ObjectWithId> = AnyObjectWithId>
   extends CommonDBSaveOptions<ROW> {}
 
-const methodMap: Record<CommonDBSaveMethod, string> = {
+type SaveOp = 'create' | 'update' | 'set'
+
+const methodMap: Record<CommonDBSaveMethod, SaveOp> = {
   insert: 'create',
   update: 'update',
   upsert: 'set',
@@ -44,10 +56,16 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     super()
   }
 
+  override support: CommonDBSupport = {
+    ...commonDBFullSupport,
+    updateByQuery: false,
+    tableSchemas: false,
+  }
+
   // GET
   override async getByIds<ROW extends ObjectWithId>(
     table: string,
-    ids: ROW['id'][],
+    ids: string[],
     _opt?: FirestoreDBOptions,
   ): Promise<ROW[]> {
     // Oj, doesn't look like a very optimal implementation!
@@ -143,21 +161,37 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     rows: ROW[],
     opt: FirestoreDBSaveOptions<ROW> = {},
   ): Promise<void> {
-    const method = methodMap[opt.saveMethod!] || 'set'
+    const { firestore } = this.cfg
+    const col = firestore.collection(table)
+    const method: SaveOp = methodMap[opt.saveMethod!] || 'set'
+
+    if (opt.tx) {
+      const { tx } = opt.tx as FirestoreDBTransaction
+
+      rows.forEach(row => {
+        _assert(
+          row.id,
+          `firestore-db doesn't support id auto-generation, but empty id was provided in saveBatch`,
+        )
+
+        tx[method as 'set' | 'create'](col.doc(escapeDocId(row.id)), _filterUndefinedValues(row))
+      })
+      return
+    }
 
     // Firestore allows max 500 items in one batch
     await pMap(
       _chunk(rows, 500),
       async chunk => {
-        const batch = this.cfg.firestore.batch()
+        const batch = firestore.batch()
 
         chunk.forEach(row => {
           _assert(
             row.id,
             `firestore-db doesn't support id auto-generation, but empty id was provided in saveBatch`,
           )
-          ;(batch as any)[method](
-            this.cfg.firestore.collection(table).doc(escapeDocId(row.id)),
+          batch[method as 'set' | 'create'](
+            col.doc(escapeDocId(row.id)),
             _filterUndefinedValues(row),
           )
         })
@@ -173,7 +207,7 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     q: DBQuery<ROW>,
     opt?: FirestoreDBOptions,
   ): Promise<number> {
-    let ids: ROW['id'][]
+    let ids: string[]
 
     const idFilter = q._filters.find(f => f.name === 'id')
     if (idFilter) {
@@ -191,16 +225,28 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     return ids.length
   }
 
-  async deleteByIds<ROW extends ObjectWithId>(
+  override async deleteByIds(
     table: string,
-    ids: ROW['id'][],
-    _opt?: FirestoreDBOptions,
+    ids: string[],
+    opt: FirestoreDBOptions = {},
   ): Promise<number> {
+    const { firestore } = this.cfg
+    const col = firestore.collection(table)
+
+    if (opt.tx) {
+      const { tx } = opt.tx as FirestoreDBTransaction
+
+      ids.forEach(id => {
+        tx.delete(col.doc(escapeDocId(id)))
+      })
+      return ids.length
+    }
+
     await pMap(_chunk(ids, 500), async chunk => {
-      const batch = this.cfg.firestore.batch()
+      const batch = firestore.batch()
 
       chunk.forEach(id => {
-        batch.delete(this.cfg.firestore.collection(table).doc(escapeDocId(id)))
+        batch.delete(col.doc(escapeDocId(id)))
       })
 
       await batch.commit()
@@ -222,27 +268,31 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     return rows
   }
 
-  override async commitTransaction(tx: DBTransaction, _opt?: CommonDBSaveOptions): Promise<void> {
-    const { firestore } = this.cfg
-
-    await firestore.runTransaction(async tr => {
-      for (const op of tx.ops) {
-        if (op.type === 'saveBatch') {
-          op.rows.forEach(row => {
-            tr.set(
-              firestore.collection(op.table).doc(escapeDocId(row.id)),
-              _filterUndefinedValues(row),
-            )
-          })
-        } else if (op.type === 'deleteByIds') {
-          op.ids.forEach(id => {
-            tr.delete(firestore.collection(op.table).doc(escapeDocId(id)))
-          })
-        } else {
-          throw new Error(`DBOperation not supported: ${(op as any).type}`)
-        }
-      }
-    })
+  // override async commitTransaction(tx: DBTransaction, _opt?: CommonDBSaveOptions): Promise<void> {
+  //   const { firestore } = this.cfg
+  //
+  //   await firestore.runTransaction(async tr => {
+  //     for (const op of tx.ops) {
+  //       if (op.type === 'saveBatch') {
+  //         op.rows.forEach(row => {
+  //           tr.set(
+  //             firestore.collection(op.table).doc(escapeDocId(row.id)),
+  //             _filterUndefinedValues(row),
+  //           )
+  //         })
+  //       } else if (op.type === 'deleteByIds') {
+  //         op.ids.forEach(id => {
+  //           tr.delete(firestore.collection(op.table).doc(escapeDocId(id)))
+  //         })
+  //       } else {
+  //         throw new Error(`DBOperation not supported: ${(op as any).type}`)
+  //       }
+  //     }
+  //   })
+  // }
+
+  override async createTransaction(): Promise<FirestoreDBTransaction> {
+    return await FirestoreDBTransaction.create(this)
   }
 
   override async ping(): Promise<void> {
@@ -253,3 +303,60 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     return []
   }
 }
+
+/**
+ * https://firebase.google.com/docs/firestore/manage-data/transactions
+ */
+export class FirestoreDBTransaction implements DBTransaction {
+  /**
+   * This defer is held during Transaction and
+   * is released when it's ready to be committed or rolled back.
+   */
+  // private txPendingDefer = pDefer()
+
+  /**
+   * This is resolved after Transaction is committed or rolled back.
+   * On error - it rejects with that error.
+   */
+  // private txCompletedDefer = pDefer()
+
+  private constructor(
+    public db: FirestoreDB,
+    public tx: Transaction,
+    private txPendingDefer: DeferredPromise,
+    private txCompletedDefer: DeferredPromise,
+  ) {}
+
+  static async create(db: FirestoreDB): Promise<FirestoreDBTransaction> {
+    const txCreated = pDefer<Transaction>()
+    const txPendingDefer = pDefer()
+    const txCompletedDefer = pDefer()
+
+    db.cfg.firestore
+      .runTransaction(async tx => {
+        txCreated.resolve(tx)
+
+        // Now we pause and let consumers to use the Transaction,
+        // until commit/rollback is called
+        await txPendingDefer
+      })
+      .then(() => {
+        txCompletedDefer.resolve()
+      })
+      .catch(err => {
+        txCompletedDefer.reject(err)
+      })
+
+    const tx = await txCreated
+    return new FirestoreDBTransaction(db, tx, txPendingDefer, txCompletedDefer)
+  }
+
+  async commit(): Promise<void> {
+    this.txPendingDefer.resolve()
+    await this.txCompletedDefer
+  }
+  async rollback(): Promise<void> {
+    this.txPendingDefer.reject(new Error('rollback'))
+    await this.txCompletedDefer
+  }
+}

package/src/index.ts

@@ -1,12 +1,4 @@
 import { Firestore } from '@google-cloud/firestore'
-import {
-  FirestoreDB,
-  FirestoreDBCfg,
-  FirestoreDBOptions,
-  FirestoreDBSaveOptions,
-} from './firestore.db'
-import { dbQueryToFirestoreQuery } from './query.util'
-
-export type { FirestoreDBCfg, FirestoreDBOptions, FirestoreDBSaveOptions }
-
-export { Firestore, FirestoreDB, dbQueryToFirestoreQuery }
+export * from './firestore.db'
+export * from './query.util'
+export { Firestore }