@naturalcycles/js-lib 15.41.0 → 15.42.0

package/dist/array/range.js

@@ -20,7 +20,6 @@ export function _range(fromIncl, toExcl, step = 1) {
  * If it was an object - it'll paste the same object reference, which can create bugs.
  */
 export function _arrayFilled(length, fill) {
-    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
     return Array(length).fill(fill);
 }
 export function _rangeIterable(fromIncl, toExcl, step = 1) {

package/dist/object/index.d.ts

@@ -1,4 +1,5 @@
 export * from './deepEquals.js';
+export * from './keySortedMap.js';
 export * from './map2.js';
 export * from './object.util.js';
 export * from './set2.js';

package/dist/object/index.js

@@ -1,4 +1,5 @@
 export * from './deepEquals.js';
+export * from './keySortedMap.js';
 export * from './map2.js';
 export * from './object.util.js';
 export * from './set2.js';

package/dist/object/keySortedMap.d.ts

@@ -0,0 +1,77 @@
+export interface KeySortedMapOptions {
+    /**
+     * Defaults to false.
+     * Set to true if your keys are numeric,
+     * so it would sort correctly.
+     */
+    numericKeys?: boolean;
+}
+/**
+ * Maintains sorted array of keys.
+ * Sorts **on insertion**, not on retrieval.
+ *
+ * - set(): O(log n) search + O(n) splice only when inserting a NEW key
+ * - get/has: O(1)
+ * - delete: O(log n) search + O(n) splice if present
+ * - iteration: O(n) over pre-sorted keys (no sorting at iteration time)
+ *
+ * @experimental
+ */
+export declare class KeySortedMap<K, V> implements Map<K, V> {
+    opt: KeySortedMapOptions;
+    private readonly map;
+    private readonly sortedKeys;
+    constructor(entries?: [K, V][], opt?: KeySortedMapOptions);
+    /**
+     * Convenience way to create KeySortedMap from object.
+     */
+    static of<V>(obj: Record<any, V>): KeySortedMap<string, V>;
+    get size(): number;
+    clear(): void;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    /**
+     * Allows to set multiple key-value pairs at once.
+     */
+    setMany(obj: Record<any, V>): this;
+    /**
+     * Insert or update. Keeps keys array sorted at all times.
+     * Returns this (Map-like).
+     */
+    set(key: K, value: V): this;
+    /**
+     * Delete by key. Returns boolean like Map.delete.
+     */
+    delete(key: K): boolean;
+    /**
+     * Iterables (Map-compatible), all in sorted order.
+     */
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    entries(): MapIterator<[K, V]>;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+    [Symbol.toStringTag]: string;
+    /**
+     * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
+     */
+    forEach(cb: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    /**
+     * Convenience methods that MATERIALIZE arrays (if you really want arrays).
+     * These allocate; use iterators/forEach for maximum performance.
+     */
+    keysArray(): K[];
+    valuesArray(): V[];
+    entriesArray(): [K, V][];
+    /** Fast helpers */
+    firstKey(): K | undefined;
+    lastKey(): K | undefined;
+    firstEntry(): [K, V] | undefined;
+    lastEntry(): [K, V] | undefined;
+    toJSON(): Record<string, V>;
+    toObject(): Record<string, V>;
+    /**
+     * lowerBound: first index i s.t. keys[i] >= target
+     */
+    private lowerBound;
+    private sortKeys;
+}

package/dist/object/keySortedMap.js

@@ -0,0 +1,205 @@
+/**
+ * Maintains sorted array of keys.
+ * Sorts **on insertion**, not on retrieval.
+ *
+ * - set(): O(log n) search + O(n) splice only when inserting a NEW key
+ * - get/has: O(1)
+ * - delete: O(log n) search + O(n) splice if present
+ * - iteration: O(n) over pre-sorted keys (no sorting at iteration time)
+ *
+ * @experimental
+ */
+export class KeySortedMap {
+    opt;
+    map;
+    sortedKeys;
+    constructor(entries = [], opt = {}) {
+        this.opt = opt;
+        this.map = new Map(entries);
+        this.sortedKeys = [...this.map.keys()];
+        this.sortKeys();
+    }
+    /**
+     * Convenience way to create KeySortedMap from object.
+     */
+    static of(obj) {
+        return new KeySortedMap(Object.entries(obj));
+    }
+    get size() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+        this.sortedKeys.length = 0;
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    get(key) {
+        return this.map.get(key);
+    }
+    /**
+     * Allows to set multiple key-value pairs at once.
+     */
+    setMany(obj) {
+        for (const [k, v] of Object.entries(obj)) {
+            this.map.set(k, v);
+            this.sortedKeys.push(k);
+        }
+        // Resort all at once
+        this.sortKeys();
+        return this;
+    }
+    /**
+     * Insert or update. Keeps keys array sorted at all times.
+     * Returns this (Map-like).
+     */
+    set(key, value) {
+        if (this.map.has(key)) {
+            // Update only; position unchanged.
+            this.map.set(key, value);
+            return this;
+        }
+        // Find insertion index (lower_bound).
+        const i = this.lowerBound(key);
+        // Only insert into keys when actually new.
+        this.sortedKeys.splice(i, 0, key);
+        this.map.set(key, value);
+        return this;
+    }
+    /**
+     * Delete by key. Returns boolean like Map.delete.
+     */
+    delete(key) {
+        if (!this.map.has(key))
+            return false;
+        this.map.delete(key);
+        // Remove from keys using binary search to avoid O(n) find.
+        const i = this.lowerBound(key);
+        // Because key existed, it must be at i.
+        if (i < this.sortedKeys.length && this.sortedKeys[i] === key) {
+            this.sortedKeys.splice(i, 1);
+        }
+        else {
+            // Extremely unlikely if external mutation happened; safe guard.
+            // Fall back to linear search (shouldn't happen).
+            const j = this.sortedKeys.indexOf(key);
+            if (j !== -1)
+                this.sortedKeys.splice(j, 1);
+        }
+        return true;
+    }
+    /**
+     * Iterables (Map-compatible), all in sorted order.
+     */
+    *keys() {
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            yield this.sortedKeys[i];
+        }
+    }
+    *values() {
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            yield this.map.get(this.sortedKeys[i]);
+        }
+    }
+    *entries() {
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            const k = this.sortedKeys[i];
+            yield [k, this.map.get(k)];
+        }
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    [Symbol.toStringTag] = 'KeySortedMap';
+    /**
+     * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
+     */
+    forEach(cb, thisArg) {
+        const m = this.map;
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            const k = this.sortedKeys[i];
+            cb.call(thisArg, m.get(k), k, this);
+        }
+    }
+    /**
+     * Convenience methods that MATERIALIZE arrays (if you really want arrays).
+     * These allocate; use iterators/forEach for maximum performance.
+     */
+    keysArray() {
+        return this.sortedKeys.slice();
+    }
+    valuesArray() {
+        // oxlint-disable-next-line unicorn/no-new-array
+        const a = Array(this.sortedKeys.length);
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            a[i] = this.map.get(this.sortedKeys[i]);
+        }
+        return a;
+    }
+    entriesArray() {
+        // oxlint-disable-next-line unicorn/no-new-array
+        const out = Array(this.sortedKeys.length);
+        for (let i = 0; i < this.sortedKeys.length; i++) {
+            const k = this.sortedKeys[i];
+            out[i] = [k, this.map.get(k)];
+        }
+        return out;
+    }
+    /** Fast helpers */
+    firstKey() {
+        return this.sortedKeys[0];
+    }
+    lastKey() {
+        return this.sortedKeys.length ? this.sortedKeys[this.sortedKeys.length - 1] : undefined;
+    }
+    firstEntry() {
+        if (!this.sortedKeys.length)
+            return;
+        const k = this.sortedKeys[0];
+        return [k, this.map.get(k)];
+    }
+    lastEntry() {
+        if (!this.sortedKeys.length)
+            return;
+        const k = this.sortedKeys[this.sortedKeys.length - 1];
+        return [k, this.map.get(k)];
+    }
+    toJSON() {
+        return this.toObject();
+    }
+    toObject() {
+        return Object.fromEntries(this.map);
+    }
+    /**
+     * lowerBound: first index i s.t. keys[i] >= target
+     */
+    lowerBound(target) {
+        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) {
+                lo = mid + 1;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        return lo;
+    }
+    sortKeys() {
+        if (this.opt.numericKeys) {
+            ;
+            this.sortedKeys.sort(numericAscCompare);
+        }
+        else {
+            // Default sort - fastest for Strings
+            this.sortedKeys.sort();
+        }
+    }
+}
+function numericAscCompare(a, b) {
+    return a - b;
+}

package/dist/object/object.util.js

@@ -354,7 +354,6 @@ export function _get(obj = {}, path = '') {
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
 export function _set(obj, path, value) {
-    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
     if (!obj || Object(obj) !== obj || !path)
         return obj; // When obj is not an object
     // If not yet an array, get the keys from the string-path
@@ -366,9 +365,7 @@ export function _set(obj, path, value) {
     }
     // oxlint-disable-next-line unicorn/no-array-reduce
     ;
-    path.slice(0, -1).reduce((a, c, i) => 
-    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
-    Object(a[c]) === a[c] // Does the key exist and is its value an object?
+    path.slice(0, -1).reduce((a, c, i) => Object(a[c]) === a[c] // Does the key exist and is its value an object?
         ? // Yes: then follow that path
             a[c]
         : // No: create the key. Is the next key a potential array-index?

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.41.0",
+  "version": "15.42.0",
   "dependencies": {
     "tslib": "^2",
     "undici": "^7",
@@ -13,7 +13,7 @@
     "@types/semver": "^7",
     "crypto-js": "^4",
     "dayjs": "^1",
-    "@naturalcycles/dev-lib": "18.4.2"
+    "@naturalcycles/dev-lib": "20.4.2"
   },
   "exports": {
     ".": "./dist/index.js",

package/src/array/range.ts

@@ -36,7 +36,6 @@ export function _range(fromIncl: Integer, toExcl?: Integer, step = 1): number[]
  * If it was an object - it'll paste the same object reference, which can create bugs.
  */
 export function _arrayFilled<T extends Primitive>(length: Integer, fill: T): T[] {
-  // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
   return Array(length).fill(fill)
 }
 

package/src/object/index.ts

@@ -1,4 +1,5 @@
 export * from './deepEquals.js'
+export * from './keySortedMap.js'
 export * from './map2.js'
 export * from './object.util.js'
 export * from './set2.js'

package/src/object/keySortedMap.ts

@@ -0,0 +1,234 @@
+export interface KeySortedMapOptions {
+  /**
+   * Defaults to false.
+   * Set to true if your keys are numeric,
+   * so it would sort correctly.
+   */
+  numericKeys?: boolean
+}
+
+/**
+ * Maintains sorted array of keys.
+ * Sorts **on insertion**, not on retrieval.
+ *
+ * - set(): O(log n) search + O(n) splice only when inserting a NEW key
+ * - get/has: O(1)
+ * - delete: O(log n) search + O(n) splice if present
+ * - iteration: O(n) over pre-sorted keys (no sorting at iteration time)
+ *
+ * @experimental
+ */
+export class KeySortedMap<K, V> implements Map<K, V> {
+  private readonly map: Map<K, V>
+  private readonly sortedKeys: K[]
+
+  constructor(
+    entries: [K, V][] = [],
+    public opt: KeySortedMapOptions = {},
+  ) {
+    this.map = new Map(entries)
+    this.sortedKeys = [...this.map.keys()]
+    this.sortKeys()
+  }
+
+  /**
+   * Convenience way to create KeySortedMap from object.
+   */
+  static of<V>(obj: Record<any, V>): KeySortedMap<string, V> {
+    return new KeySortedMap(Object.entries(obj))
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  clear(): void {
+    this.map.clear()
+    this.sortedKeys.length = 0
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key)
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(key)
+  }
+
+  /**
+   * Allows to set multiple key-value pairs at once.
+   */
+  setMany(obj: Record<any, V>): this {
+    for (const [k, v] of Object.entries(obj)) {
+      this.map.set(k as K, v)
+      this.sortedKeys.push(k as K)
+    }
+    // Resort all at once
+    this.sortKeys()
+    return this
+  }
+
+  /**
+   * Insert or update. Keeps keys array sorted at all times.
+   * Returns this (Map-like).
+   */
+  set(key: K, value: V): this {
+    if (this.map.has(key)) {
+      // Update only; position unchanged.
+      this.map.set(key, value)
+      return this
+    }
+    // Find insertion index (lower_bound).
+    const i = this.lowerBound(key)
+    // Only insert into keys when actually new.
+    this.sortedKeys.splice(i, 0, key)
+    this.map.set(key, value)
+    return this
+  }
+
+  /**
+   * Delete by key. Returns boolean like Map.delete.
+   */
+  delete(key: K): boolean {
+    if (!this.map.has(key)) return false
+    this.map.delete(key)
+    // Remove from keys using binary search to avoid O(n) find.
+    const i = this.lowerBound(key)
+    // Because key existed, it must be at i.
+    if (i < this.sortedKeys.length && this.sortedKeys[i] === key) {
+      this.sortedKeys.splice(i, 1)
+    } else {
+      // Extremely unlikely if external mutation happened; safe guard.
+      // Fall back to linear search (shouldn't happen).
+      const j = this.sortedKeys.indexOf(key)
+      if (j !== -1) this.sortedKeys.splice(j, 1)
+    }
+    return true
+  }
+
+  /**
+   * Iterables (Map-compatible), all in sorted order.
+   */
+  *keys(): MapIterator<K> {
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      yield this.sortedKeys[i]!
+    }
+  }
+
+  *values(): MapIterator<V> {
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      yield this.map.get(this.sortedKeys[i]!)!
+    }
+  }
+
+  *entries(): MapIterator<[K, V]> {
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      const k = this.sortedKeys[i]!
+      yield [k, this.map.get(k)!]
+    }
+  }
+
+  [Symbol.iterator](): MapIterator<[K, V]> {
+    return this.entries()
+  }
+
+  [Symbol.toStringTag] = 'KeySortedMap'
+
+  /**
+   * Zero-allocation callbacks over sorted data (faster than spreading to arrays).
+   */
+  forEach(cb: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void {
+    const m = this.map
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      const k = this.sortedKeys[i]!
+      cb.call(thisArg, m.get(k)!, k, this)
+    }
+  }
+
+  /**
+   * Convenience methods that MATERIALIZE arrays (if you really want arrays).
+   * These allocate; use iterators/forEach for maximum performance.
+   */
+  keysArray(): K[] {
+    return this.sortedKeys.slice()
+  }
+
+  valuesArray(): V[] {
+    // oxlint-disable-next-line unicorn/no-new-array
+    const a = Array<V>(this.sortedKeys.length)
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      a[i] = this.map.get(this.sortedKeys[i]!)!
+    }
+    return a
+  }
+
+  entriesArray(): [K, V][] {
+    // oxlint-disable-next-line unicorn/no-new-array
+    const out = Array<[K, V]>(this.sortedKeys.length)
+    for (let i = 0; i < this.sortedKeys.length; i++) {
+      const k = this.sortedKeys[i]!
+      out[i] = [k, this.map.get(k)!]
+    }
+    return out
+  }
+
+  /** Fast helpers */
+  firstKey(): K | undefined {
+    return this.sortedKeys[0]
+  }
+
+  lastKey(): K | undefined {
+    return this.sortedKeys.length ? this.sortedKeys[this.sortedKeys.length - 1] : undefined
+  }
+
+  firstEntry(): [K, V] | undefined {
+    if (!this.sortedKeys.length) return
+    const k = this.sortedKeys[0]!
+    return [k, this.map.get(k)!]
+  }
+
+  lastEntry(): [K, V] | undefined {
+    if (!this.sortedKeys.length) return
+    const k = this.sortedKeys[this.sortedKeys.length - 1]!
+    return [k, this.map.get(k)!]
+  }
+
+  toJSON(): Record<string, V> {
+    return this.toObject()
+  }
+
+  toObject(): Record<string, V> {
+    return Object.fromEntries(this.map)
+  }
+
+  /**
+   * lowerBound: first index i s.t. keys[i] >= target
+   */
+  private lowerBound(target: K): number {
+    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) {
+        lo = mid + 1
+      } else {
+        hi = mid
+      }
+    }
+    return lo
+  }
+
+  private sortKeys(): void {
+    if (this.opt.numericKeys) {
+      ;(this.sortedKeys as number[]).sort(numericAscCompare)
+    } else {
+      // Default sort - fastest for Strings
+      this.sortedKeys.sort()
+    }
+  }
+}
+
+function numericAscCompare(a: number, b: number): number {
+  return a - b
+}

package/src/object/object.util.ts

@@ -421,7 +421,6 @@ type PropertyPath = Many<PropertyKey>
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
 export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any): T {
-  // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
   if (!obj || Object(obj) !== obj || !path) return obj as any // When obj is not an object
 
   // If not yet an array, get the keys from the string-path
@@ -438,7 +437,6 @@ export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any
       c,
       i, // Iterate all of them except the last one
     ) =>
-      // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
       Object(a[c]) === a[c] // Does the key exist and is its value an object?
         ? // Yes: then follow that path
           a[c]