@naturalcycles/db-lib 9.14.3 → 9.15.0

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, DBPatch, DBTransaction, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
-import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
+import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -86,11 +86,11 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * 2. Applies the patch on top of loaded data.
      * 3. Saves (as fast as possible since the read) with the Patch applied, but only if the data has changed.
      */
-    patchById(id: string, patch: Partial<BM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<BM>;
+    patchById(id: string, patch: Partial<BM>, opt?: CommonDaoPatchByIdOptions<DBM>): Promise<BM>;
     /**
      * Like patchById, but runs all operations within a Transaction.
      */
-    patchByIdInTransaction(id: string, patch: Partial<BM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<BM>;
+    patchByIdInTransaction(id: string, patch: Partial<BM>, opt?: CommonDaoPatchByIdOptions<DBM>): Promise<BM>;
     /**
      * Same as patchById, but takes the whole object as input.
      * This "whole object" is mutated with the patch and returned.

package/dist/commondao/common.dao.js

@@ -486,6 +486,7 @@ class CommonDao {
             }
         }
         else {
+            (0, js_lib_1._assert)(!opt.requireToExist, `${this.cfg.table}.patchById(${id}) is required, but missing`);
             patched = this.create({ ...patch, id }, opt);
         }
         return await this.save(patched, opt);

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

@@ -162,7 +162,7 @@ export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity
     useUpdatedProperty?: boolean;
     /**
      * Defaults to false.
-     * If true - run patch operations (patch, patchById) in a Transaction.
+     * If true - run patch operations (patch, patchById, patchByIdOrCreate) in a Transaction.
      *
      * @experimental
      */
@@ -211,6 +211,16 @@ export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseD
      */
     skipIfEquals?: BM;
 }
+export interface CommonDaoPatchByIdOptions<DBM extends BaseDBEntity> extends CommonDaoSaveBatchOptions<DBM> {
+    /**
+     * Defaults to false.
+     * With false, if the row doesn't exist - it will be auto-created with `dao.create`.
+     * With true, if the row doesn't exist - it will throw an error.
+     *
+     * Use true when you expect the row to exist and it would be an error if it doesn't.
+     */
+    requireToExist?: boolean;
+}
 export interface CommonDaoPatchOptions<DBM extends BaseDBEntity> extends CommonDaoSaveBatchOptions<DBM> {
     /**
      * If true - patch will skip loading from DB, and will just optimistically patch passed object.

package/dist/query/dbQuery.d.ts

@@ -69,6 +69,9 @@ export declare class DBQuery<ROW extends ObjectWithId> {
     filter(name: keyof ROW, op: DBQueryFilterOperator, val: any): this;
     filterEq(name: keyof ROW, val: any): this;
     filterIn(name: keyof ROW, val: any[]): this;
+    /**
+     * Passing 0 means "no limit".
+     */
     limit(limit: number): this;
     offset(offset: number): this;
     order(name: keyof ROW, descending?: boolean): this;

package/dist/query/dbQuery.js

@@ -54,6 +54,9 @@ class DBQuery {
         this._filters.push({ name, op: 'in', val });
         return this;
     }
+    /**
+     * Passing 0 means "no limit".
+     */
     limit(limit) {
         this._limitValue = limit;
         return this;

package/dist/testing/daoTest.js

@@ -8,6 +8,7 @@ const __1 = require("..");
 const common_dao_1 = require("../commondao/common.dao");
 const dbTest_1 = require("./dbTest");
 const test_model_1 = require("./test.model");
+// eslint-disable-next-line jest/no-export
 function runCommonDaoTest(db, quirks = {}) {
     const { support } = db;
     const dao = new common_dao_1.CommonDao({

package/dist/testing/keyValueDBTest.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCommonKeyValueDBTest = runCommonKeyValueDBTest;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const test_model_1 = require("./test.model");
+/* eslint-disable jest/no-export */
 const testIds = (0, js_lib_1._range)(1, 4).map(n => `id${n}`);
 const testEntries = testIds.map(id => [id, Buffer.from(`${id}value`)]);
 function runCommonKeyValueDBTest(db) {

package/dist/testing/keyValueDaoTest.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCommonKeyValueDaoTest = runCommonKeyValueDaoTest;
 const js_lib_1 = require("@naturalcycles/js-lib");
+/* eslint-disable jest/no-export */
 const testIds = (0, js_lib_1._range)(1, 4).map(n => `id${n}`);
 const testEntries = testIds.map(id => [id, Buffer.from(`${id}value`)]);
 function runCommonKeyValueDaoTest(dao) {

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@naturalcycles/db-lib",
   "scripts": {
-    "prepare": "husky"
+    "prepare": "husky",
+    "build": "dev-lib build",
+    "test": "dev-lib test",
+    "lint": "dev-lib lint",
+    "bt": "dev-lib bt",
+    "lbt": "dev-lib lbt"
   },
   "dependencies": {
     "@naturalcycles/js-lib": "^14.116.0",
@@ -9,8 +14,8 @@
   },
   "devDependencies": {
     "@naturalcycles/bench-lib": "^3.0.0",
-    "@naturalcycles/dev-lib": "^13.0.0",
-    "@types/node": "^20.2.1",
+    "@naturalcycles/dev-lib": "^15.4.1",
+    "@types/node": "^22.1.0",
     "jest": "^29.0.0"
   },
   "files": [
@@ -38,9 +43,9 @@
     "url": "https://github.com/NaturalCycles/db-lib"
   },
   "engines": {
-    "node": ">=18.12"
+    "node": ">=20.13"
   },
-  "version": "9.14.3",
+  "version": "9.15.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

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

@@ -203,7 +203,7 @@ export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity
 
   /**
    * Defaults to false.
-   * If true - run patch operations (patch, patchById) in a Transaction.
+   * If true - run patch operations (patch, patchById, patchByIdOrCreate) in a Transaction.
    *
    * @experimental
    */
@@ -260,6 +260,18 @@ export interface CommonDaoSaveOptions<BM extends BaseDBEntity, DBM extends BaseD
   skipIfEquals?: BM
 }
 
+export interface CommonDaoPatchByIdOptions<DBM extends BaseDBEntity>
+  extends CommonDaoSaveBatchOptions<DBM> {
+  /**
+   * Defaults to false.
+   * With false, if the row doesn't exist - it will be auto-created with `dao.create`.
+   * With true, if the row doesn't exist - it will throw an error.
+   *
+   * Use true when you expect the row to exist and it would be an error if it doesn't.
+   */
+  requireToExist?: boolean
+}
+
 export interface CommonDaoPatchOptions<DBM extends BaseDBEntity>
   extends CommonDaoSaveBatchOptions<DBM> {
   /**

package/src/commondao/common.dao.ts

@@ -52,6 +52,7 @@ import {
   CommonDaoHooks,
   CommonDaoLogLevel,
   CommonDaoOptions,
+  CommonDaoPatchByIdOptions,
   CommonDaoPatchOptions,
   CommonDaoSaveBatchOptions,
   CommonDaoSaveOptions,
@@ -635,7 +636,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   async patchById(
     id: string,
     patch: Partial<BM>,
-    opt: CommonDaoSaveBatchOptions<DBM> = {},
+    opt: CommonDaoPatchByIdOptions<DBM> = {},
   ): Promise<BM> {
     if (this.cfg.patchInTransaction && !opt.tx) {
       // patchInTransaction means that we should run this op in Transaction
@@ -655,6 +656,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
         return patched
       }
     } else {
+      _assert(!opt.requireToExist, `${this.cfg.table}.patchById(${id}) is required, but missing`)
       patched = this.create({ ...patch, id }, opt)
     }
 
@@ -667,7 +669,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   async patchByIdInTransaction(
     id: string,
     patch: Partial<BM>,
-    opt?: CommonDaoSaveBatchOptions<DBM>,
+    opt?: CommonDaoPatchByIdOptions<DBM>,
   ): Promise<BM> {
     return await this.runInTransaction(async daoTx => {
       return await this.patchById(id, patch, { ...opt, tx: daoTx.tx })

package/src/query/dbQuery.ts

@@ -128,6 +128,9 @@ export class DBQuery<ROW extends ObjectWithId> {
     return this
   }
 
+  /**
+   * Passing 0 means "no limit".
+   */
   limit(limit: number): this {
     this._limitValue = limit
     return this

package/src/testing/daoTest.ts

@@ -14,6 +14,7 @@ import {
   testItemBMSchema,
 } from './test.model'
 
+// eslint-disable-next-line jest/no-export
 export function runCommonDaoTest(db: CommonDB, quirks: CommonDBImplementationQuirks = {}): void {
   const { support } = db
   const dao = new CommonDao({

package/src/testing/dbTest.ts

@@ -11,6 +11,8 @@ import {
 } from './test.model'
 import { deepFreeze } from './test.util'
 
+/* eslint-disable jest/no-export */
+
 /**
  * All options default to `false`.
  */

package/src/testing/keyValueDBTest.ts

@@ -2,6 +2,8 @@ import { _range, _sortBy } from '@naturalcycles/js-lib'
 import { CommonKeyValueDB, KeyValueDBTuple } from '../kv/commonKeyValueDB'
 import { TEST_TABLE } from './test.model'
 
+/* eslint-disable jest/no-export */
+
 const testIds = _range(1, 4).map(n => `id${n}`)
 
 const testEntries: KeyValueDBTuple[] = testIds.map(id => [id, Buffer.from(`${id}value`)])

package/src/testing/keyValueDaoTest.ts

@@ -2,6 +2,8 @@ import { _range, _sortBy } from '@naturalcycles/js-lib'
 import { CommonKeyValueDao } from '../kv/commonKeyValueDao'
 import { KeyValueDBTuple } from '../kv/commonKeyValueDB'
 
+/* eslint-disable jest/no-export */
+
 const testIds = _range(1, 4).map(n => `id${n}`)
 const testEntries: KeyValueDBTuple[] = testIds.map(id => [id, Buffer.from(`${id}value`)])