@naturalcycles/js-lib 14.84.1 → 14.86.0

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

@@ -34,7 +34,7 @@ export const memoSimple = (opt = {}) => (target, key, descriptor) => {
   }
    */
     const cache = new MapMemoCache();
-    const { logHit, logMiss, noLogArgs, logger = console } = opt;
+    const { logHit, logMiss, logArgs = true, logger = console } = opt;
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     descriptor.value = function (...args) {
@@ -42,14 +42,14 @@ export const memoSimple = (opt = {}) => (target, key, descriptor) => {
         const cacheKey = jsonMemoSerializer(args);
         if (cache.has(cacheKey)) {
             if (logHit) {
-                logger.log(`${methodSignature}(${_getArgsSignature(args, noLogArgs)}) @memo hit`);
+                logger.log(`${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo hit`);
             }
             return cache.get(cacheKey);
         }
         const d = Date.now();
         const res = originalFn.apply(ctx, args);
         if (logMiss) {
-            logger.log(`${methodSignature}(${_getArgsSignature(args, noLogArgs)}) @memo miss (${Date.now() - d} ms)`);
+            logger.log(`${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo miss (${Date.now() - d} ms)`);
         }
         cache.set(cacheKey, res);
         return res;

package/dist-esm/index.js

@@ -10,6 +10,7 @@ export * from './decorators/logMethod.decorator';
 export * from './decorators/memo.decorator';
 export * from './decorators/asyncMemo.decorator';
 export * from './decorators/memoFn';
+export * from './decorators/memoFnAsync';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
 export * from './error/app.error';

package/package.json

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

package/src/decorators/asyncMemo.decorator.ts

@@ -1,25 +1,54 @@
+import { CommonLogger } from '../log/commonLogger'
 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[]
-  }
->
+import { AsyncMemoCache, jsonMemoSerializer, MapMemoCache } from './memo.util'
+
+export interface AsyncMemoOptions {
+  /**
+   * Provide a custom implementation of MemoCache.
+   * Function that creates an instance of `MemoCache`.
+   * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`.
+   */
+  cacheFactory?: () => AsyncMemoCache
+
+  /**
+   * Provide a custom implementation of CacheKey function.
+   */
+  cacheKeyFn?: (args: any[]) => any
+
+  /**
+   * Default true.
+   *
+   * Set to `false` to skip caching rejected promises (errors).
+   *
+   * True will ensure "max 1 execution", but will "remember" rejection.
+   * False will allow >1 execution in case of errors.
+   */
+  cacheRejections?: boolean
+
+  /**
+   * Default to false
+   */
+  logHit?: boolean
+
+  /**
+   * Default to false
+   */
+  logMiss?: boolean
+
+  /**
+   * Set to `false` to skip logging method arguments.
+   *
+   * Defaults to true.
+   */
+  logArgs?: boolean
+
+  /**
+   * Default to `console`
+   */
+  logger?: CommonLogger
+}
 
 /**
  * Like @_Memo, but allowing async MemoCache implementation.
@@ -29,7 +58,7 @@ export type AsyncMemoOptions = Merge<
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo =
-  (opt: AsyncMemoOptions): MethodDecorator =>
+  (opt: AsyncMemoOptions = {}): MethodDecorator =>
   (target, key, descriptor) => {
     if (typeof descriptor.value !== 'function') {
       throw new TypeError('Memoization can be applied only to methods')
@@ -38,17 +67,16 @@ export const _AsyncMemo =
     const originalFn = descriptor.value
 
     // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
-    const cache = new Map<AnyObject, AsyncMemoCache[]>()
+    const cache = new Map<AnyObject, AsyncMemoCache>()
 
     const {
       logHit = false,
       logMiss = false,
-      noLogArgs = false,
+      logArgs = true,
       logger = console,
-      cacheFactory,
+      cacheFactory = () => new MapMemoCache(),
       cacheKeyFn = jsonMemoSerializer,
-      noCacheRejected = false,
-      noCacheResolved = false,
+      cacheRejections = true,
     } = opt
 
     const keyStr = String(key)
@@ -65,29 +93,10 @@ export const _AsyncMemo =
         // 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
-          }
-        }
+        value = await cache.get(ctx)!.get(cacheKey)
       } catch (err) {
         // log error, but don't throw, treat it as a "miss"
         logger.error(err)
@@ -99,12 +108,16 @@ export const _AsyncMemo =
           logger.log(
             `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
               args,
-              noLogArgs,
+              logArgs,
             )}) @_AsyncMemo hit`,
           )
         }
 
-        return value instanceof Error ? Promise.reject(value) : Promise.resolve(value)
+        if (value instanceof Error) {
+          throw value
+        }
+
+        return value
       }
 
       // Here we know it's a MISS, let's execute the real method
@@ -113,25 +126,30 @@ export const _AsyncMemo =
       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)
-            },
-          )
-        }
+        // Save the value in the Cache, without awaiting it
+        // This is to support both sync and async functions
+        void (async () => {
+          try {
+            await cache.get(ctx)!.set(cacheKey, value)
+          } catch (err) {
+            // log and ignore the error
+            logger.error(err)
+          }
+        })()
 
         return value
       } catch (err) {
-        if (!noCacheRejected) {
+        if (cacheRejections) {
           // 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 => {
+          // This is to support both sync and async functions
+          void (async () => {
+            try {
+              await cache.get(ctx)!.set(cacheKey, err)
+            } catch (err) {
               // log and ignore the error
               logger.error(err)
-            },
-          )
+            }
+          })()
         }
 
         throw err
@@ -140,12 +158,21 @@ export const _AsyncMemo =
           logger.log(
             `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
               args,
-              noLogArgs,
+              logArgs,
             )}) @_AsyncMemo miss (${_since(started)})`,
           )
         }
       }
     } as any
+    ;(descriptor.value as any).dropCache = async () => {
+      logger.log(`${methodSignature} @_AsyncMemo.dropCache()`)
+      try {
+        await Promise.all([...cache.values()].map(c => c.clear()))
+        cache.clear()
+      } catch (err) {
+        logger.error(err)
+      }
+    }
 
     return descriptor
   }

package/src/decorators/decorator.util.ts

@@ -23,8 +23,8 @@ export function _getTargetMethodSignature(target: AnyObject, keyStr: string): st
  * returns:
  * a, b, c
  */
-export function _getArgsSignature(args: any[] = [], noLogArgs = false): string {
-  if (noLogArgs) return ''
+export function _getArgsSignature(args: any[] = [], logArgs = true): string {
+  if (!logArgs) return ''
 
   return args
     .map(arg => {

package/src/decorators/logMethod.decorator.ts

@@ -16,14 +16,16 @@ export interface LogMethodOptions {
   avg?: number
 
   /**
-   * Skip logging method arguments
+   * Defaults to true.
+   * Set to false to skip logging method arguments
    */
-  noLogArgs?: boolean
+  logArgs?: boolean
 
   /**
-   * Skip logging result length when result is an array.
+   * Defaults to true.
+   * Set to false to skip logging result length when result is an array.
    */
-  noLogResultLength?: boolean
+  logResultLength?: boolean
 
   /**
    * Also log on method start.
@@ -74,12 +76,19 @@ export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
     const originalFn = descriptor.value
     const keyStr = String(key)
 
-    const { avg, noLogArgs, logStart, logResult, noLogResultLength, logger = console } = opt
+    const {
+      avg,
+      logArgs = true,
+      logStart,
+      logResult,
+      logResultLength = true,
+      logger = console,
+    } = opt
     let { logResultFn } = opt
     if (!logResultFn) {
       if (logResult) {
         logResultFn = r => ['result:', _stringifyAny(r)]
-      } else if (!noLogResultLength) {
+      } else if (logResultLength) {
         logResultFn = r => (Array.isArray(r) ? [`result: ${r.length} items`] : [])
       }
     }
@@ -94,7 +103,7 @@ export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
       // e.g `NameOfYourClass.methodName`
       // or `NameOfYourClass(instanceId).methodName`
       const methodSignature = _getMethodSignature(ctx, keyStr)
-      const argsStr = _getArgsSignature(args, noLogArgs)
+      const argsStr = _getArgsSignature(args, logArgs)
       const callSignature = `${methodSignature}(${argsStr}) #${++count}`
       if (logStart) logger.log(`>> ${callSignature}`)
 

package/src/decorators/memo.decorator.ts

@@ -1,67 +1,50 @@
-// Based on:
-// https://github.com/mgechev/memo-decorator/blob/master/index.ts
-// http://decodize.com/blog/2012/08/27/javascript-memoization-caching-results-for-better-performance/
-// http://inlehmansterms.net/2015/03/01/javascript-memoization/
-// https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
-
 import { CommonLogger } from '../log/commonLogger'
 import { _since } from '../time/time.util'
 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
-   */
-  logHit?: boolean
-  /**
-   * Default to false
+   * Provide a custom implementation of MemoCache.
+   * Function that creates an instance of `MemoCache`.
+   * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`
    */
-  logMiss?: boolean
+  cacheFactory?: () => MemoCache
 
   /**
-   * Skip logging method arguments.
+   * Provide a custom implementation of CacheKey function.
    */
-  noLogArgs?: boolean
+  cacheKeyFn?: (args: any[]) => any
 
   /**
-   * Default to `console`
+   * Defaults to true.
+   * Set to false to skip caching errors.
+   *
+   * True will ensure "max 1 execution", but will "remember" errors.
+   * False will allow >1 execution in case of errors.
    */
-  logger?: CommonLogger
+  cacheErrors?: boolean
 
   /**
-   * Provide a custom implementation of MemoCache.
-   * Function that creates an instance of `MemoCache`.
-   * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`
+   * Default to false
    */
-  cacheFactory?: () => MemoCache
-
+  logHit?: boolean
   /**
-   * Provide a custom implementation of CacheKey function.
+   * Default to false
    */
-  cacheKeyFn?: (args: any[]) => any
+  logMiss?: boolean
 
   /**
-   * Don't cache resolved promises.
-   * Setting this to `true` will make the decorator to await the result.
-   *
-   * Default false.
+   * Defaults to true.
+   * Set to false to skip logging method arguments.
    */
-  noCacheResolved?: boolean
+  logArgs?: boolean
 
   /**
-   * Don't cache rejected promises.
-   * Setting this to `true` will make the decorator to await the result.
-   *
-   * Default false.
+   * Default to `console`
    */
-  noCacheRejected?: boolean
+  logger?: CommonLogger
 }
 
 /**
@@ -73,6 +56,15 @@ export interface MemoOptions {
  * If you don't want it that way - you can use a static method, then there will be only one "instance".
  *
  * Supports dropping it's cache by calling .dropCache() method of decorated function (useful in unit testing).
+ *
+ * Doesn't support Async functions, use @_AsyncMemo instead!
+ * (or, it will simply return the [unresolved] Promise further, without awaiting it)
+ *
+ * Based on:
+ * https://github.com/mgechev/memo-decorator/blob/master/index.ts
+ * http://decodize.com/blog/2012/08/27/javascript-memoization-caching-results-for-better-performance/
+ * http://inlehmansterms.net/2015/03/01/javascript-memoization/
+ * https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const _Memo =
@@ -96,105 +88,77 @@ export const _Memo =
     const {
       logHit = false,
       logMiss = false,
-      noLogArgs = false,
+      logArgs = true,
       logger = console,
       cacheFactory = () => new MapMemoCache(),
       cacheKeyFn = jsonMemoSerializer,
-      noCacheRejected = false,
-      noCacheResolved = false,
+      cacheErrors = true,
     } = opt
 
-    const awaitPromise = Boolean(noCacheRejected || noCacheResolved)
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)
 
     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)
+      let value: any
 
       if (!cache.has(ctx)) {
         cache.set(ctx, cacheFactory())
       } else if (cache.get(ctx)!.has(cacheKey)) {
         if (logHit) {
           logger.log(
-            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, noLogArgs)}) @_Memo hit`,
+            `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(args, logArgs)}) @_Memo hit`,
           )
         }
 
-        const res = cache.get(ctx)!.get(cacheKey)
+        value = cache.get(ctx)!.get(cacheKey)
 
-        if (awaitPromise) {
-          return res instanceof Error ? Promise.reject(res) : Promise.resolve(res)
-        } else {
-          return res
+        if (value instanceof Error) {
+          throw value
         }
+
+        return value
       }
 
       const started = Date.now()
 
-      const res: any = originalFn.apply(ctx, args)
-
-      if (awaitPromise) {
-        return (res as Promise<any>)
-          .then(res => {
-            // console.log('RESOLVED', res)
-            if (logMiss) {
-              logger.log(
-                `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
-                  args,
-                  noLogArgs,
-                )}) @_Memo miss resolved (${_since(started)})`,
-              )
-            }
-
-            if (!noCacheResolved) {
-              cache.get(ctx)!.set(cacheKey, res)
-            }
-
-            return res
-          })
-          .catch(err => {
-            // console.log('REJECTED', err)
-            if (logMiss) {
-              logger.log(
-                `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
-                  args,
-                  noLogArgs,
-                )}) @_Memo miss rejected (${_since(started)})`,
-              )
-            }
-
-            if (!noCacheRejected) {
-              // We put it to cache as raw Error, not Promise.reject(err)
-              // So, we'll need to check if it's instanceof Error to reject it or resolve
-              // Wrap as Error if it's not Error
-              cache.get(ctx)!.set(cacheKey, err instanceof Error ? err : new Error(err))
-            }
-
-            throw err
-          })
-      } else {
+      try {
+        value = originalFn.apply(ctx, args)
+
+        try {
+          cache.get(ctx)!.set(cacheKey, value)
+        } catch (err) {
+          logger.error(err)
+        }
+
+        return value
+      } catch (err) {
+        if (cacheErrors) {
+          try {
+            cache.get(ctx)!.set(cacheKey, err)
+          } catch (err) {
+            logger.error(err)
+          }
+        }
+
+        throw err
+      } finally {
         if (logMiss) {
           logger.log(
             `${_getMethodSignature(ctx, keyStr)}(${_getArgsSignature(
               args,
-              noLogArgs,
+              logArgs,
             )}) @_Memo miss (${_since(started)})`,
           )
         }
-
-        cache.get(ctx)!.set(cacheKey, res)
-        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

@@ -11,8 +11,8 @@ export const jsonMemoSerializer: MemoSerializer = args => {
 
 export interface MemoCache<KEY = any, VALUE = any> {
   has(k: KEY): boolean
-  get(k: KEY): VALUE | undefined
-  set(k: KEY, v: VALUE): void
+  get(k: KEY): VALUE | Error | undefined
+  set(k: KEY, v: VALUE | Error): void
 
   /**
    * Clear is only called when `.dropCache()` is called.
@@ -29,8 +29,8 @@ export interface AsyncMemoCache<KEY = any, VALUE = any> {
    * 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>
+  get(k: KEY): Promisable<VALUE | Error | undefined>
+  set(k: KEY, v: VALUE | Error): Promisable<void>
 
   /**
    * Clear is only called when `.dropCache()` is called.
@@ -88,17 +88,17 @@ export class ObjectMemoCache implements MemoCache {
 export class MapMemoCache<KEY = any, VALUE = any>
   implements MemoCache<KEY, VALUE>, AsyncMemoCache<KEY, VALUE>
 {
-  private m = new Map<KEY, VALUE>()
+  private m = new Map<KEY, VALUE | Error>()
 
   has(k: KEY): boolean {
     return this.m.has(k)
   }
 
-  get(k: KEY): VALUE | undefined {
+  get(k: KEY): VALUE | Error | undefined {
     return this.m.get(k)
   }
 
-  set(k: KEY, v: VALUE): void {
+  set(k: KEY, v: VALUE | Error): void {
     this.m.set(k, v)
   }