@naturalcycles/db-lib 10.43.0 → 10.45.0

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

@@ -201,7 +201,7 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      *   return dbm
      * }
      */
-    static decompressLegacyRow<T extends ObjectWithId>(row: T): Promise<T>;
+    static decompressLegacyRow<T extends ObjectWithId>(this: void, row: T): Promise<T>;
     /**
      * Temporary helper to migrate from the old `data` compressed property to the new `__compressed` property.
      * Use as your `beforeDBMToBM` hook during the migration period.

package/dist/commondao/common.dao.js

@@ -89,7 +89,7 @@ export class CommonDao {
         if (!id)
             return null;
         const [row] = await this.loadByIds([id], opt);
-        return await (this.anyToDBM(row, opt) || null);
+        return await this.anyToDBM(row, opt);
     }
     async getByIds(ids, opt = {}) {
         const dbms = await this.loadByIds(ids, opt);

package/dist/kv/commonSyncKeyValueDB.d.ts

@@ -0,0 +1,56 @@
+import type { Pipeline } from '@naturalcycles/nodejs-lib/stream';
+import type { CommonDBCreateOptions } from '../db.model.js';
+import type { CommonKeyValueDBSaveBatchOptions, CommonKeyValueDBSupport, IncrementTuple, KeyValueDBTuple } from './commonKeyValueDB.js';
+/**
+ * Common interface for Synchronous Key-Value database implementations.
+ * Same as CommonKeyValueDB, but with a sync implementation,
+ * modeled after e.g SQLite in Node.js, which is designed to be sync.
+ *
+ * Methods use `Sync` postfix to allow one implementation to support
+ * both async and sync CommonKeyValueDB interfaces.
+ *
+ * @experimental
+ */
+export interface CommonSyncKeyValueDB {
+    /**
+     * Manifest of supported features.
+     */
+    support: CommonKeyValueDBSupport;
+    /**
+     * Check that DB connection is working properly.
+     */
+    pingSync: () => void;
+    /**
+     * Will do like `create table ...` for mysql.
+     * Caution! dropIfExists defaults to false. If set to true - will actually DROP the table!
+     */
+    createTableSync: (table: string, opt?: CommonDBCreateOptions) => void;
+    /**
+     * Returns an array of tuples [key, value]. Not found values are not returned (no error is thrown).
+     *
+     * Currently it is NOT required to maintain the same order as input `ids`.
+     */
+    getByIdsSync: (table: string, ids: string[]) => KeyValueDBTuple[];
+    deleteByIdsSync: (table: string, ids: string[]) => void;
+    saveBatchSync: (table: string, entries: KeyValueDBTuple[], opt?: CommonKeyValueDBSaveBatchOptions) => void;
+    streamIds: (table: string, limit?: number) => Pipeline<string>;
+    streamValues: (table: string, limit?: number) => Pipeline<Buffer>;
+    streamEntries: (table: string, limit?: number) => Pipeline<KeyValueDBTuple>;
+    countSync: (table: string) => number;
+    /**
+     * Perform a batch of Increment operations.
+     * Given entries array, increment each key of it (1st index of the tuple) by the given amount (2nd index of the tuple).
+     *
+     * Example:
+     * [
+     *   ['key1', 2],
+     *   ['key2', 3],
+     * ]
+     * would increment `key1` by 2, and `key2` by 3.
+     *
+     * Returns the entries array with tuples of the same structure, with updated numbers.
+     *
+     * @experimental
+     */
+    incrementBatchSync: (table: string, entries: IncrementTuple[]) => IncrementTuple[];
+}

package/dist/kv/commonSyncKeyValueDB.js

@@ -0,0 +1 @@
+export {};

package/dist/kv/index.d.ts

@@ -1,3 +1,4 @@
 export * from './commonKeyValueDao.js';
 export * from './commonKeyValueDaoMemoCache.js';
 export * from './commonKeyValueDB.js';
+export * from './commonSyncKeyValueDB.js';

package/dist/kv/index.js

@@ -1,3 +1,4 @@
 export * from './commonKeyValueDao.js';
 export * from './commonKeyValueDaoMemoCache.js';
 export * from './commonKeyValueDB.js';
+export * from './commonSyncKeyValueDB.js';

package/dist/testing/commonDaoTest.js

@@ -1,7 +1,6 @@
 import { _sortBy } from '@naturalcycles/js-lib/array/sort.js';
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js';
 import { _deepCopy, _filterObject, _omit, _pick } from '@naturalcycles/js-lib/object';
-import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv';
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream';
 import { CommonDao } from '../commondao/common.dao.js';
 import { DBQuery } from '../query/dbQuery.js';
@@ -13,7 +12,7 @@ export async function runCommonDaoTest(db, quirks = {}) {
     const dao = new CommonDao({
         table: TEST_TABLE,
         db,
-        validateBM: AjvSchema.create(testItemBMSchema).getValidationFunction(),
+        validateBM: testItemBMSchema.getValidationFunction(),
     });
     const items = createTestItemsBM(3);
     const itemsClone = _deepCopy(items);

package/dist/testing/test.model.d.ts

@@ -1,5 +1,5 @@
 import type { BaseDBEntity } from '@naturalcycles/js-lib/types';
-import type { JsonSchemaObjectBuilder } from '@naturalcycles/nodejs-lib/ajv';
+import type { JSchema } from '@naturalcycles/nodejs-lib/ajv';
 export declare const TEST_TABLE = "TEST_TABLE";
 export declare const TEST_TABLE_2 = "TEST_TABLE_2";
 export interface TestItemBM extends BaseDBEntity {
@@ -19,7 +19,7 @@ export interface TestItemTM {
     even?: boolean;
 }
 export declare const testItemTMSchema: any;
-export declare const testItemBMSchema: JsonSchemaObjectBuilder<TestItemBM, false>;
+export declare const testItemBMSchema: JSchema<TestItemBM, false>;
 export declare function createTestItemDBM(num?: number): TestItemDBM;
 export declare function createTestItemBM(num?: number): TestItemBM;
 export declare function createTestItemsDBM(count?: number): TestItemDBM[];

package/dist/validation/index.d.ts

@@ -1,5 +1,5 @@
 import type { CommonDBOptions } from '../db.model.js';
-export declare const commonDBOptionsSchema: () => JsonSchemaObjectBuilder<CommonDBOptions, false>;
+export declare const commonDBOptionsSchema: () => JBuilder<CommonDBOptions, false>;
 export declare const commonDBSaveOptionsSchema: <ROW extends ObjectWithId>() => any;
 export declare const dbQueryFilterOperatorSchema: any;
 export declare const dbQueryFilterSchema: <ROW extends ObjectWithId>() => any;

package/dist/validation/index.js

@@ -1,10 +1,10 @@
-import { j, JsonSchemaAnyBuilder } from '@naturalcycles/nodejs-lib/ajv';
+import { j, JBuilder } from '@naturalcycles/nodejs-lib/ajv';
 import { dbQueryFilterOperatorValues } from '../query/dbQuery.js';
 // oxlint-disable typescript/explicit-function-return-type
 // DBTransaction schema - validates presence without deep validation
 const dbTransactionSchema = j.object.any().castAs();
 // Schema that accepts any value (string, number, boolean, object, array, null)
-const anyValueSchema = new JsonSchemaAnyBuilder({});
+const anyValueSchema = new JBuilder({});
 export const commonDBOptionsSchema = () => j.object({
     tx: dbTransactionSchema.optional(),
 });

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@naturalcycles/db-lib",
   "type": "module",
-  "version": "10.43.0",
+  "version": "10.45.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@naturalcycles/nodejs-lib": "^15"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260201.1",
-    "@naturalcycles/dev-lib": "18.4.2"
+    "@naturalcycles/dev-lib": "20.36.0"
   },
   "files": [
     "dist",

package/src/commondao/common.dao.ts

@@ -137,7 +137,7 @@ export class CommonDao<
   async getByIdAsDBM(id?: ID | null, opt: CommonDaoReadOptions = {}): Promise<DBM | null> {
     if (!id) return null
     const [row] = await this.loadByIds([id], opt)
-    return await (this.anyToDBM(row, opt) || null)
+    return await this.anyToDBM(row, opt)
   }
 
   async getByIds(ids: ID[], opt: CommonDaoReadOptions = {}): Promise<BM[]> {
@@ -989,7 +989,7 @@ export class CommonDao<
    *   return dbm
    * }
    */
-  static async decompressLegacyRow<T extends ObjectWithId>(row: T): Promise<T> {
+  static async decompressLegacyRow<T extends ObjectWithId>(this: void, row: T): Promise<T> {
     // Check both __compressed (current) and data (legacy) for backward compatibility
     const compressed = (row as any).__compressed ?? (row as any).data
     if (!Buffer.isBuffer(compressed)) return row

package/src/kv/commonSyncKeyValueDB.ts

@@ -0,0 +1,74 @@
+import type { Pipeline } from '@naturalcycles/nodejs-lib/stream'
+import type { CommonDBCreateOptions } from '../db.model.js'
+import type {
+  CommonKeyValueDBSaveBatchOptions,
+  CommonKeyValueDBSupport,
+  IncrementTuple,
+  KeyValueDBTuple,
+} from './commonKeyValueDB.js'
+
+/**
+ * Common interface for Synchronous Key-Value database implementations.
+ * Same as CommonKeyValueDB, but with a sync implementation,
+ * modeled after e.g SQLite in Node.js, which is designed to be sync.
+ *
+ * Methods use `Sync` postfix to allow one implementation to support
+ * both async and sync CommonKeyValueDB interfaces.
+ *
+ * @experimental
+ */
+export interface CommonSyncKeyValueDB {
+  /**
+   * Manifest of supported features.
+   */
+  support: CommonKeyValueDBSupport
+
+  /**
+   * Check that DB connection is working properly.
+   */
+  pingSync: () => void
+
+  /**
+   * Will do like `create table ...` for mysql.
+   * Caution! dropIfExists defaults to false. If set to true - will actually DROP the table!
+   */
+  createTableSync: (table: string, opt?: CommonDBCreateOptions) => void
+
+  /**
+   * Returns an array of tuples [key, value]. Not found values are not returned (no error is thrown).
+   *
+   * Currently it is NOT required to maintain the same order as input `ids`.
+   */
+  getByIdsSync: (table: string, ids: string[]) => KeyValueDBTuple[]
+
+  deleteByIdsSync: (table: string, ids: string[]) => void
+
+  saveBatchSync: (
+    table: string,
+    entries: KeyValueDBTuple[],
+    opt?: CommonKeyValueDBSaveBatchOptions,
+  ) => void
+
+  streamIds: (table: string, limit?: number) => Pipeline<string>
+  streamValues: (table: string, limit?: number) => Pipeline<Buffer>
+  streamEntries: (table: string, limit?: number) => Pipeline<KeyValueDBTuple>
+
+  countSync: (table: string) => number
+
+  /**
+   * Perform a batch of Increment operations.
+   * Given entries array, increment each key of it (1st index of the tuple) by the given amount (2nd index of the tuple).
+   *
+   * Example:
+   * [
+   *   ['key1', 2],
+   *   ['key2', 3],
+   * ]
+   * would increment `key1` by 2, and `key2` by 3.
+   *
+   * Returns the entries array with tuples of the same structure, with updated numbers.
+   *
+   * @experimental
+   */
+  incrementBatchSync: (table: string, entries: IncrementTuple[]) => IncrementTuple[]
+}

package/src/kv/index.ts

@@ -1,3 +1,4 @@
 export * from './commonKeyValueDao.js'
 export * from './commonKeyValueDaoMemoCache.js'
 export * from './commonKeyValueDB.js'
+export * from './commonSyncKeyValueDB.js'

package/src/testing/commonDaoTest.ts

@@ -1,7 +1,6 @@
 import { _sortBy } from '@naturalcycles/js-lib/array/sort.js'
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js'
 import { _deepCopy, _filterObject, _omit, _pick } from '@naturalcycles/js-lib/object'
-import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv'
 import { Pipeline } from '@naturalcycles/nodejs-lib/stream'
 import { CommonDao } from '../commondao/common.dao.js'
 import type { CommonDB } from '../commondb/common.db.js'
@@ -21,7 +20,7 @@ export async function runCommonDaoTest(
   const dao = new CommonDao({
     table: TEST_TABLE,
     db,
-    validateBM: AjvSchema.create(testItemBMSchema).getValidationFunction(),
+    validateBM: testItemBMSchema.getValidationFunction(),
   })
 
   const items = createTestItemsBM(3)

package/src/testing/test.model.ts

@@ -1,7 +1,7 @@
 import { _range } from '@naturalcycles/js-lib/array/range.js'
 import type { BaseDBEntity, UnixTimestamp } from '@naturalcycles/js-lib/types'
+import type { JSchema } from '@naturalcycles/nodejs-lib/ajv'
 import { j } from '@naturalcycles/nodejs-lib/ajv'
-import type { JsonSchemaObjectBuilder } from '@naturalcycles/nodejs-lib/ajv'
 
 const MOCK_TS_2018_06_21 = 1529539200 as UnixTimestamp
 
@@ -31,19 +31,18 @@ export const testItemTMSchema = j.object<TestItemTM>({
   even: j.boolean().optional(),
 })
 
-export const testItemBMSchema: JsonSchemaObjectBuilder<TestItemBM, false> =
-  j.object.dbEntity<TestItemBM>({
-    // todo: figure out how to not copy-paste these 3 fields
-    id: j.string(), // todo: not strictly needed here
-    created: j.number().integer().unixTimestamp(),
-    updated: j.number().integer().unixTimestamp(),
-    k1: j.string(),
-    k2: j.string().nullable().optional(),
-    k3: j.number().optional(),
-    even: j.boolean().optional(),
-    b1: j.buffer().optional(),
-    nested: j.object.infer({ foo: j.number() }).optional(),
-  })
+export const testItemBMSchema: JSchema<TestItemBM, false> = j.object.dbEntity<TestItemBM>({
+  // todo: figure out how to not copy-paste these 3 fields
+  id: j.string(), // todo: not strictly needed here
+  created: j.number().integer().unixTimestamp(),
+  updated: j.number().integer().unixTimestamp(),
+  k1: j.string(),
+  k2: j.string().nullable().optional(),
+  k3: j.number().optional(),
+  even: j.boolean().optional(),
+  b1: j.buffer().optional(),
+  nested: j.object.infer({ foo: j.number() }).optional(),
+})
 
 export function createTestItemDBM(num = 1): TestItemDBM {
   return {

package/src/validation/index.ts

@@ -1,9 +1,8 @@
 import type { ObjectWithId } from '@naturalcycles/js-lib/types'
-import { j, JsonSchemaAnyBuilder } from '@naturalcycles/nodejs-lib/ajv'
-import type { JsonSchemaObjectBuilder } from '@naturalcycles/nodejs-lib/ajv'
+import { j, JBuilder } from '@naturalcycles/nodejs-lib/ajv'
 import type { CommonDBOptions, CommonDBSaveOptions, DBTransaction } from '../db.model.js'
-import { dbQueryFilterOperatorValues } from '../query/dbQuery.js'
 import type { DBQueryFilter, DBQueryOrder } from '../query/dbQuery.js'
+import { dbQueryFilterOperatorValues } from '../query/dbQuery.js'
 
 // oxlint-disable typescript/explicit-function-return-type
 
@@ -11,9 +10,9 @@ import type { DBQueryFilter, DBQueryOrder } from '../query/dbQuery.js'
 const dbTransactionSchema = j.object.any().castAs<DBTransaction>()
 
 // Schema that accepts any value (string, number, boolean, object, array, null)
-const anyValueSchema = new JsonSchemaAnyBuilder<any, false>({})
+const anyValueSchema = new JBuilder<any, false>({})
 
-export const commonDBOptionsSchema = (): JsonSchemaObjectBuilder<CommonDBOptions, false> =>
+export const commonDBOptionsSchema = (): JBuilder<CommonDBOptions, false> =>
   j.object<CommonDBOptions>({
     tx: dbTransactionSchema.optional(),
   })