@naturalcycles/firestore-lib 1.5.1 → 1.6.1

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, DBTransactionFn, RunQueryResult } from '@naturalcycles/db-lib';
 import { ObjectWithId, AnyObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
 export interface FirestoreDBCfg {
@@ -9,19 +9,35 @@ export interface FirestoreDBOptions extends CommonDBOptions {
 }
 export interface FirestoreDBSaveOptions<ROW extends Partial<ObjectWithId> = AnyObjectWithId> extends CommonDBSaveOptions<ROW> {
 }
+export declare class RollbackError extends Error {
+    constructor();
+}
 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>;
+    runInTransaction(fn: DBTransactionFn): Promise<void>;
     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;
+    constructor(db: FirestoreDB, tx: Transaction);
+    rollback(): Promise<void>;
+    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/firestore.db.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirestoreDB = void 0;
+exports.FirestoreDBTransaction = exports.FirestoreDB = exports.RollbackError = 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");
@@ -11,23 +11,29 @@ const methodMap = {
     update: 'update',
     upsert: 'set',
 };
+class RollbackError extends Error {
+    constructor() {
+        super('rollback');
+    }
+}
+exports.RollbackError = RollbackError;
 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) {
-        // Oj, doesn't look like a very optimal implementation!
-        // TODO: check if we can query by keys or smth
-        // return (await Promise.all(ids.map(id => this.getById<ROW>(table, id, opt)))).filter(
-        //   Boolean,
-        // ) as ROW[]
+    async getByIds(table, ids, opt = {}) {
         if (!ids.length)
             return [];
         const { firestore } = this.cfg;
         const col = firestore.collection(table);
-        return (await firestore.getAll(...ids.map(id => col.doc((0, firestore_util_1.escapeDocId)(id)))))
+        return (await (opt.tx?.tx || firestore).getAll(...ids.map(id => col.doc((0, firestore_util_1.escapeDocId)(id)))))
             .map(doc => {
             const data = doc.data();
             if (data === undefined)
@@ -79,13 +85,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 +120,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 +149,20 @@ 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}`);
-                }
+    async runInTransaction(fn) {
+        try {
+            await this.cfg.firestore.runTransaction(async (firestoreTx) => {
+                const tx = new FirestoreDBTransaction(this, firestoreTx);
+                await fn(tx);
+            });
+        }
+        catch (err) {
+            if (err instanceof RollbackError) {
+                // RollbackError should be handled gracefully (not re-throw)
+                return;
             }
-        });
+            throw err;
+        }
     }
     async ping() {
         // no-op now
@@ -152,3 +172,25 @@ class FirestoreDB extends db_lib_1.BaseCommonDB {
     }
 }
 exports.FirestoreDB = FirestoreDB;
+/**
+ * https://firebase.google.com/docs/firestore/manage-data/transactions
+ */
+class FirestoreDBTransaction {
+    constructor(db, tx) {
+        this.db = db;
+        this.tx = tx;
+    }
+    async rollback() {
+        throw new RollbackError();
+    }
+    async getByIds(table, ids, opt) {
+        return await this.db.getByIds(table, ids, { ...opt, tx: this });
+    }
+    async saveBatch(table, rows, opt) {
+        await this.db.saveBatch(table, rows, { ...opt, tx: this });
+    }
+    async deleteByIds(table, ids, opt) {
+        return await this.db.deleteByIds(table, ids, { ...opt, tx: this });
+    }
+}
+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"
   },
@@ -37,7 +37,7 @@
   "engines": {
     "node": ">=18.12.0"
   },
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Firestore implementation of CommonDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT"

package/src/firestore.db.ts

@@ -1,13 +1,22 @@
-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,
+  DBTransactionFn,
   RunQueryResult,
 } from '@naturalcycles/db-lib'
 import {
@@ -33,34 +42,47 @@ 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',
 }
 
+export class RollbackError extends Error {
+  constructor() {
+    super('rollback')
+  }
+}
+
 export class FirestoreDB extends BaseCommonDB implements CommonDB {
   constructor(public cfg: FirestoreDBCfg) {
     super()
   }
 
+  override support: CommonDBSupport = {
+    ...commonDBFullSupport,
+    updateByQuery: false,
+    tableSchemas: false,
+  }
+
   // GET
   override async getByIds<ROW extends ObjectWithId>(
     table: string,
-    ids: ROW['id'][],
-    _opt?: FirestoreDBOptions,
+    ids: string[],
+    opt: FirestoreDBOptions = {},
   ): Promise<ROW[]> {
-    // Oj, doesn't look like a very optimal implementation!
-    // TODO: check if we can query by keys or smth
-    // return (await Promise.all(ids.map(id => this.getById<ROW>(table, id, opt)))).filter(
-    //   Boolean,
-    // ) as ROW[]
     if (!ids.length) return []
 
     const { firestore } = this.cfg
     const col = firestore.collection(table)
 
-    return (await firestore.getAll(...ids.map(id => col.doc(escapeDocId(id)))))
+    return (
+      await ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(
+        ...ids.map(id => col.doc(escapeDocId(id))),
+      )
+    )
       .map(doc => {
         const data = doc.data()
         if (data === undefined) return
@@ -143,21 +165,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 +211,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 +229,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 +272,19 @@ 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 runInTransaction(fn: DBTransactionFn): Promise<void> {
+    try {
+      await this.cfg.firestore.runTransaction(async firestoreTx => {
+        const tx = new FirestoreDBTransaction(this, firestoreTx)
+        await fn(tx)
+      })
+    } catch (err) {
+      if (err instanceof RollbackError) {
+        // RollbackError should be handled gracefully (not re-throw)
+        return
       }
-    })
+      throw err
+    }
   }
 
   override async ping(): Promise<void> {
@@ -253,3 +295,37 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     return []
   }
 }
+
+/**
+ * https://firebase.google.com/docs/firestore/manage-data/transactions
+ */
+export class FirestoreDBTransaction implements DBTransaction {
+  constructor(
+    public db: FirestoreDB,
+    public tx: Transaction,
+  ) {}
+
+  async rollback(): Promise<void> {
+    throw new RollbackError()
+  }
+
+  async getByIds<ROW extends ObjectWithId>(
+    table: string,
+    ids: string[],
+    opt?: CommonDBOptions,
+  ): Promise<ROW[]> {
+    return await this.db.getByIds(table, ids, { ...opt, tx: this })
+  }
+
+  async saveBatch<ROW extends Partial<ObjectWithId>>(
+    table: string,
+    rows: ROW[],
+    opt?: CommonDBSaveOptions<ROW>,
+  ): Promise<void> {
+    await this.db.saveBatch(table, rows, { ...opt, tx: this })
+  }
+
+  async deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number> {
+    return await this.db.deleteByIds(table, ids, { ...opt, tx: this })
+  }
+}

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 }