@naturalcycles/datastore-lib 3.38.3 → 3.39.1

package/dist/DatastoreStreamReadable.d.ts

@@ -6,20 +6,21 @@ import type { DatastoreDBStreamOptions } from './datastore.model';
 export declare class DatastoreStreamReadable<T = any> extends Readable implements ReadableTyped<T> {
     private q;
     private logger;
-    private originalLimit;
+    private readonly originalLimit;
     private rowsRetrieved;
     private endCursor?;
     private running;
     private done;
     private lastQueryDone?;
     private totalWait;
-    private table;
+    private readonly table;
     /**
      * Used to support maxWait
      */
     private lastReadTimestamp;
-    private maxWaitInterval;
-    private opt;
+    private readonly maxWaitInterval;
+    private readonly opt;
+    private readonly dsOpt;
     constructor(q: Query, opt: DatastoreDBStreamOptions, logger: CommonLogger);
     private runNextQuery;
     /**

package/dist/DatastoreStreamReadable.js

@@ -26,6 +26,11 @@ class DatastoreStreamReadable extends node_stream_1.Readable {
             batchSize: 1000,
             ...opt,
         };
+        this.dsOpt = {};
+        if (opt.readAt) {
+            // Datastore expects UnixTimestamp in milliseconds
+            this.dsOpt.readTime = opt.readAt * 1000;
+        }
         this.originalLimit = q.limitVal;
         this.table = q.kinds[0];
         logger.log(`!! using experimentalCursorStream !! ${this.table}, batchSize: ${opt.batchSize}`);
@@ -71,7 +76,7 @@ class DatastoreStreamReadable extends node_stream_1.Readable {
         let info = {};
         try {
             await (0, js_lib_1.pRetry)(async () => {
-                const res = await q.run();
+                const res = await q.run(this.dsOpt);
                 rows = res[0];
                 info = res[1];
             }, {

package/dist/datastore.db.d.ts

@@ -1,9 +1,9 @@
-import type { Datastore, Key, Query } from '@google-cloud/datastore';
+import type { Datastore, Key } from '@google-cloud/datastore';
 import { Transaction } from '@google-cloud/datastore';
-import { BaseCommonDB, CommonDB, CommonDBOptions, CommonDBSaveOptions, CommonDBSupport, CommonDBTransactionOptions, DBQuery, DBTransaction, DBTransactionFn, RunQueryResult } from '@naturalcycles/db-lib';
+import { BaseCommonDB, CommonDB, CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions, CommonDBSupport, CommonDBTransactionOptions, DBQuery, DBTransaction, DBTransactionFn, RunQueryResult } from '@naturalcycles/db-lib';
 import { CommonLogger, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { DatastoreDBCfg, DatastoreDBOptions, DatastoreDBSaveOptions, DatastoreDBStreamOptions, DatastorePayload, DatastorePropertyStats, DatastoreStats } from './datastore.model';
+import { DatastoreDBCfg, DatastoreDBOptions, DatastoreDBReadOptions, DatastoreDBSaveOptions, DatastoreDBStreamOptions, DatastorePropertyStats, DatastoreStats } from './datastore.model';
 /**
  * Datastore API:
  * https://googlecloudplatform.github.io/google-cloud-node/#/docs/datastore/1.0.3/datastore
@@ -22,17 +22,17 @@ export declare class DatastoreDB extends BaseCommonDB implements CommonDB {
     protected KEY: symbol;
     ds(): Datastore;
     ping(): Promise<void>;
-    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: DatastoreDBOptions): Promise<ROW[]>;
-    runQuery<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, _opt?: DatastoreDBOptions): Promise<RunQueryResult<ROW>>;
-    runQueryCount<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, _opt?: DatastoreDBOptions): Promise<number>;
-    runDatastoreQuery<ROW extends ObjectWithId>(q: Query): Promise<RunQueryResult<ROW>>;
+    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: DatastoreDBReadOptions): Promise<ROW[]>;
+    runQuery<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, opt?: DatastoreDBReadOptions): Promise<RunQueryResult<ROW>>;
+    runQueryCount<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, opt?: DatastoreDBReadOptions): Promise<number>;
+    private runDatastoreQuery;
     private runQueryStream;
     streamQuery<ROW extends ObjectWithId>(dbQuery: DBQuery<ROW>, opt?: DatastoreDBStreamOptions): ReadableTyped<ROW>;
     /**
      * Returns saved entities with generated id/updated/created (non-mutating!)
      */
     saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: DatastoreDBSaveOptions<ROW>): Promise<void>;
-    deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: DatastoreDBOptions): Promise<number>;
+    deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: DatastoreDBReadOptions): Promise<number>;
     /**
      * Limitation: Datastore's delete returns void, so we always return all ids here as "deleted"
      * regardless if they were actually deleted or not.
@@ -46,12 +46,10 @@ export declare class DatastoreDB extends BaseCommonDB implements CommonDB {
     getStats(table: string): Promise<DatastoreStats | undefined>;
     getStatsCount(table: string): Promise<number | undefined>;
     getTableProperties(table: string): Promise<DatastorePropertyStats[]>;
-    mapId<T extends ObjectWithId>(o: any, preserveKey?: boolean): T;
-    toDatastoreEntity<T = any>(kind: string, o: T & {
-        id?: string | number;
-    }, excludeFromIndexes?: string[]): DatastorePayload<T>;
-    key(kind: string, id: string | number): Key;
-    getDsKey(o: any): Key | undefined;
+    private mapId;
+    private toDatastoreEntity;
+    key(kind: string, id: string): Key;
+    private getDsKey;
     getKey(key: Key): string | undefined;
     createTable<ROW extends ObjectWithId>(_table: string, _schema: JsonSchemaObject<ROW>): Promise<void>;
     getTables(): Promise<string[]>;
@@ -62,6 +60,7 @@ export declare class DatastoreDB extends BaseCommonDB implements CommonDB {
      * It may happen that transaction is already committed/rolled back, so we don't want to throw an error here.
      */
     private rollback;
+    private getRunQueryOptions;
 }
 /**
  * https://cloud.google.com/datastore/docs/concepts/transactions#datastore-datastore-transactional-update-nodejs
@@ -71,7 +70,7 @@ export declare class DatastoreDBTransaction implements DBTransaction {
     tx: Transaction;
     constructor(db: DatastoreDB, tx: Transaction);
     rollback(): Promise<void>;
-    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBOptions): Promise<ROW[]>;
+    getByIds<ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBReadOptions): Promise<ROW[]>;
     saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number>;
 }

package/dist/datastore.db.js

@@ -76,10 +76,11 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
             return [];
         const keys = ids.map(id => this.key(table, id));
         let rows;
+        const dsOpt = this.getRunQueryOptions(opt);
         if (this.cfg.timeout) {
             // First try
             try {
-                const r = await (0, js_lib_1.pTimeout)(() => (opt.tx?.tx || this.ds()).get(keys), {
+                const r = await (0, js_lib_1.pTimeout)(() => (opt.tx?.tx || this.ds()).get(keys, dsOpt), {
                     timeout: this.cfg.timeout,
                     name: `datastore.getByIds(${table})`,
                 });
@@ -92,7 +93,7 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
                 const DS = datastoreLib.Datastore;
                 this.cachedDatastore = new DS(this.cfg);
                 // Second try (will throw)
-                const r = await (0, js_lib_1.pRetry)(() => (opt.tx?.tx || this.ds()).get(keys), {
+                const r = await (0, js_lib_1.pRetry)(() => (opt.tx?.tx || this.ds()).get(keys, dsOpt), {
                     ...this.getPRetryOptions(`datastore.getByIds(${table}) second try`),
                     maxAttempts: 3,
                     timeout: this.cfg.timeout,
@@ -106,7 +107,7 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
         }
         else {
             rows = await (0, js_lib_1.pRetry)(async () => {
-                return (await this.ds().get(keys))[0];
+                return (await this.ds().get(keys, dsOpt))[0];
             }, this.getPRetryOptions(`datastore.getByIds(${table})`));
         }
         return (rows
@@ -119,30 +120,32 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
     //   if (!q?.kinds?.length) return '' // should never be the case, but
     //   return q.kinds[0]!
     // }
-    async runQuery(dbQuery, _opt) {
+    async runQuery(dbQuery, opt = {}) {
         const idFilter = dbQuery._filters.find(f => f.name === 'id');
         if (idFilter) {
             const ids = idFilter.op === '==' ? [idFilter.val] : idFilter.val;
             return {
-                rows: await this.getByIds(dbQuery.table, ids),
+                rows: await this.getByIds(dbQuery.table, ids, opt),
             };
         }
         const q = (0, query_util_1.dbQueryToDatastoreQuery)(dbQuery, this.ds().createQuery(dbQuery.table));
-        const qr = await this.runDatastoreQuery(q);
+        const dsOpt = this.getRunQueryOptions(opt);
+        const qr = await this.runDatastoreQuery(q, dsOpt);
         // Special case when projection query didn't specify 'id'
         if (dbQuery._selectedFieldNames && !dbQuery._selectedFieldNames.includes('id')) {
             qr.rows = qr.rows.map(r => (0, js_lib_1._omit)(r, ['id']));
         }
         return qr;
     }
-    async runQueryCount(dbQuery, _opt) {
+    async runQueryCount(dbQuery, opt = {}) {
         const q = (0, query_util_1.dbQueryToDatastoreQuery)(dbQuery.select([]), this.ds().createQuery(dbQuery.table));
         const aq = this.ds().createAggregationQuery(q).count('count');
-        const [entities] = await this.ds().runAggregationQuery(aq);
+        const dsOpt = this.getRunQueryOptions(opt);
+        const [entities] = await this.ds().runAggregationQuery(aq, dsOpt);
         return entities[0]?.count;
     }
-    async runDatastoreQuery(q) {
-        const [entities, queryResult] = await this.ds().runQuery(q);
+    async runDatastoreQuery(q, dsOpt) {
+        const [entities, queryResult] = await this.ds().runQuery(q, dsOpt);
         const rows = entities.map(e => this.mapId(e));
         return {
             ...queryResult,
@@ -154,9 +157,10 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
             ...this.cfg.streamOptions,
             ..._opt,
         };
+        const dsOpt = this.getRunQueryOptions(opt);
         return (opt.experimentalCursorStream
             ? new DatastoreStreamReadable_1.DatastoreStreamReadable(q, opt, (0, js_lib_1.commonLoggerMinLevel)(this.cfg.logger, opt.debug ? 'log' : 'warn'))
-            : this.ds().runQueryStream(q)).map(chunk => this.mapId(chunk));
+            : this.ds().runQueryStream(q, dsOpt)).map(chunk => this.mapId(chunk));
     }
     streamQuery(dbQuery, opt) {
         const q = (0, query_util_1.dbQueryToDatastoreQuery)(dbQuery, this.ds().createQuery(dbQuery.table));
@@ -190,14 +194,15 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
             throw err;
         }
     }
-    async deleteByQuery(q, opt) {
+    async deleteByQuery(q, opt = {}) {
         const idFilter = q._filters.find(f => f.name === 'id');
         if (idFilter) {
             const ids = idFilter.op === '==' ? [idFilter.val] : idFilter.val;
             return await this.deleteByIds(q.table, ids, opt);
         }
         const datastoreQuery = (0, query_util_1.dbQueryToDatastoreQuery)(q.select([]), this.ds().createQuery(q.table));
-        const { rows } = await this.runDatastoreQuery(datastoreQuery);
+        const dsOpt = this.getRunQueryOptions(opt);
+        const { rows } = await this.runDatastoreQuery(datastoreQuery, dsOpt);
         return await this.deleteByIds(q.table, rows.map(obj => obj.id), opt);
     }
     /**
@@ -282,7 +287,7 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
     }
     key(kind, id) {
         (0, js_lib_1._assert)(id, `Cannot save "${kind}" entity without "id"`);
-        return this.ds().key([kind, String(id)]);
+        return this.ds().key([kind, id]);
     }
     getDsKey(o) {
         return o?.[this.KEY];
@@ -392,6 +397,14 @@ class DatastoreDB extends db_lib_1.BaseCommonDB {
             this.cfg.logger.error(err);
         }
     }
+    getRunQueryOptions(opt) {
+        if (!opt.readAt)
+            return {};
+        return {
+            // Datastore expects UnixTimestamp in milliseconds
+            readTime: opt.readAt * 1000,
+        };
+    }
 }
 exports.DatastoreDB = DatastoreDB;
 /**

package/dist/datastore.model.d.ts

@@ -1,5 +1,5 @@
 import type { DatastoreOptions, Key } from '@google-cloud/datastore';
-import { CommonDBOptions, CommonDBSaveOptions } from '@naturalcycles/db-lib';
+import { CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions } from '@naturalcycles/db-lib';
 import { CommonLogger, NumberOfSeconds, ObjectWithId } from '@naturalcycles/js-lib';
 export interface DatastorePayload<T = any> {
     key: Key;
@@ -47,7 +47,7 @@ export interface DatastoreCredentials {
     client_secret?: string;
     refresh_token?: string;
 }
-export interface DatastoreDBStreamOptions extends DatastoreDBOptions {
+export interface DatastoreDBStreamOptions extends DatastoreDBReadOptions {
     /**
      * Set to `true` to stream via experimental "cursor-query based stream".
      *
@@ -101,6 +101,8 @@ export interface DatastoreDBStreamOptions extends DatastoreDBOptions {
 }
 export interface DatastoreDBOptions extends CommonDBOptions {
 }
+export interface DatastoreDBReadOptions extends CommonDBReadOptions {
+}
 export interface DatastoreDBSaveOptions<ROW extends ObjectWithId> extends CommonDBSaveOptions<ROW> {
 }
 export interface DatastoreStats {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/datastore-lib",
-  "version": "3.38.3",
+  "version": "3.39.1",
   "description": "Opinionated library to work with Google Datastore",
   "scripts": {
     "prepare": "husky",

package/src/DatastoreStreamReadable.ts

@@ -1,26 +1,27 @@
 import { Readable } from 'node:stream'
 import { Query } from '@google-cloud/datastore'
-import type { RunQueryInfo } from '@google-cloud/datastore/build/src/query'
-import { _ms, CommonLogger, pRetry, UnixTimestampMillisNumber } from '@naturalcycles/js-lib'
+import type { RunQueryInfo, RunQueryOptions } from '@google-cloud/datastore/build/src/query'
+import { _ms, CommonLogger, pRetry, UnixTimestampMillis } from '@naturalcycles/js-lib'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import type { DatastoreDBStreamOptions } from './datastore.model'
 
 export class DatastoreStreamReadable<T = any> extends Readable implements ReadableTyped<T> {
-  private originalLimit: number
+  private readonly originalLimit: number
   private rowsRetrieved = 0
   private endCursor?: string
   private running = false
   private done = false
   private lastQueryDone?: number
   private totalWait = 0
-  private table: string
+  private readonly table: string
   /**
    * Used to support maxWait
    */
-  private lastReadTimestamp: UnixTimestampMillisNumber = 0
-  private maxWaitInterval: NodeJS.Timeout | undefined
+  private lastReadTimestamp = 0 as UnixTimestampMillis
+  private readonly maxWaitInterval: NodeJS.Timeout | undefined
 
-  private opt: DatastoreDBStreamOptions & { batchSize: number }
+  private readonly opt: DatastoreDBStreamOptions & { batchSize: number }
+  private readonly dsOpt: RunQueryOptions
 
   constructor(
     private q: Query,
@@ -34,6 +35,11 @@ export class DatastoreStreamReadable<T = any> extends Readable implements Readab
       batchSize: 1000,
       ...opt,
     }
+    this.dsOpt = {}
+    if (opt.readAt) {
+      // Datastore expects UnixTimestamp in milliseconds
+      this.dsOpt.readTime = opt.readAt * 1000
+    }
 
     this.originalLimit = q.limitVal
     this.table = q.kinds[0]!
@@ -99,7 +105,7 @@ export class DatastoreStreamReadable<T = any> extends Readable implements Readab
     try {
       await pRetry(
         async () => {
-          const res = await q.run()
+          const res = await q.run(this.dsOpt)
           rows = res[0]
           info = res[1]
         },
@@ -181,7 +187,7 @@ export class DatastoreStreamReadable<T = any> extends Readable implements Readab
   count = 0
 
   override _read(): void {
-    this.lastReadTimestamp = Date.now()
+    this.lastReadTimestamp = Date.now() as UnixTimestampMillis
 
     // console.log(`_read called ${++this.count}, wasRunning: ${this.running}`) // debugging
     this.count++

package/src/datastore.db.ts

@@ -1,10 +1,12 @@
 import type { Datastore, Key, Query } from '@google-cloud/datastore'
 import { PropertyFilter, Transaction } from '@google-cloud/datastore'
+import { type RunQueryOptions } from '@google-cloud/datastore/build/src/query'
 import {
   BaseCommonDB,
   CommonDB,
   commonDBFullSupport,
   CommonDBOptions,
+  CommonDBReadOptions,
   CommonDBSaveMethod,
   CommonDBSaveOptions,
   CommonDBSupport,
@@ -38,6 +40,7 @@ import { boldWhite, ReadableTyped } from '@naturalcycles/nodejs-lib'
 import {
   DatastoreDBCfg,
   DatastoreDBOptions,
+  DatastoreDBReadOptions,
   DatastoreDBSaveOptions,
   DatastoreDBStreamOptions,
   DatastorePayload,
@@ -138,17 +141,19 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
   override async getByIds<ROW extends ObjectWithId>(
     table: string,
     ids: string[],
-    opt: DatastoreDBOptions = {},
+    opt: DatastoreDBReadOptions = {},
   ): Promise<ROW[]> {
     if (!ids.length) return []
     const keys = ids.map(id => this.key(table, id))
     let rows: any[]
 
+    const dsOpt = this.getRunQueryOptions(opt)
+
     if (this.cfg.timeout) {
       // First try
       try {
         const r = await pTimeout(
-          () => ((opt.tx as DatastoreDBTransaction)?.tx || this.ds()).get(keys),
+          () => ((opt.tx as DatastoreDBTransaction)?.tx || this.ds()).get(keys, dsOpt),
           {
             timeout: this.cfg.timeout,
             name: `datastore.getByIds(${table})`,
@@ -165,7 +170,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
 
         // Second try (will throw)
         const r = await pRetry(
-          () => ((opt.tx as DatastoreDBTransaction)?.tx || this.ds()).get(keys),
+          () => ((opt.tx as DatastoreDBTransaction)?.tx || this.ds()).get(keys, dsOpt),
           {
             ...this.getPRetryOptions(`datastore.getByIds(${table}) second try`),
             maxAttempts: 3,
@@ -181,7 +186,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
     } else {
       rows = await pRetry(
         async () => {
-          return (await this.ds().get(keys))[0]
+          return (await this.ds().get(keys, dsOpt))[0]
         },
         this.getPRetryOptions(`datastore.getByIds(${table})`),
       )
@@ -203,19 +208,20 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
 
   override async runQuery<ROW extends ObjectWithId>(
     dbQuery: DBQuery<ROW>,
-    _opt?: DatastoreDBOptions,
+    opt: DatastoreDBReadOptions = {},
   ): Promise<RunQueryResult<ROW>> {
     const idFilter = dbQuery._filters.find(f => f.name === 'id')
     if (idFilter) {
       const ids: string[] = idFilter.op === '==' ? [idFilter.val] : idFilter.val
 
       return {
-        rows: await this.getByIds(dbQuery.table, ids),
+        rows: await this.getByIds(dbQuery.table, ids, opt),
       }
     }
 
     const q = dbQueryToDatastoreQuery(dbQuery, this.ds().createQuery(dbQuery.table))
-    const qr = await this.runDatastoreQuery<ROW>(q)
+    const dsOpt = this.getRunQueryOptions(opt)
+    const qr = await this.runDatastoreQuery<ROW>(q, dsOpt)
 
     // Special case when projection query didn't specify 'id'
     if (dbQuery._selectedFieldNames && !dbQuery._selectedFieldNames.includes('id')) {
@@ -227,16 +233,20 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
 
   override async runQueryCount<ROW extends ObjectWithId>(
     dbQuery: DBQuery<ROW>,
-    _opt?: DatastoreDBOptions,
+    opt: DatastoreDBReadOptions = {},
   ): Promise<number> {
     const q = dbQueryToDatastoreQuery(dbQuery.select([]), this.ds().createQuery(dbQuery.table))
     const aq = this.ds().createAggregationQuery(q).count('count')
-    const [entities] = await this.ds().runAggregationQuery(aq)
+    const dsOpt = this.getRunQueryOptions(opt)
+    const [entities] = await this.ds().runAggregationQuery(aq, dsOpt)
     return entities[0]?.count
   }
 
-  async runDatastoreQuery<ROW extends ObjectWithId>(q: Query): Promise<RunQueryResult<ROW>> {
-    const [entities, queryResult] = await this.ds().runQuery(q)
+  private async runDatastoreQuery<ROW extends ObjectWithId>(
+    q: Query,
+    dsOpt: RunQueryOptions,
+  ): Promise<RunQueryResult<ROW>> {
+    const [entities, queryResult] = await this.ds().runQuery(q, dsOpt)
 
     const rows = entities.map(e => this.mapId<ROW>(e))
 
@@ -254,6 +264,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
       ...this.cfg.streamOptions,
       ..._opt,
     }
+    const dsOpt = this.getRunQueryOptions(opt)
 
     return (
       opt.experimentalCursorStream
@@ -262,7 +273,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
             opt,
             commonLoggerMinLevel(this.cfg.logger, opt.debug ? 'log' : 'warn'),
           )
-        : (this.ds().runQueryStream(q) as ReadableTyped<ROW>)
+        : (this.ds().runQueryStream(q, dsOpt) as ReadableTyped<ROW>)
     ).map(chunk => this.mapId(chunk))
   }
 
@@ -320,7 +331,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
 
   override async deleteByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    opt?: DatastoreDBOptions,
+    opt: DatastoreDBReadOptions = {},
   ): Promise<number> {
     const idFilter = q._filters.find(f => f.name === 'id')
     if (idFilter) {
@@ -329,7 +340,8 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
     }
 
     const datastoreQuery = dbQueryToDatastoreQuery(q.select([]), this.ds().createQuery(q.table))
-    const { rows } = await this.runDatastoreQuery<ROW>(datastoreQuery)
+    const dsOpt = this.getRunQueryOptions(opt)
+    const { rows } = await this.runDatastoreQuery<ROW>(datastoreQuery, dsOpt)
     return await this.deleteByIds(
       q.table,
       rows.map(obj => obj.id),
@@ -413,7 +425,7 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
     return stats
   }
 
-  mapId<T extends ObjectWithId>(o: any, preserveKey = false): T {
+  private mapId<T extends ObjectWithId>(o: any, preserveKey = false): T {
     if (!o) return o
     const r = {
       ...o,
@@ -424,12 +436,12 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
   }
 
   // if key field exists on entity, it will be used as key (prevent to duplication of numeric keyed entities)
-  toDatastoreEntity<T = any>(
+  private toDatastoreEntity<T extends ObjectWithId>(
     kind: string,
-    o: T & { id?: string | number },
+    o: T,
     excludeFromIndexes: string[] = [],
   ): DatastorePayload<T> {
-    const key = this.getDsKey(o) || this.key(kind, o.id!)
+    const key = this.getDsKey(o) || this.key(kind, o.id)
     const data = Object.assign({}, o) as any
     delete data.id
     delete data[this.KEY]
@@ -441,12 +453,12 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
     }
   }
 
-  key(kind: string, id: string | number): Key {
+  key(kind: string, id: string): Key {
     _assert(id, `Cannot save "${kind}" entity without "id"`)
-    return this.ds().key([kind, String(id)])
+    return this.ds().key([kind, id])
   }
 
-  getDsKey(o: any): Key | undefined {
+  private getDsKey(o: any): Key | undefined {
     return o?.[this.KEY]
   }
 
@@ -562,6 +574,15 @@ export class DatastoreDB extends BaseCommonDB implements CommonDB {
       this.cfg.logger.error(err)
     }
   }
+
+  private getRunQueryOptions(opt: DatastoreDBReadOptions): RunQueryOptions {
+    if (!opt.readAt) return {}
+
+    return {
+      // Datastore expects UnixTimestamp in milliseconds
+      readTime: opt.readAt * 1000,
+    }
+  }
 }
 
 /**
@@ -585,7 +606,7 @@ export class DatastoreDBTransaction implements DBTransaction {
   async getByIds<ROW extends ObjectWithId>(
     table: string,
     ids: string[],
-    opt?: CommonDBOptions,
+    opt?: CommonDBReadOptions,
   ): Promise<ROW[]> {
     return await this.db.getByIds(table, ids, { ...opt, tx: this })
   }

package/src/datastore.model.ts

@@ -1,5 +1,5 @@
 import type { DatastoreOptions, Key } from '@google-cloud/datastore'
-import { CommonDBOptions, CommonDBSaveOptions } from '@naturalcycles/db-lib'
+import { CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions } from '@naturalcycles/db-lib'
 import { CommonLogger, NumberOfSeconds, ObjectWithId } from '@naturalcycles/js-lib'
 
 export interface DatastorePayload<T = any> {
@@ -56,7 +56,7 @@ export interface DatastoreCredentials {
   refresh_token?: string
 }
 
-export interface DatastoreDBStreamOptions extends DatastoreDBOptions {
+export interface DatastoreDBStreamOptions extends DatastoreDBReadOptions {
   /**
    * Set to `true` to stream via experimental "cursor-query based stream".
    *
@@ -116,6 +116,8 @@ export interface DatastoreDBStreamOptions extends DatastoreDBOptions {
 
 export interface DatastoreDBOptions extends CommonDBOptions {}
 
+export interface DatastoreDBReadOptions extends CommonDBReadOptions {}
+
 export interface DatastoreDBSaveOptions<ROW extends ObjectWithId>
   extends CommonDBSaveOptions<ROW> {}