@naturalcycles/js-lib 15.98.0 → 15.98.1

package/dist/decorators/asyncMemo.decorator.d.ts

@@ -1,13 +1,16 @@
 import type { CommonLogger } from '../log/commonLogger.js';
-import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js';
+import type { AnyFunction, AnyObject, MaybeParameters } from '../types.js';
 import type { MethodDecorator } from './decorator.util.js';
 import type { AsyncMemoCache } from './memo.util.js';
 export interface AsyncMemoOptions<FN> {
     /**
      * Provide a custom implementation of AsyncMemoCache.
      * Function that creates an instance of `AsyncMemoCache`.
+     * Defaults to in-memory `MapAsyncMemoCache`, which never expires.
+     * e.g `LRUAsyncMemoCache` (ttl, max) from `@naturalcycles/nodejs-lib`,
+     * or `CommonKeyValueDaoMemoCache` (persisted in a DB) from `@naturalcycles/db-lib`.
      */
-    cacheFactory: () => AsyncMemoCache;
+    cacheFactory?: () => AsyncMemoCache;
     /**
      * Provide a custom implementation of CacheKey function.
      */
@@ -23,17 +26,23 @@ export interface AsyncMemoInstance {
      */
     clear: () => Promise<void>;
     getInstanceCache: () => Map<AnyObject, AsyncMemoCache>;
-    getCache: (instance: AnyAsyncFunction) => AsyncMemoCache | undefined;
+    getCache: (instance: AnyObject) => AsyncMemoCache | undefined;
 }
 /**
- * Like `@_Memo`, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but awaits the method and caches the resolved **value**, not the Promise:
+ *
+ * - A rejection is NOT cached, so the next call retries the method.
+ *   `@_Memo` caches the Promise as-is, so it serves a rejection to every caller until the key is evicted.
+ * - The cache is async (`AsyncMemoCache`), so it can be backed by e.g Redis or Datastore
+ *   and survive a process restart.
+ * - Parallel calls with the same key share one in-flight Promise, also while the cache lookup is pending.
+ *
+ * Cache errors (`get`/`set`) are logged and treated as a cache miss, they never fail the method.
  *
  * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
- *
- * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
-export declare const _AsyncMemo: <FN>(opt: AsyncMemoOptions<FN>) => MethodDecorator<FN>;
+export declare const _AsyncMemo: <FN>(opt?: AsyncMemoOptions<FN>) => MethodDecorator<FN>;
 /**
  Call it on a method that is decorated with `@_AsyncMemo` to get access to additional functions,
  e.g `clear` to clear the cache, or get its underlying data.

package/dist/decorators/asyncMemo.decorator.js

@@ -2,16 +2,22 @@ import { _assert, _assertTypeOf } from '../error/assert.js';
 import { consoleLogger } from '../log/commonLogger.js';
 import { _objectAssign, MISS } from '../types.js';
 import { _getTargetMethodSignature } from './decorator.util.js';
-import { jsonMemoSerializer } from './memo.util.js';
+import { jsonMemoSerializer, MapAsyncMemoCache } from './memo.util.js';
 /**
- * Like `@_Memo`, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but awaits the method and caches the resolved **value**, not the Promise:
+ *
+ * - A rejection is NOT cached, so the next call retries the method.
+ *   `@_Memo` caches the Promise as-is, so it serves a rejection to every caller until the key is evicted.
+ * - The cache is async (`AsyncMemoCache`), so it can be backed by e.g Redis or Datastore
+ *   and survive a process restart.
+ * - Parallel calls with the same key share one in-flight Promise, also while the cache lookup is pending.
+ *
+ * Cache errors (`get`/`set`) are logged and treated as a cache miss, they never fail the method.
  *
  * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
- *
- * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
-export const _AsyncMemo = (opt) => (target, key, descriptor) => {
+export const _AsyncMemo = (opt = {}) => (target, key, descriptor) => {
     _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
     const originalFn = descriptor.value;
     // Map from "instance" of the Class where @_AsyncMemo is applied to AsyncMemoCache instance.
@@ -21,7 +27,7 @@ export const _AsyncMemo = (opt) => (target, key, descriptor) => {
     // It only holds values that are "in-flight", until Promise is resolved
     // After it's resolved - it's evicted from the cache and moved to the "proper" `instanceCache`
     const instancePromiseCache = new Map();
-    const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt;
+    const { logger = consoleLogger, cacheFactory = () => new MapAsyncMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
     const keyStr = String(key);
     const methodSignature = _getTargetMethodSignature(target, keyStr);
     // oxlint-disable-next-line @typescript-eslint/promise-function-async

package/dist/decorators/memo.decorator.d.ts

@@ -24,7 +24,7 @@ export interface MemoInstance {
      */
     clear: () => void;
     getInstanceCache: () => Map<AnyObject, MemoCache>;
-    getCache: (instance: AnyFunction) => MemoCache | undefined;
+    getCache: (instance: AnyObject) => MemoCache | undefined;
 }
 /**
  * Memoizes the method of the class, so it caches the output and returns the cached version if the "key"
@@ -35,6 +35,10 @@ export interface MemoInstance {
  * So, error-throwing functions will be called multiple times.
  * Therefor, if the origin function can possibly throw - it should try to be idempotent.
  *
+ * For an async method it's the returned **Promise** that is cached, so a rejected Promise IS cached:
+ * every caller gets the same rejection until the key is evicted from the cache.
+ * Use `@_AsyncMemo` to cache only the resolved value and retry the method on rejection.
+ *
  * Cache is stored **per instance** - separate cache for separate instances of the class.
  * If you don't want it that way - you can use a static method, then there will be only one "instance".
  *

package/dist/decorators/memo.decorator.js

@@ -12,6 +12,10 @@ import { jsonMemoSerializer, MapMemoCache } from './memo.util.js';
  * So, error-throwing functions will be called multiple times.
  * Therefor, if the origin function can possibly throw - it should try to be idempotent.
  *
+ * For an async method it's the returned **Promise** that is cached, so a rejected Promise IS cached:
+ * every caller gets the same rejection until the key is evicted from the cache.
+ * Use `@_AsyncMemo` to cache only the resolved value and retry the method on rejection.
+ *
  * Cache is stored **per instance** - separate cache for separate instances of the class.
  * If you don't want it that way - you can use a static method, then there will be only one "instance".
  *

package/dist/decorators/memo.util.d.ts

@@ -48,12 +48,11 @@ export declare class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<K
 }
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
- * Doesn't have a practical use except testing,
- * because the point of AsyncMemoCache is to have an **async** backed cache.
+ * The default cache of `@_AsyncMemo`: in-memory, never expires.
+ * Use it over `@_Memo` when a rejection should not be cached (e.g an `init()` that may fail and
+ * should be retried). For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export declare class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
-    private delay;
-    constructor(delay?: number);
     private m;
     get(k: KEY): Promise<VALUE | typeof MISS>;
     set(k: KEY, v: VALUE): Promise<void>;

package/dist/decorators/memo.util.js

@@ -1,5 +1,4 @@
 import { _isPrimitive } from '../is.util.js';
-import { pDelay } from '../promise/pDelay.js';
 import { MISS } from '../types.js';
 export const jsonMemoSerializer = args => {
     if (args.length === 0)
@@ -70,27 +69,23 @@ export class MapMemoCache {
 }
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
- * Doesn't have a practical use except testing,
- * because the point of AsyncMemoCache is to have an **async** backed cache.
+ * The default cache of `@_AsyncMemo`: in-memory, never expires.
+ * Use it over `@_Memo` when a rejection should not be cached (e.g an `init()` that may fail and
+ * should be retried). For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export class MapAsyncMemoCache {
-    delay;
-    constructor(delay = 0) {
-        this.delay = delay;
-    }
     m = new Map();
     async get(k) {
-        await pDelay(this.delay);
-        if (!this.m.has(k))
+        const v = this.m.get(k);
+        // `undefined` is a valid VALUE, only then `has` tells it apart from a miss
+        if (v === undefined && !this.m.has(k))
             return MISS;
-        return this.m.get(k);
+        return v;
     }
     async set(k, v) {
-        await pDelay(this.delay);
         this.m.set(k, v);
     }
     async clear() {
-        await pDelay(this.delay);
         this.m.clear();
     }
 }

package/dist/decorators/memoizedAsync.d.ts

@@ -4,4 +4,10 @@ import type { AsyncMemoCache } from './memo.util.js';
 export interface MemoizedAsyncFunction {
     cache: AsyncMemoCache;
 }
-export declare function _memoizedAsync<FN extends AnyAsyncFunction>(fn: FN, opt: AsyncMemoOptions<FN>): FN & MemoizedAsyncFunction;
+/**
+ * Function version of `@_AsyncMemo`: awaits `fn` and caches the resolved value, not the Promise,
+ * so a rejection is not cached. Cache errors are logged and treated as a miss.
+ *
+ * Unlike the decorator, it does NOT dedupe parallel calls with the same key.
+ */
+export declare function _memoizedAsync<FN extends AnyAsyncFunction>(fn: FN, opt?: AsyncMemoOptions<FN>): FN & MemoizedAsyncFunction;

package/dist/decorators/memoizedAsync.js

@@ -1,13 +1,20 @@
 import { consoleLogger } from '../log/commonLogger.js';
 import { MISS } from '../types.js';
-import { jsonMemoSerializer } from './memo.util.js';
-export function _memoizedAsync(fn, opt) {
-    const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt;
+import { jsonMemoSerializer, MapAsyncMemoCache } from './memo.util.js';
+/**
+ * Function version of `@_AsyncMemo`: awaits `fn` and caches the resolved value, not the Promise,
+ * so a rejection is not cached. Cache errors are logged and treated as a miss.
+ *
+ * Unlike the decorator, it does NOT dedupe parallel calls with the same key.
+ */
+export function _memoizedAsync(fn, opt = {}) {
+    const { logger = consoleLogger, cacheFactory = () => new MapAsyncMemoCache(), cacheKeyFn = jsonMemoSerializer, } = opt;
     const cache = cacheFactory();
     const memoizedFn = async function (...args) {
         const ctx = this;
         const cacheKey = cacheKeyFn(args);
-        let value;
+        // MISS, so that a failed cache `get` is a miss too (and not a cached `undefined`)
+        let value = MISS;
         try {
             value = await cache.get(cacheKey);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.98.0",
+  "version": "15.98.1",
   "dependencies": {
     "tslib": "^2"
   },

package/src/decorators/asyncMemo.decorator.ts

@@ -1,19 +1,22 @@
 import { _assert, _assertTypeOf } from '../error/assert.js'
 import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
-import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js'
+import type { AnyFunction, AnyObject, MaybeParameters } from '../types.js'
 import { _objectAssign, MISS } from '../types.js'
 import type { MethodDecorator } from './decorator.util.js'
 import { _getTargetMethodSignature } from './decorator.util.js'
 import type { AsyncMemoCache } from './memo.util.js'
-import { jsonMemoSerializer } from './memo.util.js'
+import { jsonMemoSerializer, MapAsyncMemoCache } from './memo.util.js'
 
 export interface AsyncMemoOptions<FN> {
   /**
    * Provide a custom implementation of AsyncMemoCache.
    * Function that creates an instance of `AsyncMemoCache`.
+   * Defaults to in-memory `MapAsyncMemoCache`, which never expires.
+   * e.g `LRUAsyncMemoCache` (ttl, max) from `@naturalcycles/nodejs-lib`,
+   * or `CommonKeyValueDaoMemoCache` (persisted in a DB) from `@naturalcycles/db-lib`.
    */
-  cacheFactory: () => AsyncMemoCache
+  cacheFactory?: () => AsyncMemoCache
 
   /**
    * Provide a custom implementation of CacheKey function.
@@ -34,19 +37,25 @@ export interface AsyncMemoInstance {
 
   getInstanceCache: () => Map<AnyObject, AsyncMemoCache>
 
-  getCache: (instance: AnyAsyncFunction) => AsyncMemoCache | undefined
+  getCache: (instance: AnyObject) => AsyncMemoCache | undefined
 }
 
 /**
- * Like `@_Memo`, but allowing async MemoCache implementation.
+ * Like `@_Memo`, but awaits the method and caches the resolved **value**, not the Promise:
+ *
+ * - A rejection is NOT cached, so the next call retries the method.
+ *   `@_Memo` caches the Promise as-is, so it serves a rejection to every caller until the key is evicted.
+ * - The cache is async (`AsyncMemoCache`), so it can be backed by e.g Redis or Datastore
+ *   and survive a process restart.
+ * - Parallel calls with the same key share one in-flight Promise, also while the cache lookup is pending.
+ *
+ * Cache errors (`get`/`set`) are logged and treated as a cache miss, they never fail the method.
  *
  * Implementation is more complex than `@_Memo`, because it needs to handle "in-flight" Promises
  * while waiting for cache to resolve, to prevent "async swarm" issue.
- *
- * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
 export const _AsyncMemo =
-  <FN>(opt: AsyncMemoOptions<FN>): MethodDecorator<FN> =>
+  <FN>(opt: AsyncMemoOptions<FN> = {}): MethodDecorator<FN> =>
   (target, key, descriptor) => {
     _assertTypeOf<AnyFunction>(
       descriptor.value,
@@ -65,7 +74,11 @@ export const _AsyncMemo =
     // After it's resolved - it's evicted from the cache and moved to the "proper" `instanceCache`
     const instancePromiseCache = new Map<AnyObject, Map<any, Promise<any>>>()
 
-    const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
+    const {
+      logger = consoleLogger,
+      cacheFactory = () => new MapAsyncMemoCache(),
+      cacheKeyFn = jsonMemoSerializer,
+    } = opt
 
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)

package/src/decorators/memo.decorator.ts

@@ -35,7 +35,7 @@ export interface MemoInstance {
 
   getInstanceCache: () => Map<AnyObject, MemoCache>
 
-  getCache: (instance: AnyFunction) => MemoCache | undefined
+  getCache: (instance: AnyObject) => MemoCache | undefined
 }
 
 /**
@@ -47,6 +47,10 @@ export interface MemoInstance {
  * So, error-throwing functions will be called multiple times.
  * Therefor, if the origin function can possibly throw - it should try to be idempotent.
  *
+ * For an async method it's the returned **Promise** that is cached, so a rejected Promise IS cached:
+ * every caller gets the same rejection until the key is evicted from the cache.
+ * Use `@_AsyncMemo` to cache only the resolved value and retry the method on rejection.
+ *
  * Cache is stored **per instance** - separate cache for separate instances of the class.
  * If you don't want it that way - you can use a static method, then there will be only one "instance".
  *

package/src/decorators/memo.util.ts

@@ -1,5 +1,4 @@
 import { _isPrimitive } from '../is.util.js'
-import { pDelay } from '../promise/pDelay.js'
 import type { UnixTimestamp } from '../types.js'
 import { MISS } from '../types.js'
 
@@ -123,27 +122,25 @@ export class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALU
 
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
- * Doesn't have a practical use except testing,
- * because the point of AsyncMemoCache is to have an **async** backed cache.
+ * The default cache of `@_AsyncMemo`: in-memory, never expires.
+ * Use it over `@_Memo` when a rejection should not be cached (e.g an `init()` that may fail and
+ * should be retried). For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
-  constructor(private delay = 0) {}
-
   private m = new Map<KEY, VALUE>()
 
   async get(k: KEY): Promise<VALUE | typeof MISS> {
-    await pDelay(this.delay)
-    if (!this.m.has(k)) return MISS
-    return this.m.get(k)!
+    const v = this.m.get(k)
+    // `undefined` is a valid VALUE, only then `has` tells it apart from a miss
+    if (v === undefined && !this.m.has(k)) return MISS
+    return v!
   }
 
   async set(k: KEY, v: VALUE): Promise<void> {
-    await pDelay(this.delay)
     this.m.set(k, v)
   }
 
   async clear(): Promise<void> {
-    await pDelay(this.delay)
     this.m.clear()
   }
 }

package/src/decorators/memoizedAsync.ts

@@ -3,24 +3,35 @@ import type { AnyAsyncFunction, MaybeParameters } from '../types.js'
 import { MISS } from '../types.js'
 import type { AsyncMemoOptions } from './asyncMemo.decorator.js'
 import type { AsyncMemoCache } from './memo.util.js'
-import { jsonMemoSerializer } from './memo.util.js'
+import { jsonMemoSerializer, MapAsyncMemoCache } from './memo.util.js'
 
 export interface MemoizedAsyncFunction {
   cache: AsyncMemoCache
 }
 
+/**
+ * Function version of `@_AsyncMemo`: awaits `fn` and caches the resolved value, not the Promise,
+ * so a rejection is not cached. Cache errors are logged and treated as a miss.
+ *
+ * Unlike the decorator, it does NOT dedupe parallel calls with the same key.
+ */
 export function _memoizedAsync<FN extends AnyAsyncFunction>(
   fn: FN,
-  opt: AsyncMemoOptions<FN>,
+  opt: AsyncMemoOptions<FN> = {},
 ): FN & MemoizedAsyncFunction {
-  const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
+  const {
+    logger = consoleLogger,
+    cacheFactory = () => new MapAsyncMemoCache(),
+    cacheKeyFn = jsonMemoSerializer,
+  } = opt
 
   const cache = cacheFactory()
 
   const memoizedFn = async function (this: any, ...args: MaybeParameters<FN>): Promise<any> {
     const ctx = this
     const cacheKey = cacheKeyFn(args)
-    let value: any
+    // MISS, so that a failed cache `get` is a miss too (and not a cached `undefined`)
+    let value: any = MISS
 
     try {
       value = await cache.get(cacheKey)