@naturalcycles/js-lib 15.45.0 → 15.46.0

package/dist/string/stringify.js

@@ -57,58 +57,29 @@ export function _stringify(obj, opt = {}) {
         return _stringify(obj.error, opt);
     }
     if (obj instanceof Error || _isErrorLike(obj)) {
-        const { includeErrorCause = true } = opt;
-        //
-        // Error or ErrorLike
-        //
-        // Omit "default" error name as non-informative
-        // UPD: no, it's still important to understand that we're dealing with Error and not just some string
-        // if (obj?.name === 'Error') {
-        //   s = obj.message
-        // }
-        // if (_isErrorObject(obj) && _isHttpErrorObject(obj)) {
-        //   // Printing (0) to avoid ambiguity
-        //   s = `${obj.name}(${obj.data.backendResponseStatusCode}): ${obj.message}`
-        // }
-        s = [obj.name, obj.message].filter(Boolean).join(': ');
-        if (typeof obj.code === 'string') {
-            // Error that has no `data`, but has `code` property
-            s += `\ncode: ${obj.code}`;
-        }
-        if (opt.includeErrorData && _isErrorObject(obj) && Object.keys(obj.data).length) {
-            s += '\n' + _stringify(obj.data, opt);
-        }
-        if (opt.includeErrorStack && obj.stack) {
-            // Here we're using the previously-generated "title line" (e.g "Error: some_message"),
-            // concatenating it with the Stack (but without the title line of the Stack)
-            // This is to fix the rare error (happened with Got) where `err.message` was changed,
-            // but err.stack had "old" err.message
-            // This should "fix" that
-            const sLines = s.split('\n').length;
-            s = [s, ...obj.stack.split('\n').slice(sLines)].join('\n');
-        }
-        if (supportsAggregateError && obj instanceof AggregateError && obj.errors.length) {
-            s = [
-                s,
-                `${obj.errors.length} error(s):`,
-                ...obj.errors.map((err, i) => `${i + 1}. ${_stringify(err, opt)}`),
-            ].join('\n');
-        }
-        if (obj.cause && includeErrorCause) {
-            s = s + '\nCaused by: ' + _stringify(obj.cause, opt);
-        }
+        s = stringifyErrorLike(obj, opt);
     }
     else if (typeof obj === 'string') {
-        //
-        // String
-        //
         s = obj.trim() || 'empty_string';
+        // todo: think about it more
+        // Stringifying it like a JSON would.
+        // To highlight that it's a String (and not a Number) - using double-quotes, JSON-like.
+        // s = `"${obj}"`
+    }
+    else if (typeof obj === 'number') {
+        s = String(obj);
+        // todo: support RegExp and Date, when split between Browser and Node stringification is implemented
+        // } else if (obj instanceof RegExp) {
+        //   s = String(obj)
+        // } else if (obj instanceof Date) {
+        //   s = `Date (${obj.toISOString()})`
     }
     else {
         //
         // Other
         //
         if (obj instanceof Map) {
+            // todo: double-check it, maybe Node's inspect has good built-in stringification
             obj = Object.fromEntries(obj);
         }
         else if (obj instanceof Set) {
@@ -132,3 +103,34 @@ export function _stringify(obj, opt = {}) {
     }
     return s;
 }
+function stringifyErrorLike(obj, opt) {
+    const { includeErrorCause = true } = opt;
+    let s = [obj.name, obj.message].filter(Boolean).join(': ');
+    if (typeof obj.code === 'string') {
+        // Error that has no `data`, but has `code` property
+        s += `\ncode: ${obj.code}`;
+    }
+    if (opt.includeErrorData && _isErrorObject(obj) && Object.keys(obj.data).length) {
+        s += '\n' + _stringify(obj.data, opt);
+    }
+    if (opt.includeErrorStack && obj.stack) {
+        // Here we're using the previously-generated "title line" (e.g "Error: some_message"),
+        // concatenating it with the Stack (but without the title line of the Stack)
+        // This is to fix the rare error (happened with Got) where `err.message` was changed,
+        // but err.stack had "old" err.message
+        // This should "fix" that
+        const sLines = s.split('\n').length;
+        s = [s, ...obj.stack.split('\n').slice(sLines)].join('\n');
+    }
+    if (supportsAggregateError && obj instanceof AggregateError && obj.errors.length) {
+        s = [
+            s,
+            `${obj.errors.length} error(s):`,
+            ...obj.errors.map((err, i) => `${i + 1}. ${_stringify(err, opt)}`),
+        ].join('\n');
+    }
+    if (obj.cause && includeErrorCause) {
+        s = s + '\nCaused by: ' + _stringify(obj.cause, opt);
+    }
+    return s;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.45.0",
+  "version": "15.46.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.8.0"
   },
   "exports": {
     ".": "./dist/index.js",

package/src/env.ts

@@ -18,3 +18,12 @@ export function isClientSide(): boolean {
   // 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(): boolean {
+  return typeof process !== 'undefined' && process?.release?.name === 'node'
+}

package/src/object/keySortedMap.ts

@@ -1,3 +1,4 @@
+import { _assert } from '../error/index.js'
 import type { Comparator } from '../types.js'
 
 export interface KeySortedMapOptions<K> {
@@ -23,17 +24,17 @@ export interface KeySortedMapOptions<K> {
  */
 export class KeySortedMap<K, V> implements Map<K, V> {
   private readonly map: Map<K, V>
-  private readonly sortedKeys: K[]
+  readonly #sortedKeys: K[]
 
-  constructor(
-    entries: [K, V][] = [],
-    public opt: KeySortedMapOptions<K> = {},
-  ) {
+  constructor(entries: [K, V][] = [], opt: KeySortedMapOptions<K> = {}) {
+    this.#comparator = opt.comparator
     this.map = new Map(entries)
-    this.sortedKeys = [...this.map.keys()]
+    this.#sortedKeys = [...this.map.keys()]
     this.sortKeys()
   }
 
+  readonly #comparator: Comparator<K> | undefined
+
   /**
    * Convenience way to create KeySortedMap from object.
    */
@@ -47,7 +48,7 @@ export class KeySortedMap<K, V> implements Map<K, V> {
 
   clear(): void {
     this.map.clear()
-    this.sortedKeys.length = 0
+    this.#sortedKeys.length = 0
   }
 
   has(key: K): boolean {
@@ -64,7 +65,7 @@ export class KeySortedMap<K, V> implements Map<K, V> {
   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)
+      this.#sortedKeys.push(k as K)
     }
     // Resort all at once
     this.sortKeys()
@@ -84,7 +85,7 @@ export class KeySortedMap<K, V> implements Map<K, V> {
     // 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
   }
@@ -98,13 +99,13 @@ export class KeySortedMap<K, V> implements Map<K, V> {
     // 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)
-      if (j !== -1) this.sortedKeys.splice(j, 1)
+      const j = this.#sortedKeys.indexOf(key)
+      if (j !== -1) this.#sortedKeys.splice(j, 1)
     }
     return true
   }
@@ -113,20 +114,19 @@ export class KeySortedMap<K, V> implements Map<K, V> {
    * Iterables (Map-compatible), all in sorted order.
    */
   *keys(): MapIterator<K> {
-    for (let i = 0; i < this.sortedKeys.length; i++) {
-      yield this.sortedKeys[i]!
+    for (const key of this.#sortedKeys) {
+      yield key
     }
   }
 
   *values(): MapIterator<V> {
-    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(): MapIterator<[K, V]> {
-    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)!]
     }
   }
@@ -135,64 +135,82 @@ export class KeySortedMap<K, V> implements Map<K, V> {
     return this.entries()
   }
 
+  toString(): string {
+    console.log('toString called !!!!!!!!!!!!!!!!!!!!!')
+    return 'abc'
+  }
+
   [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)
+    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(): K[] {
-    return this.sortedKeys.slice()
+  firstKeyOrUndefined(): K | undefined {
+    return this.#sortedKeys[0]
   }
 
-  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
+  firstKey(): K {
+    _assert(this.#sortedKeys.length, 'Map.firstKey called on empty map')
+    return this.#sortedKeys[0]!
   }
 
-  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
+  lastKeyOrUndefined(): K | undefined {
+    return this.#sortedKeys.length ? this.#sortedKeys[this.#sortedKeys.length - 1] : undefined
+  }
+
+  lastKey(): K {
+    _assert(this.#sortedKeys.length, 'Map.lastKey called on empty map')
+    return this.#sortedKeys[this.#sortedKeys.length - 1]!
   }
 
-  /** Fast helpers */
-  firstKey(): K | undefined {
-    return this.sortedKeys[0]
+  firstValueOrUndefined(): V | undefined {
+    return this.map.get(this.#sortedKeys[0]!)
   }
 
-  lastKey(): K | undefined {
-    return this.sortedKeys.length ? this.sortedKeys[this.sortedKeys.length - 1] : undefined
+  firstValue(): V {
+    _assert(this.#sortedKeys.length, 'Map.firstValue called on empty map')
+    return this.map.get(this.#sortedKeys[0]!)!
   }
 
-  firstEntry(): [K, V] | undefined {
-    if (!this.sortedKeys.length) return
-    const k = this.sortedKeys[0]!
+  lastValueOrUndefined(): V | undefined {
+    return this.#sortedKeys.length
+      ? this.map.get(this.#sortedKeys[this.#sortedKeys.length - 1]!)
+      : undefined
+  }
+
+  lastValue(): V {
+    _assert(this.#sortedKeys.length, 'Map.lastValue called on empty map')
+    return this.map.get(this.#sortedKeys[this.#sortedKeys.length - 1]!)!
+  }
+
+  firstEntryOrUndefined(): [K, V] | undefined {
+    if (!this.#sortedKeys.length) return
+    const k = this.#sortedKeys[0]!
+    return [k, this.map.get(k)!]
+  }
+
+  firstEntry(): [K, V] {
+    _assert(this.#sortedKeys.length, 'Map.firstEntry called on empty map')
+    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]!
+  lastEntryOrUndefined(): [K, V] | undefined {
+    if (!this.#sortedKeys.length) return
+    const k = this.#sortedKeys[this.#sortedKeys.length - 1]!
+    return [k, this.map.get(k)!]
+  }
+
+  lastEntry(): [K, V] {
+    _assert(this.#sortedKeys.length, 'Map.lastEntry called on empty map')
+    const k = this.#sortedKeys[this.#sortedKeys.length - 1]!
     return [k, this.map.get(k)!]
   }
 
@@ -201,7 +219,14 @@ export class KeySortedMap<K, V> implements Map<K, V> {
   }
 
   toObject(): Record<string, V> {
-    return Object.fromEntries(this.map)
+    return Object.fromEntries(this.entries())
+  }
+
+  /**
+   * Clones the KeySortedMap into ordinary Map.
+   */
+  toMap(): Map<K, V> {
+    return new Map(this.entries())
   }
 
   /**
@@ -209,11 +234,11 @@ export class KeySortedMap<K, V> implements Map<K, V> {
    */
   private lowerBound(target: K): number {
     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 {
         hi = mid
@@ -223,6 +248,6 @@ export class KeySortedMap<K, V> implements Map<K, V> {
   }
 
   private sortKeys(): void {
-    this.sortedKeys.sort(this.opt.comparator)
+    this.#sortedKeys.sort(this.#comparator)
   }
 }

package/src/object/keySortedMap2.ts

@@ -0,0 +1,221 @@
+import { _assert } from '../error/index.js'
+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 class KeySortedMap2<K, V> implements Map<K, V> {
+  private readonly map: Map<K, V>
+  private readonly maybeSortedKeys: K[]
+  private keysAreSorted = false
+
+  constructor(entries: [K, V][] = [], opt: KeySortedMapOptions<K> = {}) {
+    this.#comparator = opt.comparator
+    this.map = new Map(entries)
+    this.maybeSortedKeys = [...this.map.keys()]
+  }
+
+  readonly #comparator: Comparator<K> | undefined
+
+  /**
+   * Convenience way to create KeySortedMap from object.
+   */
+  static of<V>(obj: Record<any, V>): KeySortedMap2<string, V> {
+    return new KeySortedMap2(Object.entries(obj))
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  clear(): void {
+    this.map.clear()
+    this.maybeSortedKeys.length = 0
+    this.keysAreSorted = true
+  }
+
+  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.maybeSortedKeys.push(k as K)
+    }
+    this.keysAreSorted = false
+    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)) {
+      this.maybeSortedKeys.push(key)
+      this.keysAreSorted = false
+    }
+    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)
+    // 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(): MapIterator<K> {
+    for (const key of this.getSortedKeys()) {
+      yield key
+    }
+  }
+
+  *values(): MapIterator<V> {
+    for (const key of this.getSortedKeys()) {
+      yield this.map.get(key)!
+    }
+  }
+
+  *entries(): MapIterator<[K, V]> {
+    for (const k of this.getSortedKeys()) {
+      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 { map } = this
+    for (const k of this.getSortedKeys()) {
+      cb.call(thisArg, map.get(k)!, k, this)
+    }
+  }
+
+  firstKeyOrUndefined(): K | undefined {
+    return this.getSortedKeys()[0]
+  }
+
+  firstKey(): K {
+    _assert(this.maybeSortedKeys.length, 'Map.firstKey called on empty map')
+    return this.getSortedKeys()[0]!
+  }
+
+  lastKeyOrUndefined(): K | undefined {
+    if (!this.maybeSortedKeys.length) return
+    const keys = this.getSortedKeys()
+    return keys[keys.length - 1]
+  }
+
+  lastKey(): K {
+    const k = this.lastKeyOrUndefined()
+    _assert(k, 'Map.lastKey called on empty map')
+    return k
+  }
+
+  firstValueOrUndefined(): V | undefined {
+    if (!this.maybeSortedKeys.length) return
+    return this.map.get(this.getSortedKeys()[0]!)
+  }
+
+  firstValue(): V {
+    const v = this.firstValueOrUndefined()
+    _assert(v, 'Map.firstValue called on empty map')
+    return v
+  }
+
+  lastValueOrUndefined(): V | undefined {
+    if (!this.maybeSortedKeys.length) return
+    const keys = this.getSortedKeys()
+    return this.map.get(keys[keys.length - 1]!)
+  }
+
+  lastValue(): V {
+    const v = this.lastValueOrUndefined()
+    _assert(v, 'Map.lastValue called on empty map')
+    return v
+  }
+
+  firstEntryOrUndefined(): [K, V] | undefined {
+    if (!this.maybeSortedKeys.length) return
+    const k = this.getSortedKeys()[0]!
+    return [k, this.map.get(k)!]
+  }
+
+  firstEntry(): [K, V] {
+    const e = this.firstEntryOrUndefined()
+    _assert(e, 'Map.firstEntry called on empty map')
+    return e
+  }
+
+  lastEntryOrUndefined(): [K, V] | undefined {
+    if (!this.maybeSortedKeys.length) return
+    const keys = this.getSortedKeys()
+    const k = keys[keys.length - 1]!
+    return [k, this.map.get(k)!]
+  }
+
+  lastEntry(): [K, V] {
+    const e = this.firstEntryOrUndefined()
+    _assert(e, 'Map.lastEntry called on empty map')
+    return e
+  }
+
+  toJSON(): Record<string, V> {
+    return this.toObject()
+  }
+
+  toObject(): Record<string, V> {
+    return Object.fromEntries(this.entries())
+  }
+
+  private getSortedKeys(): K[] {
+    if (!this.keysAreSorted) {
+      return this.sortKeys()
+    }
+    return this.maybeSortedKeys
+  }
+
+  private sortKeys(): K[] {
+    this.maybeSortedKeys.sort(this.#comparator)
+    this.keysAreSorted = true
+    return this.maybeSortedKeys
+  }
+}

package/src/object/map2.ts

@@ -31,5 +31,9 @@ export class Map2<K = any, V = any> extends Map<K, V> {
     return Object.fromEntries(this)
   }
 
+  override toString(): string {
+    return `Map2(${this.size}) ${JSON.stringify(Object.fromEntries(this))}`
+  }
+
   // consider more helpful .toString() ?
 }

package/src/object/set2.ts

@@ -41,8 +41,8 @@ export class Set2<T = any> extends Set<T> {
     return [...this]
   }
 
-  override get [Symbol.toStringTag](): string {
-    return 'Set'
+  override toString(): string {
+    return `Set2(${this.size}) ${JSON.stringify([...this])}`
   }
 
   // todo: consider more helpful .toString() ?