@naturalcycles/db-lib 8.33.0 → 8.34.2

package/dist/cnst.d.ts

@@ -1,5 +1,6 @@
 export declare enum DBLibError {
     DB_ROW_REQUIRED = "DB_ROW_REQUIRED",
     DAO_IS_READ_ONLY = "DAO_IS_READ_ONLY",
-    NON_UNIQUE_ID = "NON_UNIQUE_ID"
+    NON_UNIQUE_ID = "NON_UNIQUE_ID",
+    OBJECT_IS_IMMUTABLE = "OBJECT_IS_IMMUTABLE"
 }

package/dist/cnst.js

@@ -6,4 +6,5 @@ var DBLibError;
     DBLibError["DB_ROW_REQUIRED"] = "DB_ROW_REQUIRED";
     DBLibError["DAO_IS_READ_ONLY"] = "DAO_IS_READ_ONLY";
     DBLibError["NON_UNIQUE_ID"] = "NON_UNIQUE_ID";
+    DBLibError["OBJECT_IS_IMMUTABLE"] = "OBJECT_IS_IMMUTABLE";
 })(DBLibError = exports.DBLibError || (exports.DBLibError = {}));

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

@@ -31,6 +31,10 @@ export declare class CommonDao<BM extends Partial<ObjectWithId>, DBM extends Obj
      * Throws if readOnly is true
      */
     private requireWriteAccess;
+    /**
+     * Throws if readOnly is true
+     */
+    private requireObjectMutability;
     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>[]>;
@@ -81,10 +85,9 @@ export declare class CommonDao<BM extends Partial<ObjectWithId>, DBM extends Obj
      * Mutates with id, created, updated
      */
     save(bm: BM, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
-    /**
-     * Mutates id if needed
-     */
+    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

@@ -164,6 +164,17 @@ class CommonDao {
             });
         }
     }
+    /**
+     * Throws if readOnly is true
+     */
+    requireObjectMutability() {
+        if (this.cfg.immutable) {
+            throw new js_lib_1.AppError(cnst_1.DBLibError.OBJECT_IS_IMMUTABLE, {
+                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
+                table: this.cfg.table,
+            });
+        }
+    }
     async getBy(by, value, limit = 0, opt) {
         return await this.query().filterEq(by, value).limit(limit).runQuery(opt);
     }
@@ -430,6 +441,8 @@ 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]);
         const op = `save(${dbm.id})`;
         const started = this.logSaveStarted(op, bm, table);
         await this.cfg.db.saveBatch(table, [dbm], {
@@ -439,19 +452,29 @@ class CommonDao {
         this.logSaveResult(started, op, table);
         return bm;
     }
-    /**
-     * Mutates id if needed
-     */
+    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
-        const [existing] = await this.cfg.db.getByIds(table, [dbm.id]);
-        if (existing) {
-            throw new js_lib_1.AppError(cnst_1.DBLibError.NON_UNIQUE_ID, {
-                code: cnst_1.DBLibError.NON_UNIQUE_ID,
-                id: dbm.id,
+        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.
@@ -486,6 +509,8 @@ 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]);
         }
         const op = `saveAsDBM(${dbm.id})`;
         const started = this.logSaveStarted(op, dbm, table);
@@ -503,6 +528,8 @@ 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));
         const op = `saveBatch ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
             .map(bm => bm.id)
@@ -523,6 +550,8 @@ 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));
         }
         const op = `saveBatchAsDBM ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
@@ -540,6 +569,8 @@ class CommonDao {
         if (!id)
             return 0;
         this.requireWriteAccess();
+        if (!opt.allowMutability)
+            this.requireObjectMutability();
         const op = `deleteById(${id})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -549,6 +580,8 @@ class CommonDao {
     }
     async deleteByIds(ids, opt = {}) {
         this.requireWriteAccess();
+        if (!opt.allowMutability)
+            this.requireObjectMutability();
         const op = `deleteByIds(${ids.join(', ')})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -563,6 +596,8 @@ class CommonDao {
      */
     async deleteByQuery(q, opt = {}) {
         this.requireWriteAccess();
+        if (!opt.allowMutability)
+            this.requireObjectMutability();
         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

@@ -57,6 +57,15 @@ export interface CommonDaoCfg<BM extends Partial<ObjectWithId>, DBM extends Obje
     bmSchema?: ObjectSchemaTyped<BM> | AjvSchema<BM>;
     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.
+     *
+     * Although deletion is possible by passing (opt.overrideImmutability === true)
+     */
+    immutable?: boolean;
     /**
      * @default to false
      * Set to true to limit DB writing (will throw an error is such case).
@@ -128,6 +137,10 @@ export interface CommonDaoOptions extends CommonDBOptions {
      * @default false
      */
     preserveUpdatedCreated?: boolean;
+    /**
+     * @default false (for streams). Setting to true enables deletion of immutable objects
+     */
+    allowMutability?: boolean;
     /**
      * If true - data will be anonymized (by calling a BaseDao.anonymize() hook that you can extend in your Dao implementation).
      * Only applicable to loading/querying/streaming_loading operations (n/a for saving).

package/dist/kv/commonKeyValueDaoMemoCache.d.ts

@@ -1,9 +1,17 @@
 import { AsyncMemoCache } from '@naturalcycles/js-lib';
 import { CommonKeyValueDao } from './commonKeyValueDao';
+/**
+ * AsyncMemoCache implementation, backed by CommonKeyValueDao.
+ *
+ * Does NOT support persisting Errors, skips them instead.
+ *
+ * Also, does not support .clear(), as it's more dangerous than useful to actually
+ * clear the whole table/cache.
+ */
 export declare class CommonKeyValueDaoMemoCache<VALUE = any> implements AsyncMemoCache<string, VALUE> {
     private dao;
     constructor(dao: CommonKeyValueDao<VALUE>);
-    get(k: string): Promise<VALUE | undefined>;
-    set(k: string, v: VALUE): Promise<void>;
+    get(k: string): Promise<VALUE | Error | undefined>;
+    set(k: string, v: VALUE | Error): Promise<void>;
     clear(): Promise<void>;
 }

package/dist/kv/commonKeyValueDaoMemoCache.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommonKeyValueDaoMemoCache = void 0;
+/**
+ * AsyncMemoCache implementation, backed by CommonKeyValueDao.
+ *
+ * Does NOT support persisting Errors, skips them instead.
+ *
+ * Also, does not support .clear(), as it's more dangerous than useful to actually
+ * clear the whole table/cache.
+ */
 class CommonKeyValueDaoMemoCache {
     constructor(dao) {
         this.dao = dao;
@@ -9,10 +17,14 @@ class CommonKeyValueDaoMemoCache {
         return (await this.dao.getById(k)) || undefined;
     }
     async set(k, v) {
+        if (v instanceof Error) {
+            // We currently don't persist errors there
+            return;
+        }
         await this.dao.save(k, v);
     }
     async clear() {
-        throw new Error('CommonKeyValueDaoCacheFactory.clear is not supported, because cache is expected to be persistent');
+        throw new Error('CommonKeyValueDaoMemoCache.clear is not supported, because cache is expected to be persistent');
     }
 }
 exports.CommonKeyValueDaoMemoCache = CommonKeyValueDaoMemoCache;

package/package.json

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

package/src/cnst.ts

@@ -2,4 +2,5 @@ export enum DBLibError {
   DB_ROW_REQUIRED = 'DB_ROW_REQUIRED',
   DAO_IS_READ_ONLY = 'DAO_IS_READ_ONLY',
   NON_UNIQUE_ID = 'NON_UNIQUE_ID',
+  OBJECT_IS_IMMUTABLE = 'OBJECT_IS_IMMUTABLE',
 }

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

@@ -77,6 +77,16 @@ 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.
+   *
+   * Although deletion is possible by passing (opt.overrideImmutability === true)
+   */
+  immutable?: boolean
+
   /**
    * @default to false
    * Set to true to limit DB writing (will throw an error is such case).
@@ -161,6 +171,11 @@ export interface CommonDaoOptions extends CommonDBOptions {
    */
   preserveUpdatedCreated?: boolean
 
+  /**
+   * @default false (for streams). Setting to true enables deletion of immutable objects
+   */
+  allowMutability?: boolean
+
   /**
    * If true - data will be anonymized (by calling a BaseDao.anonymize() hook that you can extend in your Dao implementation).
    * Only applicable to loading/querying/streaming_loading operations (n/a for saving).

package/src/commondao/common.dao.ts

@@ -238,6 +238,18 @@ export class CommonDao<
     }
   }
 
+  /**
+   * Throws if readOnly is true
+   */
+  private requireObjectMutability(): void {
+    if (this.cfg.immutable) {
+      throw new AppError(DBLibError.OBJECT_IS_IMMUTABLE, {
+        code: DBLibError.OBJECT_IS_IMMUTABLE,
+        table: this.cfg.table,
+      })
+    }
+  }
+
   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)
   }
@@ -589,6 +601,7 @@ export class CommonDao<
     const dbm = await this.bmToDBM(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])
     const op = `save(${dbm.id})`
     const started = this.logSaveStarted(op, bm, table)
     await this.cfg.db.saveBatch(table, [dbm], {
@@ -600,19 +613,39 @@ export class CommonDao<
     return bm as any
   }
 
-  /**
-   * Mutates id if needed
-   */
+  private async ensureImmutableDontExist(table: string, ids: string[]): 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
-    const [existing] = await this.cfg.db.getByIds<DBM>(table, [dbm.id])
-    if (existing) {
-      throw new AppError(DBLibError.NON_UNIQUE_ID, {
-        code: DBLibError.NON_UNIQUE_ID,
-        id: dbm.id,
-        table,
-      })
-    }
+    await this.throwIfObjectExists(
+      table,
+      [dbm.id],
+      [
+        DBLibError.OBJECT_IS_IMMUTABLE,
+        {
+          code: DBLibError.OBJECT_IS_IMMUTABLE,
+          table,
+        },
+      ],
+    )
+  }
+
+  private async throwIfObjectExists(
+    table: string,
+    ids: string[],
+    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) })
   }
 
   /**
@@ -666,6 +699,7 @@ 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])
     }
     const op = `saveAsDBM(${dbm.id})`
     const started = this.logSaveStarted(op, dbm, table)
@@ -683,6 +717,12 @@ export class CommonDao<
     bms.forEach(bm => this.assignIdCreatedUpdated(bm, opt))
     const dbms = await this.bmsToDBM(bms, 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),
+      )
+
     const op = `saveBatch ${dbms.length} row(s) (${_truncate(
       dbms
         .slice(0, 10)
@@ -709,6 +749,11 @@ 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),
+        )
     }
     const op = `saveBatchAsDBM ${dbms.length} row(s) (${_truncate(
       dbms
@@ -737,6 +782,7 @@ export class CommonDao<
   async deleteById(id?: string, opt: CommonDaoOptions = {}): Promise<number> {
     if (!id) return 0
     this.requireWriteAccess()
+    if (!opt.allowMutability) this.requireObjectMutability()
     const op = `deleteById(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -747,6 +793,7 @@ export class CommonDao<
 
   async deleteByIds(ids: string[], opt: CommonDaoOptions = {}): Promise<number> {
     this.requireWriteAccess()
+    if (!opt.allowMutability) this.requireObjectMutability()
     const op = `deleteByIds(${ids.join(', ')})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -765,6 +812,7 @@ export class CommonDao<
     opt: CommonDaoStreamForEachOptions<DBM> & { stream?: boolean } = {},
   ): Promise<number> {
     this.requireWriteAccess()
+    if (!opt.allowMutability) this.requireObjectMutability()
     q.table = opt.table || q.table
     const op = `deleteByQuery(${q.pretty()})`
     const started = this.logStarted(op, q.table)

package/src/kv/commonKeyValueDaoMemoCache.ts

@@ -1,20 +1,33 @@
 import { AsyncMemoCache } from '@naturalcycles/js-lib'
 import { CommonKeyValueDao } from './commonKeyValueDao'
 
+/**
+ * AsyncMemoCache implementation, backed by CommonKeyValueDao.
+ *
+ * Does NOT support persisting Errors, skips them instead.
+ *
+ * Also, does not support .clear(), as it's more dangerous than useful to actually
+ * clear the whole table/cache.
+ */
 export class CommonKeyValueDaoMemoCache<VALUE = any> implements AsyncMemoCache<string, VALUE> {
   constructor(private dao: CommonKeyValueDao<VALUE>) {}
 
-  async get(k: string): Promise<VALUE | undefined> {
+  async get(k: string): Promise<VALUE | Error | undefined> {
     return (await this.dao.getById(k)) || undefined
   }
 
-  async set(k: string, v: VALUE): Promise<void> {
+  async set(k: string, v: VALUE | Error): Promise<void> {
+    if (v instanceof Error) {
+      // We currently don't persist errors there
+      return
+    }
+
     await this.dao.save(k, v)
   }
 
   async clear(): Promise<void> {
     throw new Error(
-      'CommonKeyValueDaoCacheFactory.clear is not supported, because cache is expected to be persistent',
+      'CommonKeyValueDaoMemoCache.clear is not supported, because cache is expected to be persistent',
     )
   }
 }