@naturalcycles/js-lib 14.81.0 → 14.84.0

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';
@@ -31,7 +32,6 @@ export * from './object/object.util';
 export * from './object/sortObject';
 export * from './object/sortObjectDeep';
 import { AggregatedError } from './promise/AggregatedError';
-export * from './promise/pBatch';
 import { pDefer } from './promise/pDefer';
 export * from './promise/pDelay';
 export * from './promise/pFilter';

package/dist-esm/promise/AggregatedError.js

@@ -5,17 +5,12 @@
  */
 export class AggregatedError extends Error {
     constructor(errors, results = []) {
-        const mappedErrors = errors.map(e => {
-            if (typeof e === 'string')
-                return new Error(e);
-            return e;
-        });
         const message = [
             `${errors.length} errors:`,
-            ...mappedErrors.map((e, i) => `${i + 1}. ${e.message}`),
+            ...errors.map((e, i) => `${i + 1}. ${e.message}`),
         ].join('\n');
         super(message);
-        this.errors = mappedErrors;
+        this.errors = errors;
         this.results = results;
         Object.defineProperty(this, 'name', {
             value: this.constructor.name,

package/dist-esm/promise/pFilter.js

@@ -1,5 +1,5 @@
-import { pMap } from './pMap';
-export async function pFilter(iterable, filterFn, opt) {
-    const values = await pMap(iterable, async (item, index) => await Promise.all([filterFn(item, index), item]), opt);
-    return values.filter(value => Boolean(value[0])).map(value => value[1]);
+export async function pFilter(iterable, filterFn) {
+    const items = [...iterable];
+    const predicates = await Promise.all(items.map((item, i) => filterFn(item, i)));
+    return items.filter((item, i) => predicates[i]);
 }

package/dist-esm/promise/pMap.js

@@ -6,6 +6,7 @@ Improvements:
 - Included Typescript typings (no need for @types/p-map)
 - Compatible with pProps (that had typings issues)
  */
+import { __asyncValues } from "tslib";
 import { END, ErrorMode, SKIP } from '..';
 import { AggregatedError } from './AggregatedError';
 /**
@@ -35,28 +36,85 @@ import { AggregatedError } from './AggregatedError';
  * })();
  */
 export async function pMap(iterable, mapper, opt = {}) {
+    var e_1, _a;
+    const ret = [];
+    // const iterator = iterable[Symbol.iterator]()
+    const items = [...iterable];
+    const itemsLength = items.length;
+    if (itemsLength === 0)
+        return []; // short circuit
+    const { concurrency = itemsLength, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt;
+    const errors = [];
+    let isSettled = false;
+    let resolvingCount = 0;
+    let currentIndex = 0;
+    // Special cases that are able to preserve async stack traces
+    if (concurrency === 1) {
+        try {
+            // Special case for concurrency == 1
+            for (var items_1 = __asyncValues(items), items_1_1; items_1_1 = await items_1.next(), !items_1_1.done;) {
+                const item = items_1_1.value;
+                try {
+                    const r = await mapper(item, currentIndex++);
+                    if (r === END)
+                        break;
+                    if (r !== SKIP)
+                        ret.push(r);
+                }
+                catch (err) {
+                    if (errorMode === ErrorMode.THROW_IMMEDIATELY)
+                        throw err;
+                    if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                        errors.push(err);
+                    }
+                    // otherwise, suppress completely
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (items_1_1 && !items_1_1.done && (_a = items_1.return)) await _a.call(items_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        if (errors.length) {
+            throw new AggregatedError(errors, ret);
+        }
+        return ret;
+    }
+    else if (!opt.concurrency || items.length <= opt.concurrency) {
+        // Special case for concurrency == infinity or iterable.length < concurrency
+        if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
+            return (await Promise.all(items.map((item, i) => mapper(item, i)))).filter(r => r !== SKIP && r !== END);
+        }
+        ;
+        (await Promise.allSettled(items.map((item, i) => mapper(item, i)))).forEach(r => {
+            if (r.status === 'fulfilled') {
+                if (r.value !== SKIP && r.value !== END)
+                    ret.push(r.value);
+            }
+            else if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                errors.push(r.reason);
+            }
+        });
+        if (errors.length) {
+            throw new AggregatedError(errors, ret);
+        }
+        return ret;
+    }
     return new Promise((resolve, reject) => {
-        const { concurrency = Number.POSITIVE_INFINITY, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt;
-        const ret = [];
-        const iterator = iterable[Symbol.iterator]();
-        const errors = [];
-        let isSettled = false;
-        let isIterableDone = false;
-        let resolvingCount = 0;
-        let currentIndex = 0;
-        const next = (skipped = false) => {
+        const next = () => {
             if (isSettled) {
                 return;
             }
-            const nextItem = iterator.next();
-            const i = currentIndex;
-            if (!skipped)
-                currentIndex++;
-            if (nextItem.done) {
-                isIterableDone = true;
+            const nextItem = items[currentIndex];
+            const i = currentIndex++;
+            if (currentIndex > itemsLength) {
                 if (resolvingCount === 0) {
+                    isSettled = true;
                     const r = ret.filter(r => r !== SKIP);
-                    if (errors.length && errorMode === ErrorMode.THROW_AGGREGATED) {
+                    if (errors.length) {
                         reject(new AggregatedError(errors, r));
                     }
                     else {
@@ -66,7 +124,7 @@ export async function pMap(iterable, mapper, opt = {}) {
                 return;
             }
             resolvingCount++;
-            Promise.resolve(nextItem.value)
+            Promise.resolve(nextItem)
                 .then(async (element) => await mapper(element, i))
                 .then(value => {
                 if (value === END) {
@@ -82,7 +140,9 @@ export async function pMap(iterable, mapper, opt = {}) {
                     reject(err);
                 }
                 else {
-                    errors.push(err);
+                    if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                        errors.push(err);
+                    }
                     resolvingCount--;
                     next();
                 }
@@ -90,7 +150,7 @@ export async function pMap(iterable, mapper, opt = {}) {
         };
         for (let i = 0; i < concurrency; i++) {
             next();
-            if (isIterableDone) {
+            if (isSettled) {
                 break;
             }
         }

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.81.0",
+  "version": "14.84.0",
   "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/error.model.ts

@@ -31,6 +31,13 @@ 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[]
+
   /**
    * Open-ended.
    */