@naturalcycles/db-lib 9.24.1 → 9.25.0

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

@@ -1,5 +1,5 @@
 import { Transform } from 'node:stream';
-import { AsyncMapper, BaseDBEntity, CommonLogger, JsonSchemaObject, JsonSchemaRootObject, StringMap, UnixTimestampMillisNumber, Unsaved, ZodSchema } from '@naturalcycles/js-lib';
+import { AsyncMapper, BaseDBEntity, CommonLogger, JsonSchemaObject, JsonSchemaRootObject, StringMap, UnixTimestampMillis, Unsaved, ZodSchema } from '@naturalcycles/js-lib';
 import { AjvSchema, ObjectSchema, ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { CommonDBTransactionOptions, DBTransaction, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
@@ -170,10 +170,10 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * Throws if query uses a property that is in `excludeFromIndexes` list.
      */
     private validateQueryIndexes;
-    protected logResult(started: number, op: string, res: any, table: string): void;
-    protected logSaveResult(started: number, op: string, table: string): void;
-    protected logStarted(op: string, table: string, force?: boolean): UnixTimestampMillisNumber;
-    protected logSaveStarted(op: string, items: any, table: string): UnixTimestampMillisNumber;
+    protected logResult(started: UnixTimestampMillis, op: string, res: any, table: string): void;
+    protected logSaveResult(started: UnixTimestampMillis, op: string, table: string): void;
+    protected logStarted(op: string, table: string, force?: boolean): UnixTimestampMillis;
+    protected logSaveStarted(op: string, items: any, table: string): UnixTimestampMillis;
 }
 /**
  * Transaction is committed when the function returns resolved Promise (aka "returns normally").

package/dist/commondao/common.dao.js

@@ -968,7 +968,19 @@ class CommonDao {
         }
         else {
             // Joi
+            const start = performance.now();
             const vr = (0, nodejs_lib_1.getValidationResult)(obj, schema, objectName);
+            const end = performance.now();
+            const tookMillis = end - start;
+            if (this.cfg.debugValidationTimeThreshhold &&
+                tookMillis >= this.cfg.debugValidationTimeThreshhold) {
+                this.cfg.onValidationTimeThreshold?.({
+                    tookMillis,
+                    error: !!vr.error,
+                    table,
+                    obj,
+                });
+            }
             error = vr.error;
             convertedValue = vr.value;
         }

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

@@ -1,4 +1,4 @@
-import { BaseDBEntity, CommonLogger, ErrorMode, Promisable, UnixTimestampNumber, ZodError, ZodSchema } from '@naturalcycles/js-lib';
+import { AnyObject, BaseDBEntity, CommonLogger, ErrorMode, NumberOfMilliseconds, Promisable, UnixTimestamp, 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';
@@ -111,6 +111,15 @@ export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * If set to false - save (write) operations will skip validation (and conversion).
      */
     validateOnSave?: boolean;
+    /**
+     * Defaults to undefined == disabled.
+     * If set - enable the monitoring of validation time and will alert on crossing the threshold.
+     */
+    debugValidationTimeThreshhold?: NumberOfMilliseconds;
+    /**
+     * Called when debugValidationTimeThreshhold is crossed.
+     */
+    onValidationTimeThreshold?: (info: AnyObject) => void;
     /**
      * Defaults to false.
      * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
@@ -205,7 +214,7 @@ 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;
+    readAt?: UnixTimestamp;
 }
 export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseDBEntity> extends CommonDaoSaveBatchOptions<DBM> {
     /**

package/dist/db.model.d.ts

@@ -1,4 +1,4 @@
-import { ObjectWithId, UnixTimestampNumber } from '@naturalcycles/js-lib';
+import { ObjectWithId, UnixTimestamp } from '@naturalcycles/js-lib';
 import { CommonDB } from './common.db';
 /**
  * Similar to SQL INSERT, UPDATE.
@@ -50,7 +50,7 @@ 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;
+    readAt?: UnixTimestamp;
 }
 /**
  * All properties default to undefined.

package/dist/kv/commonKeyValueDB.d.ts

@@ -1,4 +1,4 @@
-import { Integer, UnixTimestampNumber } from '@naturalcycles/js-lib';
+import { Integer, UnixTimestamp } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { CommonDBCreateOptions } from '../db.model';
 /**
@@ -56,7 +56,7 @@ export interface CommonKeyValueDBSaveBatchOptions {
      * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
      * E.g EXAT in Redis.
      */
-    expireAt?: UnixTimestampNumber;
+    expireAt?: UnixTimestamp;
 }
 /**
  * Manifest of supported features.

package/dist/kv/commonKeyValueDaoMemoCache.js

@@ -18,7 +18,9 @@ class CommonKeyValueDaoMemoCache {
         return (await this.cfg.dao.getById(k)) || js_lib_1.MISS;
     }
     async set(k, v) {
-        const opt = this.cfg.ttl ? { expireAt: js_lib_1.localTime.nowUnix() + this.cfg.ttl } : undefined;
+        const opt = this.cfg.ttl
+            ? { expireAt: (js_lib_1.localTime.nowUnix() + this.cfg.ttl) }
+            : undefined;
         await this.cfg.dao.save(k, v, opt);
     }
     async clear() {

package/dist/pipeline/dbPipelineBackup.d.ts

@@ -1,4 +1,4 @@
-import { AsyncMapper, ErrorMode, StringMap, UnixTimestampNumber } from '@naturalcycles/js-lib';
+import { AsyncMapper, ErrorMode, StringMap, UnixTimestamp } from '@naturalcycles/js-lib';
 import { NDJsonStats, TransformLogProgressOptions, TransformMapOptions } from '@naturalcycles/nodejs-lib';
 import { CommonDB } from '../common.db';
 import { DBQuery } from '../index';
@@ -33,12 +33,12 @@ export interface DBPipelineBackupOptions extends TransformLogProgressOptions {
     /**
      * If set - will do "incremental backup" (not full), only for entities that updated >= `sinceUpdated`
      */
-    sinceUpdated?: UnixTimestampNumber;
+    sinceUpdated?: UnixTimestamp;
     /**
      * Map for each table a `sinceUpdated` timestamp, or `undefined`.
      * If set - will do "incremental backup" (not full), only for entities that updated >= `sinceUpdated` (on a per table basis)
      */
-    sinceUpdatedPerTable?: StringMap<UnixTimestampNumber>;
+    sinceUpdatedPerTable?: StringMap<UnixTimestamp>;
     /**
      * By default, dbPipelineBackup creates a Query based on sinceUpdated.
      * But if queryPerTable is set for a table - it will override the Query that is ran for that table

package/dist/pipeline/dbPipelineCopy.d.ts

@@ -1,4 +1,4 @@
-import { AsyncMapper, ErrorMode } from '@naturalcycles/js-lib';
+import { AsyncMapper, ErrorMode, UnixTimestamp } from '@naturalcycles/js-lib';
 import { NDJsonStats, TransformLogProgressOptions, TransformMapOptions } from '@naturalcycles/nodejs-lib';
 import { CommonDB } from '../common.db';
 import { CommonDBSaveOptions } from '../db.model';
@@ -39,7 +39,7 @@ export interface DBPipelineCopyOptions extends TransformLogProgressOptions {
      *
      * @default undefined
      */
-    sinceUpdated?: number;
+    sinceUpdated?: UnixTimestamp;
     /**
      * Optionally you can provide mapper that is going to run for each table.
      *

package/dist/pipeline/dbPipelineRestore.d.ts

@@ -1,4 +1,4 @@
-import { AsyncMapper, ErrorMode } from '@naturalcycles/js-lib';
+import { AsyncMapper, ErrorMode, UnixTimestamp } from '@naturalcycles/js-lib';
 import { NDJsonStats, TransformLogProgressOptions, TransformMapOptions } from '@naturalcycles/nodejs-lib';
 import { CommonDB } from '../common.db';
 import { CommonDBSaveOptions } from '../index';
@@ -46,7 +46,7 @@ export interface DBPipelineRestoreOptions extends TransformLogProgressOptions {
      *
      * @default undefined
      */
-    sinceUpdated?: number;
+    sinceUpdated?: UnixTimestamp;
     /**
      * @default false
      * If true - will read ${table}.schema.json files and recreate tables before importing.

package/package.json

@@ -43,9 +43,9 @@
     "url": "https://github.com/NaturalCycles/db-lib"
   },
   "engines": {
-    "node": ">=20.13"
+    "node": ">=22.10.0"
   },
-  "version": "9.24.1",
+  "version": "9.25.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/adapter/file/file.db.ts

@@ -10,6 +10,7 @@ import {
   generateJsonSchemaFromData,
   JsonSchemaRootObject,
   ObjectWithId,
+  UnixTimestampMillis,
 } from '@naturalcycles/js-lib'
 import { dimGrey, readableCreate, ReadableTyped } from '@naturalcycles/nodejs-lib'
 import {
@@ -240,14 +241,14 @@ export class FileDB extends BaseCommonDB implements CommonDB {
     return rows
   }
 
-  private logStarted(op: string): number {
+  private logStarted(op: string): UnixTimestampMillis {
     if (this.cfg.logStarted) {
       this.cfg.logger?.log(`>> ${op}`)
     }
-    return Date.now()
+    return Date.now() as UnixTimestampMillis
   }
 
-  private logFinished(started: number, op: string): void {
+  private logFinished(started: UnixTimestampMillis, op: string): void {
     if (!this.cfg.logFinished) return
     this.cfg.logger?.log(`<< ${op} ${dimGrey(`in ${_since(started)}`)}`)
   }

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

@@ -16,6 +16,7 @@ import {
   ObjectWithId,
   pMap,
   StringMap,
+  UnixTimestampMillis,
 } from '@naturalcycles/js-lib'
 import {
   _pipeline,
@@ -314,7 +315,7 @@ export class InMemoryDB implements CommonDB {
     _assert(this.cfg.persistenceEnabled, 'flushToDisk() called but persistenceEnabled=false')
     const { persistentStoragePath, persistZip } = this.cfg
 
-    const started = Date.now()
+    const started = Date.now() as UnixTimestampMillis
 
     await fs2.emptyDirAsync(persistentStoragePath)
 
@@ -343,7 +344,7 @@ export class InMemoryDB implements CommonDB {
     _assert(this.cfg.persistenceEnabled, 'restoreFromDisk() called but persistenceEnabled=false')
     const { persistentStoragePath } = this.cfg
 
-    const started = Date.now()
+    const started = Date.now() as UnixTimestampMillis
 
     await fs2.ensureDirAsync(persistentStoragePath)
 

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

@@ -1,9 +1,11 @@
 import {
+  AnyObject,
   BaseDBEntity,
   CommonLogger,
   ErrorMode,
+  NumberOfMilliseconds,
   Promisable,
-  UnixTimestampNumber,
+  UnixTimestamp,
   ZodError,
   ZodSchema,
 } from '@naturalcycles/js-lib'
@@ -146,6 +148,17 @@ export interface CommonDaoCfg<
    */
   validateOnSave?: boolean
 
+  /**
+   * Defaults to undefined == disabled.
+   * If set - enable the monitoring of validation time and will alert on crossing the threshold.
+   */
+  debugValidationTimeThreshhold?: NumberOfMilliseconds
+
+  /**
+   * Called when debugValidationTimeThreshhold is crossed.
+   */
+  onValidationTimeThreshold?: (info: AnyObject) => void
+
   /**
    * Defaults to false.
    * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
@@ -257,7 +270,7 @@ 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
+  readAt?: UnixTimestamp
 }
 
 export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseDBEntity>

package/src/commondao/common.dao.ts

@@ -23,7 +23,7 @@ import {
   pMap,
   SKIP,
   StringMap,
-  UnixTimestampMillisNumber,
+  UnixTimestampMillis,
   Unsaved,
   ZodSchema,
   ZodValidationError,
@@ -1257,7 +1257,23 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
       })
     } else {
       // Joi
+      const start = performance.now()
       const vr = getValidationResult(obj, schema, objectName)
+      const end = performance.now()
+      const tookMillis = end - start
+
+      if (
+        this.cfg.debugValidationTimeThreshhold &&
+        tookMillis >= this.cfg.debugValidationTimeThreshhold
+      ) {
+        this.cfg.onValidationTimeThreshold?.({
+          tookMillis,
+          error: !!vr.error,
+          table,
+          obj,
+        })
+      }
+
       error = vr.error
       convertedValue = vr.value
     }
@@ -1326,7 +1342,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     }
   }
 
-  protected logResult(started: number, op: string, res: any, table: string): void {
+  protected logResult(started: UnixTimestampMillis, op: string, res: any, table: string): void {
     if (!this.cfg.logLevel) return
 
     let logRes: any
@@ -1349,19 +1365,19 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     this.cfg.logger?.log(`<< ${table}.${op}: ${logRes} in ${_since(started)}`, ...args)
   }
 
-  protected logSaveResult(started: number, op: string, table: string): void {
+  protected logSaveResult(started: UnixTimestampMillis, op: string, table: string): void {
     if (!this.cfg.logLevel) return
     this.cfg.logger?.log(`<< ${table}.${op} in ${_since(started)}`)
   }
 
-  protected logStarted(op: string, table: string, force = false): UnixTimestampMillisNumber {
+  protected logStarted(op: string, table: string, force = false): UnixTimestampMillis {
     if (this.cfg.logStarted || force) {
       this.cfg.logger?.log(`>> ${table}.${op}`)
     }
-    return Date.now()
+    return Date.now() as UnixTimestampMillis
   }
 
-  protected logSaveStarted(op: string, items: any, table: string): UnixTimestampMillisNumber {
+  protected logSaveStarted(op: string, items: any, table: string): UnixTimestampMillis {
     if (this.cfg.logStarted) {
       const args: any[] = [`>> ${table}.${op}`]
       if (Array.isArray(items)) {
@@ -1379,7 +1395,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
       this.cfg.logger?.log(...args)
     }
 
-    return Date.now()
+    return Date.now() as UnixTimestampMillis
   }
 }
 

package/src/db.model.ts

@@ -1,4 +1,4 @@
-import { ObjectWithId, UnixTimestampNumber } from '@naturalcycles/js-lib'
+import { ObjectWithId, UnixTimestamp } from '@naturalcycles/js-lib'
 import { CommonDB } from './common.db'
 
 /**
@@ -57,7 +57,7 @@ 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
+  readAt?: UnixTimestamp
 }
 
 /**

package/src/kv/commonKeyValueDB.ts

@@ -1,4 +1,4 @@
-import { Integer, UnixTimestampNumber } from '@naturalcycles/js-lib'
+import { Integer, UnixTimestamp } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDBCreateOptions } from '../db.model'
 
@@ -72,7 +72,7 @@ export interface CommonKeyValueDBSaveBatchOptions {
    * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
    * E.g EXAT in Redis.
    */
-  expireAt?: UnixTimestampNumber
+  expireAt?: UnixTimestamp
 }
 
 /**

package/src/kv/commonKeyValueDaoMemoCache.ts

@@ -1,4 +1,10 @@
-import { AsyncMemoCache, localTime, MISS, NumberOfSeconds } from '@naturalcycles/js-lib'
+import {
+  AsyncMemoCache,
+  localTime,
+  MISS,
+  NumberOfSeconds,
+  UnixTimestamp,
+} from '@naturalcycles/js-lib'
 import { CommonKeyValueDao } from './commonKeyValueDao'
 
 export interface CommonKeyValueDaoMemoCacheCfg<VALUE> {
@@ -26,7 +32,9 @@ export class CommonKeyValueDaoMemoCache<VALUE> implements AsyncMemoCache<string,
   }
 
   async set(k: string, v: VALUE): Promise<void> {
-    const opt = this.cfg.ttl ? { expireAt: localTime.nowUnix() + this.cfg.ttl } : undefined
+    const opt = this.cfg.ttl
+      ? { expireAt: (localTime.nowUnix() + this.cfg.ttl) as UnixTimestamp }
+      : undefined
 
     await this.cfg.dao.save(k, v, opt)
   }

package/src/pipeline/dbPipelineBackup.ts

@@ -6,7 +6,7 @@ import {
   localTime,
   pMap,
   StringMap,
-  UnixTimestampNumber,
+  UnixTimestamp,
 } from '@naturalcycles/js-lib'
 import {
   _pipeline,
@@ -61,13 +61,13 @@ export interface DBPipelineBackupOptions extends TransformLogProgressOptions {
   /**
    * If set - will do "incremental backup" (not full), only for entities that updated >= `sinceUpdated`
    */
-  sinceUpdated?: UnixTimestampNumber
+  sinceUpdated?: UnixTimestamp
 
   /**
    * Map for each table a `sinceUpdated` timestamp, or `undefined`.
    * If set - will do "incremental backup" (not full), only for entities that updated >= `sinceUpdated` (on a per table basis)
    */
-  sinceUpdatedPerTable?: StringMap<UnixTimestampNumber>
+  sinceUpdatedPerTable?: StringMap<UnixTimestamp>
 
   /**
    * By default, dbPipelineBackup creates a Query based on sinceUpdated.

package/src/pipeline/dbPipelineCopy.ts

@@ -5,6 +5,7 @@ import {
   ErrorMode,
   localTime,
   pMap,
+  UnixTimestamp,
 } from '@naturalcycles/js-lib'
 import {
   _pipeline,
@@ -68,7 +69,7 @@ export interface DBPipelineCopyOptions extends TransformLogProgressOptions {
    *
    * @default undefined
    */
-  sinceUpdated?: number
+  sinceUpdated?: UnixTimestamp
 
   /**
    * Optionally you can provide mapper that is going to run for each table.

package/src/pipeline/dbPipelineRestore.ts

@@ -8,6 +8,7 @@ import {
   JsonSchemaObject,
   localTime,
   pMap,
+  UnixTimestamp,
 } from '@naturalcycles/js-lib'
 import {
   _pipeline,
@@ -80,7 +81,7 @@ export interface DBPipelineRestoreOptions extends TransformLogProgressOptions {
    *
    * @default undefined
    */
-  sinceUpdated?: number
+  sinceUpdated?: UnixTimestamp
 
   /**
    * @default false

package/src/testing/test.model.ts

@@ -1,4 +1,10 @@
-import { _range, BaseDBEntity, jsonSchema, JsonSchemaObject } from '@naturalcycles/js-lib'
+import {
+  _range,
+  BaseDBEntity,
+  jsonSchema,
+  JsonSchemaObject,
+  UnixTimestamp,
+} from '@naturalcycles/js-lib'
 import {
   baseDBEntitySchema,
   binarySchema,
@@ -8,7 +14,7 @@ import {
   stringSchema,
 } from '@naturalcycles/nodejs-lib'
 
-const MOCK_TS_2018_06_21 = 1529539200
+const MOCK_TS_2018_06_21 = 1529539200 as UnixTimestamp
 
 export const TEST_TABLE = 'TEST_TABLE'