@naturalcycles/db-lib 9.23.2 → 9.24.0

package/dist/adapter/inmemory/inMemory.db.d.ts

@@ -1,6 +1,6 @@
 import { AnyObjectWithId, CommonLogger, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, StringMap } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDB, CommonDBTransactionOptions, CommonDBType, DBOperation, DBTransactionFn } from '../..';
+import { CommonDB, CommonDBSupport, CommonDBTransactionOptions, CommonDBType, DBOperation, DBTransactionFn } from '../..';
 import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, DBTransaction, RunQueryResult } from '../../db.model';
 import { DBQuery } from '../../query/dbQuery';
 export interface InMemoryDBCfg {
@@ -47,23 +47,7 @@ export interface InMemoryDBCfg {
 }
 export declare class InMemoryDB implements CommonDB {
     dbType: CommonDBType;
-    support: {
-        queries?: boolean;
-        dbQueryFilter?: boolean;
-        dbQueryFilterIn?: boolean;
-        dbQueryOrder?: boolean;
-        dbQuerySelectFields?: boolean;
-        insertSaveMethod?: boolean;
-        updateSaveMethod?: boolean;
-        patchByQuery?: boolean;
-        increment?: boolean;
-        createTable?: boolean;
-        tableSchemas?: boolean;
-        streaming?: boolean;
-        bufferValues?: boolean;
-        nullValues?: boolean;
-        transactions?: boolean;
-    };
+    support: CommonDBSupport;
     constructor(cfg?: Partial<InMemoryDBCfg>);
     cfg: InMemoryDBCfg;
     data: StringMap<StringMap<AnyObjectWithId>>;

package/dist/adapter/inmemory/inMemory.db.js

@@ -10,6 +10,7 @@ class InMemoryDB {
         this.dbType = __1.CommonDBType.document;
         this.support = {
             ...__1.commonDBFullSupport,
+            timeMachine: false,
         };
         // data[table][id] > {id: 'a', created: ... }
         this.data = {};

package/dist/common.db.d.ts

@@ -1,6 +1,6 @@
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, StringMap } from '@naturalcycles/js-lib';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBTransactionOptions, DBTransactionFn, RunQueryResult } from './db.model';
+import { CommonDBCreateOptions, CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBTransactionOptions, DBTransactionFn, RunQueryResult } from './db.model';
 import { DBQuery } from './query/dbQuery';
 export declare enum CommonDBType {
     'document' = "document",
@@ -42,12 +42,12 @@ export interface CommonDB {
      * Order of items returned is not guaranteed to match order of ids.
      * (Such limitation exists because Datastore doesn't support it).
      */
-    getByIds: <ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBOptions) => Promise<ROW[]>;
+    getByIds: <ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBReadOptions) => Promise<ROW[]>;
     /**
      * Order by 'id' is not supported by all implementations (for example, Datastore doesn't support it).
      */
-    runQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions) => Promise<RunQueryResult<ROW>>;
-    runQueryCount: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions) => Promise<number>;
+    runQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBReadOptions) => Promise<RunQueryResult<ROW>>;
+    runQueryCount: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBReadOptions) => Promise<number>;
     streamQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBStreamOptions) => ReadableTyped<ROW>;
     /**
      * rows can have missing ids only if DB supports auto-generating them (like mysql auto_increment).
@@ -74,7 +74,7 @@ export interface CommonDB {
      *
      * Returns the number of rows affected.
      */
-    patchByQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: Partial<ROW>, opt?: CommonDBOptions) => Promise<number>;
+    patchByQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: Partial<ROW>, opt?: CommonDBReadOptions) => Promise<number>;
     /**
      * Should be implemented as a Transaction (best effort), which means that
      * either ALL or NONE of the operations should be applied.
@@ -123,5 +123,6 @@ export interface CommonDBSupport {
     bufferValues?: boolean;
     nullValues?: boolean;
     transactions?: boolean;
+    timeMachine?: boolean;
 }
 export declare const commonDBFullSupport: CommonDBSupport;

package/dist/common.db.js

@@ -22,4 +22,5 @@ exports.commonDBFullSupport = {
     bufferValues: true,
     nullValues: true,
     transactions: true,
+    timeMachine: true,
 };

package/dist/commondao/common.dao.d.ts

@@ -3,7 +3,7 @@ import { AsyncMapper, BaseDBEntity, CommonLogger, JsonSchemaObject, JsonSchemaRo
 import { AjvSchema, ObjectSchema, ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { CommonDBTransactionOptions, DBTransaction, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
-import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
+import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoReadOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -15,13 +15,13 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     cfg: CommonDaoCfg<BM, DBM, ID>;
     constructor(cfg: CommonDaoCfg<BM, DBM, ID>);
     create(part?: Partial<BM>, opt?: CommonDaoOptions): BM;
-    getById(id?: ID | null, opt?: CommonDaoOptions): Promise<BM | null>;
-    getByIdOrEmpty(id: ID, part?: Partial<BM>, opt?: CommonDaoOptions): Promise<BM>;
-    getByIdAsDBM(id?: ID | null, opt?: CommonDaoOptions): Promise<DBM | null>;
-    getByIds(ids: ID[], opt?: CommonDaoOptions): Promise<BM[]>;
-    getByIdsAsDBM(ids: ID[], opt?: CommonDaoOptions): Promise<DBM[]>;
-    requireById(id: ID, opt?: CommonDaoOptions): Promise<BM>;
-    requireByIdAsDBM(id: ID, opt?: CommonDaoOptions): Promise<DBM>;
+    getById(id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
+    getByIdOrEmpty(id: ID, part?: Partial<BM>, opt?: CommonDaoReadOptions): Promise<BM>;
+    getByIdAsDBM(id?: ID | null, opt?: CommonDaoReadOptions): Promise<DBM | null>;
+    getByIds(ids: ID[], opt?: CommonDaoReadOptions): Promise<BM[]>;
+    getByIdsAsDBM(ids: ID[], opt?: CommonDaoReadOptions): Promise<DBM[]>;
+    requireById(id: ID, opt?: CommonDaoReadOptions): Promise<BM>;
+    requireByIdAsDBM(id: ID, opt?: CommonDaoReadOptions): Promise<DBM>;
     private throwRequiredError;
     /**
      * Throws if readOnly is true
@@ -32,25 +32,25 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      */
     private requireObjectMutability;
     private ensureUniqueId;
-    getBy(by: keyof DBM, value: any, limit?: number, opt?: CommonDaoOptions): Promise<BM[]>;
-    getOneBy(by: keyof DBM, value: any, opt?: CommonDaoOptions): Promise<BM | null>;
-    getAll(opt?: CommonDaoOptions): Promise<BM[]>;
+    getBy(by: keyof DBM, value: any, limit?: number, opt?: CommonDaoReadOptions): Promise<BM[]>;
+    getOneBy(by: keyof DBM, value: any, opt?: CommonDaoReadOptions): Promise<BM | null>;
+    getAll(opt?: CommonDaoReadOptions): Promise<BM[]>;
     /**
      * Pass `table` to override table
      */
     query(table?: string): RunnableDBQuery<BM, DBM, ID>;
-    runQuery(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<BM[]>;
-    runQuerySingleColumn<T = any>(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<T[]>;
+    runQuery(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<BM[]>;
+    runQuerySingleColumn<T = any>(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<T[]>;
     /**
      * Convenience method that runs multiple queries in parallel and then merges their results together.
      * Does deduplication by id.
      * Order is not guaranteed, as queries run in parallel.
      */
-    runUnionQueries(queries: DBQuery<DBM>[], opt?: CommonDaoOptions): Promise<BM[]>;
-    runQueryExtended(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<RunQueryResult<BM>>;
-    runQueryAsDBM(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<DBM[]>;
-    runQueryExtendedAsDBM(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<RunQueryResult<DBM>>;
-    runQueryCount(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<number>;
+    runUnionQueries(queries: DBQuery<DBM>[], opt?: CommonDaoReadOptions): Promise<BM[]>;
+    runQueryExtended(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<RunQueryResult<BM>>;
+    runQueryAsDBM(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<DBM[]>;
+    runQueryExtendedAsDBM(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<RunQueryResult<DBM>>;
+    runQueryCount(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<number>;
     streamQueryForEach(q: DBQuery<DBM>, mapper: AsyncMapper<BM, void>, opt?: CommonDaoStreamForEachOptions<BM>): Promise<void>;
     streamQueryAsDBMForEach(q: DBQuery<DBM>, mapper: AsyncMapper<DBM, void>, opt?: CommonDaoStreamForEachOptions<DBM>): Promise<void>;
     /**
@@ -67,7 +67,7 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * You can do `.pipe(transformNoOp)` to make it "valid again".
      */
     streamQuery(q: DBQuery<DBM>, opt?: CommonDaoStreamOptions<BM>): ReadableTyped<BM>;
-    queryIds(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<ID[]>;
+    queryIds(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<ID[]>;
     streamQueryIds(q: DBQuery<DBM>, opt?: CommonDaoStreamOptions<ID>): ReadableTyped<ID>;
     streamQueryIdsForEach(q: DBQuery<DBM>, mapper: AsyncMapper<ID, void>, opt?: CommonDaoStreamForEachOptions<ID>): Promise<void>;
     /**
@@ -193,8 +193,8 @@ export declare class CommonDaoTransaction {
      * Perform a graceful rollback without throwing/re-throwing any error.
      */
     rollback(): Promise<void>;
-    getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, id?: ID | null, opt?: CommonDaoOptions): Promise<BM | null>;
-    getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, ids: ID[], opt?: CommonDaoOptions): Promise<BM[]>;
+    getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
+    getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, ids: ID[], opt?: CommonDaoReadOptions): Promise<BM[]>;
     save<BM extends BaseDBEntity, DBM extends BaseDBEntity>(dao: CommonDao<BM, DBM>, bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<BM>;
     saveBatch<BM extends BaseDBEntity, DBM extends BaseDBEntity>(dao: CommonDao<BM, DBM>, bms: Unsaved<BM>[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<BM[]>;
     /**

package/dist/commondao/common.dao.model.d.ts

@@ -1,4 +1,4 @@
-import { BaseDBEntity, CommonLogger, ErrorMode, Promisable, ZodError, ZodSchema } from '@naturalcycles/js-lib';
+import { BaseDBEntity, CommonLogger, ErrorMode, Promisable, UnixTimestampNumber, ZodError, ZodSchema } from '@naturalcycles/js-lib';
 import { AjvSchema, AjvValidationError, JoiValidationError, ObjectSchema, TransformLogProgressOptions, TransformMapOptions } from '@naturalcycles/nodejs-lib';
 import { CommonDB } from '../common.db';
 import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions } from '../db.model';
@@ -200,6 +200,13 @@ export interface CommonDaoOptions extends CommonDBOptions {
      */
     table?: string;
 }
+export interface CommonDaoReadOptions extends CommonDaoOptions {
+    /**
+     * If provided (and supported by the DB) - will read the data at that point in time (aka "Time machine" feature).
+     * This feature is named PITR (point-in-time-recovery) query in Datastore.
+     */
+    readAt?: UnixTimestampNumber;
+}
 export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseDBEntity> extends CommonDaoSaveBatchOptions<DBM> {
     /**
      * If provided - a check will be made.
@@ -248,7 +255,7 @@ export interface CommonDaoStreamSaveOptions<DBM extends BaseDBEntity> extends Co
 }
 export interface CommonDaoStreamForEachOptions<IN> extends CommonDaoStreamOptions<IN>, TransformMapOptions<IN, any> {
 }
-export interface CommonDaoStreamOptions<IN> extends CommonDaoOptions, TransformLogProgressOptions<IN> {
+export interface CommonDaoStreamOptions<IN> extends CommonDaoReadOptions, TransformLogProgressOptions<IN> {
     /**
      * @default true (for streams)
      */

package/dist/db.model.d.ts

@@ -1,4 +1,4 @@
-import { ObjectWithId } from '@naturalcycles/js-lib';
+import { ObjectWithId, UnixTimestampNumber } from '@naturalcycles/js-lib';
 import { CommonDB } from './common.db';
 /**
  * Similar to SQL INSERT, UPDATE.
@@ -45,6 +45,13 @@ export interface CommonDBOptions {
      */
     tx?: DBTransaction;
 }
+export interface CommonDBReadOptions extends CommonDBOptions {
+    /**
+     * If provided (and supported by the DB) - will read the data at that point in time (aka "Time machine" feature).
+     * This feature is named PITR (point-in-time-recovery) query in Datastore.
+     */
+    readAt?: UnixTimestampNumber;
+}
 /**
  * All properties default to undefined.
  */
@@ -62,7 +69,7 @@ export interface CommonDBSaveOptions<ROW extends ObjectWithId> extends CommonDBO
      */
     assignGeneratedIds?: boolean;
 }
-export type CommonDBStreamOptions = CommonDBOptions;
+export type CommonDBStreamOptions = CommonDBReadOptions;
 export interface CommonDBCreateOptions extends CommonDBOptions {
     /**
      * Caution! If set to true - will actually DROP the table!

package/dist/query/dbQuery.d.ts

@@ -1,6 +1,6 @@
 import { AsyncMapper, BaseDBEntity, ObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDaoOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions } from '..';
+import { CommonDaoOptions, CommonDaoReadOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions } from '..';
 import { CommonDao } from '../commondao/common.dao';
 import { RunQueryResult } from '../db.model';
 /**
@@ -93,18 +93,18 @@ export declare class RunnableDBQuery<BM extends BaseDBEntity, DBM extends BaseDB
      * Pass `table` to override table.
      */
     constructor(dao: CommonDao<BM, DBM, ID>, table?: string);
-    runQuery(opt?: CommonDaoOptions): Promise<BM[]>;
-    runQuerySingleColumn<T = any>(opt?: CommonDaoOptions): Promise<T[]>;
-    runQueryAsDBM(opt?: CommonDaoOptions): Promise<DBM[]>;
-    runQueryExtended(opt?: CommonDaoOptions): Promise<RunQueryResult<BM>>;
-    runQueryExtendedAsDBM(opt?: CommonDaoOptions): Promise<RunQueryResult<DBM>>;
-    runQueryCount(opt?: CommonDaoOptions): Promise<number>;
+    runQuery(opt?: CommonDaoReadOptions): Promise<BM[]>;
+    runQuerySingleColumn<T = any>(opt?: CommonDaoReadOptions): Promise<T[]>;
+    runQueryAsDBM(opt?: CommonDaoReadOptions): Promise<DBM[]>;
+    runQueryExtended(opt?: CommonDaoReadOptions): Promise<RunQueryResult<BM>>;
+    runQueryExtendedAsDBM(opt?: CommonDaoReadOptions): Promise<RunQueryResult<DBM>>;
+    runQueryCount(opt?: CommonDaoReadOptions): Promise<number>;
     patchByQuery(patch: Partial<DBM>, opt?: CommonDaoOptions): Promise<number>;
     streamQueryForEach(mapper: AsyncMapper<BM, void>, opt?: CommonDaoStreamForEachOptions<BM>): Promise<void>;
     streamQueryAsDBMForEach(mapper: AsyncMapper<DBM, void>, opt?: CommonDaoStreamForEachOptions<DBM>): Promise<void>;
     streamQuery(opt?: CommonDaoStreamOptions<BM>): ReadableTyped<BM>;
     streamQueryAsDBM(opt?: CommonDaoStreamOptions<DBM>): ReadableTyped<DBM>;
-    queryIds(opt?: CommonDaoOptions): Promise<ID[]>;
+    queryIds(opt?: CommonDaoReadOptions): Promise<ID[]>;
     streamQueryIds(opt?: CommonDaoStreamOptions<ID>): ReadableTyped<ID>;
     streamQueryIdsForEach(mapper: AsyncMapper<ID, void>, opt?: CommonDaoStreamForEachOptions<ID>): Promise<void>;
     deleteByQuery(opt?: CommonDaoStreamDeleteOptions<DBM>): Promise<number>;

package/dist/testing/dbTest.js

@@ -45,6 +45,14 @@ function runCommonDBTest(db, quirks = {}) {
     test('getByIds(...) should return empty', async () => {
         expect(await db.getByIds(test_model_1.TEST_TABLE, ['abc', 'abcd'])).toEqual([]);
     });
+    // TimeMachine
+    if (support.timeMachine) {
+        test('getByIds(...) 10 minutes ago should return []', async () => {
+            expect(await db.getByIds(test_model_1.TEST_TABLE, [item1.id, 'abc'], {
+                readAt: js_lib_1.localTime.now().minus(10, 'minute').unix,
+            })).toEqual([]);
+        });
+    }
     // SAVE
     if (support.nullValues) {
         test('should allow to save and load null values', async () => {

package/package.json

@@ -45,7 +45,7 @@
   "engines": {
     "node": ">=20.13"
   },
-  "version": "9.23.2",
+  "version": "9.24.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/adapter/inmemory/inMemory.db.ts

@@ -28,6 +28,7 @@ import {
 import {
   CommonDB,
   commonDBFullSupport,
+  CommonDBSupport,
   CommonDBTransactionOptions,
   CommonDBType,
   DBOperation,
@@ -94,8 +95,9 @@ export interface InMemoryDBCfg {
 export class InMemoryDB implements CommonDB {
   dbType = CommonDBType.document
 
-  support = {
+  support: CommonDBSupport = {
     ...commonDBFullSupport,
+    timeMachine: false,
   }
 
   constructor(cfg?: Partial<InMemoryDBCfg>) {

package/src/common.db.ts

@@ -8,6 +8,7 @@ import type { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import {
   CommonDBCreateOptions,
   CommonDBOptions,
+  CommonDBReadOptions,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
   CommonDBTransactionOptions,
@@ -71,7 +72,7 @@ export interface CommonDB {
   getByIds: <ROW extends ObjectWithId>(
     table: string,
     ids: string[],
-    opt?: CommonDBOptions,
+    opt?: CommonDBReadOptions,
   ) => Promise<ROW[]>
 
   // QUERY
@@ -80,12 +81,12 @@ export interface CommonDB {
    */
   runQuery: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    opt?: CommonDBOptions,
+    opt?: CommonDBReadOptions,
   ) => Promise<RunQueryResult<ROW>>
 
   runQueryCount: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    opt?: CommonDBOptions,
+    opt?: CommonDBReadOptions,
   ) => Promise<number>
 
   streamQuery: <ROW extends ObjectWithId>(
@@ -133,7 +134,7 @@ export interface CommonDB {
   patchByQuery: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     patch: Partial<ROW>,
-    opt?: CommonDBOptions,
+    opt?: CommonDBReadOptions,
   ) => Promise<number>
 
   // TRANSACTION
@@ -192,6 +193,7 @@ export interface CommonDBSupport {
   bufferValues?: boolean
   nullValues?: boolean
   transactions?: boolean
+  timeMachine?: boolean
 }
 
 export const commonDBFullSupport: CommonDBSupport = {
@@ -210,4 +212,5 @@ export const commonDBFullSupport: CommonDBSupport = {
   bufferValues: true,
   nullValues: true,
   transactions: true,
+  timeMachine: true,
 }

package/src/commondao/common.dao.model.ts

@@ -3,6 +3,7 @@ import {
   CommonLogger,
   ErrorMode,
   Promisable,
+  UnixTimestampNumber,
   ZodError,
   ZodSchema,
 } from '@naturalcycles/js-lib'
@@ -251,6 +252,14 @@ export interface CommonDaoOptions extends CommonDBOptions {
   table?: string
 }
 
+export interface CommonDaoReadOptions extends CommonDaoOptions {
+  /**
+   * If provided (and supported by the DB) - will read the data at that point in time (aka "Time machine" feature).
+   * This feature is named PITR (point-in-time-recovery) query in Datastore.
+   */
+  readAt?: UnixTimestampNumber
+}
+
 export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseDBEntity>
   extends CommonDaoSaveBatchOptions<DBM> {
   /**
@@ -314,7 +323,7 @@ export interface CommonDaoStreamForEachOptions<IN>
     TransformMapOptions<IN, any> {}
 
 export interface CommonDaoStreamOptions<IN>
-  extends CommonDaoOptions,
+  extends CommonDaoReadOptions,
     TransformLogProgressOptions<IN> {
   /**
    * @default true (for streams)

package/src/commondao/common.dao.ts

@@ -55,6 +55,7 @@ import {
   CommonDaoOptions,
   CommonDaoPatchByIdOptions,
   CommonDaoPatchOptions,
+  CommonDaoReadOptions,
   CommonDaoSaveBatchOptions,
   CommonDaoSaveOptions,
   CommonDaoStreamDeleteOptions,
@@ -116,7 +117,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
   // overrides are disabled now, as they obfuscate errors when ID branded type is used
   // async getById(id: undefined | null, opt?: CommonDaoOptions): Promise<null>
   // async getById(id?: ID | null, opt?: CommonDaoOptions): Promise<BM | null>
-  async getById(id?: ID | null, opt: CommonDaoOptions = {}): Promise<BM | null> {
+  async getById(id?: ID | null, opt: CommonDaoReadOptions = {}): Promise<BM | null> {
     if (!id) return null
     const op = `getById(${id})`
     const table = opt.table || this.cfg.table
@@ -132,7 +133,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return bm || null
   }
 
-  async getByIdOrEmpty(id: ID, part: Partial<BM> = {}, opt?: CommonDaoOptions): Promise<BM> {
+  async getByIdOrEmpty(id: ID, part: Partial<BM> = {}, opt?: CommonDaoReadOptions): Promise<BM> {
     const bm = await this.getById(id, opt)
     if (bm) return bm
 
@@ -141,7 +142,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
 
   // async getByIdAsDBM(id: undefined | null, opt?: CommonDaoOptions): Promise<null>
   // async getByIdAsDBM(id?: ID | null, opt?: CommonDaoOptions): Promise<DBM | null>
-  async getByIdAsDBM(id?: ID | null, opt: CommonDaoOptions = {}): Promise<DBM | null> {
+  async getByIdAsDBM(id?: ID | null, opt: CommonDaoReadOptions = {}): Promise<DBM | null> {
     if (!id) return null
     const op = `getByIdAsDBM(${id})`
     const table = opt.table || this.cfg.table
@@ -156,7 +157,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return dbm || null
   }
 
-  async getByIds(ids: ID[], opt: CommonDaoOptions = {}): Promise<BM[]> {
+  async getByIds(ids: ID[], opt: CommonDaoReadOptions = {}): Promise<BM[]> {
     if (!ids.length) return []
     const op = `getByIds ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`
     const table = opt.table || this.cfg.table
@@ -173,7 +174,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return bms
   }
 
-  async getByIdsAsDBM(ids: ID[], opt: CommonDaoOptions = {}): Promise<DBM[]> {
+  async getByIdsAsDBM(ids: ID[], opt: CommonDaoReadOptions = {}): Promise<DBM[]> {
     if (!ids.length) return []
     const op = `getByIdsAsDBM ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`
     const table = opt.table || this.cfg.table
@@ -189,7 +190,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return dbms
   }
 
-  async requireById(id: ID, opt: CommonDaoOptions = {}): Promise<BM> {
+  async requireById(id: ID, opt: CommonDaoReadOptions = {}): Promise<BM> {
     const r = await this.getById(id, opt)
     if (!r) {
       this.throwRequiredError(id, opt)
@@ -197,7 +198,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return r
   }
 
-  async requireByIdAsDBM(id: ID, opt: CommonDaoOptions = {}): Promise<DBM> {
+  async requireByIdAsDBM(id: ID, opt: CommonDaoReadOptions = {}): Promise<DBM> {
     const r = await this.getByIdAsDBM(id, opt)
     if (!r) {
       this.throwRequiredError(id, opt)
@@ -246,16 +247,16 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     }
   }
 
-  async getBy(by: keyof DBM, value: any, limit = 0, opt?: CommonDaoOptions): Promise<BM[]> {
+  async getBy(by: keyof DBM, value: any, limit = 0, opt?: CommonDaoReadOptions): Promise<BM[]> {
     return await this.query().filterEq(by, value).limit(limit).runQuery(opt)
   }
 
-  async getOneBy(by: keyof DBM, value: any, opt?: CommonDaoOptions): Promise<BM | null> {
+  async getOneBy(by: keyof DBM, value: any, opt?: CommonDaoReadOptions): Promise<BM | null> {
     const [bm] = await this.query().filterEq(by, value).limit(1).runQuery(opt)
     return bm || null
   }
 
-  async getAll(opt?: CommonDaoOptions): Promise<BM[]> {
+  async getAll(opt?: CommonDaoReadOptions): Promise<BM[]> {
     return await this.query().runQuery(opt)
   }
 
@@ -267,12 +268,12 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return new RunnableDBQuery<BM, DBM, ID>(this, table)
   }
 
-  async runQuery(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<BM[]> {
+  async runQuery(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<BM[]> {
     const { rows } = await this.runQueryExtended(q, opt)
     return rows
   }
 
-  async runQuerySingleColumn<T = any>(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<T[]> {
+  async runQuerySingleColumn<T = any>(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<T[]> {
     _assert(
       q._selectedFieldNames?.length === 1,
       `runQuerySingleColumn requires exactly 1 column to be selected: ${q.pretty()}`,
@@ -289,14 +290,17 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
    * Does deduplication by id.
    * Order is not guaranteed, as queries run in parallel.
    */
-  async runUnionQueries(queries: DBQuery<DBM>[], opt?: CommonDaoOptions): Promise<BM[]> {
+  async runUnionQueries(queries: DBQuery<DBM>[], opt?: CommonDaoReadOptions): Promise<BM[]> {
     const results = (
       await pMap(queries, async q => (await this.runQueryExtended(q, opt)).rows)
     ).flat()
     return _uniqBy(results, r => r.id)
   }
 
-  async runQueryExtended(q: DBQuery<DBM>, opt: CommonDaoOptions = {}): Promise<RunQueryResult<BM>> {
+  async runQueryExtended(
+    q: DBQuery<DBM>,
+    opt: CommonDaoReadOptions = {},
+  ): Promise<RunQueryResult<BM>> {
     this.validateQueryIndexes(q) // throws if query uses `excludeFromIndexes` property
     q.table = opt.table || q.table
     const op = `runQuery(${q.pretty()})`
@@ -317,14 +321,14 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     }
   }
 
-  async runQueryAsDBM(q: DBQuery<DBM>, opt?: CommonDaoOptions): Promise<DBM[]> {
+  async runQueryAsDBM(q: DBQuery<DBM>, opt?: CommonDaoReadOptions): Promise<DBM[]> {
     const { rows } = await this.runQueryExtendedAsDBM(q, opt)
     return rows
   }
 
   async runQueryExtendedAsDBM(
     q: DBQuery<DBM>,
-    opt: CommonDaoOptions = {},
+    opt: CommonDaoReadOptions = {},
   ): Promise<RunQueryResult<DBM>> {
     this.validateQueryIndexes(q) // throws if query uses `excludeFromIndexes` property
     q.table = opt.table || q.table
@@ -343,7 +347,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return { rows: dbms, ...queryResult }
   }
 
-  async runQueryCount(q: DBQuery<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
+  async runQueryCount(q: DBQuery<DBM>, opt: CommonDaoReadOptions = {}): Promise<number> {
     this.validateQueryIndexes(q) // throws if query uses `excludeFromIndexes` property
     q.table = opt.table || q.table
     const op = `runQueryCount(${q.pretty()})`
@@ -548,7 +552,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     )
   }
 
-  async queryIds(q: DBQuery<DBM>, opt: CommonDaoOptions = {}): Promise<ID[]> {
+  async queryIds(q: DBQuery<DBM>, opt: CommonDaoReadOptions = {}): Promise<ID[]> {
     this.validateQueryIndexes(q) // throws if query uses `excludeFromIndexes` property
     q.table = opt.table || q.table
     const { rows } = await this.cfg.db.runQuery(q.select(['id']), opt)
@@ -1411,7 +1415,7 @@ export class CommonDaoTransaction {
   async getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
     dao: CommonDao<BM, DBM, ID>,
     id?: ID | null,
-    opt?: CommonDaoOptions,
+    opt?: CommonDaoReadOptions,
   ): Promise<BM | null> {
     return await dao.getById(id, { ...opt, tx: this.tx })
   }
@@ -1419,7 +1423,7 @@ export class CommonDaoTransaction {
   async getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
     dao: CommonDao<BM, DBM, ID>,
     ids: ID[],
-    opt?: CommonDaoOptions,
+    opt?: CommonDaoReadOptions,
   ): Promise<BM[]> {
     return await dao.getByIds(ids, { ...opt, tx: this.tx })
   }

package/src/db.model.ts

@@ -1,4 +1,4 @@
-import { ObjectWithId } from '@naturalcycles/js-lib'
+import { ObjectWithId, UnixTimestampNumber } from '@naturalcycles/js-lib'
 import { CommonDB } from './common.db'
 
 /**
@@ -52,6 +52,14 @@ export interface CommonDBOptions {
   tx?: DBTransaction
 }
 
+export interface CommonDBReadOptions extends CommonDBOptions {
+  /**
+   * If provided (and supported by the DB) - will read the data at that point in time (aka "Time machine" feature).
+   * This feature is named PITR (point-in-time-recovery) query in Datastore.
+   */
+  readAt?: UnixTimestampNumber
+}
+
 /**
  * All properties default to undefined.
  */
@@ -72,7 +80,7 @@ export interface CommonDBSaveOptions<ROW extends ObjectWithId> extends CommonDBO
   assignGeneratedIds?: boolean
 }
 
-export type CommonDBStreamOptions = CommonDBOptions
+export type CommonDBStreamOptions = CommonDBReadOptions
 
 export interface CommonDBCreateOptions extends CommonDBOptions {
   /**

package/src/query/dbQuery.ts

@@ -8,6 +8,7 @@ import {
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import {
   CommonDaoOptions,
+  CommonDaoReadOptions,
   CommonDaoStreamDeleteOptions,
   CommonDaoStreamForEachOptions,
   CommonDaoStreamOptions,
@@ -251,27 +252,27 @@ export class RunnableDBQuery<
     super(table || dao.cfg.table)
   }
 
-  async runQuery(opt?: CommonDaoOptions): Promise<BM[]> {
+  async runQuery(opt?: CommonDaoReadOptions): Promise<BM[]> {
     return await this.dao.runQuery(this, opt)
   }
 
-  async runQuerySingleColumn<T = any>(opt?: CommonDaoOptions): Promise<T[]> {
+  async runQuerySingleColumn<T = any>(opt?: CommonDaoReadOptions): Promise<T[]> {
     return await this.dao.runQuerySingleColumn<T>(this, opt)
   }
 
-  async runQueryAsDBM(opt?: CommonDaoOptions): Promise<DBM[]> {
+  async runQueryAsDBM(opt?: CommonDaoReadOptions): Promise<DBM[]> {
     return await this.dao.runQueryAsDBM(this, opt)
   }
 
-  async runQueryExtended(opt?: CommonDaoOptions): Promise<RunQueryResult<BM>> {
+  async runQueryExtended(opt?: CommonDaoReadOptions): Promise<RunQueryResult<BM>> {
     return await this.dao.runQueryExtended(this, opt)
   }
 
-  async runQueryExtendedAsDBM(opt?: CommonDaoOptions): Promise<RunQueryResult<DBM>> {
+  async runQueryExtendedAsDBM(opt?: CommonDaoReadOptions): Promise<RunQueryResult<DBM>> {
     return await this.dao.runQueryExtendedAsDBM(this, opt)
   }
 
-  async runQueryCount(opt?: CommonDaoOptions): Promise<number> {
+  async runQueryCount(opt?: CommonDaoReadOptions): Promise<number> {
     return await this.dao.runQueryCount(this, opt)
   }
 
@@ -301,7 +302,7 @@ export class RunnableDBQuery<
     return this.dao.streamQueryAsDBM(this, opt)
   }
 
-  async queryIds(opt?: CommonDaoOptions): Promise<ID[]> {
+  async queryIds(opt?: CommonDaoReadOptions): Promise<ID[]> {
     return await this.dao.queryIds(this, opt)
   }
 

package/src/testing/dbTest.ts

@@ -1,4 +1,4 @@
-import { _deepFreeze, _filterObject, _pick, _sortBy, pMap } from '@naturalcycles/js-lib'
+import { _deepFreeze, _filterObject, _pick, _sortBy, localTime, pMap } from '@naturalcycles/js-lib'
 import { CommonDB, CommonDBType } from '../common.db'
 import { DBQuery } from '../query/dbQuery'
 import {
@@ -77,6 +77,17 @@ export function runCommonDBTest(db: CommonDB, quirks: CommonDBImplementationQuir
     expect(await db.getByIds(TEST_TABLE, ['abc', 'abcd'])).toEqual([])
   })
 
+  // TimeMachine
+  if (support.timeMachine) {
+    test('getByIds(...) 10 minutes ago should return []', async () => {
+      expect(
+        await db.getByIds(TEST_TABLE, [item1.id, 'abc'], {
+          readAt: localTime.now().minus(10, 'minute').unix,
+        }),
+      ).toEqual([])
+    })
+  }
+
   // SAVE
   if (support.nullValues) {
     test('should allow to save and load null values', async () => {

package/src/transaction/dbTransaction.util.ts

@@ -107,6 +107,7 @@ export class FakeDBTransaction implements DBTransaction {
   ): Promise<ROW[]> {
     return await this.db.getByIds(table, ids, opt)
   }
+
   // async runQuery<ROW extends ObjectWithId>(
   //   q: DBQuery<ROW>,
   //   opt?: CommonDBOptions,
@@ -120,6 +121,7 @@ export class FakeDBTransaction implements DBTransaction {
   ): Promise<void> {
     await this.db.saveBatch(table, rows, opt)
   }
+
   async deleteByIds(table: string, ids: string[], opt?: CommonDBOptions): Promise<number> {
     return await this.db.deleteByIds(table, ids, opt)
   }