@naturalcycles/db-lib 8.31.0 → 8.34.0

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 ensureImmutableDoesntExist;
     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.ensureImmutableDoesntExist(table, dbm);
         const op = `save(${dbm.id})`;
         const started = this.logSaveStarted(op, bm, table);
         await this.cfg.db.saveBatch(table, [dbm], {
@@ -439,19 +452,31 @@ class CommonDao {
         this.logSaveResult(started, op, table);
         return bm;
     }
-    /**
-     * Mutates id if needed
-     */
+    async ensureImmutableDoesntExist(table, dbm) {
+        await this.throwIfObjectExists(table, dbm, [
+            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
+            {
+                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
+                id: dbm.id,
+                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,
+        await this.throwIfObjectExists(table, dbm, [
+            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
+            {
+                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
                 id: dbm.id,
                 table,
-            });
-        }
+            },
+        ]);
+    }
+    async throwIfObjectExists(table, dbm, errorMeta) {
+        const [existing] = await this.cfg.db.getByIds(table, [dbm.id]);
+        if (existing)
+            throw new js_lib_1.AppError(errorMeta[0], errorMeta[1]);
     }
     /**
      * Loads the row by id.
@@ -486,6 +511,8 @@ class CommonDao {
             dbm = this.anyToDBM(dbm, opt);
             if (opt.ensureUniqueId && idWasGenerated)
                 await this.ensureUniqueId(table, dbm);
+            if (this.cfg.immutable)
+                await this.ensureImmutableDoesntExist(table, dbm);
         }
         const op = `saveAsDBM(${dbm.id})`;
         const started = this.logSaveStarted(op, dbm, table);
@@ -503,6 +530,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)
+            throw new js_lib_1.AppError('immutable DB entries are not supported in saveBatch');
         const op = `saveBatch ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
             .map(bm => bm.id)
@@ -523,6 +552,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)
+                throw new js_lib_1.AppError('immutable objects are not supported in saveBatch');
         }
         const op = `saveBatchAsDBM ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
@@ -540,6 +571,8 @@ class CommonDao {
         if (!id)
             return 0;
         this.requireWriteAccess();
+        if (!opt.allowMutabiliity)
+            this.requireObjectMutability();
         const op = `deleteById(${id})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -549,6 +582,8 @@ class CommonDao {
     }
     async deleteByIds(ids, opt = {}) {
         this.requireWriteAccess();
+        if (!opt.allowMutabiliity)
+            this.requireObjectMutability();
         const op = `deleteByIds(${ids.join(', ')})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -563,6 +598,8 @@ class CommonDao {
      */
     async deleteByQuery(q, opt = {}) {
         this.requireWriteAccess();
+        if (!opt.allowMutabiliity)
+            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
+     */
+    allowMutabiliity?: 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/index.d.ts

@@ -17,5 +17,6 @@ import { dbPipelineRestore, DBPipelineRestoreOptions } from './pipeline/dbPipeli
 import { DBQuery, DBQueryFilter, DBQueryFilterOperator, dbQueryFilterOperatorValues, DBQueryOrder, RunnableDBQuery } from './query/dbQuery';
 import { DBTransaction, RunnableDBTransaction } from './transaction/dbTransaction';
 import { commitDBTransactionSimple, mergeDBOperations } from './transaction/dbTransaction.util';
+export * from './kv/commonKeyValueDaoMemoCache';
 export type { DBQueryFilterOperator, DBQueryFilter, DBQueryOrder, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBCreateOptions, CommonDB, RunQueryResult, CommonDaoCfg, CommonDaoCreateIdHook, CommonDaoParseNaturalIdHook, CommonDaoBeforeCreateHook, CommonDaoBeforeDBMValidateHook, CommonDaoBeforeDBMToBMHook, CommonDaoBeforeBMToDBMHook, CommonDaoBeforeTMToBMHook, CommonDaoBeforeBMToTMHook, CommonDaoAnonymizeHook, InMemoryDBCfg, InMemoryKeyValueDBCfg, DBPipelineBackupOptions, DBPipelineRestoreOptions, DBPipelineCopyOptions, CommonDBAdapter, DBOperation, DBSaveBatchOperation, DBDeleteByIdsOperation, CommonKeyValueDB, CommonKeyValueDaoCfg, KeyValueDBTuple, };
 export { DBQuery, dbQueryFilterOperatorValues, RunnableDBQuery, CommonDaoLogLevel, DBRelation, DBModelType, CommonDao, createdUpdatedFields, createdUpdatedIdFields, InMemoryDB, InMemoryKeyValueDB, queryInMemory, serializeJsonField, deserializeJsonField, dbPipelineBackup, dbPipelineRestore, dbPipelineCopy, getDB, DBLibError, BaseCommonDB, DBTransaction, RunnableDBTransaction, mergeDBOperations, commitDBTransactionSimple, CommonKeyValueDao, };

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommonKeyValueDao = exports.commitDBTransactionSimple = exports.mergeDBOperations = exports.RunnableDBTransaction = exports.DBTransaction = exports.BaseCommonDB = exports.DBLibError = exports.getDB = exports.dbPipelineCopy = exports.dbPipelineRestore = exports.dbPipelineBackup = exports.deserializeJsonField = exports.serializeJsonField = exports.queryInMemory = exports.InMemoryKeyValueDB = exports.InMemoryDB = exports.createdUpdatedIdFields = exports.createdUpdatedFields = exports.CommonDao = exports.DBModelType = exports.DBRelation = exports.CommonDaoLogLevel = exports.RunnableDBQuery = exports.dbQueryFilterOperatorValues = exports.DBQuery = void 0;
+const tslib_1 = require("tslib");
 const inMemory_db_1 = require("./adapter/inmemory/inMemory.db");
 Object.defineProperty(exports, "InMemoryDB", { enumerable: true, get: function () { return inMemory_db_1.InMemoryDB; } });
 const inMemoryKeyValueDB_1 = require("./adapter/inmemory/inMemoryKeyValueDB");
@@ -43,3 +44,4 @@ Object.defineProperty(exports, "RunnableDBTransaction", { enumerable: true, get:
 const dbTransaction_util_1 = require("./transaction/dbTransaction.util");
 Object.defineProperty(exports, "commitDBTransactionSimple", { enumerable: true, get: function () { return dbTransaction_util_1.commitDBTransactionSimple; } });
 Object.defineProperty(exports, "mergeDBOperations", { enumerable: true, get: function () { return dbTransaction_util_1.mergeDBOperations; } });
+(0, tslib_1.__exportStar)(require("./kv/commonKeyValueDaoMemoCache"), exports);

package/dist/kv/commonKeyValueDao.d.ts

@@ -25,6 +25,12 @@ export interface CommonKeyValueDaoCfg<T> {
         mapBufferToValue?: (b: Buffer) => Promise<T>;
         beforeCreate?: (v: Partial<T>) => Partial<T>;
     };
+    /**
+     * Set to `true` to conveniently enable zipping+JSON.stringify
+     * (and unzipping+JSON.parse) of the Buffer value via hooks.
+     * Custom hooks will override these hooks (if provided).
+     */
+    deflatedJsonValue?: boolean;
 }
 export declare class CommonKeyValueDao<T> {
     cfg: CommonKeyValueDaoCfg<T>;
@@ -33,6 +39,7 @@ export declare class CommonKeyValueDao<T> {
     createTable(opt?: CommonDBCreateOptions): Promise<void>;
     create(input?: Partial<T>): T;
     getById(id?: string): Promise<T | null>;
+    requireById(id: string): Promise<T>;
     getByIdOrEmpty(id: string, part?: Partial<T>): Promise<T>;
     patch(id: string, patch: Partial<T>): Promise<T>;
     getByIds(ids: string[]): Promise<KeyValueTuple<string, T>[]>;

package/dist/kv/commonKeyValueDao.js

@@ -3,11 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommonKeyValueDao = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
+const cnst_1 = require("../cnst");
 // todo: logging
 // todo: readonly
 class CommonKeyValueDao {
     constructor(cfg) {
         this.cfg = cfg;
+        if (cfg.deflatedJsonValue) {
+            cfg.hooks = {
+                mapValueToBuffer: async (v) => await (0, nodejs_lib_1.deflateString)(JSON.stringify(v)),
+                mapBufferToValue: async (buf) => JSON.parse(await (0, nodejs_lib_1.inflateToString)(buf)),
+                ...cfg.hooks,
+            };
+        }
     }
     async ping() {
         await this.cfg.db.ping();
@@ -26,6 +34,18 @@ class CommonKeyValueDao {
         const [r] = await this.getByIds([id]);
         return r?.[1] || null;
     }
+    async requireById(id) {
+        const [r] = await this.getByIds([id]);
+        if (!r) {
+            const { table } = this.cfg;
+            throw new js_lib_1.AppError(`DB row required, but not found: ${table}.${id}`, {
+                code: cnst_1.DBLibError.DB_ROW_REQUIRED,
+                table,
+                id,
+            });
+        }
+        return r[1];
+    }
     async getByIdOrEmpty(id, part = {}) {
         const [r] = await this.getByIds([id]);
         if (r)

package/dist/kv/commonKeyValueDaoMemoCache.d.ts

@@ -0,0 +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 | Error | undefined>;
+    set(k: string, v: VALUE | Error): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/kv/commonKeyValueDaoMemoCache.js

@@ -0,0 +1,30 @@
+"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;
+    }
+    async get(k) {
+        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('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.31.0",
+  "version": "8.34.0",
   "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
+   */
+  allowMutabiliity?: 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.ensureImmutableDoesntExist(table, dbm)
     const op = `save(${dbm.id})`
     const started = this.logSaveStarted(op, bm, table)
     await this.cfg.db.saveBatch(table, [dbm], {
@@ -600,19 +613,36 @@ export class CommonDao<
     return bm as any
   }
 
-  /**
-   * Mutates id if needed
-   */
+  private async ensureImmutableDoesntExist(table: string, dbm: DBM): Promise<void> {
+    await this.throwIfObjectExists(table, dbm, [
+      DBLibError.OBJECT_IS_IMMUTABLE,
+      {
+        code: DBLibError.OBJECT_IS_IMMUTABLE,
+        id: dbm.id,
+        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,
+    await this.throwIfObjectExists(table, dbm, [
+      DBLibError.OBJECT_IS_IMMUTABLE,
+      {
+        code: DBLibError.OBJECT_IS_IMMUTABLE,
         id: dbm.id,
         table,
-      })
-    }
+      },
+    ])
+  }
+
+  private async throwIfObjectExists(
+    table: string,
+    dbm: DBM,
+    errorMeta: [DBLibError, any],
+  ): Promise<void> {
+    const [existing] = await this.cfg.db.getByIds<DBM>(table, [dbm.id])
+    if (existing) throw new AppError(errorMeta[0], errorMeta[1])
   }
 
   /**
@@ -666,6 +696,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.ensureImmutableDoesntExist(table, dbm)
     }
     const op = `saveAsDBM(${dbm.id})`
     const started = this.logSaveStarted(op, dbm, table)
@@ -683,6 +714,8 @@ 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)
+      throw new AppError('immutable DB entries are not supported in saveBatch')
     const op = `saveBatch ${dbms.length} row(s) (${_truncate(
       dbms
         .slice(0, 10)
@@ -709,6 +742,7 @@ 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) throw new AppError('immutable objects are not supported in saveBatch')
     }
     const op = `saveBatchAsDBM ${dbms.length} row(s) (${_truncate(
       dbms
@@ -737,6 +771,7 @@ export class CommonDao<
   async deleteById(id?: string, opt: CommonDaoOptions = {}): Promise<number> {
     if (!id) return 0
     this.requireWriteAccess()
+    if (!opt.allowMutabiliity) this.requireObjectMutability()
     const op = `deleteById(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -747,6 +782,7 @@ export class CommonDao<
 
   async deleteByIds(ids: string[], opt: CommonDaoOptions = {}): Promise<number> {
     this.requireWriteAccess()
+    if (!opt.allowMutabiliity) this.requireObjectMutability()
     const op = `deleteByIds(${ids.join(', ')})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -765,6 +801,7 @@ export class CommonDao<
     opt: CommonDaoStreamForEachOptions<DBM> & { stream?: boolean } = {},
   ): Promise<number> {
     this.requireWriteAccess()
+    if (!opt.allowMutabiliity) this.requireObjectMutability()
     q.table = opt.table || q.table
     const op = `deleteByQuery(${q.pretty()})`
     const started = this.logStarted(op, q.table)

package/src/index.ts

@@ -58,6 +58,7 @@ import {
 } from './query/dbQuery'
 import { DBTransaction, RunnableDBTransaction } from './transaction/dbTransaction'
 import { commitDBTransactionSimple, mergeDBOperations } from './transaction/dbTransaction.util'
+export * from './kv/commonKeyValueDaoMemoCache'
 
 export type {
   DBQueryFilterOperator,

package/src/kv/commonKeyValueDao.ts

@@ -1,5 +1,11 @@
-import { ErrorMode, KeyValueTuple, pMap } from '@naturalcycles/js-lib'
-import { ReadableTyped, transformMap } from '@naturalcycles/nodejs-lib'
+import { AppError, ErrorMode, KeyValueTuple, pMap } from '@naturalcycles/js-lib'
+import {
+  deflateString,
+  inflateToString,
+  ReadableTyped,
+  transformMap,
+} from '@naturalcycles/nodejs-lib'
+import { DBLibError } from '../cnst'
 import { CommonDaoLogLevel } from '../commondao/common.dao.model'
 import { CommonDBCreateOptions } from '../db.model'
 import { CommonKeyValueDB, KeyValueDBTuple } from './commonKeyValueDB'
@@ -30,13 +36,28 @@ export interface CommonKeyValueDaoCfg<T> {
     mapBufferToValue?: (b: Buffer) => Promise<T>
     beforeCreate?: (v: Partial<T>) => Partial<T>
   }
+
+  /**
+   * Set to `true` to conveniently enable zipping+JSON.stringify
+   * (and unzipping+JSON.parse) of the Buffer value via hooks.
+   * Custom hooks will override these hooks (if provided).
+   */
+  deflatedJsonValue?: boolean
 }
 
 // todo: logging
 // todo: readonly
 
 export class CommonKeyValueDao<T> {
-  constructor(public cfg: CommonKeyValueDaoCfg<T>) {}
+  constructor(public cfg: CommonKeyValueDaoCfg<T>) {
+    if (cfg.deflatedJsonValue) {
+      cfg.hooks = {
+        mapValueToBuffer: async v => await deflateString(JSON.stringify(v)),
+        mapBufferToValue: async buf => JSON.parse(await inflateToString(buf)),
+        ...cfg.hooks,
+      }
+    }
+  }
 
   async ping(): Promise<void> {
     await this.cfg.db.ping()
@@ -58,6 +79,21 @@ export class CommonKeyValueDao<T> {
     return r?.[1] || null
   }
 
+  async requireById(id: string): Promise<T> {
+    const [r] = await this.getByIds([id])
+
+    if (!r) {
+      const { table } = this.cfg
+      throw new AppError(`DB row required, but not found: ${table}.${id}`, {
+        code: DBLibError.DB_ROW_REQUIRED,
+        table,
+        id,
+      })
+    }
+
+    return r[1]
+  }
+
   async getByIdOrEmpty(id: string, part: Partial<T> = {}): Promise<T> {
     const [r] = await this.getByIds([id])
     if (r) return r[1]

package/src/kv/commonKeyValueDaoMemoCache.ts

@@ -0,0 +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 | Error | undefined> {
+    return (await this.dao.getById(k)) || undefined
+  }
+
+  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(
+      'CommonKeyValueDaoMemoCache.clear is not supported, because cache is expected to be persistent',
+    )
+  }
+}