@naturalcycles/firestore-lib 2.14.4 → 2.15.0

package/dist/firestore.db.d.ts

@@ -12,9 +12,9 @@ export declare class FirestoreDB extends BaseCommonDB implements CommonDB {
     support: CommonDBSupport;
     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>;
+    runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBReadOptions): Promise<RunQueryResult<ROW>>;
+    runFirestoreQuery<ROW extends ObjectWithId>(q: Query, opt?: FirestoreDBReadOptions): Promise<ROW[]>;
+    runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: FirestoreDBReadOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt_?: FirestoreDBStreamOptions): Pipeline<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>;

package/dist/firestore.db.js

@@ -10,7 +10,7 @@ import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 import { escapeDocId, unescapeDocId } from './firestore.util.js';
 import { FirestoreShardedReadable } from './firestoreShardedReadable.js';
 import { FirestoreStreamReadable } from './firestoreStreamReadable.js';
-import { dbQueryToFirestoreQuery } from './query.util.js';
+import { dbQueryToFirestoreQuery, readAtToReadTime } from './query.util.js';
 export class FirestoreDB extends BaseCommonDB {
     constructor(cfg) {
         super();
@@ -30,10 +30,17 @@ export class FirestoreDB extends BaseCommonDB {
     async getByIds(table, ids, opt = {}) {
         if (!ids.length)
             return [];
-        // todo: support PITR: https://firebase.google.com/docs/firestore/enterprise/use-pitr#read-pitr
         const { firestore } = this.cfg;
         const col = firestore.collection(table);
-        return (await (opt.tx?.tx || firestore).getAll(...ids.map(id => col.doc(escapeDocId(id)))))
+        const refs = ids.map(id => col.doc(escapeDocId(id)));
+        const readTime = readAtToReadTime(opt);
+        if (readTime) {
+            _assert(!opt.tx, 'readAt is not supported inside an existing transaction');
+        }
+        const snapshots = await (readTime
+            ? firestore.runTransaction(tx => tx.getAll(...refs), { readOnly: true, readTime })
+            : (opt.tx?.tx || firestore).getAll(...refs));
+        return snapshots
             .map(doc => {
             const data = doc.data();
             if (data === undefined)
@@ -54,7 +61,13 @@ export class FirestoreDB extends BaseCommonDB {
             const col = firestore.collection(table);
             refs.push(...ids.map(id => col.doc(escapeDocId(id))));
         }
-        const snapshots = await (opt.tx?.tx || firestore).getAll(...refs);
+        const readTime = readAtToReadTime(opt);
+        if (readTime) {
+            _assert(!opt.tx, 'readAt is not supported inside an existing transaction');
+        }
+        const snapshots = await (readTime
+            ? firestore.runTransaction(tx => tx.getAll(...refs), { readOnly: true, readTime })
+            : (opt.tx?.tx || firestore).getAll(...refs));
         snapshots.forEach(snap => {
             const data = snap.data();
             if (data === undefined)
@@ -69,7 +82,7 @@ export class FirestoreDB extends BaseCommonDB {
         return result;
     }
     // QUERY
-    async runQuery(q, opt) {
+    async runQuery(q, opt = {}) {
         const idFilter = q._filters.find(f => f.name === 'id');
         if (idFilter) {
             const ids = Array.isArray(idFilter.val) ? idFilter.val : [idFilter.val];
@@ -78,18 +91,34 @@ export class FirestoreDB extends BaseCommonDB {
             };
         }
         const firestoreQuery = dbQueryToFirestoreQuery(q, this.cfg.firestore.collection(q.table));
-        let rows = await this.runFirestoreQuery(firestoreQuery);
+        let rows = await this.runFirestoreQuery(firestoreQuery, opt);
         // Special case when projection query didn't specify 'id'
         if (q._selectedFieldNames && !q._selectedFieldNames.includes('id')) {
             rows = rows.map(r => _omit(r, ['id']));
         }
         return { rows };
     }
-    async runFirestoreQuery(q) {
+    async runFirestoreQuery(q, opt = {}) {
+        const readTime = readAtToReadTime(opt);
+        if (readTime) {
+            const qs = await this.cfg.firestore.runTransaction(tx => tx.get(q), {
+                readOnly: true,
+                readTime,
+            });
+            return this.querySnapshotToArray(qs);
+        }
         return this.querySnapshotToArray(await q.get());
     }
-    async runQueryCount(q, _opt) {
+    async runQueryCount(q, opt = {}) {
         const firestoreQuery = dbQueryToFirestoreQuery(q, this.cfg.firestore.collection(q.table));
+        const readTime = readAtToReadTime(opt);
+        if (readTime) {
+            const r = await this.cfg.firestore.runTransaction(tx => tx.get(firestoreQuery.count()), {
+                readOnly: true,
+                readTime,
+            });
+            return r.data().count;
+        }
         const r = await firestoreQuery.count().get();
         return r.data().count;
     }
@@ -101,7 +130,7 @@ export class FirestoreDB extends BaseCommonDB {
             ...this.cfg.streamOptions,
             ...opt_,
         };
-        if (opt.experimentalCursorStream) {
+        if (opt.experimentalCursorStream || opt.readAt) {
             return Pipeline.from(new FirestoreStreamReadable(firestoreQuery, q, opt));
         }
         if (opt.experimentalShardedStream) {

package/dist/firestoreStreamReadable.d.ts

@@ -18,6 +18,7 @@ export declare class FirestoreStreamReadable<T extends ObjectWithId = any> exten
      * For debugging.
      */
     countReads: number;
+    private readonly readTime?;
     private readonly opt;
     private logger;
     constructor(q: Query, dbQuery: DBQuery<T>, opt: FirestoreDBStreamOptions);

package/dist/firestoreStreamReadable.js

@@ -6,6 +6,7 @@ import { TimeoutError } from '@naturalcycles/js-lib/error/error.util.js';
 import { createCommonLoggerAtLevel } from '@naturalcycles/js-lib/log';
 import { pRetry } from '@naturalcycles/js-lib/promise/pRetry.js';
 import { unescapeDocId } from './firestore.util.js';
+import { readAtToReadTime } from './query.util.js';
 export class FirestoreStreamReadable extends Readable {
     q;
     table;
@@ -20,6 +21,7 @@ export class FirestoreStreamReadable extends Readable {
      * For debugging.
      */
     countReads = 0;
+    readTime;
     opt;
     logger;
     constructor(q, dbQuery, opt) {
@@ -34,7 +36,7 @@ export class FirestoreStreamReadable extends Readable {
             batchSize,
             highWaterMark,
         };
-        // todo: support PITR!
+        this.readTime = readAtToReadTime(opt);
         this.originalLimit = dbQuery._limitValue;
         this.table = dbQuery.table;
         const logger = createCommonLoggerAtLevel(opt.logger, opt.logLevel);
@@ -135,6 +137,12 @@ export class FirestoreStreamReadable extends Readable {
         const { table, logger } = this;
         try {
             return await pRetry(async () => {
+                if (this.readTime) {
+                    return await this.q.firestore.runTransaction(tx => tx.get(q), {
+                        readOnly: true,
+                        readTime: this.readTime,
+                    });
+                }
                 return await q.get();
             }, {
                 name: `FirestoreStreamReadable.query(${table})`,

package/dist/query.util.d.ts

@@ -1,4 +1,6 @@
+import { Timestamp } from '@google-cloud/firestore';
 import type { Query } from '@google-cloud/firestore';
-import type { DBQuery } from '@naturalcycles/db-lib';
+import type { CommonDBReadOptions, DBQuery } from '@naturalcycles/db-lib';
 import type { ObjectWithId } from '@naturalcycles/js-lib/types';
+export declare function readAtToReadTime(opt: CommonDBReadOptions): Timestamp | undefined;
 export declare function dbQueryToFirestoreQuery<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, emptyQuery: Query): Query;

package/dist/query.util.js

@@ -1,4 +1,15 @@
-import { FieldPath } from '@google-cloud/firestore';
+import { FieldPath, Timestamp } from '@google-cloud/firestore';
+import { _round } from '@naturalcycles/js-lib';
+export function readAtToReadTime(opt) {
+    if (!opt.readAt)
+        return;
+    // Same logic as Datastore: round to whole minutes, guard against future
+    let readTimeMs = _round(opt.readAt, 60) * 1000;
+    if (readTimeMs >= Date.now() - 1000) {
+        readTimeMs -= 60_000;
+    }
+    return Timestamp.fromMillis(readTimeMs);
+}
 // Map DBQueryFilterOp to WhereFilterOp
 // Currently it's fully aligned!
 const OP_MAP = {};

package/package.json

@@ -10,8 +10,7 @@
   },
   "devDependencies": {
     "@types/node": "^25",
-    "@typescript/native-preview": "7.0.0-dev.20260201.1",
-    "dotenv": "^17",
+    "@typescript/native-preview": "7.0.0-dev.20260301.1",
     "firebase-admin": "^13",
     "@naturalcycles/dev-lib": "18.4.2"
   },
@@ -39,7 +38,7 @@
   "engines": {
     "node": ">=24.10.0"
   },
-  "version": "2.14.4",
+  "version": "2.15.0",
   "description": "Firestore implementation of CommonDB interface",
   "author": "Natural Cycles Team",
   "license": "MIT",

package/src/firestore.db.ts

@@ -35,7 +35,7 @@ import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream'
 import { escapeDocId, unescapeDocId } from './firestore.util.js'
 import { FirestoreShardedReadable } from './firestoreShardedReadable.js'
 import { FirestoreStreamReadable } from './firestoreStreamReadable.js'
-import { dbQueryToFirestoreQuery } from './query.util.js'
+import { dbQueryToFirestoreQuery, readAtToReadTime } from './query.util.js'
 
 export class FirestoreDB extends BaseCommonDB implements CommonDB {
   constructor(cfg: FirestoreDBCfg) {
@@ -63,16 +63,20 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
   ): Promise<ROW[]> {
     if (!ids.length) return []
 
-    // todo: support PITR: https://firebase.google.com/docs/firestore/enterprise/use-pitr#read-pitr
-
     const { firestore } = this.cfg
     const col = firestore.collection(table)
+    const refs = ids.map(id => col.doc(escapeDocId(id)))
 
-    return (
-      await ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(
-        ...ids.map(id => col.doc(escapeDocId(id))),
-      )
-    )
+    const readTime = readAtToReadTime(opt)
+    if (readTime) {
+      _assert(!opt.tx, 'readAt is not supported inside an existing transaction')
+    }
+
+    const snapshots = await (readTime
+      ? firestore.runTransaction(tx => tx.getAll(...refs), { readOnly: true, readTime })
+      : ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(...refs))
+
+    return snapshots
       .map(doc => {
         const data = doc.data()
         if (data === undefined) return
@@ -97,7 +101,15 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
       refs.push(...ids.map(id => col.doc(escapeDocId(id))))
     }
 
-    const snapshots = await ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(...refs)
+    const readTime = readAtToReadTime(opt)
+    if (readTime) {
+      _assert(!opt.tx, 'readAt is not supported inside an existing transaction')
+    }
+
+    const snapshots = await (readTime
+      ? firestore.runTransaction(tx => tx.getAll(...refs), { readOnly: true, readTime })
+      : ((opt.tx as FirestoreDBTransaction)?.tx || firestore).getAll(...refs))
+
     snapshots.forEach(snap => {
       const data = snap.data()
       if (data === undefined) return
@@ -115,7 +127,7 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
   // QUERY
   override async runQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    opt?: FirestoreDBOptions,
+    opt: FirestoreDBReadOptions = {},
   ): Promise<RunQueryResult<ROW>> {
     const idFilter = q._filters.find(f => f.name === 'id')
     if (idFilter) {
@@ -127,7 +139,7 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
 
     const firestoreQuery = dbQueryToFirestoreQuery(q, this.cfg.firestore.collection(q.table))
 
-    let rows = await this.runFirestoreQuery<ROW>(firestoreQuery)
+    let rows = await this.runFirestoreQuery<ROW>(firestoreQuery, opt)
 
     // Special case when projection query didn't specify 'id'
     if (q._selectedFieldNames && !q._selectedFieldNames.includes('id')) {
@@ -137,15 +149,36 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
     return { rows }
   }
 
-  async runFirestoreQuery<ROW extends ObjectWithId>(q: Query): Promise<ROW[]> {
+  async runFirestoreQuery<ROW extends ObjectWithId>(
+    q: Query,
+    opt: FirestoreDBReadOptions = {},
+  ): Promise<ROW[]> {
+    const readTime = readAtToReadTime(opt)
+    if (readTime) {
+      const qs = await this.cfg.firestore.runTransaction(tx => tx.get(q), {
+        readOnly: true,
+        readTime,
+      })
+      return this.querySnapshotToArray(qs)
+    }
     return this.querySnapshotToArray(await q.get())
   }
 
   override async runQueryCount<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    _opt?: FirestoreDBOptions,
+    opt: FirestoreDBReadOptions = {},
   ): Promise<number> {
     const firestoreQuery = dbQueryToFirestoreQuery(q, this.cfg.firestore.collection(q.table))
+
+    const readTime = readAtToReadTime(opt)
+    if (readTime) {
+      const r = await this.cfg.firestore.runTransaction(tx => tx.get(firestoreQuery.count()), {
+        readOnly: true,
+        readTime,
+      })
+      return r.data().count
+    }
+
     const r = await firestoreQuery.count().get()
     return r.data().count
   }
@@ -163,7 +196,7 @@ export class FirestoreDB extends BaseCommonDB implements CommonDB {
       ...opt_,
     }
 
-    if (opt.experimentalCursorStream) {
+    if (opt.experimentalCursorStream || opt.readAt) {
       return Pipeline.from(new FirestoreStreamReadable(firestoreQuery, q, opt))
     }
 

package/src/firestoreStreamReadable.ts

@@ -1,6 +1,11 @@
 import { Readable } from 'node:stream'
 import { FieldPath } from '@google-cloud/firestore'
-import type { Query, QueryDocumentSnapshot, QuerySnapshot } from '@google-cloud/firestore'
+import type {
+  Query,
+  QueryDocumentSnapshot,
+  QuerySnapshot,
+  Timestamp,
+} from '@google-cloud/firestore'
 import type { DBQuery } from '@naturalcycles/db-lib'
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js'
 import { _ms } from '@naturalcycles/js-lib/datetime/time.util.js'
@@ -12,6 +17,7 @@ import type { ObjectWithId } from '@naturalcycles/js-lib/types'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream'
 import type { FirestoreDBStreamOptions } from './firestore.db.js'
 import { unescapeDocId } from './firestore.util.js'
+import { readAtToReadTime } from './query.util.js'
 
 export class FirestoreStreamReadable<T extends ObjectWithId = any>
   extends Readable
@@ -30,6 +36,7 @@ export class FirestoreStreamReadable<T extends ObjectWithId = any>
    */
   countReads = 0
 
+  private readonly readTime?: Timestamp
   private readonly opt: FirestoreDBStreamOptions & { batchSize: number; highWaterMark: number }
   private logger: CommonLogger
 
@@ -49,7 +56,7 @@ export class FirestoreStreamReadable<T extends ObjectWithId = any>
       batchSize,
       highWaterMark,
     }
-    // todo: support PITR!
+    this.readTime = readAtToReadTime(opt)
 
     this.originalLimit = dbQuery._limitValue
     this.table = dbQuery.table
@@ -176,6 +183,12 @@ export class FirestoreStreamReadable<T extends ObjectWithId = any>
     try {
       return await pRetry(
         async () => {
+          if (this.readTime) {
+            return await this.q.firestore.runTransaction(tx => tx.get(q), {
+              readOnly: true,
+              readTime: this.readTime,
+            })
+          }
           return await q.get()
         },
         {

package/src/query.util.ts

@@ -1,8 +1,21 @@
-import { FieldPath } from '@google-cloud/firestore'
+import { FieldPath, Timestamp } from '@google-cloud/firestore'
 import type { Query, WhereFilterOp } from '@google-cloud/firestore'
-import type { DBQuery, DBQueryFilterOperator } from '@naturalcycles/db-lib'
+import type { CommonDBReadOptions, DBQuery, DBQueryFilterOperator } from '@naturalcycles/db-lib'
+import { _round } from '@naturalcycles/js-lib'
 import type { ObjectWithId } from '@naturalcycles/js-lib/types'
 
+export function readAtToReadTime(opt: CommonDBReadOptions): Timestamp | undefined {
+  if (!opt.readAt) return
+
+  // Same logic as Datastore: round to whole minutes, guard against future
+  let readTimeMs = _round(opt.readAt, 60) * 1000
+  if (readTimeMs >= Date.now() - 1000) {
+    readTimeMs -= 60_000
+  }
+
+  return Timestamp.fromMillis(readTimeMs)
+}
+
 // Map DBQueryFilterOp to WhereFilterOp
 // Currently it's fully aligned!
 const OP_MAP: Partial<Record<DBQueryFilterOperator, WhereFilterOp>> = {