@naturalcycles/db-lib 8.37.1 → 8.38.0

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);
     }
@@ -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.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.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.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.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/package.json

@@ -42,7 +42,7 @@
   "engines": {
     "node": ">=14.15"
   },
-  "version": "8.37.1",
+  "version": "8.38.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

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)
   }
@@ -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 ||= '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 ||= '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 ||= '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 ||= '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)