@naturalcycles/js-lib 14.84.2 → 14.87.0

package/src/decorators/memo.decorator.ts

@@ -1,9 +1,3 @@
-// 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'
@@ -12,51 +6,45 @@ import { jsonMemoSerializer, MapMemoCache, MemoCache } from './memo.util'
 
 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
 }
 
 /**
@@ -68,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 =
@@ -91,96 +88,70 @@ 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
-
       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 = () => {

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

package/src/decorators/memoFn.ts

@@ -7,6 +7,11 @@ export interface MemoizedFunction {
   cache: MemoCache
 }
 
+/**
+ * Only supports Sync functions.
+ * To support Async functions - use _memoFnAsync.
+ * Technically, you can use it with Async functions, but it'll return the Promise without awaiting it.
+ */
 export function _memoFn<T extends (...args: any[]) => any>(
   fn: T,
   opt: MemoOptions = {},
@@ -14,86 +19,63 @@ export function _memoFn<T extends (...args: any[]) => any>(
   const {
     logHit = false,
     logMiss = false,
-    noLogArgs = false,
+    logArgs = true,
     logger = console,
-    noCacheRejected = false,
-    noCacheResolved = false,
+    cacheErrors = true,
     cacheFactory = () => new MapMemoCache(),
     cacheKeyFn = jsonMemoSerializer,
   } = opt
 
   const cache = cacheFactory()
-  const awaitPromise = Boolean(noCacheRejected || noCacheResolved)
   const fnName = fn.name
 
   const memoizedFn = function (this: any, ...args: any[]): T {
     const ctx = this
     const cacheKey = cacheKeyFn(args)
+    let value: any
 
     if (cache.has(cacheKey)) {
       if (logHit) {
-        logger.log(`${fnName}(${_getArgsSignature(args, noLogArgs)}) memoFn hit`)
+        logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFn hit`)
       }
 
-      const res = cache.get(cacheKey)
+      value = cache.get(cacheKey)
 
-      if (awaitPromise) {
-        return res instanceof Error ? (Promise.reject(res) as any) : Promise.resolve(res)
-      } else {
-        return res
+      if (value instanceof Error) {
+        throw value
       }
+
+      return value
     }
 
     const started = Date.now()
 
-    const res: any = fn.apply(ctx, args)
-
-    if (awaitPromise) {
-      return (res as Promise<any>)
-        .then(res => {
-          // console.log('RESOLVED', res)
-          if (logMiss) {
-            logger.log(
-              `${fnName}(${_getArgsSignature(args, noLogArgs)}) memoFn miss resolved (${_since(
-                started,
-              )})`,
-            )
-          }
-
-          if (!noCacheResolved) {
-            cache.set(cacheKey, res)
-          }
+    try {
+      value = fn.apply(ctx, args)
 
-          return res
-        })
-        .catch(err => {
-          // console.log('REJECTED', err)
-          if (logMiss) {
-            logger.log(
-              `${fnName}(${_getArgsSignature(args, noLogArgs)}) memoFn miss rejected (${_since(
-                started,
-              )})`,
-            )
-          }
+      try {
+        cache.set(cacheKey, value)
+      } catch (err) {
+        logger.error(err)
+      }
 
-          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.set(cacheKey, err instanceof Error ? err : new Error(err))
-          }
+      return value
+    } catch (err) {
+      if (cacheErrors) {
+        try {
+          cache.set(cacheKey, err)
+        } catch (err) {
+          logger.error(err)
+        }
+      }
 
-          throw err
-        }) as any
-    } else {
+      throw err
+    } finally {
       if (logMiss) {
         logger.log(
-          `${fnName}(${_getArgsSignature(args, noLogArgs)}) memoFn miss (${_since(started)})`,
+          `${fnName}(${_getArgsSignature(args, logArgs)}) memoFn miss (${_since(started)})`,
         )
       }
-
-      cache.set(cacheKey, res)
-      return res
     }
   }
 

package/src/decorators/memoFnAsync.ts

@@ -0,0 +1,91 @@
+import { _since } from '../time/time.util'
+import { AsyncMemoOptions } from './asyncMemo.decorator'
+import { _getArgsSignature } from './decorator.util'
+import { AsyncMemoCache, jsonMemoSerializer, MapMemoCache } from './memo.util'
+
+export interface MemoizedAsyncFunction {
+  cache: AsyncMemoCache
+}
+
+/**
+ * Only supports Sync functions.
+ * To support Async functions - use _memoFnAsync
+ */
+export function _memoFnAsync<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  opt: AsyncMemoOptions = {},
+): T & MemoizedAsyncFunction {
+  const {
+    logHit = false,
+    logMiss = false,
+    logArgs = true,
+    logger = console,
+    cacheRejections = true,
+    cacheFactory = () => new MapMemoCache(),
+    cacheKeyFn = jsonMemoSerializer,
+  } = opt
+
+  const cache = cacheFactory()
+  const fnName = fn.name
+
+  const memoizedFn = async function (this: any, ...args: any[]): Promise<any> {
+    const ctx = this
+    const cacheKey = cacheKeyFn(args)
+    let value: any
+
+    try {
+      value = await cache.get(cacheKey)
+    } catch (err) {
+      logger.error(err)
+    }
+
+    if (value !== undefined) {
+      if (logHit) {
+        logger.log(`${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync hit`)
+      }
+
+      if (value instanceof Error) {
+        throw value
+      }
+
+      return value
+    }
+
+    const started = Date.now()
+
+    try {
+      value = await fn.apply(ctx, args)
+
+      void (async () => {
+        try {
+          await cache.set(cacheKey, value)
+        } catch (err) {
+          logger.error(err)
+        }
+      })()
+
+      return value
+    } catch (err) {
+      if (cacheRejections) {
+        void (async () => {
+          try {
+            await cache.set(cacheKey, err)
+          } catch (err) {
+            logger.error(err)
+          }
+        })()
+      }
+
+      throw err
+    } finally {
+      if (logMiss) {
+        logger.log(
+          `${fnName}(${_getArgsSignature(args, logArgs)}) memoFnAsync miss (${_since(started)})`,
+        )
+      }
+    }
+  }
+
+  Object.assign(memoizedFn, { cache })
+  return memoizedFn as T & MemoizedAsyncFunction
+}

package/src/decorators/memoSimple.decorator.ts

@@ -18,7 +18,7 @@ import { jsonMemoSerializer, MapMemoCache, MemoCache } from './memo.util'
 export interface MemoOpts {
   logHit?: boolean
   logMiss?: boolean
-  noLogArgs?: boolean
+  logArgs?: boolean
   logger?: CommonLogger
 }
 
@@ -57,7 +57,7 @@ export const memoSimple =
    */
     const cache: MemoCache = 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)
 
@@ -67,7 +67,7 @@ export const memoSimple =
 
       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)
       }
@@ -78,7 +78,7 @@ export const memoSimple =
 
       if (logMiss) {
         logger.log(
-          `${methodSignature}(${_getArgsSignature(args, noLogArgs)}) @memo miss (${
+          `${methodSignature}(${_getArgsSignature(args, logArgs)}) @memo miss (${
             Date.now() - d
           } ms)`,
         )

package/src/index.ts

@@ -15,6 +15,7 @@ export * from './decorators/memo.decorator'
 export * from './decorators/asyncMemo.decorator'
 import { MemoCache, AsyncMemoCache } from './decorators/memo.util'
 export * from './decorators/memoFn'
+export * from './decorators/memoFnAsync'
 export * from './decorators/retry.decorator'
 export * from './decorators/timeout.decorator'
 export * from './error/app.error'
@@ -118,6 +119,7 @@ import {
   SavedDBEntity,
   StringMap,
   UnixTimestamp,
+  Integer,
   ValueOf,
   ValuesOf,
   AbortableMapper,
@@ -203,6 +205,7 @@ export type {
   ConditionalExcept,
   Class,
   UnixTimestamp,
+  Integer,
   BaseDBEntity,
   SavedDBEntity,
   Saved,

package/src/types.ts

@@ -166,6 +166,11 @@ export type IsoDateTime = string
  */
 export type UnixTimestamp = number
 
+/**
+ * Same as `number`, but with semantic meaning that it's an Integer.
+ */
+export type Integer = number
+
 /**
  * Base interface for any Entity that was saved to DB.
  */