@naturalcycles/js-lib 14.80.0 → 14.83.0

package/dist-esm/promise/pRetry.js

@@ -1,54 +1,85 @@
 import { _since, _stringifyAny } from '..';
+import { TimeoutError } from './pTimeout';
 /**
  * Returns a Function (!), enhanced with retry capabilities.
  * Implements "Exponential back-off strategy" by multiplying the delay by `delayMultiplier` with each try.
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
-export function pRetry(fn, opt = {}) {
-    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name = fn.name, } = opt;
+export function pRetryFn(fn, opt = {}) {
+    return async function pRetryFunction(...args) {
+        return await pRetry(() => fn.call(this, ...args), opt);
+    };
+}
+export async function pRetry(fn, opt = {}) {
+    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name, keepStackTrace = true, timeout, } = opt;
+    const fakeError = keepStackTrace ? new Error('RetryError') : undefined;
     let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt;
     if (opt.logAll) {
-        logFirstAttempt = logRetries = logFailures = true;
+        logSuccess = logFirstAttempt = logRetries = logFailures = true;
     }
     if (opt.logNone) {
         logSuccess = logFirstAttempt = logRetries = logFailures = false;
     }
-    const fname = ['pRetry', name].filter(Boolean).join('.');
-    return async function (...args) {
-        let delay = initialDelay;
-        let attempt = 0;
-        return await new Promise((resolve, reject) => {
-            const next = async () => {
-                const started = Date.now();
-                try {
-                    attempt++;
-                    if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
-                        logger.log(`${fname} attempt #${attempt}...`);
-                    }
-                    const r = await fn.apply(this, args);
-                    if (logSuccess) {
-                        logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`);
-                    }
-                    resolve(r);
+    const fname = name || fn.name || 'pRetry function';
+    let delay = initialDelay;
+    let attempt = 0;
+    let timer;
+    let timedOut = false;
+    return await new Promise((resolve, reject) => {
+        const rejectWithTimeout = () => {
+            timedOut = true; // to prevent more tries
+            const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`);
+            if (fakeError) {
+                // keep original stack
+                err.stack = fakeError.stack.replace('Error: RetryError', 'TimeoutError');
+            }
+            reject(err);
+        };
+        const next = async () => {
+            if (timedOut)
+                return;
+            if (timeout) {
+                timer = setTimeout(rejectWithTimeout, timeout);
+            }
+            const started = Date.now();
+            try {
+                attempt++;
+                if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
+                    logger.log(`${fname} attempt #${attempt}...`);
                 }
-                catch (err) {
-                    if (logFailures) {
-                        logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, _stringifyAny(err, {
-                            includeErrorData: true,
-                        }));
-                    }
-                    if (attempt >= maxAttempts || (predicate && !predicate(err, attempt, maxAttempts))) {
-                        // Give up
-                        reject(err);
-                    }
-                    else {
-                        // Retry after delay
-                        delay *= delayMultiplier;
-                        setTimeout(next, delay);
+                const r = await fn(attempt);
+                clearTimeout(timer);
+                if (logSuccess) {
+                    logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`);
+                }
+                resolve(r);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                if (logFailures) {
+                    logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, _stringifyAny(err, {
+                        includeErrorData: true,
+                    }));
+                }
+                if (attempt >= maxAttempts ||
+                    (predicate && !predicate(err, attempt, maxAttempts))) {
+                    // Give up
+                    if (fakeError) {
+                        // Preserve the original call stack
+                        Object.defineProperty(err, 'stack', {
+                            value: err.stack +
+                                '\n    --' +
+                                fakeError.stack.replace('Error: RetryError', ''),
+                        });
                     }
+                    reject(err);
                 }
-            };
-            void next();
-        });
-    };
+                else {
+                    // Retry after delay
+                    delay *= delayMultiplier;
+                    setTimeout(next, delay);
+                }
+            }
+        };
+        void next();
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.80.0",
+  "version": "14.83.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

@@ -3,18 +3,41 @@ import { _isPrimitive } from '../object/object.util'
 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): Promise<VALUE | undefined>
+  set(k: KEY, v: VALUE): Promise<void>
+
+  /**
+   * Clear is only called when `.dropCache()` is called.
+   * Otherwise the Cache is "persistent" (never cleared).
+   */
+  clear(): Promise<void>
+}
+
 // SingleValueMemoCache and ObjectMemoCache are example-only, not used in production code
 /*
 export class SingleValueMemoCache implements MemoCache {
@@ -61,18 +84,18 @@ 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> {
+  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)
   }
 
@@ -80,3 +103,19 @@ export class MapMemoCache implements MemoCache {
     this.m.clear()
   }
 }
+
+export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
+  private m = new Map<KEY, VALUE>()
+
+  async get(k: KEY): Promise<VALUE | undefined> {
+    return this.m.get(k)
+  }
+
+  async set(k: KEY, v: VALUE): Promise<void> {
+    this.m.set(k, v)
+  }
+
+  async clear(): Promise<void> {
+    this.m.clear()
+  }
+}

package/src/decorators/retry.decorator.ts

@@ -1,10 +1,10 @@
-import { pRetry, PRetryOptions } from '..'
+import { pRetryFn, PRetryOptions } from '..'
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Retry(opt: PRetryOptions = {}): MethodDecorator {
   return (target, key, descriptor) => {
     const originalFn = descriptor.value
-    descriptor.value = pRetry(originalFn as any, opt)
+    descriptor.value = pRetryFn(originalFn as any, opt)
     return descriptor
   }
 }

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.
    */

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'
@@ -67,14 +68,13 @@ export * from './object/object.util'
 export * from './object/sortObject'
 export * from './object/sortObjectDeep'
 import { AggregatedError } from './promise/AggregatedError'
-export * from './promise/pBatch'
 import { DeferredPromise, pDefer } from './promise/pDefer'
 export * from './promise/pDelay'
 export * from './promise/pFilter'
 export * from './promise/pHang'
 import { pMap, PMapOptions } from './promise/pMap'
 export * from './promise/pProps'
-import { pRetry, PRetryOptions } from './promise/pRetry'
+import { pRetry, pRetryFn, PRetryOptions } from './promise/pRetry'
 export * from './promise/pState'
 import { pTimeout, pTimeoutFn, PTimeoutOptions } from './promise/pTimeout'
 export * from './promise/pTuple'
@@ -161,6 +161,7 @@ export type {
   AbortableAsyncMapper,
   PQueueCfg,
   MemoCache,
+  AsyncMemoCache,
   PromiseDecoratorCfg,
   PromiseDecoratorResp,
   ErrorData,
@@ -250,6 +251,7 @@ export {
   pDefer,
   AggregatedError,
   pRetry,
+  pRetryFn,
   pTimeout,
   pTimeoutFn,
   _tryCatch,

package/src/json-schema/jsonSchemaBuilder.ts

@@ -365,9 +365,9 @@ export class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyB
     return this
   }
 
-  baseDBEntity(): JsonSchemaObjectBuilder<T & BaseDBEntity> {
+  baseDBEntity<ID = string>(idType = 'string'): JsonSchemaObjectBuilder<T & BaseDBEntity<ID>> {
     Object.assign(this.schema.properties, {
-      id: { type: 'string' },
+      id: { type: idType },
       created: { type: 'number', format: 'unixTimestamp' },
       updated: { type: 'number', format: 'unixTimestamp' },
     })
@@ -375,8 +375,8 @@ export class JsonSchemaObjectBuilder<T extends AnyObject> extends JsonSchemaAnyB
     return this
   }
 
-  savedDBEntity(): JsonSchemaObjectBuilder<T & SavedDBEntity> {
-    return this.baseDBEntity().addRequired(['id', 'created', 'updated']) as any
+  savedDBEntity<ID = string>(idType = 'string'): JsonSchemaObjectBuilder<T & SavedDBEntity<ID>> {
+    return this.baseDBEntity(idType).addRequired(['id', 'created', 'updated']) as any
   }
 
   extend<T2 extends AnyObject>(s2: JsonSchemaObjectBuilder<T2>): JsonSchemaObjectBuilder<T & T2> {

package/src/promise/AggregatedError.ts

@@ -7,20 +7,15 @@ export class AggregatedError<RESULT = any> extends Error {
   errors!: Error[]
   results!: RESULT[]
 
-  constructor(errors: (Error | string)[], results: RESULT[] = []) {
-    const mappedErrors = errors.map(e => {
-      if (typeof e === 'string') return new Error(e)
-      return e
-    })
-
+  constructor(errors: Error[], results: RESULT[] = []) {
     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', {

package/src/promise/pFilter.ts

@@ -1,16 +1,7 @@
-import { AbortableAsyncPredicate } from '../types'
-import { pMap, PMapOptions } from './pMap'
+import { AsyncPredicate } from '../types'
 
-export async function pFilter<T>(
-  iterable: Iterable<T | PromiseLike<T>>,
-  filterFn: AbortableAsyncPredicate<T>,
-  opt?: PMapOptions,
-): Promise<T[]> {
-  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<T>(iterable: Iterable<T>, filterFn: AsyncPredicate<T>): Promise<T[]> {
+  const items = [...iterable]
+  const predicates = await Promise.all(items.map((item, i) => filterFn(item, i)))
+  return items.filter((item, i) => predicates[i])
 }