@naturalcycles/js-lib 15.42.1 → 15.44.0

package/dist/types.d.ts

@@ -273,9 +273,10 @@ export type SemVerString = string;
  */
 export type Reviver = (this: any, key: string, value: any) => any;
 /**
- * Like _stringMapValues, but values are sorted.
+ * Function to be passed to the `sort` method.
+ * Returns -1 | 0 | 1 canonically, but any positive/negative number is supported.
  */
-export declare function _stringMapValuesSorted<T>(map: StringMap<T>, mapper: Mapper<T, any>, dir?: SortDirection): T[];
+export type Comparator<T> = (a: T, b: T) => number;
 /**
  * Needed due to https://github.com/microsoft/TypeScript/issues/13778
  * Only affects typings, no runtime effect.
@@ -328,6 +329,18 @@ export declare const _objectAssign: <T extends AnyObject>(target: T, part: Parti
  */
 export type ErrorDataTuple<T = unknown, ERR = Error> = [err: null, data: T] | [err: ERR, data: null];
 export type SortDirection = 'asc' | 'desc';
+export interface MutateOptions {
+    /**
+     * Defaults to false.
+     */
+    mutate?: boolean;
+}
+export interface SortOptions extends MutateOptions {
+    /**
+     * Defaults to 'asc'.
+     */
+    dir?: SortDirection;
+}
 export type Inclusiveness = '[]' | '[)';
 /**
  * @experimental
@@ -346,29 +359,29 @@ export type Promisable<T> = T | PromiseLike<T>;
 export type Class<T = any> = new (...args: any[]) => T;
 /**
  Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
- 
+
  This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around.
- 
+
  Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript.
- 
+
  @example
  ```
  // data.json
  {
  "foo": ["bar"]
  }
- 
+
  // main.ts
  import {ReadonlyDeep} from 'type-fest';
  import dataJson = require('./data.json');
- 
+
  const data: ReadonlyDeep<typeof dataJson> = dataJson;
- 
+
  export default data;
- 
+
  // test.ts
  import data from './main';
- 
+
  data.foo.push('bar');
  //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
  ```

package/dist/types.js

@@ -1,4 +1,3 @@
-import { _sortBy } from './array/array.util.js';
 /**
  * Symbol to indicate END of Sequence.
  */
@@ -21,12 +20,6 @@ export const _noop = (..._args) => undefined;
 export const _passthroughPredicate = () => true;
 export const _passNothingPredicate = () => false;
 export const JWT_REGEX = /^[\w-]+\.[\w-]+\.[\w-]+$/;
-/**
- * Like _stringMapValues, but values are sorted.
- */
-export function _stringMapValuesSorted(map, mapper, dir = 'asc') {
-    return _sortBy(_stringMapValues(map), mapper, { dir });
-}
 /**
  * Needed due to https://github.com/microsoft/TypeScript/issues/13778
  * Only affects typings, no runtime effect.

package/package.json

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

package/src/array/array.util.ts

@@ -3,8 +3,8 @@ import type {
   AbortablePredicate,
   FalsyValue,
   Mapper,
+  MutateOptions,
   Predicate,
-  SortDirection,
   StringMap,
 } from '../types.js'
 import { END } from '../types.js'
@@ -170,47 +170,6 @@ export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): String
   return map
 }
 
-export interface MutateOptions {
-  /**
-   * Defaults to false.
-   */
-  mutate?: boolean
-}
-
-export interface SortOptions extends MutateOptions {
-  /**
-   * Defaults to 'asc'.
-   */
-  dir?: SortDirection
-}
-
-/**
- * _sortBy([{age: 20}, {age: 10}], 'age')
- * // => [{age: 10}, {age: 20}]
- *
- * Same:
- * _sortBy([{age: 20}, {age: 10}], o => o.age)
- */
-export function _sortBy<T, COMPARE_TYPE extends string | number>(
-  items: T[],
-  mapper: Mapper<T, COMPARE_TYPE>,
-  opt: SortOptions = {},
-): T[] {
-  const mod = opt.dir === 'desc' ? -1 : 1
-
-  return (opt.mutate ? items : [...items]).sort((_a, _b) => {
-    // This implementation may call mapper more than once per item,
-    // but the benchmarks show no significant difference in performance.
-    const a = mapper(_a)
-    const b = mapper(_b)
-    // if (typeof a === 'number' && typeof b === 'number') return (a - b) * mod
-    // return String(a).localeCompare(String(b)) * mod
-    if (a > b) return mod
-    if (a < b) return -mod
-    return 0
-  })
-}
-
 /**
  * Similar to `Array.find`, but the `predicate` may return `END` to stop the iteration early.
  *

package/src/array/array2.ts

@@ -0,0 +1,52 @@
+import { _shuffle } from './array.util.js'
+
+/**
+ * Better Array.
+ *
+ * @experimental
+ */
+export class Array2<T> extends Array<T> {
+  static override of<T>(...items: T[]): Array2<T> {
+    return new Array2(...items)
+  }
+
+  // eslint-disable-next-line @typescript-eslint/class-literal-property-style
+  get [Symbol.toStringTag](): string {
+    return 'Array2'
+  }
+
+  firstOrUndefined(): T | undefined {
+    return this[0]
+  }
+
+  first(): T {
+    if (!this.length) throw new Error('Array.first called on empty array')
+    return this[0]!
+  }
+
+  lastOrUndefined(): T | undefined {
+    return this[this.length - 1]
+  }
+
+  last(): T {
+    const { length } = this
+    if (!length) throw new Error('Array.last called on empty array')
+    return this[length - 1]!
+  }
+
+  uniq(): Array2<T> {
+    return new Array2<T>(...new Set(this))
+  }
+
+  shuffle(): Array2<T> {
+    return new Array2(..._shuffle(this))
+  }
+
+  isEmpty(): boolean {
+    return this.length === 0
+  }
+
+  isNotEmpty(): boolean {
+    return this.length !== 0
+  }
+}

package/src/array/index.ts

@@ -1,2 +1,6 @@
 export * from './array.util.js'
+export * from './array2.js'
 export * from './range.js'
+export * from './sort.js'
+export * from './sortedArray.js'
+export * from './sortedSet.js'

package/src/array/sort.ts

@@ -0,0 +1,96 @@
+import {
+  _stringMapValues,
+  type Comparator,
+  type Mapper,
+  type SortDirection,
+  type SortOptions,
+  type StringMap,
+} from '../types.js'
+
+class Comparators {
+  /**
+   * Good for numbers.
+   */
+  numericAsc(a: number, b: number): number {
+    return a - b
+  }
+
+  numericDesc(a: number, b: number): number {
+    return b - a
+  }
+
+  localeAsc(a: string, b: string): number {
+    return a.localeCompare(b)
+  }
+
+  localeDesc(a: string, b: string): number {
+    return -a.localeCompare(b)
+  }
+
+  by<T, COMPARE_TYPE extends string | number>(
+    mapper: Mapper<T, COMPARE_TYPE>,
+    opt: ComparatorByOptions = {},
+  ): Comparator<T> {
+    const mod = opt.dir === 'desc' ? -1 : 1
+    return (objA: T, objB: T): number => {
+      // This implementation may call mapper more than once per item,
+      // but the benchmarks show no significant difference in performance.
+      const a = mapper(objA)
+      const b = mapper(objB)
+      if (a > b) return mod
+      if (a < b) return -mod
+      return 0
+    }
+  }
+
+  updatedAsc(a: { updated: number }, b: { updated: number }): number {
+    return a.updated - b.updated
+  }
+
+  updatedDesc(a: { updated: number }, b: { updated: number }): number {
+    return b.updated - a.updated
+  }
+
+  createdAsc(a: { created: number }, b: { created: number }): number {
+    return a.created - b.created
+  }
+
+  createdDesc(a: { created: number }, b: { created: number }): number {
+    return b.created - a.created
+  }
+}
+
+export const comparators = new Comparators()
+
+interface ComparatorByOptions {
+  /**
+   * Defaults to 'asc'.
+   */
+  dir?: SortDirection
+}
+
+/**
+ * _sortBy([{age: 20}, {age: 10}], 'age')
+ * // => [{age: 10}, {age: 20}]
+ *
+ * Same:
+ * _sortBy([{age: 20}, {age: 10}], o => o.age)
+ */
+export function _sortBy<T, COMPARE_TYPE extends string | number>(
+  items: T[],
+  mapper: Mapper<T, COMPARE_TYPE>,
+  opt: SortOptions = {},
+): T[] {
+  return (opt.mutate ? items : [...items]).sort(comparators.by(mapper, opt))
+}
+
+/**
+ * Like _stringMapValues, but values are sorted.
+ */
+export function _stringMapValuesSorted<T>(
+  map: StringMap<T>,
+  mapper: Mapper<T, any>,
+  dir: SortDirection = 'asc',
+): T[] {
+  return _sortBy(_stringMapValues(map), mapper, { dir })
+}

package/src/array/sortedArray.ts

@@ -0,0 +1,78 @@
+import type { Comparator } from '../types.js'
+import { Array2 } from './array2.js'
+import { comparators } from './sort.js'
+
+export interface SortedArrayOptions<T> {
+  /**
+   * 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<T>
+}
+
+/**
+ * Like Array, but keeps values sorted after every insertion.
+ */
+export class SortedArray<T> extends Array2<T> {
+  constructor(values: Iterable<T> = [], opt: SortedArrayOptions<T> = {}) {
+    super(...values)
+    this.#comparator = opt.comparator
+    this.resort()
+  }
+
+  readonly #comparator: Comparator<T> | undefined
+
+  override push(...values: T[]): number {
+    const length = super.push(...values)
+    this.resort()
+    return length
+  }
+
+  override unshift(...values: T[]): number {
+    const length = super.unshift(...values)
+    this.resort()
+    return length
+  }
+
+  override splice(start: number, deleteCount?: number, ...items: T[]): T[] {
+    const removed = super.splice(start, deleteCount ?? this.length - start, ...items)
+    if (items.length) {
+      this.resort()
+    }
+    return removed
+  }
+
+  static override get [Symbol.species](): ArrayConstructor {
+    return Array
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'Array'
+  }
+
+  private resort(): void {
+    super.sort(this.#comparator)
+  }
+}
+
+export class SortedStringArray extends SortedArray<string> {
+  constructor(values: Iterable<string> = []) {
+    super(values)
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'Array'
+  }
+}
+
+export class SortedNumberArray extends SortedArray<number> {
+  constructor(values: Iterable<number> = []) {
+    super(values, { comparator: comparators.numericAsc })
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'Array'
+  }
+}

package/src/array/sortedSet.ts

@@ -0,0 +1,54 @@
+import { Set2 } from '../object/index.js'
+import type { Comparator } from '../types.js'
+
+export interface SortedSetOptions<T> {
+  /**
+   * 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<T>
+}
+
+/**
+ * Like Set, but keeps members sorted after every insertion.
+ */
+export class SortedSet<T> extends Set2<T> {
+  constructor(values: Iterable<T> = [], opt: SortedSetOptions<T> = {}) {
+    super()
+    this.#comparator = opt.comparator
+    this.addMany(values)
+  }
+
+  readonly #comparator: Comparator<T> | undefined
+
+  override add(value: T): this {
+    if (super.has(value)) {
+      return this
+    }
+    super.add(value)
+    return this.recreate()
+  }
+
+  override addMany(items: Iterable<T>): this {
+    for (const item of items) {
+      super.add(item)
+    }
+    return this.recreate()
+  }
+
+  private recreate(): this {
+    const items = Array.from(super.values())
+    items.sort(this.#comparator)
+    super.clear()
+    for (const item of items) {
+      super.add(item)
+    }
+    return this
+  }
+
+  override get [Symbol.toStringTag](): string {
+    return 'Set'
+  }
+}

package/src/datetime/localDate.ts

@@ -1,4 +1,3 @@
-import type { MutateOptions, SortOptions } from '../array/array.util.js'
 import { _assert } from '../error/assert.js'
 import { Iterable2 } from '../iter/iterable2.js'
 import type {
@@ -6,6 +5,8 @@ import type {
   IsoDate,
   IsoDateTime,
   MonthId,
+  MutateOptions,
+  SortOptions,
   UnixTimestamp,
   UnixTimestampMillis,
 } from '../types.js'

package/src/datetime/localTime.ts

@@ -1,4 +1,3 @@
-import type { MutateOptions } from '../array/array.util.js'
 import { _assert } from '../error/assert.js'
 import type {
   IANATimezone,
@@ -6,6 +5,7 @@ import type {
   IsoDate,
   IsoDateTime,
   MonthId,
+  MutateOptions,
   NumberOfHours,
   NumberOfMinutes,
   SortDirection,

package/src/log/commonLogger.ts

@@ -1,4 +1,4 @@
-import type { MutateOptions } from '../array/array.util.js'
+import type { MutateOptions } from '../types.js'
 
 // copy-pasted to avoid weird circular dependency
 const _noop = (..._args: any[]): undefined => undefined

package/src/math/math.util.ts

@@ -1,5 +1,5 @@
+import { comparators } from '../array/sort.js'
 import { _assert } from '../error/assert.js'
-import { _sortNumbers } from '../number/number.util.js'
 
 /**
  * @returns Average of the array of numbers
@@ -49,7 +49,7 @@ export function _averageWeighted(values: number[], weights: number[]): number {
  * // 3
  */
 export function _percentile(values: number[], pc: number): number {
-  const sorted = _sortNumbers(values)
+  const sorted = values.sort(comparators.numericAsc)
 
   // Floating pos in the range of [0; length - 1]
   const pos = ((values.length - 1) * pc) / 100
@@ -66,7 +66,7 @@ export function _percentile(values: number[], pc: number): number {
 export function _percentiles(values: number[], pcs: number[]): Record<number, number> {
   const r = {} as Record<number, number>
 
-  const sorted = _sortNumbers(values)
+  const sorted = values.sort(comparators.numericAsc)
 
   for (const pc of pcs) {
     // Floating pos in the range of [0; length - 1]

package/src/number/number.util.ts

@@ -1,4 +1,3 @@
-import type { SortOptions } from '../array/array.util.js'
 import type { Inclusiveness } from '../types.js'
 
 export function _randomInt(minIncl: number, maxIncl: number): number {
@@ -55,20 +54,6 @@ export function _clamp(x: number, minIncl: number, maxIncl: number): number {
   return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x
 }
 
-/**
- * This function exists, because in JS you cannot just .sort() numbers,
- * as .sort() function first maps everything to String.
- *
- * @example
- *
- * _sortNumbers([1, 3, 2])
- * // [1, 2, 3]
- */
-export function _sortNumbers(numbers: number[], opt: SortOptions = {}): number[] {
-  const mod = opt.dir === 'desc' ? -1 : 1
-  return (opt.mutate ? numbers : [...numbers]).sort((a, b) => (a - b) * mod)
-}
-
 /**
  * Same as .toFixed(), but conveniently casts the output to Number.
  *

package/src/object/keySortedMap.ts

@@ -1,10 +1,13 @@
-export interface KeySortedMapOptions {
+import type { Comparator } from '../types.js'
+
+export interface KeySortedMapOptions<K> {
   /**
-   * Defaults to false.
-   * Set to true if your keys are numeric,
-   * so it would sort correctly.
+   * 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).
    */
-  numericKeys?: boolean
+  comparator?: Comparator<K>
 }
 
 /**
@@ -24,7 +27,7 @@ export class KeySortedMap<K, V> implements Map<K, V> {
 
   constructor(
     entries: [K, V][] = [],
-    public opt: KeySortedMapOptions = {},
+    public opt: KeySortedMapOptions<K> = {},
   ) {
     this.map = new Map(entries)
     this.sortedKeys = [...this.map.keys()]
@@ -220,15 +223,6 @@ export class KeySortedMap<K, V> implements Map<K, V> {
   }
 
   private sortKeys(): void {
-    if (this.opt.numericKeys) {
-      ;(this.sortedKeys as number[]).sort(numericAscCompare)
-    } else {
-      // Default sort - fastest for Strings
-      this.sortedKeys.sort()
-    }
+    this.sortedKeys.sort(this.opt.comparator)
   }
 }
-
-function numericAscCompare(a: number, b: number): number {
-  return a - b
-}

package/src/object/object.util.ts

@@ -1,8 +1,8 @@
-import type { MutateOptions } from '../array/array.util.js'
 import { _isEmpty, _isObject } from '../is.util.js'
 import type {
   AnyObject,
   KeyValueTuple,
+  MutateOptions,
   ObjectMapper,
   ObjectPredicate,
   Reviver,

package/src/object/set2.ts

@@ -6,6 +6,10 @@
  * @experimental
  */
 export class Set2<T = any> extends Set<T> {
+  static of<T>(items?: Iterable<T> | null): Set2<T> {
+    return new Set2(items)
+  }
+
   /**
    * Like .add(), but allows to add multiple items at once.
    * Mutates the Set, but also returns it conveniently.
@@ -17,6 +21,18 @@ export class Set2<T = any> extends Set<T> {
     return this
   }
 
+  first(): T {
+    if (!this.size) throw new Error('Set.first called on empty set')
+    return this.firstOrUndefined()!
+  }
+
+  firstOrUndefined(): T | undefined {
+    return this.values().next().value
+  }
+
+  // Last is not implemented, because it requires to traverse the whole Set - not optimal
+  // last(): T {
+
   toArray(): T[] {
     return [...this]
   }
@@ -25,5 +41,9 @@ export class Set2<T = any> extends Set<T> {
     return [...this]
   }
 
-  // consider more helpful .toString() ?
+  override get [Symbol.toStringTag](): string {
+    return 'Set'
+  }
+
+  // todo: consider more helpful .toString() ?
 }

package/src/semver.ts

@@ -1,6 +1,6 @@
-import type { SortOptions } from './array/array.util.js'
 import { _range } from './array/range.js'
 import { _assert } from './error/assert.js'
+import type { SortOptions } from './types.js'
 
 export type SemverInput = string | Semver
 export type SemverInputNullable = SemverInput | null | undefined