@naturalcycles/js-lib 15.93.3 → 15.94.0

package/dist/decorators/createPromiseDecorator.d.ts

@@ -19,10 +19,11 @@ export interface PromiseDecoratorCfg<RES = any, PARAMS = any> {
      * which will most likely be "unhandledRejection" (unless there's another higher-level @Decorator that will catch it).
      * If `catchFn` is present - it's responsible for handling or re-throwing the error.
      * Whatever `catchFn` returns - passed to the original output.
+     * If Promise is returned - it will be awaited.
      */
     catchFn?: (r: PromiseDecoratorResp<PARAMS> & {
         err: any;
-    }) => RES;
+    }) => RES | Promise<RES>;
     /**
      * Fires AFTER thenFn / catchFn, like a usual Promise.finally().
      * Doesn't have access to neither res nor err (same as Promise.finally).

package/dist/decorators/createPromiseDecorator.js

@@ -63,17 +63,18 @@ export function _createPromiseDecorator(cfg, decoratorParams = {}) {
                     decoratorName,
                     started,
                 };
-                let handled = false;
-                if (cfg.catchFn) {
-                    cfg.catchFn({
+                if (!cfg.catchFn) {
+                    cfg.finallyFn?.(resp);
+                    throw err; // rethrow
+                }
+                try {
+                    return await cfg.catchFn({
                         ...resp,
                         err,
                     });
-                    handled = true;
                 }
-                cfg.finallyFn?.(resp);
-                if (!handled) {
-                    throw err; // rethrow
+                finally {
+                    cfg.finallyFn?.(resp);
                 }
             }
         };

package/dist/intl/intl.d.ts

@@ -12,6 +12,19 @@ import type { IANATimezone } from '../types.js';
  * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 declare class MemoizedIntl {
+    /**
+     * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+     * Intl2.Intl.*
+     *
+     * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+     * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+     *
+     * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+     * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+     * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+     * Use `new Intl2.Intl.Locale(tag)` instead.
+     */
+    readonly Intl: typeof Intl;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

package/dist/intl/intl.js

@@ -14,6 +14,19 @@ import { _Memo } from '../decorators/memo.decorator.js';
  * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 class MemoizedIntl {
+    /**
+     * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+     * Intl2.Intl.*
+     *
+     * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+     * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+     *
+     * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+     * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+     * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+     * Use `new Intl2.Intl.Locale(tag)` instead.
+     */
+    Intl = Intl;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

package/dist/object/keySortedMap.d.ts

@@ -78,7 +78,7 @@ export declare class KeySortedMap<K, V> {
      */
     toMap(): Map<K, V>;
     /**
-     * lowerBound: first index i s.t. keys[i] >= target
+     * lowerBound: first index i s.t. keys[i] >= target, in comparator order
      */
     private lowerBound;
     private sortKeys;

package/dist/object/keySortedMap.js

@@ -32,12 +32,17 @@ export class KeySortedMap {
      * Allows to set multiple key-value pairs at once.
      */
     setMany(obj) {
+        let hasNewKeys = false;
         for (const [k, v] of Object.entries(obj)) {
+            if (!this.map.has(k)) {
+                this.#sortedKeys.push(k);
+                hasNewKeys = true;
+            }
             this.map.set(k, v);
-            this.#sortedKeys.push(k);
         }
         // Resort all at once
-        this.sortKeys();
+        if (hasNewKeys)
+            this.sortKeys();
         return this;
     }
     /**
@@ -101,8 +106,7 @@ export class KeySortedMap {
         return this.entries();
     }
     toString() {
-        console.log('toString called !!!!!!!!!!!!!!!!!!!!!');
-        return 'abc';
+        return `KeySortedMap(${this.size}) ${JSON.stringify(this.toObject())}`;
     }
     [Symbol.toStringTag] = 'KeySortedMap';
     /**
@@ -179,15 +183,17 @@ export class KeySortedMap {
         return new Map(this.entries());
     }
     /**
-     * lowerBound: first index i s.t. keys[i] >= target
+     * lowerBound: first index i s.t. keys[i] >= target, in comparator order
      */
     lowerBound(target) {
+        const comparator = this.#comparator;
         let lo = 0;
         let hi = this.#sortedKeys.length;
         while (lo < hi) {
             // oxlint-disable-next-line no-bitwise
             const mid = (lo + hi) >>> 1;
-            if (this.#sortedKeys[mid] < target) {
+            const key = this.#sortedKeys[mid];
+            if (comparator ? comparator(key, target) < 0 : key < target) {
                 lo = mid + 1;
             }
             else {

package/dist/object/lazyKeySortedMap.d.ts

@@ -50,7 +50,7 @@ export declare class LazyKeySortedMap<K, V> {
     values(): MapIterator<V>;
     entries(): MapIterator<[K, V]>;
     [Symbol.iterator](): MapIterator<[K, V]>;
-    readonly [Symbol.toStringTag] = "KeySortedMap";
+    readonly [Symbol.toStringTag] = "LazyKeySortedMap";
     /**
      * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
      */

package/dist/object/lazyKeySortedMap.js

@@ -34,10 +34,12 @@ export class LazyKeySortedMap {
      */
     setMany(obj) {
         for (const [k, v] of Object.entries(obj)) {
+            if (!this.map.has(k)) {
+                this.maybeSortedKeys.push(k);
+                this.keysAreSorted = false;
+            }
             this.map.set(k, v);
-            this.maybeSortedKeys.push(k);
         }
-        this.keysAreSorted = false;
         return this;
     }
     /**
@@ -86,7 +88,7 @@ export class LazyKeySortedMap {
     [Symbol.iterator]() {
         return this.entries();
     }
-    [Symbol.toStringTag] = 'KeySortedMap';
+    [Symbol.toStringTag] = 'LazyKeySortedMap';
     /**
      * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
      */
@@ -110,9 +112,9 @@ export class LazyKeySortedMap {
         return keys[keys.length - 1];
     }
     lastKey() {
-        const k = this.lastKeyOrUndefined();
-        _assert(k, 'Map.lastKey called on empty map');
-        return k;
+        _assert(this.maybeSortedKeys.length, 'Map.lastKey called on empty map');
+        const keys = this.getSortedKeys();
+        return keys[keys.length - 1];
     }
     firstValueOrUndefined() {
         if (!this.maybeSortedKeys.length)
@@ -120,9 +122,8 @@ export class LazyKeySortedMap {
         return this.map.get(this.getSortedKeys()[0]);
     }
     firstValue() {
-        const v = this.firstValueOrUndefined();
-        _assert(v, 'Map.firstValue called on empty map');
-        return v;
+        _assert(this.maybeSortedKeys.length, 'Map.firstValue called on empty map');
+        return this.map.get(this.getSortedKeys()[0]);
     }
     lastValueOrUndefined() {
         if (!this.maybeSortedKeys.length)
@@ -131,9 +132,9 @@ export class LazyKeySortedMap {
         return this.map.get(keys[keys.length - 1]);
     }
     lastValue() {
-        const v = this.lastValueOrUndefined();
-        _assert(v, 'Map.lastValue called on empty map');
-        return v;
+        _assert(this.maybeSortedKeys.length, 'Map.lastValue called on empty map');
+        const keys = this.getSortedKeys();
+        return this.map.get(keys[keys.length - 1]);
     }
     firstEntryOrUndefined() {
         if (!this.maybeSortedKeys.length)
@@ -154,7 +155,7 @@ export class LazyKeySortedMap {
         return [k, this.map.get(k)];
     }
     lastEntry() {
-        const e = this.firstEntryOrUndefined();
+        const e = this.lastEntryOrUndefined();
         _assert(e, 'Map.lastEntry called on empty map');
         return e;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.93.3",
+  "version": "15.94.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -14,7 +14,7 @@
     }
   },
   "devDependencies": {
-    "@naturalcycles/dev-lib": "0.0.0",
+    "@naturalcycles/dev-lib": "20.66.0",
     "@types/node": "^26",
     "@types/semver": "^7",
     "typescript": "^7",
@@ -63,7 +63,7 @@
   "types": "dist/index.d.ts",
   "sideEffects": false,
   "engines": {
-    "node": ">=24.11.0"
+    "node": ">=26.12.1"
   },
   "publishConfig": {
     "provenance": true,

package/src/decorators/createPromiseDecorator.ts

@@ -22,8 +22,9 @@ export interface PromiseDecoratorCfg<RES = any, PARAMS = any> {
    * which will most likely be "unhandledRejection" (unless there's another higher-level @Decorator that will catch it).
    * If `catchFn` is present - it's responsible for handling or re-throwing the error.
    * Whatever `catchFn` returns - passed to the original output.
+   * If Promise is returned - it will be awaited.
    */
-  catchFn?: (r: PromiseDecoratorResp<PARAMS> & { err: any }) => RES
+  catchFn?: (r: PromiseDecoratorResp<PARAMS> & { err: any }) => RES | Promise<RES>
 
   /**
    * Fires AFTER thenFn / catchFn, like a usual Promise.finally().
@@ -122,20 +123,18 @@ export function _createPromiseDecorator<RES = any, PARAMS = any>(
           started,
         }
 
-        let handled = false
+        if (!cfg.catchFn) {
+          cfg.finallyFn?.(resp)
+          throw err // rethrow
+        }
 
-        if (cfg.catchFn) {
-          cfg.catchFn({
+        try {
+          return await cfg.catchFn({
             ...resp,
             err,
           })
-          handled = true
-        }
-
-        cfg.finallyFn?.(resp)
-
-        if (!handled) {
-          throw err // rethrow
+        } finally {
+          cfg.finallyFn?.(resp)
         }
       }
     }

package/src/intl/intl.ts

@@ -16,6 +16,20 @@ import type { AnyObject, IANATimezone } from '../types.js'
  * Don't pass unbounded dynamic values (e.g arbitrary user input) as locales or options.
  */
 class MemoizedIntl {
+  /**
+   * Escape hatch: for when you want to use native Intl, but linter screams at you - then you can use
+   * Intl2.Intl.*
+   *
+   * Prefer the memoized methods of Intl2 for creating formatters; use this for static functions
+   * (e.g `getCanonicalLocales`), `instanceof` checks, and cheap objects like Locale.
+   *
+   * Intl.Locale is not wrapped consciously: it was benchmarked and does NOT benefit from memoization.
+   * It's cheap to create (~1.3µs raw vs ~0.2µs cache hit, so ~1µs saved), while its tag often comes
+   * from runtime data (e.g request language), which would grow the never-evicted cache unboundedly.
+   * Use `new Intl2.Intl.Locale(tag)` instead.
+   */
+  readonly Intl = Intl
+
   /**
    * Returns the IANA timezone e.g `Europe/Stockholm`.
    * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

package/src/object/keySortedMap.ts

@@ -66,12 +66,16 @@ export class KeySortedMap<K, V> {
    * Allows to set multiple key-value pairs at once.
    */
   setMany(obj: Record<any, V>): this {
+    let hasNewKeys = false
     for (const [k, v] of Object.entries(obj)) {
+      if (!this.map.has(k as K)) {
+        this.#sortedKeys.push(k as K)
+        hasNewKeys = true
+      }
       this.map.set(k as K, v)
-      this.#sortedKeys.push(k as K)
     }
     // Resort all at once
-    this.sortKeys()
+    if (hasNewKeys) this.sortKeys()
     return this
   }
 
@@ -139,8 +143,7 @@ export class KeySortedMap<K, V> {
   }
 
   toString(): string {
-    console.log('toString called !!!!!!!!!!!!!!!!!!!!!')
-    return 'abc'
+    return `KeySortedMap(${this.size}) ${JSON.stringify(this.toObject())}`
   }
 
   readonly [Symbol.toStringTag] = 'KeySortedMap'
@@ -233,15 +236,17 @@ export class KeySortedMap<K, V> {
   }
 
   /**
-   * lowerBound: first index i s.t. keys[i] >= target
+   * lowerBound: first index i s.t. keys[i] >= target, in comparator order
    */
   private lowerBound(target: K): number {
+    const comparator = this.#comparator
     let lo = 0
     let hi = this.#sortedKeys.length
     while (lo < hi) {
       // oxlint-disable-next-line no-bitwise
       const mid = (lo + hi) >>> 1
-      if (this.#sortedKeys[mid]! < target) {
+      const key = this.#sortedKeys[mid]!
+      if (comparator ? comparator(key, target) < 0 : key < target) {
         lo = mid + 1
       } else {
         hi = mid

package/src/object/lazyKeySortedMap.ts

@@ -63,10 +63,12 @@ export class LazyKeySortedMap<K, V> {
    */
   setMany(obj: Record<any, V>): this {
     for (const [k, v] of Object.entries(obj)) {
+      if (!this.map.has(k as K)) {
+        this.maybeSortedKeys.push(k as K)
+        this.keysAreSorted = false
+      }
       this.map.set(k as K, v)
-      this.maybeSortedKeys.push(k as K)
     }
-    this.keysAreSorted = false
     return this
   }
 
@@ -120,7 +122,7 @@ export class LazyKeySortedMap<K, V> {
     return this.entries()
   }
 
-  readonly [Symbol.toStringTag] = 'KeySortedMap'
+  readonly [Symbol.toStringTag] = 'LazyKeySortedMap'
 
   /**
    * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
@@ -148,9 +150,9 @@ export class LazyKeySortedMap<K, V> {
   }
 
   lastKey(): K {
-    const k = this.lastKeyOrUndefined()
-    _assert(k, 'Map.lastKey called on empty map')
-    return k
+    _assert(this.maybeSortedKeys.length, 'Map.lastKey called on empty map')
+    const keys = this.getSortedKeys()
+    return keys[keys.length - 1]!
   }
 
   firstValueOrUndefined(): V | undefined {
@@ -159,9 +161,8 @@ export class LazyKeySortedMap<K, V> {
   }
 
   firstValue(): V {
-    const v = this.firstValueOrUndefined()
-    _assert(v, 'Map.firstValue called on empty map')
-    return v
+    _assert(this.maybeSortedKeys.length, 'Map.firstValue called on empty map')
+    return this.map.get(this.getSortedKeys()[0]!)!
   }
 
   lastValueOrUndefined(): V | undefined {
@@ -171,9 +172,9 @@ export class LazyKeySortedMap<K, V> {
   }
 
   lastValue(): V {
-    const v = this.lastValueOrUndefined()
-    _assert(v, 'Map.lastValue called on empty map')
-    return v
+    _assert(this.maybeSortedKeys.length, 'Map.lastValue called on empty map')
+    const keys = this.getSortedKeys()
+    return this.map.get(keys[keys.length - 1]!)!
   }
 
   firstEntryOrUndefined(): [K, V] | undefined {
@@ -196,7 +197,7 @@ export class LazyKeySortedMap<K, V> {
   }
 
   lastEntry(): [K, V] {
-    const e = this.firstEntryOrUndefined()
+    const e = this.lastEntryOrUndefined()
     _assert(e, 'Map.lastEntry called on empty map')
     return e
   }