@naturalcycles/js-lib 14.82.0 → 14.84.1

package/dist/decorators/asyncMemo.decorator.d.ts

@@ -0,0 +1,22 @@
+import { Merge } from '../typeFest';
+import { MemoOptions } from './memo.decorator';
+import { AsyncMemoCache } from './memo.util';
+export declare type AsyncMemoOptions = Merge<MemoOptions, {
+    /**
+     * Provide a custom implementation of MemoCache.
+     * Function that creates an instance of `MemoCache`.
+     * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`.
+     *
+     * It's an ARRAY of Caches, to allow multiple layers of Cache.
+     * It will check it one by one, starting from the first.
+     * HIT will be returned immediately, MISS will go one level deeper, or returned (if the end of the Cache stack is reached).
+     */
+    cacheFactory: () => AsyncMemoCache[];
+}>;
+/**
+ * Like @_Memo, but allowing async MemoCache implementation.
+ *
+ * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
+ * Return `null` instead (it'll be cached).
+ */
+export declare const _AsyncMemo: (opt: AsyncMemoOptions) => MethodDecorator;

package/dist/decorators/asyncMemo.decorator.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._AsyncMemo = void 0;
+const time_util_1 = require("../time/time.util");
+const decorator_util_1 = require("./decorator.util");
+const memo_decorator_1 = require("./memo.decorator");
+const memo_util_1 = require("./memo.util");
+/**
+ * Like @_Memo, but allowing async MemoCache implementation.
+ *
+ * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
+ * Return `null` instead (it'll be cached).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const _AsyncMemo = (opt) => (target, key, descriptor) => {
+    if (typeof descriptor.value !== 'function') {
+        throw new TypeError('Memoization can be applied only to methods');
+    }
+    const originalFn = descriptor.value;
+    // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
+    const cache = new Map();
+    const { logHit = false, logMiss = false, noLogArgs = false, logger = console, cacheFactory, cacheKeyFn = memo_util_1.jsonMemoSerializer, noCacheRejected = false, noCacheResolved = false, } = opt;
+    const keyStr = String(key);
+    const methodSignature = (0, decorator_util_1._getTargetMethodSignature)(target, keyStr);
+    descriptor.value = async function (...args) {
+        const ctx = this;
+        const cacheKey = cacheKeyFn(args);
+        if (!cache.has(ctx)) {
+            cache.set(ctx, cacheFactory());
+            // here, no need to check the cache. It's definitely a miss, because the cacheLayers is just created
+            // UPD: no! AsyncMemo supports "persistent caches" (e.g Database-backed cache)
+        }
+        if (args.length === 1 && args[0] === memo_decorator_1.CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_AsyncMemo.dropCache()`);
+            try {
+                await Promise.all(cache.get(ctx).map(c => c.clear()));
+            }
+            catch (err) {
+                logger.error(err);
+            }
+            return;
+        }
+        let value;
+        try {
+            for await (const cacheLayer of cache.get(ctx)) {
+                value = await cacheLayer.get(cacheKey);
+                if (value !== undefined) {
+                    // it's a hit!
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            // log error, but don't throw, treat it as a "miss"
+            logger.error(err);
+        }
+        if (value !== undefined) {
+            // hit!
+            if (logHit) {
+                logger.log(`${(0, decorator_util_1._getMethodSignature)(ctx, keyStr)}(${(0, decorator_util_1._getArgsSignature)(args, noLogArgs)}) @_AsyncMemo hit`);
+            }
+            return value instanceof Error ? Promise.reject(value) : Promise.resolve(value);
+        }
+        // Here we know it's a MISS, let's execute the real method
+        const started = Date.now();
+        try {
+            value = await originalFn.apply(ctx, args);
+            if (!noCacheResolved) {
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, value))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            return value;
+        }
+        catch (err) {
+            if (!noCacheRejected) {
+                // We put it to cache as raw Error, not Promise.reject(err)
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, err))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            throw err;
+        }
+        finally {
+            if (logMiss) {
+                logger.log(`${(0, decorator_util_1._getMethodSignature)(ctx, keyStr)}(${(0, decorator_util_1._getArgsSignature)(args, noLogArgs)}) @_AsyncMemo miss (${(0, time_util_1._since)(started)})`);
+            }
+        }
+    };
+    return descriptor;
+};
+exports._AsyncMemo = _AsyncMemo;

package/dist/decorators/memo.decorator.d.ts

@@ -1,5 +1,9 @@
 import { CommonLogger } from '../log/commonLogger';
 import { MemoCache } from './memo.util';
+/**
+ * Symbol to indicate that the Cache should be dropped.
+ */
+export declare const CACHE_DROP: unique symbol;
 export interface MemoOptions {
     /**
      * Default to false
@@ -30,11 +34,15 @@ export interface MemoOptions {
     /**
      * Don't cache resolved promises.
      * Setting this to `true` will make the decorator to await the result.
+     *
+     * Default false.
      */
     noCacheResolved?: boolean;
     /**
      * Don't cache rejected promises.
      * Setting this to `true` will make the decorator to await the result.
+     *
+     * Default false.
      */
     noCacheRejected?: boolean;
 }

package/dist/decorators/memo.decorator.js

@@ -5,10 +5,14 @@
 // http://inlehmansterms.net/2015/03/01/javascript-memoization/
 // https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._Memo = void 0;
+exports._Memo = exports.CACHE_DROP = void 0;
 const time_util_1 = require("../time/time.util");
 const decorator_util_1 = require("./decorator.util");
 const memo_util_1 = require("./memo.util");
+/**
+ * Symbol to indicate that the Cache should be dropped.
+ */
+exports.CACHE_DROP = Symbol('CACHE_DROP');
 /**
  * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
  * of the cache is the same. Key, by defaul, is calculated as `JSON.stringify(...args)`.
@@ -39,6 +43,12 @@ const _Memo = (opt = {}) => (target, key, descriptor) => {
     const methodSignature = (0, decorator_util_1._getTargetMethodSignature)(target, keyStr);
     descriptor.value = function (...args) {
         const ctx = this;
+        if (args.length === 1 && args[0] === exports.CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_Memo.CACHE_DROP`);
+            return cache.get(ctx)?.clear();
+        }
         const cacheKey = cacheKeyFn(args);
         if (!cache.has(ctx)) {
             cache.set(ctx, cacheFactory());
@@ -91,11 +101,6 @@ const _Memo = (opt = {}) => (target, key, descriptor) => {
             return res;
         }
     };
-    descriptor.value.dropCache = () => {
-        logger.log(`${methodSignature} @_Memo.dropCache()`);
-        cache.forEach(memoCache => memoCache.clear());
-        cache.clear();
-    };
     return descriptor;
 };
 exports._Memo = _Memo;

package/dist/decorators/memo.util.d.ts

@@ -1,15 +1,34 @@
+import { Promisable } from '../typeFest';
 export declare type MemoSerializer = (args: any[]) => any;
 export declare const jsonMemoSerializer: MemoSerializer;
-export interface MemoCache {
-    has(k: any): boolean;
-    get(k: any): any;
-    set(k: any, v: any): void;
+export interface MemoCache<KEY = any, VALUE = any> {
+    has(k: KEY): boolean;
+    get(k: KEY): VALUE | undefined;
+    set(k: KEY, v: VALUE): void;
+    /**
+     * Clear is only called when `.dropCache()` is called.
+     * Otherwise the Cache is "persistent" (never cleared).
+     */
     clear(): void;
 }
-export declare class MapMemoCache implements MemoCache {
+export interface AsyncMemoCache<KEY = any, VALUE = any> {
+    /**
+     * `undefined` value returned indicates the ABSENCE of value in the Cache.
+     * This also means that you CANNOT store `undefined` value in the Cache, as it'll be treated as a MISS.
+     * You CAN store `null` value instead, it will be treated as a HIT.
+     */
+    get(k: KEY): Promisable<VALUE | undefined>;
+    set(k: KEY, v: VALUE): Promisable<void>;
+    /**
+     * Clear is only called when `.dropCache()` is called.
+     * Otherwise the Cache is "persistent" (never cleared).
+     */
+    clear(): Promisable<void>;
+}
+export declare class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALUE>, AsyncMemoCache<KEY, VALUE> {
     private m;
-    has(k: any): boolean;
-    get(k: any): any;
-    set(k: any, v: any): void;
+    has(k: KEY): boolean;
+    get(k: KEY): VALUE | undefined;
+    set(k: KEY, v: VALUE): void;
     clear(): void;
 }

package/dist/decorators/memo.util.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapMemoCache = exports.jsonMemoSerializer = void 0;
 const object_util_1 = require("../object/object.util");
 const jsonMemoSerializer = args => {
-    if (!args.length)
+    if (args.length === 0)
         return undefined;
     if (args.length === 1 && (0, object_util_1._isPrimitive)(args[0]))
         return args[0];

package/dist/error/assert.d.ts

@@ -1,4 +1,4 @@
-import { ErrorData, HttpErrorData } from '..';
+import { ErrorData } from '..';
 import { AppError } from './app.error';
 /**
  * Evaluates the `condition` (casts it to Boolean).
@@ -16,21 +16,21 @@ import { AppError } from './app.error';
  * 3. Sets `userFriendly` flag to true, cause it's always better to have at least SOME clue, rather than fully generic "Oops" error.
  */
 export declare function _assert(condition: any, // will be evaluated as Boolean
-message?: string, errorData?: Partial<HttpErrorData>): asserts condition;
+message?: string, errorData?: ErrorData): asserts condition;
 /**
  * Like _assert(), but prints more helpful error message.
  * API is similar to Node's assert.equals().
  *
  * Does SHALLOW, but strict equality (===), use _assertDeepEquals() for deep equality.
  */
-export declare function _assertEquals<T>(actual: any, expected: T, message?: string, errorData?: Partial<HttpErrorData>): asserts actual is T;
+export declare function _assertEquals<T>(actual: any, expected: T, message?: string, errorData?: ErrorData): asserts actual is T;
 /**
  * Like _assert(), but prints more helpful error message.
  * API is similar to Node's assert.deepEquals().
  *
  * Does DEEP equality via _deepEquals()
  */
-export declare function _assertDeepEquals<T>(actual: any, expected: T, message?: string, errorData?: Partial<HttpErrorData>): asserts actual is T;
+export declare function _assertDeepEquals<T>(actual: any, expected: T, message?: string, errorData?: ErrorData): asserts actual is T;
 export declare function _assertIsError<ERR extends Error = Error>(err: any, message?: string): asserts err is ERR;
 export declare function _assertIsString(v: any, message?: string): asserts v is string;
 export declare function _assertIsNumber(v: any, message?: string): asserts v is number;

package/dist/error/error.model.d.ts

@@ -26,6 +26,13 @@ export interface ErrorData {
      * `originalMessage` is used to preserve the original `error.message` as it came from the backend.
      */
     originalMessage?: string;
+    /**
+     * Can be used by error-reporting tools (e.g Sentry).
+     * If fingerprint is defined - it'll be used INSTEAD of default fingerprint of a tool.
+     * Can be used to force-group errors that are NOT needed to be split by endpoint or calling function.
+     */
+    fingerprint?: string[];
+    httpStatusCode?: number;
     /**
      * Open-ended.
      */

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export * from './decorators/debounce.decorator';
 export * from './decorators/decorator.util';
 export * from './decorators/logMethod.decorator';
 export * from './decorators/memo.decorator';
-import { MemoCache } from './decorators/memo.util';
+export * from './decorators/asyncMemo.decorator';
+import { MemoCache, AsyncMemoCache } from './decorators/memo.util';
 export * from './decorators/memoFn';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
@@ -58,5 +59,5 @@ export * from './string/safeJsonStringify';
 import { PQueue, PQueueCfg } from './promise/pQueue';
 export * from './seq/seq';
 export * from './math/stack.util';
-export type { AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateTime, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestamp, BaseDBEntity, SavedDBEntity, Saved, Unsaved, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
+export type { AbortableMapper, AbortablePredicate, AbortableAsyncPredicate, AbortableAsyncMapper, PQueueCfg, MemoCache, AsyncMemoCache, PromiseDecoratorCfg, PromiseDecoratorResp, ErrorData, ErrorObject, HttpErrorData, HttpErrorResponse, Admin401ErrorData, Admin403ErrorData, StringMap, PromiseMap, AnyObject, AnyFunction, ValuesOf, ValueOf, KeyValueTuple, ObjectMapper, ObjectPredicate, InstanceId, IsoDate, IsoDateTime, Reviver, PMapOptions, Mapper, AsyncMapper, Predicate, AsyncPredicate, BatchResult, DeferredPromise, PRetryOptions, PTimeoutOptions, TryCatchOptions, StringifyAnyOptions, JsonStringifyFunction, Merge, ReadonlyDeep, Promisable, Simplify, ConditionalPick, ConditionalExcept, Class, UnixTimestamp, BaseDBEntity, SavedDBEntity, Saved, Unsaved, CreatedUpdated, CreatedUpdatedId, ObjectWithId, AnyObjectWithId, JsonSchema, JsonSchemaAny, JsonSchemaOneOf, JsonSchemaAllOf, JsonSchemaAnyOf, JsonSchemaNot, JsonSchemaRef, JsonSchemaConst, JsonSchemaEnum, JsonSchemaString, JsonSchemaNumber, JsonSchemaBoolean, JsonSchemaNull, JsonSchemaRootObject, JsonSchemaObject, JsonSchemaArray, JsonSchemaTuple, JsonSchemaBuilder, CommonLogLevel, CommonLogWithLevelFunction, CommonLogFunction, CommonLogger, };
 export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pRetryFn, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };

package/dist/index.js

@@ -13,6 +13,7 @@ Object.defineProperty(exports, "_createPromiseDecorator", { enumerable: true, ge
 (0, tslib_1.__exportStar)(require("./decorators/decorator.util"), exports);
 (0, tslib_1.__exportStar)(require("./decorators/logMethod.decorator"), exports);
 (0, tslib_1.__exportStar)(require("./decorators/memo.decorator"), exports);
+(0, tslib_1.__exportStar)(require("./decorators/asyncMemo.decorator"), exports);
 (0, tslib_1.__exportStar)(require("./decorators/memoFn"), exports);
 (0, tslib_1.__exportStar)(require("./decorators/retry.decorator"), exports);
 (0, tslib_1.__exportStar)(require("./decorators/timeout.decorator"), exports);

package/dist/promise/pRetry.d.ts

@@ -1,4 +1,4 @@
-import { AnyFunction, CommonLogger } from '..';
+import { AnyFunction, CommonLogger, ErrorData } from '..';
 export interface PRetryOptions {
     /**
      * If set - will be included in the error message.
@@ -76,6 +76,10 @@ export interface PRetryOptions {
      * @experimental
      */
     keepStackTrace?: boolean;
+    /**
+     * Will be merged with `err.data` object.
+     */
+    errorData?: ErrorData;
 }
 /**
  * Returns a Function (!), enhanced with retry capabilities.

package/dist/promise/pRetry.js

@@ -31,7 +31,7 @@ async function pRetry(fn, opt = {}) {
     return await new Promise((resolve, reject) => {
         const rejectWithTimeout = () => {
             timedOut = true; // to prevent more tries
-            const err = new pTimeout_1.TimeoutError(`"${fname}" timed out after ${timeout} ms`);
+            const err = new pTimeout_1.TimeoutError(`"${fname}" timed out after ${timeout} ms`, opt.errorData);
             if (fakeError) {
                 // keep original stack
                 err.stack = fakeError.stack.replace('Error: RetryError', 'TimeoutError');
@@ -75,6 +75,11 @@ async function pRetry(fn, opt = {}) {
                                 fakeError.stack.replace('Error: RetryError', ''),
                         });
                     }
+                    ;
+                    err.data = {
+                        ...err.data,
+                        ...opt.errorData,
+                    };
                     reject(err);
                 }
                 else {

package/dist/promise/pTimeout.d.ts

@@ -1,4 +1,5 @@
 import { AppError } from '../error/app.error';
+import { ErrorData } from '../error/error.model';
 import { AnyFunction } from '../types';
 export declare class TimeoutError extends AppError {
 }
@@ -25,6 +26,10 @@ export interface PTimeoutOptions {
      * @experimental
      */
     keepStackTrace?: boolean;
+    /**
+     * Will be merged with `err.data` object.
+     */
+    errorData?: ErrorData;
 }
 /**
  * Decorates a Function with a timeout.

package/dist/promise/pTimeout.js

@@ -37,11 +37,15 @@ async function pTimeout(promise, opt) {
                 catch (err) {
                     if (fakeError)
                         err.stack = fakeError.stack; // keep original stack
+                    err.data = {
+                        ...err.data,
+                        ...opt.errorData,
+                    };
                     reject(err);
                 }
                 return;
             }
-            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`);
+            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`, opt.errorData);
             if (fakeError)
                 err.stack = fakeError.stack; // keep original stack
             reject(err);

package/dist-esm/decorators/asyncMemo.decorator.js

@@ -0,0 +1,104 @@
+import { __asyncValues } from "tslib";
+import { _since } from '../time/time.util';
+import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
+import { CACHE_DROP } from './memo.decorator';
+import { jsonMemoSerializer } from './memo.util';
+/**
+ * Like @_Memo, but allowing async MemoCache implementation.
+ *
+ * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
+ * Return `null` instead (it'll be cached).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const _AsyncMemo = (opt) => (target, key, descriptor) => {
+    if (typeof descriptor.value !== 'function') {
+        throw new TypeError('Memoization can be applied only to methods');
+    }
+    const originalFn = descriptor.value;
+    // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
+    const cache = new Map();
+    const { logHit = false, logMiss = false, noLogArgs = false, logger = console, cacheFactory, cacheKeyFn = jsonMemoSerializer, noCacheRejected = false, noCacheResolved = false, } = opt;
+    const keyStr = String(key);
+    const methodSignature = _getTargetMethodSignature(target, keyStr);
+    descriptor.value = async function (...args) {
+        var e_1, _a;
+        const ctx = this;
+        const cacheKey = cacheKeyFn(args);
+        if (!cache.has(ctx)) {
+            cache.set(ctx, cacheFactory());
+            // here, no need to check the cache. It's definitely a miss, because the cacheLayers is just created
+            // UPD: no! AsyncMemo supports "persistent caches" (e.g Database-backed cache)
+        }
+        if (args.length === 1 && args[0] === CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_AsyncMemo.dropCache()`);
+            try {
+                await Promise.all(cache.get(ctx).map(c => c.clear()));
+            }
+            catch (err) {
+                logger.error(err);
+            }
+            return;
+        }
+        let value;
+        try {
+            try {
+                for (var _b = __asyncValues(cache.get(ctx)), _c; _c = await _b.next(), !_c.done;) {
+                    const cacheLayer = _c.value;
+                    value = await cacheLayer.get(cacheKey);
+                    if (value !== undefined) {
+                        // it's a hit!
+                        break;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) await _a.call(_b);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            // log error, but don't throw, treat it as a "miss"
+            logger.error(err);
+        }
+        if (value !== undefined) {
+            // hit!
+            if (logHit) {
+                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, noLogArgs)}) @_AsyncMemo hit`);
+            }
+            return value instanceof Error ? Promise.reject(value) : Promise.resolve(value);
+        }
+        // Here we know it's a MISS, let's execute the real method
+        const started = Date.now();
+        try {
+            value = await originalFn.apply(ctx, args);
+            if (!noCacheResolved) {
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, value))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            return value;
+        }
+        catch (err) {
+            if (!noCacheRejected) {
+                // We put it to cache as raw Error, not Promise.reject(err)
+                Promise.all(cache.get(ctx).map(cacheLayer => cacheLayer.set(cacheKey, err))).catch(err => {
+                    // log and ignore the error
+                    logger.error(err);
+                });
+            }
+            throw err;
+        }
+        finally {
+            if (logMiss) {
+                logger.log(`${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, noLogArgs)}) @_AsyncMemo miss (${_since(started)})`);
+            }
+        }
+    };
+    return descriptor;
+};

package/dist-esm/decorators/memo.decorator.js

@@ -6,6 +6,10 @@
 import { _since } from '../time/time.util';
 import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util';
 import { jsonMemoSerializer, MapMemoCache } from './memo.util';
+/**
+ * Symbol to indicate that the Cache should be dropped.
+ */
+export const CACHE_DROP = Symbol('CACHE_DROP');
 /**
  * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
  * of the cache is the same. Key, by defaul, is calculated as `JSON.stringify(...args)`.
@@ -35,7 +39,14 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = function (...args) {
+        var _a;
         const ctx = this;
+        if (args.length === 1 && args[0] === CACHE_DROP) {
+            // Special event - CACHE_DROP
+            // Function will return undefined
+            logger.log(`${methodSignature} @_Memo.CACHE_DROP`);
+            return (_a = cache.get(ctx)) === null || _a === void 0 ? void 0 : _a.clear();
+        }
         const cacheKey = cacheKeyFn(args);
         if (!cache.has(ctx)) {
             cache.set(ctx, cacheFactory());
@@ -88,10 +99,5 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
             return res;
         }
     };
-    descriptor.value.dropCache = () => {
-        logger.log(`${methodSignature} @_Memo.dropCache()`);
-        cache.forEach(memoCache => memoCache.clear());
-        cache.clear();
-    };
     return descriptor;
 };

package/dist-esm/decorators/memo.util.js

@@ -1,6 +1,6 @@
 import { _isPrimitive } from '../object/object.util';
 export const jsonMemoSerializer = args => {
-    if (!args.length)
+    if (args.length === 0)
         return undefined;
     if (args.length === 1 && _isPrimitive(args[0]))
         return args[0];

package/dist-esm/index.js

@@ -8,6 +8,7 @@ export * from './decorators/debounce.decorator';
 export * from './decorators/decorator.util';
 export * from './decorators/logMethod.decorator';
 export * from './decorators/memo.decorator';
+export * from './decorators/asyncMemo.decorator';
 export * from './decorators/memoFn';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';

package/dist-esm/promise/pRetry.js

@@ -27,7 +27,7 @@ export async function pRetry(fn, opt = {}) {
     return await new Promise((resolve, reject) => {
         const rejectWithTimeout = () => {
             timedOut = true; // to prevent more tries
-            const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`);
+            const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`, opt.errorData);
             if (fakeError) {
                 // keep original stack
                 err.stack = fakeError.stack.replace('Error: RetryError', 'TimeoutError');
@@ -71,6 +71,8 @@ export async function pRetry(fn, opt = {}) {
                                 fakeError.stack.replace('Error: RetryError', ''),
                         });
                     }
+                    ;
+                    err.data = Object.assign(Object.assign({}, err.data), opt.errorData);
                     reject(err);
                 }
                 else {

package/dist-esm/promise/pTimeout.js

@@ -32,11 +32,12 @@ export async function pTimeout(promise, opt) {
                 catch (err) {
                     if (fakeError)
                         err.stack = fakeError.stack; // keep original stack
+                    err.data = Object.assign(Object.assign({}, err.data), opt.errorData);
                     reject(err);
                 }
                 return;
             }
-            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`);
+            const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`, opt.errorData);
             if (fakeError)
                 err.stack = fakeError.stack; // keep original stack
             reject(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.82.0",
+  "version": "14.84.1",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/decorators/asyncMemo.decorator.ts

@@ -0,0 +1,151 @@
+import { _since } from '../time/time.util'
+import { Merge } from '../typeFest'
+import { AnyObject } from '../types'
+import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util'
+import { CACHE_DROP, MemoOptions } from './memo.decorator'
+import { AsyncMemoCache, jsonMemoSerializer } from './memo.util'
+
+export type AsyncMemoOptions = Merge<
+  MemoOptions,
+  {
+    /**
+     * Provide a custom implementation of MemoCache.
+     * Function that creates an instance of `MemoCache`.
+     * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`.
+     *
+     * It's an ARRAY of Caches, to allow multiple layers of Cache.
+     * It will check it one by one, starting from the first.
+     * HIT will be returned immediately, MISS will go one level deeper, or returned (if the end of the Cache stack is reached).
+     */
+    cacheFactory: () => AsyncMemoCache[]
+  }
+>
+
+/**
+ * Like @_Memo, but allowing async MemoCache implementation.
+ *
+ * Method CANNOT return `undefined`, as undefined will always be treated as cache MISS and retried.
+ * Return `null` instead (it'll be cached).
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const _AsyncMemo =
+  (opt: AsyncMemoOptions): MethodDecorator =>
+  (target, key, descriptor) => {
+    if (typeof descriptor.value !== 'function') {
+      throw new TypeError('Memoization can be applied only to methods')
+    }
+
+    const originalFn = descriptor.value
+
+    // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
+    const cache = new Map<AnyObject, AsyncMemoCache[]>()
+
+    const {
+      logHit = false,
+      logMiss = false,
+      noLogArgs = false,
+      logger = console,
+      cacheFactory,
+      cacheKeyFn = jsonMemoSerializer,
+      noCacheRejected = false,
+      noCacheResolved = false,
+    } = opt
+
+    const keyStr = String(key)
+    const methodSignature = _getTargetMethodSignature(target, keyStr)
+
+    descriptor.value = async function (this: typeof target, ...args: any[]): Promise<any> {
+      const ctx = this
+
+      const cacheKey = cacheKeyFn(args)
+
+      if (!cache.has(ctx)) {
+        cache.set(ctx, cacheFactory())
+        // here, no need to check the cache. It's definitely a miss, because the cacheLayers is just created
+        // UPD: no! AsyncMemo supports "persistent caches" (e.g Database-backed cache)
+      }
+
+      if (args.length === 1 && args[0] === CACHE_DROP) {
+        // Special event - CACHE_DROP
+        // Function will return undefined
+        logger.log(`${methodSignature} @_AsyncMemo.dropCache()`)
+        try {
+          await Promise.all(cache.get(ctx)!.map(c => c.clear()))
+        } catch (err) {
+          logger.error(err)
+        }
+
+        return
+      }
+
+      let value: any
+
+      try {
+        for await (const cacheLayer of cache.get(ctx)!) {
+          value = await cacheLayer.get(cacheKey)
+          if (value !== undefined) {
+            // it's a hit!
+            break
+          }
+        }
+      } catch (err) {
+        // log error, but don't throw, treat it as a "miss"
+        logger.error(err)
+      }
+
+      if (value !== undefined) {
+        // hit!
+        if (logHit) {
+          logger.log(
+            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
+              args,
+              noLogArgs,
+            )}) @_AsyncMemo hit`,
+          )
+        }
+
+        return value instanceof Error ? Promise.reject(value) : Promise.resolve(value)
+      }
+
+      // Here we know it's a MISS, let's execute the real method
+      const started = Date.now()
+
+      try {
+        value = await originalFn.apply(ctx, args)
+
+        if (!noCacheResolved) {
+          Promise.all(cache.get(ctx)!.map(cacheLayer => cacheLayer.set(cacheKey, value))).catch(
+            err => {
+              // log and ignore the error
+              logger.error(err)
+            },
+          )
+        }
+
+        return value
+      } catch (err) {
+        if (!noCacheRejected) {
+          // We put it to cache as raw Error, not Promise.reject(err)
+          Promise.all(cache.get(ctx)!.map(cacheLayer => cacheLayer.set(cacheKey, err))).catch(
+            err => {
+              // log and ignore the error
+              logger.error(err)
+            },
+          )
+        }
+
+        throw err
+      } finally {
+        if (logMiss) {
+          logger.log(
+            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
+              args,
+              noLogArgs,
+            )}) @_AsyncMemo miss (${_since(started)})`,
+          )
+        }
+      }
+    } as any
+
+    return descriptor
+  }

package/src/decorators/memo.decorator.ts

@@ -10,6 +10,11 @@ import { AnyObject } from '../types'
 import { _getArgsSignature, _getMethodSignature, _getTargetMethodSignature } from './decorator.util'
 import { jsonMemoSerializer, MapMemoCache, MemoCache } from './memo.util'
 
+/**
+ * Symbol to indicate that the Cache should be dropped.
+ */
+export const CACHE_DROP = Symbol('CACHE_DROP')
+
 export interface MemoOptions {
   /**
    * Default to false
@@ -45,12 +50,16 @@ export interface MemoOptions {
   /**
    * Don't cache resolved promises.
    * Setting this to `true` will make the decorator to await the result.
+   *
+   * Default false.
    */
   noCacheResolved?: boolean
 
   /**
    * Don't cache rejected promises.
    * Setting this to `true` will make the decorator to await the result.
+   *
+   * Default false.
    */
   noCacheRejected?: boolean
 }
@@ -102,6 +111,13 @@ export const _Memo =
     descriptor.value = function (this: typeof target, ...args: any[]): any {
       const ctx = this
 
+      if (args.length === 1 && args[0] === CACHE_DROP) {
+        // Special event - CACHE_DROP
+        // Function will return undefined
+        logger.log(`${methodSignature} @_Memo.CACHE_DROP`)
+        return cache.get(ctx)?.clear()
+      }
+
       const cacheKey = cacheKeyFn(args)
 
       if (!cache.has(ctx)) {
@@ -179,11 +195,6 @@ export const _Memo =
         return res
       }
     } as any
-    ;(descriptor.value as any).dropCache = () => {
-      logger.log(`${methodSignature} @_Memo.dropCache()`)
-      cache.forEach(memoCache => memoCache.clear())
-      cache.clear()
-    }
 
     return descriptor
   }

package/src/decorators/memo.util.ts

@@ -1,20 +1,44 @@
 import { _isPrimitive } from '../object/object.util'
+import { Promisable } from '../typeFest'
 
 export type MemoSerializer = (args: any[]) => any
 
 export const jsonMemoSerializer: MemoSerializer = args => {
-  if (!args.length) return undefined
+  if (args.length === 0) return undefined
   if (args.length === 1 && _isPrimitive(args[0])) return args[0]
   return JSON.stringify(args)
 }
 
-export interface MemoCache {
-  has(k: any): boolean
-  get(k: any): any
-  set(k: any, v: any): void
+export interface MemoCache<KEY = any, VALUE = any> {
+  has(k: KEY): boolean
+  get(k: KEY): VALUE | undefined
+  set(k: KEY, v: VALUE): void
+
+  /**
+   * Clear is only called when `.dropCache()` is called.
+   * Otherwise the Cache is "persistent" (never cleared).
+   */
   clear(): void
 }
 
+export interface AsyncMemoCache<KEY = any, VALUE = any> {
+  // `has` method is removed, because it is assumed that it has a cost and it's best to avoid doing both `has` and then `get`
+  // has(k: any): Promise<boolean>
+  /**
+   * `undefined` value returned indicates the ABSENCE of value in the Cache.
+   * This also means that you CANNOT store `undefined` value in the Cache, as it'll be treated as a MISS.
+   * You CAN store `null` value instead, it will be treated as a HIT.
+   */
+  get(k: KEY): Promisable<VALUE | undefined>
+  set(k: KEY, v: VALUE): Promisable<void>
+
+  /**
+   * Clear is only called when `.dropCache()` is called.
+   * Otherwise the Cache is "persistent" (never cleared).
+   */
+  clear(): Promisable<void>
+}
+
 // SingleValueMemoCache and ObjectMemoCache are example-only, not used in production code
 /*
 export class SingleValueMemoCache implements MemoCache {
@@ -61,18 +85,20 @@ export class ObjectMemoCache implements MemoCache {
 }
  */
 
-export class MapMemoCache implements MemoCache {
-  private m = new Map<any, any>()
+export class MapMemoCache<KEY = any, VALUE = any>
+  implements MemoCache<KEY, VALUE>, AsyncMemoCache<KEY, VALUE>
+{
+  private m = new Map<KEY, VALUE>()
 
-  has(k: any): boolean {
+  has(k: KEY): boolean {
     return this.m.has(k)
   }
 
-  get(k: any): any {
+  get(k: KEY): VALUE | undefined {
     return this.m.get(k)
   }
 
-  set(k: any, v: any): void {
+  set(k: KEY, v: VALUE): void {
     this.m.set(k, v)
   }
 

package/src/error/assert.ts

@@ -1,4 +1,4 @@
-import { ErrorData, HttpErrorData, _deepEquals, _stringifyAny } from '..'
+import { ErrorData, _deepEquals, _stringifyAny } from '..'
 import { AppError } from './app.error'
 
 /**
@@ -19,7 +19,7 @@ import { AppError } from './app.error'
 export function _assert(
   condition: any, // will be evaluated as Boolean
   message?: string,
-  errorData?: Partial<HttpErrorData>,
+  errorData?: ErrorData,
 ): asserts condition {
   if (!condition) {
     throw new AssertionError(message || 'see stacktrace', {
@@ -39,7 +39,7 @@ export function _assertEquals<T>(
   actual: any,
   expected: T,
   message?: string,
-  errorData?: Partial<HttpErrorData>,
+  errorData?: ErrorData,
 ): asserts actual is T {
   if (actual !== expected) {
     const msg = [
@@ -67,7 +67,7 @@ export function _assertDeepEquals<T>(
   actual: any,
   expected: T,
   message?: string,
-  errorData?: Partial<HttpErrorData>,
+  errorData?: ErrorData,
 ): asserts actual is T {
   if (!_deepEquals(actual, expected)) {
     const msg = [

package/src/error/error.model.ts

@@ -31,6 +31,15 @@ export interface ErrorData {
    */
   originalMessage?: string
 
+  /**
+   * Can be used by error-reporting tools (e.g Sentry).
+   * If fingerprint is defined - it'll be used INSTEAD of default fingerprint of a tool.
+   * Can be used to force-group errors that are NOT needed to be split by endpoint or calling function.
+   */
+  fingerprint?: string[]
+
+  httpStatusCode?: number
+
   /**
    * Open-ended.
    */

package/src/index.ts

@@ -12,7 +12,8 @@ export * from './decorators/debounce.decorator'
 export * from './decorators/decorator.util'
 export * from './decorators/logMethod.decorator'
 export * from './decorators/memo.decorator'
-import { MemoCache } from './decorators/memo.util'
+export * from './decorators/asyncMemo.decorator'
+import { MemoCache, AsyncMemoCache } from './decorators/memo.util'
 export * from './decorators/memoFn'
 export * from './decorators/retry.decorator'
 export * from './decorators/timeout.decorator'
@@ -160,6 +161,7 @@ export type {
   AbortableAsyncMapper,
   PQueueCfg,
   MemoCache,
+  AsyncMemoCache,
   PromiseDecoratorCfg,
   PromiseDecoratorResp,
   ErrorData,

package/src/promise/pRetry.ts

@@ -1,4 +1,4 @@
-import { _since, _stringifyAny, AnyFunction, CommonLogger } from '..'
+import { _since, _stringifyAny, AnyFunction, AppError, CommonLogger, ErrorData } from '..'
 import { TimeoutError } from './pTimeout'
 
 export interface PRetryOptions {
@@ -91,6 +91,11 @@ export interface PRetryOptions {
    * @experimental
    */
   keepStackTrace?: boolean
+
+  /**
+   * Will be merged with `err.data` object.
+   */
+  errorData?: ErrorData
 }
 
 /**
@@ -139,7 +144,7 @@ export async function pRetry<T>(
   return await new Promise((resolve, reject) => {
     const rejectWithTimeout = () => {
       timedOut = true // to prevent more tries
-      const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`)
+      const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`, opt.errorData)
       if (fakeError) {
         // keep original stack
         err.stack = fakeError.stack!.replace('Error: RetryError', 'TimeoutError')
@@ -199,6 +204,11 @@ export async function pRetry<T>(
             })
           }
 
+          ;(err as AppError).data = {
+            ...(err as AppError).data,
+            ...opt.errorData,
+          }
+
           reject(err)
         } else {
           // Retry after delay

package/src/promise/pTimeout.ts

@@ -1,4 +1,5 @@
 import { AppError } from '../error/app.error'
+import { ErrorData } from '../error/error.model'
 import { AnyFunction } from '../types'
 
 export class TimeoutError extends AppError {}
@@ -29,6 +30,11 @@ export interface PTimeoutOptions {
    * @experimental
    */
   keepStackTrace?: boolean
+
+  /**
+   * Will be merged with `err.data` object.
+   */
+  errorData?: ErrorData
 }
 
 /**
@@ -63,12 +69,19 @@ export async function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Pr
           resolve(onTimeout())
         } catch (err: any) {
           if (fakeError) err.stack = fakeError.stack // keep original stack
+          err.data = {
+            ...err.data,
+            ...opt.errorData,
+          }
           reject(err)
         }
         return
       }
 
-      const err = new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`)
+      const err = new TimeoutError(
+        `"${name || 'pTimeout function'}" timed out after ${timeout} ms`,
+        opt.errorData,
+      )
       if (fakeError) err.stack = fakeError.stack // keep original stack
       reject(err)
     }, timeout)