@naturalcycles/js-lib 15.98.1 → 15.100.0

package/dist/array/array.util.js

@@ -369,8 +369,7 @@ export function _shuffle(array, opt = {}) {
     return a;
 }
 export function _firstLast(array) {
-    if (!array.length)
-        throw new Error('_firstLast called on empty array');
+    _assert(array.length, '_firstLast called on empty array');
     return [array[0], array[array.length - 1]];
 }
 export function _firstLastOrUndefined(array) {
@@ -383,8 +382,7 @@ export function _firstLastOrUndefined(array) {
  * Throws if array is empty.
  */
 export function _last(array) {
-    if (!array.length)
-        throw new Error('_last called on empty array');
+    _assert(array.length, '_last called on empty array');
     return array[array.length - 1];
 }
 /**
@@ -398,8 +396,7 @@ export function _lastOrUndefined(array) {
  * Throws if array is empty.
  */
 export function _first(array) {
-    if (!array.length)
-        throw new Error('_first called on empty array');
+    _assert(array.length, '_first called on empty array');
     return array[0];
 }
 /**
@@ -482,8 +479,7 @@ export function _minBy(array, mapper) {
     return min;
 }
 export function _minMax(array) {
-    if (!array.length)
-        throw new Error('_minMax called on empty array');
+    _assert(array.length, '_minMax called on empty array');
     const result = _minMaxOrUndefined(array);
     _assert(result !== undefined, '_minBy returned undefined');
     return result;
@@ -510,8 +506,7 @@ export function _minMaxOrUndefined(array) {
     return [min, max];
 }
 export function _minMaxBy(array, mapper) {
-    if (!array.length)
-        throw new Error('_minMaxBy called on empty array');
+    _assert(array.length, '_minMaxBy called on empty array');
     const result = _minMaxByOrUndefined(array, mapper);
     _assert(result !== undefined, '_minMaxBy returned undefined');
     return result;

package/dist/array/array2.js

@@ -1,3 +1,4 @@
+import { _assert } from '../error/assert.js';
 import { _shuffle } from './array.util.js';
 /**
  * Better Array.
@@ -16,8 +17,7 @@ export class Array2 extends Array {
         return this[0];
     }
     first() {
-        if (!this.length)
-            throw new Error('Array.first called on empty array');
+        _assert(this.length, 'Array.first called on empty array');
         return this[0];
     }
     lastOrUndefined() {
@@ -25,8 +25,7 @@ export class Array2 extends Array {
     }
     last() {
         const { length } = this;
-        if (!length)
-            throw new Error('Array.last called on empty array');
+        _assert(length, 'Array.last called on empty array');
         return this[length - 1];
     }
     uniq() {

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

@@ -31,10 +31,9 @@ export interface AsyncMemoInstance {
 /**
  * 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.
+ *   and survive a process restart. That's the reason to use it over `@_Memo`.
+ * - A rejection is NOT cached, so the next call retries the method (same as `@_Memo`).
  * - 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.

package/dist/decorators/asyncMemo.decorator.js

@@ -6,10 +6,9 @@ import { jsonMemoSerializer, MapAsyncMemoCache } from './memo.util.js';
 /**
  * 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.
+ *   and survive a process restart. That's the reason to use it over `@_Memo`.
+ * - A rejection is NOT cached, so the next call retries the method (same as `@_Memo`).
  * - 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.

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

@@ -35,9 +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.
+ * For an async method it's the returned **Promise** that is cached, so parallel calls with the same key
+ * share one in-flight Promise. A rejected Promise is evicted from the cache, so the next call retries
+ * the method, same as for a thrown Error.
+ * Use `@_AsyncMemo` for an async-backed cache (e.g Redis), which stores the resolved value instead.
  *
  * 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,9 +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.
+ * For an async method it's the returned **Promise** that is cached, so parallel calls with the same key
+ * share one in-flight Promise. A rejected Promise is evicted from the cache, so the next call retries
+ * the method, same as for a thrown Error.
+ * Use `@_AsyncMemo` for an async-backed cache (e.g Redis), which stores the resolved value instead.
  *
  * 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".
@@ -61,6 +62,20 @@ export const _Memo = (opt = {}) => (target, key, descriptor) => {
         catch (err) {
             logger.error({ err });
         }
+        if (value instanceof Promise) {
+            // Don't cache a rejection: evict it, so the next call retries the method.
+            // The derived Promise is handled, so it adds no unhandled rejection.
+            value.catch(() => {
+                try {
+                    // Only if the key still holds this very Promise (and not a newer one, cached after an eviction)
+                    if (cache.get(cacheKey) === value)
+                        cache.delete(cacheKey);
+                }
+                catch (err) {
+                    logger.error({ err });
+                }
+            });
+        }
         return value;
     };
     _objectAssign(descriptor.value, {

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

@@ -19,6 +19,7 @@ export interface MemoCache<KEY = any, VALUE = any> {
      */
     get: (k: KEY) => VALUE;
     set: (k: KEY, v: VALUE, opt?: MemoCacheOptions) => void;
+    delete: (k: KEY) => void;
     /**
      * Clear is only called when `_getMemoCache().clear()` is called.
      * Otherwise the Cache is "persistent" (never cleared).
@@ -33,6 +34,7 @@ export interface AsyncMemoCache<KEY = any, VALUE = any> {
      */
     get: (k: KEY) => Promise<VALUE | typeof MISS>;
     set: (k: KEY, v: VALUE, opt?: MemoCacheOptions) => Promise<void>;
+    delete: (k: KEY) => Promise<void>;
     /**
      * Clear is only called when `_getAsyncMemo().clear()` is called.
      * Otherwise the Cache is "persistent" (never cleared).
@@ -44,17 +46,18 @@ export declare class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<K
     has(k: KEY): boolean;
     get(k: KEY): VALUE;
     set(k: KEY, v: VALUE): void;
+    delete(k: KEY): void;
     clear(): void;
 }
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
  * 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.
+ * For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export declare class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
     private m;
     get(k: KEY): Promise<VALUE | typeof MISS>;
     set(k: KEY, v: VALUE): Promise<void>;
+    delete(k: KEY): Promise<void>;
     clear(): Promise<void>;
 }

package/dist/decorators/memo.util.js

@@ -63,6 +63,9 @@ export class MapMemoCache {
     set(k, v) {
         this.m.set(k, v);
     }
+    delete(k) {
+        this.m.delete(k);
+    }
     clear() {
         this.m.clear();
     }
@@ -70,8 +73,7 @@ export class MapMemoCache {
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
  * 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.
+ * For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export class MapAsyncMemoCache {
     m = new Map();
@@ -85,6 +87,9 @@ export class MapAsyncMemoCache {
     async set(k, v) {
         this.m.set(k, v);
     }
+    async delete(k) {
+        this.m.delete(k);
+    }
     async clear() {
         this.m.clear();
     }

package/dist/decorators/memoized.js

@@ -21,6 +21,20 @@ export function _memoized(fn, opt = {}) {
         catch (err) {
             logger.error({ err });
         }
+        if (value instanceof Promise) {
+            // Don't cache a rejection: evict it, so the next call retries the function.
+            // The derived Promise is handled, so it adds no unhandled rejection.
+            value.catch(() => {
+                try {
+                    // Only if the key still holds this very Promise (and not a newer one, cached after an eviction)
+                    if (cache.get(cacheKey) === value)
+                        cache.delete(cacheKey);
+                }
+                catch (err) {
+                    logger.error({ err });
+                }
+            });
+        }
         return value;
     };
     Object.assign(memoizedFn, { cache });

package/dist/error/assert.js

@@ -1,3 +1,5 @@
+// `_assert` and friends are implemented by throwing in an if
+// oxlint-disable nc/prefer-assert
 import { _deepEquals } from '../object/deepEquals.js';
 import { _stringify } from '../string/stringify.js';
 import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util.js';

package/dist/http/fetcher.js

@@ -4,7 +4,7 @@
 import { abortSignalAnyOrUndefined, abortSignalTimeoutOrUndefined } from '../abort.js';
 import { _ms, _since } from '../datetime/time.util.js';
 import { isServerSide } from '../env.js';
-import { _assertErrorClassOrRethrow, _assertIsError } from '../error/assert.js';
+import { _assert, _assertErrorClassOrRethrow, _assertIsError } from '../error/assert.js';
 import { _anyToError, _anyToErrorObject, _errorDataAppend, _errorLikeToErrorObject, HttpRequestError, UnexpectedPassError, } from '../error/error.util.js';
 import { consoleLogger } from '../log/commonLogger.js';
 import { _clamp } from '../number/number.util.js';
@@ -454,10 +454,8 @@ export class Fetcher {
         }
         else if (responseType === 'readableStream') {
             res.body = res.fetchResponse.body;
-            if (res.body === null) {
-                // Error is to be handled upstream
-                throw new Error('fetchResponse.body is null');
-            }
+            // Error is to be handled upstream
+            _assert(res.body !== null, 'fetchResponse.body is null');
         }
         res.retryStatus.retryStopped = true;
         if (req.logResponse) {

package/dist/object/set2.js

@@ -1,3 +1,4 @@
+import { _assert } from '../error/assert.js';
 /**
  * Like Set, but serializes to JSON as an array.
  *
@@ -20,8 +21,7 @@ export class Set2 extends Set {
         return this;
     }
     first() {
-        if (!this.size)
-            throw new Error('Set.first called on empty set');
+        _assert(this.size, 'Set.first called on empty set');
         return this.firstOrUndefined();
     }
     firstOrUndefined() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.98.1",
+  "version": "15.100.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -14,7 +14,7 @@
     }
   },
   "devDependencies": {
-    "@naturalcycles/dev-lib": "0.0.0",
+    "@naturalcycles/dev-lib": "20.70.0",
     "@types/node": "^26",
     "@types/semver": "^7",
     "typescript": "^7",

package/src/array/array.util.ts

@@ -435,7 +435,7 @@ export function _shuffle<T>(array: T[], opt: MutateOptions = {}): T[] {
 }
 
 export function _firstLast<T>(array: readonly T[]): [first: T, last: T] {
-  if (!array.length) throw new Error('_firstLast called on empty array')
+  _assert(array.length, '_firstLast called on empty array')
   return [array[0]!, array[array.length - 1]!]
 }
 
@@ -449,7 +449,7 @@ export function _firstLastOrUndefined<T>(array: readonly T[]): [first: T, last:
  * Throws if array is empty.
  */
 export function _last<T>(array: readonly T[]): T {
-  if (!array.length) throw new Error('_last called on empty array')
+  _assert(array.length, '_last called on empty array')
   return array[array.length - 1]!
 }
 
@@ -465,7 +465,7 @@ export function _lastOrUndefined<T>(array: readonly T[]): T | undefined {
  * Throws if array is empty.
  */
 export function _first<T>(array: readonly T[]): T {
-  if (!array.length) throw new Error('_first called on empty array')
+  _assert(array.length, '_first called on empty array')
   return array[0]!
 }
 
@@ -561,7 +561,7 @@ export function _minBy<T>(array: readonly T[], mapper: Mapper<T, number | string
 }
 
 export function _minMax<T>(array: readonly T[]): [min: NonNullable<T>, max: NonNullable<T>] {
-  if (!array.length) throw new Error('_minMax called on empty array')
+  _assert(array.length, '_minMax called on empty array')
   const result = _minMaxOrUndefined(array)
   _assert(result !== undefined, '_minBy returned undefined')
   return result
@@ -592,7 +592,7 @@ export function _minMaxBy<T>(
   array: readonly T[],
   mapper: Mapper<T, number | string | undefined>,
 ): [min: NonNullable<T>, max: NonNullable<T>] {
-  if (!array.length) throw new Error('_minMaxBy called on empty array')
+  _assert(array.length, '_minMaxBy called on empty array')
   const result = _minMaxByOrUndefined(array, mapper)
   _assert(result !== undefined, '_minMaxBy returned undefined')
   return result

package/src/array/array2.ts

@@ -1,3 +1,4 @@
+import { _assert } from '../error/assert.js'
 import { _shuffle } from './array.util.js'
 
 /**
@@ -20,7 +21,7 @@ export class Array2<T> extends Array<T> {
   }
 
   first(): T {
-    if (!this.length) throw new Error('Array.first called on empty array')
+    _assert(this.length, 'Array.first called on empty array')
     return this[0]!
   }
 
@@ -30,7 +31,7 @@ export class Array2<T> extends Array<T> {
 
   last(): T {
     const { length } = this
-    if (!length) throw new Error('Array.last called on empty array')
+    _assert(length, 'Array.last called on empty array')
     return this[length - 1]!
   }
 

package/src/decorators/asyncMemo.decorator.ts

@@ -43,10 +43,9 @@ export interface AsyncMemoInstance {
 /**
  * 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.
+ *   and survive a process restart. That's the reason to use it over `@_Memo`.
+ * - A rejection is NOT cached, so the next call retries the method (same as `@_Memo`).
  * - 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.

package/src/decorators/memo.decorator.ts

@@ -47,9 +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.
+ * For an async method it's the returned **Promise** that is cached, so parallel calls with the same key
+ * share one in-flight Promise. A rejected Promise is evicted from the cache, so the next call retries
+ * the method, same as for a thrown Error.
+ * Use `@_AsyncMemo` for an async-backed cache (e.g Redis), which stores the resolved value instead.
  *
  * 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".
@@ -115,6 +116,19 @@ export const _Memo =
         logger.error({ err })
       }
 
+      if (value instanceof Promise) {
+        // Don't cache a rejection: evict it, so the next call retries the method.
+        // The derived Promise is handled, so it adds no unhandled rejection.
+        value.catch(() => {
+          try {
+            // Only if the key still holds this very Promise (and not a newer one, cached after an eviction)
+            if (cache.get(cacheKey) === value) cache.delete(cacheKey)
+          } catch (err) {
+            logger.error({ err })
+          }
+        })
+      }
+
       return value
     } as any
 

package/src/decorators/memo.util.ts

@@ -28,7 +28,7 @@ export interface MemoCache<KEY = any, VALUE = any> {
    */
   get: (k: KEY) => VALUE
   set: (k: KEY, v: VALUE, opt?: MemoCacheOptions) => void
-
+  delete: (k: KEY) => void
   /**
    * Clear is only called when `_getMemoCache().clear()` is called.
    * Otherwise the Cache is "persistent" (never cleared).
@@ -46,6 +46,7 @@ export interface AsyncMemoCache<KEY = any, VALUE = any> {
    */
   get: (k: KEY) => Promise<VALUE | typeof MISS>
   set: (k: KEY, v: VALUE, opt?: MemoCacheOptions) => Promise<void>
+  delete: (k: KEY) => Promise<void>
 
   /**
    * Clear is only called when `_getAsyncMemo().clear()` is called.
@@ -115,6 +116,10 @@ export class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALU
     this.m.set(k, v)
   }
 
+  delete(k: KEY): void {
+    this.m.delete(k)
+  }
+
   clear(): void {
     this.m.clear()
   }
@@ -123,8 +128,7 @@ export class MapMemoCache<KEY = any, VALUE = any> implements MemoCache<KEY, VALU
 /**
  * Implementation of AsyncMemoCache backed by a synchronous Map.
  * 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.
+ * For an **async** backed cache (Redis, Datastore) use another implementation.
  */
 export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache<KEY, VALUE> {
   private m = new Map<KEY, VALUE>()
@@ -140,6 +144,10 @@ export class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncMemoCache
     this.m.set(k, v)
   }
 
+  async delete(k: KEY): Promise<void> {
+    this.m.delete(k)
+  }
+
   async clear(): Promise<void> {
     this.m.clear()
   }

package/src/decorators/memoized.ts

@@ -41,6 +41,19 @@ export function _memoized<FN extends AnyFunction>(
       logger.error({ err })
     }
 
+    if (value instanceof Promise) {
+      // Don't cache a rejection: evict it, so the next call retries the function.
+      // The derived Promise is handled, so it adds no unhandled rejection.
+      value.catch(() => {
+        try {
+          // Only if the key still holds this very Promise (and not a newer one, cached after an eviction)
+          if (cache.get(cacheKey) === value) cache.delete(cacheKey)
+        } catch (err) {
+          logger.error({ err })
+        }
+      })
+    }
+
     return value
   }
 

package/src/error/assert.ts

@@ -1,3 +1,5 @@
+// `_assert` and friends are implemented by throwing in an if
+// oxlint-disable nc/prefer-assert
 import { _deepEquals } from '../object/deepEquals.js'
 import { _stringify } from '../string/stringify.js'
 import type { Class, NonEmptyArray, UnixTimestamp } from '../types.js'

package/src/http/fetcher.ts

@@ -6,7 +6,7 @@ import type { ReadableStream as WebReadableStream } from 'node:stream/web'
 import { abortSignalAnyOrUndefined, abortSignalTimeoutOrUndefined } from '../abort.js'
 import { _ms, _since } from '../datetime/time.util.js'
 import { isServerSide } from '../env.js'
-import { _assertErrorClassOrRethrow, _assertIsError } from '../error/assert.js'
+import { _assert, _assertErrorClassOrRethrow, _assertIsError } from '../error/assert.js'
 import type { ErrorLike, ErrorObject } from '../error/error.model.js'
 import {
   _anyToError,
@@ -560,10 +560,8 @@ export class Fetcher {
     } else if (responseType === 'readableStream') {
       res.body = res.fetchResponse.body
 
-      if (res.body === null) {
-        // Error is to be handled upstream
-        throw new Error('fetchResponse.body is null')
-      }
+      // Error is to be handled upstream
+      _assert(res.body !== null, 'fetchResponse.body is null')
     }
 
     res.retryStatus.retryStopped = true

package/src/object/set2.ts

@@ -1,3 +1,5 @@
+import { _assert } from '../error/assert.js'
+
 /**
  * Like Set, but serializes to JSON as an array.
  *
@@ -22,7 +24,7 @@ export class Set2<T = any> extends Set<T> {
   }
 
   first(): T {
-    if (!this.size) throw new Error('Set.first called on empty set')
+    _assert(this.size, 'Set.first called on empty set')
     return this.firstOrUndefined()!
   }