@naturalcycles/db-lib 8.37.1 → 8.39.0

package/dist/adapter/inmemory/queryInMemory.js

@@ -4,6 +4,7 @@ exports.queryInMemory = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const FILTER_FNS = {
     '==': (v, val) => v === val,
+    '!=': (v, val) => v !== val,
     '<': (v, val) => v < val,
     '<=': (v, val) => v <= val,
     '>': (v, val) => v > val,

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

@@ -35,6 +35,7 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
      * Throws if readOnly is true
      */
     private requireObjectMutability;
+    private ensureUniqueId;
     getBy(by: keyof DBM, value: any, limit?: number, opt?: CommonDaoOptions): Promise<Saved<BM>[]>;
     getOneBy(by: keyof DBM, value: any, opt?: CommonDaoOptions): Promise<Saved<BM> | null>;
     getAll(opt?: CommonDaoOptions): Promise<Saved<BM>[]>;
@@ -86,9 +87,6 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
      * Mutates with id, created, updated
      */
     save(bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
-    private ensureImmutableDontExist;
-    private ensureUniqueId;
-    private throwIfObjectExists;
     /**
      * Loads the row by id.
      * Creates the row (via this.create()) if it doesn't exist

package/dist/commondao/common.dao.js

@@ -175,14 +175,25 @@ class CommonDao {
     /**
      * Throws if readOnly is true
      */
-    requireObjectMutability() {
-        if (this.cfg.immutable) {
+    requireObjectMutability(opt) {
+        if (this.cfg.immutable && !opt.allowMutability) {
             throw new js_lib_1.AppError(cnst_1.DBLibError.OBJECT_IS_IMMUTABLE, {
                 code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
                 table: this.cfg.table,
             });
         }
     }
+    async ensureUniqueId(table, dbm) {
+        // todo: retry N times
+        const existing = await this.cfg.db.getByIds(table, [dbm.id]);
+        if (existing.length) {
+            throw new js_lib_1.AppError(cnst_1.DBLibError.NON_UNIQUE_ID, {
+                table,
+                code: cnst_1.DBLibError.NON_UNIQUE_ID,
+                ids: existing.map(i => i.id),
+            });
+        }
+    }
     async getBy(by, value, limit = 0, opt) {
         return await this.query().filterEq(by, value).limit(limit).runQuery(opt);
     }
@@ -399,7 +410,7 @@ class CommonDao {
     }
     async streamQueryIdsForEach(q, mapper, opt = {}) {
         q.table = opt.table || q.table;
-        opt.errorMode = opt.errorMode || js_lib_1.ErrorMode.SUPPRESS;
+        opt.errorMode || (opt.errorMode = js_lib_1.ErrorMode.SUPPRESS);
         const op = `streamQueryIdsForEach(${q.pretty()})`;
         const started = this.logStarted(op, q.table, true);
         let count = 0;
@@ -445,8 +456,9 @@ class CommonDao {
         const table = opt.table || this.cfg.table;
         if (opt.ensureUniqueId && idWasGenerated)
             await this.ensureUniqueId(table, dbm);
-        if (this.cfg.immutable)
-            await this.ensureImmutableDontExist(table, [dbm.id]);
+        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+            opt = { ...opt, saveMethod: 'insert' };
+        }
         const op = `save(${dbm.id})`;
         const started = this.logSaveStarted(op, bm, table);
         await this.cfg.db.saveBatch(table, [dbm], {
@@ -456,30 +468,6 @@ class CommonDao {
         this.logSaveResult(started, op, table);
         return bm;
     }
-    async ensureImmutableDontExist(table, ids) {
-        await this.throwIfObjectExists(table, ids, [
-            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-            {
-                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-                table,
-            },
-        ]);
-    }
-    async ensureUniqueId(table, dbm) {
-        // todo: retry N times
-        await this.throwIfObjectExists(table, [dbm.id], [
-            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-            {
-                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-                table,
-            },
-        ]);
-    }
-    async throwIfObjectExists(table, ids, errorMeta) {
-        const existing = await this.cfg.db.getByIds(table, ids);
-        if (existing.length > 0)
-            throw new js_lib_1.AppError(errorMeta[0], { ...errorMeta[1], ids: existing.map(i => i.id) });
-    }
     /**
      * Loads the row by id.
      * Creates the row (via this.create()) if it doesn't exist
@@ -513,8 +501,9 @@ class CommonDao {
             dbm = this.anyToDBM(dbm, opt);
             if (opt.ensureUniqueId && idWasGenerated)
                 await this.ensureUniqueId(table, dbm);
-            if (this.cfg.immutable)
-                await this.ensureImmutableDontExist(table, [dbm.id]);
+        }
+        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+            opt = { ...opt, saveMethod: 'insert' };
         }
         const op = `saveAsDBM(${dbm.id})`;
         const started = this.logSaveStarted(op, dbm, table);
@@ -532,8 +521,9 @@ class CommonDao {
         const dbms = await this.bmsToDBM(bms, opt);
         if (opt.ensureUniqueId)
             throw new js_lib_1.AppError('ensureUniqueId is not supported in saveBatch');
-        if (this.cfg.immutable)
-            await this.ensureImmutableDontExist(table, dbms.map(dbm => dbm.id));
+        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+            opt = { ...opt, saveMethod: 'insert' };
+        }
         const op = `saveBatch ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
             .map(bm => bm.id)
@@ -554,8 +544,9 @@ class CommonDao {
             dbms = this.anyToDBMs(dbms, opt);
             if (opt.ensureUniqueId)
                 throw new js_lib_1.AppError('ensureUniqueId is not supported in saveBatch');
-            if (this.cfg.immutable)
-                await this.ensureImmutableDontExist(table, dbms.map(dbm => dbm.id));
+        }
+        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+            opt = { ...opt, saveMethod: 'insert' };
         }
         const op = `saveBatchAsDBM ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
@@ -573,8 +564,7 @@ class CommonDao {
         if (!id)
             return 0;
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         const op = `deleteById(${id})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -584,8 +574,7 @@ class CommonDao {
     }
     async deleteByIds(ids, opt = {}) {
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         const op = `deleteByIds(${ids.join(', ')})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -600,8 +589,7 @@ class CommonDao {
      */
     async deleteByQuery(q, opt = {}) {
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         q.table = opt.table || q.table;
         const op = `deleteByQuery(${q.pretty()})`;
         const started = this.logStarted(op, q.table);

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

@@ -49,17 +49,18 @@ export interface CommonDaoCfg<BM extends Partial<ObjectWithId<ID>>, DBM extends
     tmSchema?: ObjectSchemaTyped<TM> | AjvSchema<TM>;
     excludeFromIndexes?: (keyof DBM)[];
     /**
-     * @default to false
-     * Set to true to limit DB writing:
-     * * Will throw an error if an object with matching ID already exists during save().
-     * * saveBatch, delete*() and patch() will throw.
+     * Defaults to false.
+     * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
+     * fail for rows that already exist in the DB (if CommonDB implementation supports it).
      *
-     * Although deletion is possible by passing (opt.overrideImmutability === true)
+     * `delete*` and `patch` will throw.
+     *
+     * You can still override saveMethod, or set opt.allowMutability to allow deletion.
      */
     immutable?: boolean;
     /**
-     * @default to false
-     * Set to true to limit DB writing (will throw an error is such case).
+     * Defaults to false.
+     * Set to true to limit DB writing (will throw an error in such case).
      */
     readOnly?: boolean;
     /**

package/dist/query/dbQuery.d.ts

@@ -22,8 +22,8 @@ import { RunQueryResult } from '../db.model';
  *
  * You may also look at queryInMemory() for its implementation (it implements all those).
  */
-export declare type DBQueryFilterOperator = '<' | '<=' | '==' | '>=' | '>' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any';
-export declare const dbQueryFilterOperatorValues: string[];
+export declare type DBQueryFilterOperator = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any';
+export declare const dbQueryFilterOperatorValues: DBQueryFilterOperator[];
 export interface DBQueryFilter<ROW extends ObjectWithId = AnyObjectWithId> {
     name: keyof ROW;
     op: DBQueryFilterOperator;

package/dist/query/dbQuery.js

@@ -6,6 +6,7 @@ exports.dbQueryFilterOperatorValues = [
     '<',
     '<=',
     '==',
+    '!=',
     '>=',
     '>',
     'in',

package/package.json

@@ -12,7 +12,7 @@
     "@naturalcycles/bench-lib": "^1.0.0",
     "@naturalcycles/dev-lib": "^12.0.1",
     "@types/node": "^17.0.0",
-    "jest": "^27.0.3",
+    "jest": "^28.0.3",
     "weak-napi": "^2.0.2"
   },
   "files": [
@@ -42,7 +42,7 @@
   "engines": {
     "node": ">=14.15"
   },
-  "version": "8.37.1",
+  "version": "8.39.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/adapter/inmemory/queryInMemory.ts

@@ -4,6 +4,7 @@ import { DBQuery, DBQueryFilterOperator } from '../../query/dbQuery'
 type FilterFn = (v: any, val: any) => boolean
 const FILTER_FNS: Record<DBQueryFilterOperator, FilterFn> = {
   '==': (v, val) => v === val,
+  '!=': (v, val) => v !== val,
   '<': (v, val) => v < val,
   '<=': (v, val) => v <= val,
   '>': (v, val) => v > val,

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

@@ -73,18 +73,19 @@ export interface CommonDaoCfg<
   excludeFromIndexes?: (keyof DBM)[]
 
   /**
-   * @default to false
-   * Set to true to limit DB writing:
-   * * Will throw an error if an object with matching ID already exists during save().
-   * * saveBatch, delete*() and patch() will throw.
+   * Defaults to false.
+   * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
+   * fail for rows that already exist in the DB (if CommonDB implementation supports it).
    *
-   * Although deletion is possible by passing (opt.overrideImmutability === true)
+   * `delete*` and `patch` will throw.
+   *
+   * You can still override saveMethod, or set opt.allowMutability to allow deletion.
    */
   immutable?: boolean
 
   /**
-   * @default to false
-   * Set to true to limit DB writing (will throw an error is such case).
+   * Defaults to false.
+   * Set to true to limit DB writing (will throw an error in such case).
    */
   readOnly?: boolean
 

package/src/commondao/common.dao.ts

@@ -245,8 +245,8 @@ export class CommonDao<
   /**
    * Throws if readOnly is true
    */
-  private requireObjectMutability(): void {
-    if (this.cfg.immutable) {
+  private requireObjectMutability(opt: CommonDaoOptions): void {
+    if (this.cfg.immutable && !opt.allowMutability) {
       throw new AppError(DBLibError.OBJECT_IS_IMMUTABLE, {
         code: DBLibError.OBJECT_IS_IMMUTABLE,
         table: this.cfg.table,
@@ -254,6 +254,18 @@ export class CommonDao<
     }
   }
 
+  private async ensureUniqueId(table: string, dbm: DBM): Promise<void> {
+    // todo: retry N times
+    const existing = await this.cfg.db.getByIds<DBM>(table, [dbm.id])
+    if (existing.length) {
+      throw new AppError(DBLibError.NON_UNIQUE_ID, {
+        table,
+        code: DBLibError.NON_UNIQUE_ID,
+        ids: existing.map(i => i.id),
+      })
+    }
+  }
+
   async getBy(by: keyof DBM, value: any, limit = 0, opt?: CommonDaoOptions): Promise<Saved<BM>[]> {
     return await this.query().filterEq(by, value).limit(limit).runQuery(opt)
   }
@@ -541,7 +553,7 @@ export class CommonDao<
     opt: CommonDaoStreamForEachOptions<ID> = {},
   ): Promise<void> {
     q.table = opt.table || q.table
-    opt.errorMode = opt.errorMode || ErrorMode.SUPPRESS
+    opt.errorMode ||= ErrorMode.SUPPRESS
 
     const op = `streamQueryIdsForEach(${q.pretty()})`
     const started = this.logStarted(op, q.table, true)
@@ -602,7 +614,9 @@ export class CommonDao<
     const dbm = await this.bmToDBM(bm as BM, opt)
     const table = opt.table || this.cfg.table
     if (opt.ensureUniqueId && idWasGenerated) await this.ensureUniqueId(table, dbm)
-    if (this.cfg.immutable) await this.ensureImmutableDontExist(table, [dbm.id])
+    if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+      opt = { ...opt, saveMethod: 'insert' }
+    }
     const op = `save(${dbm.id})`
     const started = this.logSaveStarted(op, bm, table)
     await this.cfg.db.saveBatch(table, [dbm], {
@@ -614,41 +628,6 @@ export class CommonDao<
     return bm as any
   }
 
-  private async ensureImmutableDontExist(table: string, ids: ID[]): Promise<void> {
-    await this.throwIfObjectExists(table, ids, [
-      DBLibError.OBJECT_IS_IMMUTABLE,
-      {
-        code: DBLibError.OBJECT_IS_IMMUTABLE,
-        table,
-      },
-    ])
-  }
-
-  private async ensureUniqueId(table: string, dbm: DBM): Promise<void> {
-    // todo: retry N times
-    await this.throwIfObjectExists(
-      table,
-      [dbm.id],
-      [
-        DBLibError.OBJECT_IS_IMMUTABLE,
-        {
-          code: DBLibError.OBJECT_IS_IMMUTABLE,
-          table,
-        },
-      ],
-    )
-  }
-
-  private async throwIfObjectExists(
-    table: string,
-    ids: ID[],
-    errorMeta: [DBLibError, any],
-  ): Promise<void> {
-    const existing = await this.cfg.db.getByIds<DBM>(table, ids)
-    if (existing.length > 0)
-      throw new AppError(errorMeta[0], { ...errorMeta[1], ids: existing.map(i => i.id) })
-  }
-
   /**
    * Loads the row by id.
    * Creates the row (via this.create()) if it doesn't exist
@@ -692,7 +671,9 @@ export class CommonDao<
       this.assignIdCreatedUpdated(dbm, opt) // mutates
       dbm = this.anyToDBM(dbm, opt)
       if (opt.ensureUniqueId && idWasGenerated) await this.ensureUniqueId(table, dbm)
-      if (this.cfg.immutable) await this.ensureImmutableDontExist(table, [dbm.id])
+    }
+    if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+      opt = { ...opt, saveMethod: 'insert' }
     }
     const op = `saveAsDBM(${dbm.id})`
     const started = this.logSaveStarted(op, dbm, table)
@@ -710,11 +691,9 @@ export class CommonDao<
     bms.forEach(bm => this.assignIdCreatedUpdated(bm, opt))
     const dbms = await this.bmsToDBM(bms as BM[], opt)
     if (opt.ensureUniqueId) throw new AppError('ensureUniqueId is not supported in saveBatch')
-    if (this.cfg.immutable)
-      await this.ensureImmutableDontExist(
-        table,
-        dbms.map(dbm => dbm.id),
-      )
+    if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+      opt = { ...opt, saveMethod: 'insert' }
+    }
 
     const op = `saveBatch ${dbms.length} row(s) (${_truncate(
       dbms
@@ -742,11 +721,9 @@ export class CommonDao<
       dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt)) // mutates
       dbms = this.anyToDBMs(dbms, opt)
       if (opt.ensureUniqueId) throw new AppError('ensureUniqueId is not supported in saveBatch')
-      if (this.cfg.immutable)
-        await this.ensureImmutableDontExist(
-          table,
-          dbms.map(dbm => dbm.id),
-        )
+    }
+    if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+      opt = { ...opt, saveMethod: 'insert' }
     }
     const op = `saveBatchAsDBM ${dbms.length} row(s) (${_truncate(
       dbms
@@ -775,7 +752,7 @@ export class CommonDao<
   async deleteById(id?: ID, opt: CommonDaoOptions = {}): Promise<number> {
     if (!id) return 0
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     const op = `deleteById(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -786,7 +763,7 @@ export class CommonDao<
 
   async deleteByIds(ids: ID[], opt: CommonDaoOptions = {}): Promise<number> {
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     const op = `deleteByIds(${ids.join(', ')})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -805,7 +782,7 @@ export class CommonDao<
     opt: CommonDaoStreamForEachOptions<DBM> & { stream?: boolean } = {},
   ): Promise<number> {
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     q.table = opt.table || q.table
     const op = `deleteByQuery(${q.pretty()})`
     const started = this.logStarted(op, q.table)

package/src/query/dbQuery.ts

@@ -27,6 +27,7 @@ export type DBQueryFilterOperator =
   | '<'
   | '<='
   | '=='
+  | '!='
   | '>='
   | '>'
   | 'in'
@@ -34,10 +35,11 @@ export type DBQueryFilterOperator =
   | 'array-contains'
   | 'array-contains-any'
 
-export const dbQueryFilterOperatorValues = [
+export const dbQueryFilterOperatorValues: DBQueryFilterOperator[] = [
   '<',
   '<=',
   '==',
+  '!=',
   '>=',
   '>',
   'in',