@naturalcycles/firestore-lib 2.5.0 → 2.7.0

package/dist/firestore.db.d.ts

@@ -1,5 +1,5 @@
 import type { Firestore, Query, Transaction } from '@google-cloud/firestore';
-import type { CommonDB, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBSupport, CommonDBTransactionOptions, DBQuery, DBTransaction, DBTransactionFn, RunQueryResult } from '@naturalcycles/db-lib';
+import type { CommonDB, CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBSupport, CommonDBTransactionOptions, DBQuery, DBTransaction, DBTransactionFn, RunQueryResult } from '@naturalcycles/db-lib';
 import { BaseCommonDB } from '@naturalcycles/db-lib';
 import type { ObjectWithId, StringMap } from '@naturalcycles/js-lib/types';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
@@ -8,6 +8,8 @@ export interface FirestoreDBCfg {
 }
 export interface FirestoreDBOptions extends CommonDBOptions {
 }
+export interface FirestoreDBReadOptions extends CommonDBReadOptions {
+}
 export interface FirestoreDBSaveOptions<ROW extends ObjectWithId> extends CommonDBSaveOptions<ROW> {
 }
 export declare class RollbackError extends Error {
@@ -17,14 +19,18 @@ export declare class FirestoreDB extends BaseCommonDB implements CommonDB {
     cfg: FirestoreDBCfg;
     constructor(cfg: FirestoreDBCfg);
     support: CommonDBSupport;
-    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: FirestoreDBOptions): Promise<ROW[]>;
+    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: FirestoreDBReadOptions): Promise<ROW[]>;
+    multiGet<ROW extends ObjectWithId>(map: StringMap<string[]>, opt?: CommonDBReadOptions): Promise<StringMap<ROW[]>>;
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBOptions): Promise<RunQueryResult<ROW>>;
     runFirestoreQuery<ROW extends ObjectWithId>(q: Query): 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 ObjectWithId>(table: string, rows: ROW[], opt?: FirestoreDBSaveOptions<ROW>): Promise<void>;
+    multiSave<ROW extends ObjectWithId>(map: StringMap<ROW[]>, opt?: FirestoreDBSaveOptions<ROW>): Promise<void>;
+    patchById<ROW extends ObjectWithId>(table: string, id: string, patch: Partial<ROW>, opt?: FirestoreDBOptions): Promise<void>;
     deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBOptions): Promise<number>;
     deleteByIds(table: string, ids: string[], opt?: FirestoreDBOptions): Promise<number>;
+    multiDelete(map: StringMap<string[]>, opt?: FirestoreDBOptions): Promise<number>;
     private querySnapshotToArray;
     runInTransaction(fn: DBTransactionFn, opt?: CommonDBTransactionOptions): Promise<void>;
     /**

package/dist/firestore.db.js

@@ -47,6 +47,29 @@ export class FirestoreDB extends BaseCommonDB {
         })
             .filter(_isTruthy);
     }
+    async multiGet(map, opt = {}) {
+        const result = {};
+        const { firestore } = this.cfg;
+        const refs = [];
+        for (const [table, ids] of _stringMapEntries(map)) {
+            result[table] = [];
+            const col = firestore.collection(table);
+            refs.push(...ids.map(id => col.doc(escapeDocId(id))));
+        }
+        const snapshots = await (opt.tx?.tx || firestore).getAll(...refs);
+        snapshots.forEach(snap => {
+            const data = snap.data();
+            if (data === undefined)
+                return;
+            const table = snap.ref.parent.id;
+            const row = {
+                id: unescapeDocId(snap.id),
+                ...data,
+            };
+            result[table].push(row);
+        });
+        return result;
+    }
     // QUERY
     async runQuery(q, opt) {
         const idFilter = q._filters.find(f => f.name === 'id');
@@ -96,6 +119,10 @@ export class FirestoreDB extends BaseCommonDB {
             return;
         }
         await pMap(_chunk(rows, MAX_ITEMS), async (chunk) => {
+            // .batch is called "Atomic batch writer"
+            // Executes multiple writes in a single atomic transaction-like commit — all succeed or all fail.
+            // If any write in the batch fails (e.g., permission error, missing doc), the whole batch fails.
+            // Good for small, related sets of writes where consistency is critical.
             const batch = firestore.batch();
             for (const row of chunk) {
                 _assert(row.id, `firestore-db doesn't support id auto-generation, but empty id was provided in saveBatch`);
@@ -105,6 +132,47 @@ export class FirestoreDB extends BaseCommonDB {
             await batch.commit();
         }, { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY });
     }
+    async multiSave(map, opt = {}) {
+        const { firestore } = this.cfg;
+        const method = methodMap[opt.saveMethod] || 'set';
+        if (opt.tx) {
+            const { tx } = opt.tx;
+            for (const [table, rows] of _stringMapEntries(map)) {
+                const col = firestore.collection(table);
+                for (const row of rows) {
+                    _assert(row.id, `firestore-db doesn't support id auto-generation, but empty id was provided in multiSaveBatch`);
+                    const { id, ...rowWithoutId } = row;
+                    tx[method](col.doc(escapeDocId(id)), _filterUndefinedValues(rowWithoutId));
+                }
+            }
+            return;
+        }
+        const tableRows = [];
+        for (const [table, rows] of _stringMapEntries(map)) {
+            for (const row of rows) {
+                tableRows.push([table, row]);
+            }
+        }
+        await pMap(_chunk(tableRows, MAX_ITEMS), async (chunk) => {
+            const batch = firestore.batch();
+            for (const [table, row] of chunk) {
+                _assert(row.id, `firestore-db doesn't support id auto-generation, but empty id was provided in multiSaveBatch`);
+                const { id, ...rowWithoutId } = row;
+                batch[method](firestore.collection(table).doc(escapeDocId(id)), _filterUndefinedValues(rowWithoutId));
+            }
+            await batch.commit();
+        }, { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY });
+    }
+    async patchById(table, id, patch, opt = {}) {
+        const { firestore } = this.cfg;
+        const col = firestore.collection(table);
+        if (opt.tx) {
+            const { tx } = opt.tx;
+            tx.update(col.doc(escapeDocId(id)), patch);
+            return;
+        }
+        await col.doc(escapeDocId(id)).update(patch);
+    }
     // DELETE
     async deleteByQuery(q, opt) {
         let ids;
@@ -135,11 +203,33 @@ export class FirestoreDB extends BaseCommonDB {
                 batch.delete(col.doc(escapeDocId(id)));
             }
             await batch.commit();
-        }, {
-            concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY,
-        });
+        }, { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY });
         return ids.length;
     }
+    async multiDelete(map, opt = {}) {
+        const { firestore } = this.cfg;
+        const refs = [];
+        for (const [table, ids] of _stringMapEntries(map)) {
+            const col = firestore.collection(table);
+            refs.push(...ids.map(id => col.doc(escapeDocId(id))));
+        }
+        if (opt.tx) {
+            const { tx } = opt.tx;
+            for (const ref of refs) {
+                tx.delete(ref);
+            }
+        }
+        else {
+            await pMap(_chunk(refs, MAX_ITEMS), async (chunk) => {
+                const batch = firestore.batch();
+                for (const ref of chunk) {
+                    batch.delete(ref);
+                }
+                await batch.commit();
+            }, { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY });
+        }
+        return refs.length;
+    }
     querySnapshotToArray(qs) {
         return qs.docs.map(doc => ({
             id: unescapeDocId(doc.id),

package/package.json

@@ -38,7 +38,7 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Firestore implementation of CommonDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT",

package/src/firestore.db.ts

@@ -1,14 +1,17 @@
 import type {
+  DocumentReference,
   Firestore,
   Query,
   QueryDocumentSnapshot,
   QuerySnapshot,
   Transaction,
+  UpdateData,
 } from '@google-cloud/firestore'
 import { FieldValue } from '@google-cloud/firestore'
 import type {
   CommonDB,
   CommonDBOptions,
+  CommonDBReadOptions,
   CommonDBSaveMethod,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
@@ -36,6 +39,7 @@ export interface FirestoreDBCfg {
 }
 
 export interface FirestoreDBOptions extends CommonDBOptions {}
+export interface FirestoreDBReadOptions extends CommonDBReadOptions {}
 export interface FirestoreDBSaveOptions<ROW extends ObjectWithId>
   extends CommonDBSaveOptions<ROW> {}
 
@@ -68,7 +72,7 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
   override async getByIds<ROW extends ObjectWithId>(
     table: string,
     ids: string[],
-    opt: FirestoreDBOptions = {},
+    opt: FirestoreDBReadOptions = {},
   ): Promise<ROW[]> {
     if (!ids.length) return []
 
@@ -91,6 +95,34 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
       .filter(_isTruthy)
   }
 
+  override async multiGet<ROW extends ObjectWithId>(
+    map: StringMap<string[]>,
+    opt: CommonDBReadOptions = {},
+  ): Promise<StringMap<ROW[]>> {
+    const result: StringMap<ROW[]> = {}
+    const { firestore } = this.cfg
+    const refs: DocumentReference[] = []
+    for (const [table, ids] of _stringMapEntries(map)) {
+      result[table] = []
+      const col = firestore.collection(table)
+      refs.push(...ids.map(id => col.doc(escapeDocId(id))))
+    }
+
+    const snapshots = await ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(...refs)
+    snapshots.forEach(snap => {
+      const data = snap.data()
+      if (data === undefined) return
+      const table = snap.ref.parent.id
+      const row = {
+        id: unescapeDocId(snap.id),
+        ...data,
+      } as ROW
+      result[table]!.push(row)
+    })
+
+    return result
+  }
+
   // QUERY
   override async runQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
@@ -174,6 +206,10 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     await pMap(
       _chunk(rows, MAX_ITEMS),
       async chunk => {
+        // .batch is called "Atomic batch writer"
+        // Executes multiple writes in a single atomic transaction-like commit — all succeed or all fail.
+        // If any write in the batch fails (e.g., permission error, missing doc), the whole batch fails.
+        // Good for small, related sets of writes where consistency is critical.
         const batch = firestore.batch()
 
         for (const row of chunk) {
@@ -194,6 +230,82 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     )
   }
 
+  override async multiSave<ROW extends ObjectWithId>(
+    map: StringMap<ROW[]>,
+    opt: FirestoreDBSaveOptions<ROW> = {},
+  ): Promise<void> {
+    const { firestore } = this.cfg
+    const method: SaveOp = methodMap[opt.saveMethod!] || 'set'
+
+    if (opt.tx) {
+      const { tx } = opt.tx as FirestoreDBTransaction
+
+      for (const [table, rows] of _stringMapEntries(map)) {
+        const col = firestore.collection(table)
+        for (const row of rows) {
+          _assert(
+            row.id,
+            `firestore-db doesn't support id auto-generation, but empty id was provided in multiSaveBatch`,
+          )
+
+          const { id, ...rowWithoutId } = row
+          tx[method as 'set' | 'create'](
+            col.doc(escapeDocId(id)),
+            _filterUndefinedValues(rowWithoutId),
+          )
+        }
+      }
+      return
+    }
+
+    const tableRows: TableRow<ROW>[] = []
+    for (const [table, rows] of _stringMapEntries(map)) {
+      for (const row of rows) {
+        tableRows.push([table, row])
+      }
+    }
+
+    await pMap(
+      _chunk(tableRows, MAX_ITEMS),
+      async chunk => {
+        const batch = firestore.batch()
+
+        for (const [table, row] of chunk) {
+          _assert(
+            row.id,
+            `firestore-db doesn't support id auto-generation, but empty id was provided in multiSaveBatch`,
+          )
+          const { id, ...rowWithoutId } = row
+          batch[method as 'set' | 'create'](
+            firestore.collection(table).doc(escapeDocId(id)),
+            _filterUndefinedValues(rowWithoutId),
+          )
+        }
+
+        await batch.commit()
+      },
+      { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY },
+    )
+  }
+
+  override async patchById<ROW extends ObjectWithId>(
+    table: string,
+    id: string,
+    patch: Partial<ROW>,
+    opt: FirestoreDBOptions = {},
+  ): Promise<void> {
+    const { firestore } = this.cfg
+    const col = firestore.collection(table)
+
+    if (opt.tx) {
+      const { tx } = opt.tx as FirestoreDBTransaction
+      tx.update(col.doc(escapeDocId(id)), patch as UpdateData<ROW>)
+      return
+    }
+
+    await col.doc(escapeDocId(id)).update(patch)
+  }
+
   // DELETE
   override async deleteByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
@@ -238,21 +350,50 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
       _chunk(ids, MAX_ITEMS),
       async chunk => {
         const batch = firestore.batch()
-
         for (const id of chunk) {
           batch.delete(col.doc(escapeDocId(id)))
         }
-
         await batch.commit()
       },
-      {
-        concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY,
-      },
+      { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY },
     )
 
     return ids.length
   }
 
+  override async multiDelete(
+    map: StringMap<string[]>,
+    opt: FirestoreDBOptions = {},
+  ): Promise<number> {
+    const { firestore } = this.cfg
+    const refs: DocumentReference[] = []
+    for (const [table, ids] of _stringMapEntries(map)) {
+      const col = firestore.collection(table)
+      refs.push(...ids.map(id => col.doc(escapeDocId(id))))
+    }
+
+    if (opt.tx) {
+      const { tx } = opt.tx as FirestoreDBTransaction
+      for (const ref of refs) {
+        tx.delete(ref)
+      }
+    } else {
+      await pMap(
+        _chunk(refs, MAX_ITEMS),
+        async chunk => {
+          const batch = firestore.batch()
+          for (const ref of chunk) {
+            batch.delete(ref)
+          }
+          await batch.commit()
+        },
+        { concurrency: FIRESTORE_RECOMMENDED_CONCURRENCY },
+      )
+    }
+
+    return refs.length
+  }
+
   private querySnapshotToArray<T = any>(qs: QuerySnapshot): T[] {
     return qs.docs.map(
       doc =>
@@ -366,3 +507,5 @@ export class FirestoreDBTransaction implements DBTransaction {
 const MAX_ITEMS = 500
 // It's an empyrical value, but anything less than infinity is better than infinity
 const FIRESTORE_RECOMMENDED_CONCURRENCY = 8
+
+type TableRow<ROW extends ObjectWithId> = [table: string, row: ROW]