@naturalcycles/js-lib 15.45.0 → 15.46.0

package/dist/env.d.ts

@@ -12,3 +12,9 @@ export declare function isServerSide(): boolean;
  * Will return `false` in Node.js.
  */
 export declare function isClientSide(): boolean;
+/**
+ * Almost the same as isServerSide()
+ * (isServerSide should return true for Node),
+ * but detects Node specifically (not Deno, not Bun, etc).
+ */
+export declare function isNode(): boolean;

package/dist/env.js

@@ -17,3 +17,11 @@ export function isClientSide() {
     // oxlint-disable-next-line unicorn/prefer-global-this
     return typeof window !== 'undefined' && !!window?.document;
 }
+/**
+ * Almost the same as isServerSide()
+ * (isServerSide should return true for Node),
+ * but detects Node specifically (not Deno, not Bun, etc).
+ */
+export function isNode() {
+    return typeof process !== 'undefined' && process?.release?.name === 'node';
+}

package/dist/object/keySortedMap.d.ts

@@ -20,9 +20,8 @@ export interface KeySortedMapOptions<K> {
  * @experimental
  */
 export declare class KeySortedMap<K, V> implements Map<K, V> {
-    opt: KeySortedMapOptions<K>;
+    #private;
     private readonly map;
-    private readonly sortedKeys;
     constructor(entries?: [K, V][], opt?: KeySortedMapOptions<K>);
     /**
      * Convenience way to create KeySortedMap from object.
@@ -52,25 +51,30 @@ export declare class KeySortedMap<K, V> implements Map<K, V> {
     values(): MapIterator<V>;
     entries(): MapIterator<[K, V]>;
     [Symbol.iterator](): MapIterator<[K, V]>;
+    toString(): string;
     [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;
+    firstKeyOrUndefined(): K | undefined;
+    firstKey(): K;
+    lastKeyOrUndefined(): K | undefined;
+    lastKey(): K;
+    firstValueOrUndefined(): V | undefined;
+    firstValue(): V;
+    lastValueOrUndefined(): V | undefined;
+    lastValue(): V;
+    firstEntryOrUndefined(): [K, V] | undefined;
+    firstEntry(): [K, V];
+    lastEntryOrUndefined(): [K, V] | undefined;
+    lastEntry(): [K, V];
     toJSON(): Record<string, V>;
     toObject(): Record<string, V>;
+    /**
+     * Clones the KeySortedMap into ordinary Map.
+     */
+    toMap(): Map<K, V>;
     /**
      * lowerBound: first index i s.t. keys[i] >= target
      */

package/dist/object/keySortedMap.js

@@ -1,3 +1,4 @@
+import { _assert } from '../error/index.js';
 /**
  * Maintains sorted array of keys.
  * Sorts **on insertion**, not on retrieval.
@@ -10,15 +11,15 @@
  * @experimental
  */
 export class KeySortedMap {
-    opt;
     map;
-    sortedKeys;
+    #sortedKeys;
     constructor(entries = [], opt = {}) {
-        this.opt = opt;
+        this.#comparator = opt.comparator;
         this.map = new Map(entries);
-        this.sortedKeys = [...this.map.keys()];
+        this.#sortedKeys = [...this.map.keys()];
         this.sortKeys();
     }
+    #comparator;
     /**
      * Convenience way to create KeySortedMap from object.
      */
@@ -30,7 +31,7 @@ export class KeySortedMap {
     }
     clear() {
         this.map.clear();
-        this.sortedKeys.length = 0;
+        this.#sortedKeys.length = 0;
     }
     has(key) {
         return this.map.has(key);
@@ -44,7 +45,7 @@ export class KeySortedMap {
     setMany(obj) {
         for (const [k, v] of Object.entries(obj)) {
             this.map.set(k, v);
-            this.sortedKeys.push(k);
+            this.#sortedKeys.push(k);
         }
         // Resort all at once
         this.sortKeys();
@@ -63,7 +64,7 @@ export class KeySortedMap {
         // Find insertion index (lower_bound).
         const i = this.lowerBound(key);
         // Only insert into keys when actually new.
-        this.sortedKeys.splice(i, 0, key);
+        this.#sortedKeys.splice(i, 0, key);
         this.map.set(key, value);
         return this;
     }
@@ -77,15 +78,15 @@ export class KeySortedMap {
         // 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);
+        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);
+            const j = this.#sortedKeys.indexOf(key);
             if (j !== -1)
-                this.sortedKeys.splice(j, 1);
+                this.#sortedKeys.splice(j, 1);
         }
         return true;
     }
@@ -93,94 +94,111 @@ export class KeySortedMap {
      * Iterables (Map-compatible), all in sorted order.
      */
     *keys() {
-        for (let i = 0; i < this.sortedKeys.length; i++) {
-            yield this.sortedKeys[i];
+        for (const key of this.#sortedKeys) {
+            yield key;
         }
     }
     *values() {
-        for (let i = 0; i < this.sortedKeys.length; i++) {
-            yield this.map.get(this.sortedKeys[i]);
+        for (const key of this.#sortedKeys) {
+            yield this.map.get(key);
         }
     }
     *entries() {
-        for (let i = 0; i < this.sortedKeys.length; i++) {
-            const k = this.sortedKeys[i];
+        for (const k of this.#sortedKeys) {
             yield [k, this.map.get(k)];
         }
     }
     [Symbol.iterator]() {
         return this.entries();
     }
+    toString() {
+        console.log('toString called !!!!!!!!!!!!!!!!!!!!!');
+        return 'abc';
+    }
     [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);
+        const { map } = this;
+        for (const k of this.#sortedKeys) {
+            cb.call(thisArg, map.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;
+    firstKeyOrUndefined() {
+        return this.#sortedKeys[0];
     }
-    /** Fast helpers */
     firstKey() {
-        return this.sortedKeys[0];
+        _assert(this.#sortedKeys.length, 'Map.firstKey called on empty map');
+        return this.#sortedKeys[0];
+    }
+    lastKeyOrUndefined() {
+        return this.#sortedKeys.length ? this.#sortedKeys[this.#sortedKeys.length - 1] : undefined;
     }
     lastKey() {
-        return this.sortedKeys.length ? this.sortedKeys[this.sortedKeys.length - 1] : undefined;
+        _assert(this.#sortedKeys.length, 'Map.lastKey called on empty map');
+        return this.#sortedKeys[this.#sortedKeys.length - 1];
+    }
+    firstValueOrUndefined() {
+        return this.map.get(this.#sortedKeys[0]);
+    }
+    firstValue() {
+        _assert(this.#sortedKeys.length, 'Map.firstValue called on empty map');
+        return this.map.get(this.#sortedKeys[0]);
+    }
+    lastValueOrUndefined() {
+        return this.#sortedKeys.length
+            ? this.map.get(this.#sortedKeys[this.#sortedKeys.length - 1])
+            : undefined;
+    }
+    lastValue() {
+        _assert(this.#sortedKeys.length, 'Map.lastValue called on empty map');
+        return this.map.get(this.#sortedKeys[this.#sortedKeys.length - 1]);
+    }
+    firstEntryOrUndefined() {
+        if (!this.#sortedKeys.length)
+            return;
+        const k = this.#sortedKeys[0];
+        return [k, this.map.get(k)];
     }
     firstEntry() {
-        if (!this.sortedKeys.length)
+        _assert(this.#sortedKeys.length, 'Map.firstEntry called on empty map');
+        const k = this.#sortedKeys[0];
+        return [k, this.map.get(k)];
+    }
+    lastEntryOrUndefined() {
+        if (!this.#sortedKeys.length)
             return;
-        const k = this.sortedKeys[0];
+        const k = this.#sortedKeys[this.#sortedKeys.length - 1];
         return [k, this.map.get(k)];
     }
     lastEntry() {
-        if (!this.sortedKeys.length)
-            return;
-        const k = this.sortedKeys[this.sortedKeys.length - 1];
+        _assert(this.#sortedKeys.length, 'Map.lastEntry called on empty map');
+        const k = this.#sortedKeys[this.#sortedKeys.length - 1];
         return [k, this.map.get(k)];
     }
     toJSON() {
         return this.toObject();
     }
     toObject() {
-        return Object.fromEntries(this.map);
+        return Object.fromEntries(this.entries());
+    }
+    /**
+     * Clones the KeySortedMap into ordinary Map.
+     */
+    toMap() {
+        return new Map(this.entries());
     }
     /**
      * lowerBound: first index i s.t. keys[i] >= target
      */
     lowerBound(target) {
         let lo = 0;
-        let hi = this.sortedKeys.length;
+        let hi = this.#sortedKeys.length;
         while (lo < hi) {
             // oxlint-disable-next-line no-bitwise
             const mid = (lo + hi) >>> 1;
-            if (this.sortedKeys[mid] < target) {
+            if (this.#sortedKeys[mid] < target) {
                 lo = mid + 1;
             }
             else {
@@ -190,6 +208,6 @@ export class KeySortedMap {
         return lo;
     }
     sortKeys() {
-        this.sortedKeys.sort(this.opt.comparator);
+        this.#sortedKeys.sort(this.#comparator);
     }
 }

package/dist/object/keySortedMap2.d.ts

@@ -0,0 +1,72 @@
+import type { Comparator } from '../types.js';
+export interface KeySortedMapOptions<K> {
+    /**
+     * Defaults to undefined.
+     * Undefined (default comparator) works well for String keys.
+     * For Number keys - use comparators.numericAsc (or desc),
+     * otherwise sorting will be wrong (lexicographic).
+     */
+    comparator?: Comparator<K>;
+}
+/**
+ * Maintains sorted array of keys.
+ * Sorts **data access**, not on insertion.
+ *
+ * @experimental
+ */
+export declare class KeySortedMap2<K, V> implements Map<K, V> {
+    #private;
+    private readonly map;
+    private readonly maybeSortedKeys;
+    private keysAreSorted;
+    constructor(entries?: [K, V][], opt?: KeySortedMapOptions<K>);
+    /**
+     * Convenience way to create KeySortedMap from object.
+     */
+    static of<V>(obj: Record<any, V>): KeySortedMap2<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;
+    firstKeyOrUndefined(): K | undefined;
+    firstKey(): K;
+    lastKeyOrUndefined(): K | undefined;
+    lastKey(): K;
+    firstValueOrUndefined(): V | undefined;
+    firstValue(): V;
+    lastValueOrUndefined(): V | undefined;
+    lastValue(): V;
+    firstEntryOrUndefined(): [K, V] | undefined;
+    firstEntry(): [K, V];
+    lastEntryOrUndefined(): [K, V] | undefined;
+    lastEntry(): [K, V];
+    toJSON(): Record<string, V>;
+    toObject(): Record<string, V>;
+    private getSortedKeys;
+    private sortKeys;
+}

package/dist/object/keySortedMap2.js

@@ -0,0 +1,184 @@
+import { _assert } from '../error/index.js';
+/**
+ * Maintains sorted array of keys.
+ * Sorts **data access**, not on insertion.
+ *
+ * @experimental
+ */
+export class KeySortedMap2 {
+    map;
+    maybeSortedKeys;
+    keysAreSorted = false;
+    constructor(entries = [], opt = {}) {
+        this.#comparator = opt.comparator;
+        this.map = new Map(entries);
+        this.maybeSortedKeys = [...this.map.keys()];
+    }
+    #comparator;
+    /**
+     * Convenience way to create KeySortedMap from object.
+     */
+    static of(obj) {
+        return new KeySortedMap2(Object.entries(obj));
+    }
+    get size() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+        this.maybeSortedKeys.length = 0;
+        this.keysAreSorted = true;
+    }
+    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.maybeSortedKeys.push(k);
+        }
+        this.keysAreSorted = false;
+        return this;
+    }
+    /**
+     * Insert or update. Keeps keys array sorted at all times.
+     * Returns this (Map-like).
+     */
+    set(key, value) {
+        if (!this.map.has(key)) {
+            this.maybeSortedKeys.push(key);
+            this.keysAreSorted = false;
+        }
+        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);
+        // Delete operation keeps the array **as-is**, it may have been sorted or not.
+        const j = this.maybeSortedKeys.indexOf(key);
+        if (j !== -1)
+            this.maybeSortedKeys.splice(j, 1);
+        return true;
+    }
+    /**
+     * Iterables (Map-compatible), all in sorted order.
+     */
+    *keys() {
+        for (const key of this.getSortedKeys()) {
+            yield key;
+        }
+    }
+    *values() {
+        for (const key of this.getSortedKeys()) {
+            yield this.map.get(key);
+        }
+    }
+    *entries() {
+        for (const k of this.getSortedKeys()) {
+            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 { map } = this;
+        for (const k of this.getSortedKeys()) {
+            cb.call(thisArg, map.get(k), k, this);
+        }
+    }
+    firstKeyOrUndefined() {
+        return this.getSortedKeys()[0];
+    }
+    firstKey() {
+        _assert(this.maybeSortedKeys.length, 'Map.firstKey called on empty map');
+        return this.getSortedKeys()[0];
+    }
+    lastKeyOrUndefined() {
+        if (!this.maybeSortedKeys.length)
+            return;
+        const keys = this.getSortedKeys();
+        return keys[keys.length - 1];
+    }
+    lastKey() {
+        const k = this.lastKeyOrUndefined();
+        _assert(k, 'Map.lastKey called on empty map');
+        return k;
+    }
+    firstValueOrUndefined() {
+        if (!this.maybeSortedKeys.length)
+            return;
+        return this.map.get(this.getSortedKeys()[0]);
+    }
+    firstValue() {
+        const v = this.firstValueOrUndefined();
+        _assert(v, 'Map.firstValue called on empty map');
+        return v;
+    }
+    lastValueOrUndefined() {
+        if (!this.maybeSortedKeys.length)
+            return;
+        const keys = this.getSortedKeys();
+        return this.map.get(keys[keys.length - 1]);
+    }
+    lastValue() {
+        const v = this.lastValueOrUndefined();
+        _assert(v, 'Map.lastValue called on empty map');
+        return v;
+    }
+    firstEntryOrUndefined() {
+        if (!this.maybeSortedKeys.length)
+            return;
+        const k = this.getSortedKeys()[0];
+        return [k, this.map.get(k)];
+    }
+    firstEntry() {
+        const e = this.firstEntryOrUndefined();
+        _assert(e, 'Map.firstEntry called on empty map');
+        return e;
+    }
+    lastEntryOrUndefined() {
+        if (!this.maybeSortedKeys.length)
+            return;
+        const keys = this.getSortedKeys();
+        const k = keys[keys.length - 1];
+        return [k, this.map.get(k)];
+    }
+    lastEntry() {
+        const e = this.firstEntryOrUndefined();
+        _assert(e, 'Map.lastEntry called on empty map');
+        return e;
+    }
+    toJSON() {
+        return this.toObject();
+    }
+    toObject() {
+        return Object.fromEntries(this.entries());
+    }
+    getSortedKeys() {
+        if (!this.keysAreSorted) {
+            return this.sortKeys();
+        }
+        return this.maybeSortedKeys;
+    }
+    sortKeys() {
+        this.maybeSortedKeys.sort(this.#comparator);
+        this.keysAreSorted = true;
+        return this.maybeSortedKeys;
+    }
+}

package/dist/object/map2.d.ts

@@ -16,4 +16,5 @@ export declare class Map2<K = any, V = any> extends Map<K, V> {
     setMany(obj: Record<any, V>): this;
     toObject(): Record<string, V>;
     toJSON(): Record<string, V>;
+    toString(): string;
 }

package/dist/object/map2.js

@@ -27,4 +27,7 @@ export class Map2 extends Map {
     toJSON() {
         return Object.fromEntries(this);
     }
+    toString() {
+        return `Map2(${this.size}) ${JSON.stringify(Object.fromEntries(this))}`;
+    }
 }

package/dist/object/set2.d.ts

@@ -16,5 +16,5 @@ export declare class Set2<T = any> extends Set<T> {
     firstOrUndefined(): T | undefined;
     toArray(): T[];
     toJSON(): T[];
-    get [Symbol.toStringTag](): string;
+    toString(): string;
 }

package/dist/object/set2.js

@@ -35,7 +35,7 @@ export class Set2 extends Set {
     toJSON() {
         return [...this];
     }
-    get [Symbol.toStringTag]() {
-        return 'Set';
+    toString() {
+        return `Set2(${this.size}) ${JSON.stringify([...this])}`;
     }
 }