@naturalcycles/js-lib 14.80.1 → 14.83.1

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/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/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])
 }

package/src/promise/pMap.ts

@@ -55,36 +55,85 @@ export interface PMapOptions {
  * })();
  */
 export async function pMap<IN, OUT>(
-  iterable: Iterable<IN | PromiseLike<IN>>,
+  iterable: Iterable<IN>,
   mapper: AbortableAsyncMapper<IN, OUT>,
   opt: PMapOptions = {},
 ): Promise<OUT[]> {
-  return new Promise<OUT[]>((resolve, reject) => {
-    const { concurrency = Number.POSITIVE_INFINITY, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt
+  const ret: (OUT | typeof SKIP)[] = []
+  // 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: Error[] = []
+  let isSettled = false
+  let resolvingCount = 0
+  let currentIndex = 0
+
+  // Special cases that are able to preserve async stack traces
+
+  if (concurrency === 1) {
+    // Special case for concurrency == 1
+
+    for await (const item of items) {
+      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 as Error)
+        }
+        // otherwise, suppress completely
+      }
+    }
+
+    if (errors.length) {
+      throw new AggregatedError(errors, ret)
+    }
+
+    return ret as OUT[]
+  } 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,
+      ) as OUT[]
+    }
+
+    ;(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)
+    }
 
-    const ret: (OUT | typeof SKIP)[] = []
-    const iterator = iterable[Symbol.iterator]()
-    const errors: Error[] = []
-    let isSettled = false
-    let isIterableDone = false
-    let resolvingCount = 0
-    let currentIndex = 0
+    return ret as OUT[]
+  }
 
-    const next = (skipped = false) => {
+  return new Promise<OUT[]>((resolve, reject) => {
+    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) as OUT[]
-          if (errors.length && errorMode === ErrorMode.THROW_AGGREGATED) {
+          if (errors.length) {
             reject(new AggregatedError(errors, r))
           } else {
             resolve(r)
@@ -96,7 +145,7 @@ export async function pMap<IN, OUT>(
 
       resolvingCount++
 
-      Promise.resolve(nextItem.value)
+      Promise.resolve(nextItem)
         .then(async element => await mapper(element, i))
         .then(
           value => {
@@ -114,7 +163,9 @@ export async function pMap<IN, OUT>(
               isSettled = true
               reject(err)
             } else {
-              errors.push(err)
+              if (errorMode === ErrorMode.THROW_AGGREGATED) {
+                errors.push(err)
+              }
               resolvingCount--
               next()
             }
@@ -125,7 +176,7 @@ export async function pMap<IN, OUT>(
     for (let i = 0; i < concurrency; i++) {
       next()
 
-      if (isIterableDone) {
+      if (isSettled) {
         break
       }
     }