@naturalcycles/js-lib 14.71.0 → 14.75.0

package/src/index.ts

@@ -1,29 +1,7 @@
-import {
-  _by,
-  _chunk,
-  _countBy,
-  _difference,
-  _dropRightWhile,
-  _dropWhile,
-  _findLast,
-  _flatten,
-  _flattenDeep,
-  _groupBy,
-  _intersection,
-  _last,
-  _mapToObject,
-  _shuffle,
-  _sortBy,
-  _sum,
-  _sumBy,
-  _takeRightWhile,
-  _takeWhile,
-  _uniq,
-  _uniqBy,
-} from './array/array.util'
-import { _defineLazyProperty, _defineLazyProps, _lazyValue } from './lazy'
-import { _parseQueryString } from './string/url.util'
-import { _range } from './array/range'
+export * from './array/array.util'
+export * from './lazy'
+export * from './string/url.util'
+export * from './array/range'
 import {
   PromiseDecoratorCfg,
   PromiseDecoratorResp,
@@ -89,82 +67,29 @@ import {
   JsonSchemaAnyBuilder,
   JsonSchemaBuilder,
 } from './json-schema/jsonSchemaBuilder'
-import { _average, _averageWeighted, _median, _percentile } from './math/math.util'
-import { SimpleMovingAverage } from './math/sma'
-import { _createDeterministicRandom } from './number/createDeterministicRandom'
-import {
-  _clamp,
-  _inRange,
-  _randomInt,
-  _randomArrayItem,
-  _round,
-  _sortNumbers,
-  _toFixed,
-  _toPrecision,
-} from './number/number.util'
-import { _deepEquals } from './object/deepEquals'
-import {
-  _deepCopy,
-  _deepTrim,
-  _filterEmptyArrays,
-  _filterEmptyValues,
-  _filterFalsyValues,
-  _filterNullishValues,
-  _filterObject,
-  _filterUndefinedValues,
-  _findKeyByValue,
-  _get,
-  _has,
-  _invert,
-  _invertMap,
-  _isEmpty,
-  _isEmptyObject,
-  _isObject,
-  _isPrimitive,
-  _mapKeys,
-  _mapObject,
-  _mapValues,
-  _mask,
-  _merge,
-  _objectNullValuesToUndefined,
-  _omit,
-  _pick,
-  _set,
-  _undefinedIfEmpty,
-  _unset,
-} from './object/object.util'
-import { _sortObject } from './object/sortObject'
-import { _sortObjectDeep } from './object/sortObjectDeep'
+export * from './math/math.util'
+export * from './math/sma'
+export * from './number/createDeterministicRandom'
+export * from './number/number.util'
+export * from './object/deepEquals'
+export * from './object/object.util'
+export * from './object/sortObject'
+export * from './object/sortObjectDeep'
 import { AggregatedError } from './promise/AggregatedError'
-import { pBatch } from './promise/pBatch'
+export * from './promise/pBatch'
 import { DeferredPromise, pDefer } from './promise/pDefer'
-import { pDelay } from './promise/pDelay'
-import { pFilter } from './promise/pFilter'
-import { pHang } from './promise/pHang'
+export * from './promise/pDelay'
+export * from './promise/pFilter'
+export * from './promise/pHang'
 import { pMap, PMapOptions } from './promise/pMap'
-import { pProps } from './promise/pProps'
+export * from './promise/pProps'
 import { pRetry, PRetryOptions } from './promise/pRetry'
-import { pState } from './promise/pState'
+export * from './promise/pState'
 import { pTimeout, PTimeoutOptions } from './promise/pTimeout'
-import { pTuple } from './promise/pTuple'
-import { _camelCase, _kebabCase, _snakeCase } from './string/case'
-import { _jsonParseIfPossible } from './string/json.util'
-import {
-  _capitalize,
-  _lowerFirst,
-  _nl2br,
-  _removeWhitespace,
-  _replaceAll,
-  _split,
-  _substringAfter,
-  _substringAfterLast,
-  _substringBefore,
-  _substringBeforeLast,
-  _substringBetweenLast,
-  _truncate,
-  _truncateMiddle,
-  _upperFirst,
-} from './string/string.util'
+export * from './promise/pTuple'
+export * from './string/case'
+export * from './string/json.util'
+export * from './string/string.util'
 import { JsonStringifyFunction, StringifyAnyOptions, _stringifyAny } from './string/stringifyAny'
 import { _ms, _since } from './time/time.util'
 import {
@@ -236,6 +161,7 @@ import {
 import { _safeJsonStringify } from './string/safeJsonStringify'
 import { PQueue, PQueueCfg } from './promise/pQueue'
 export * from './seq/seq'
+export * from './math/stack.util'
 
 export type {
   AbortableMapper,
@@ -334,86 +260,9 @@ export {
   _assertIsString,
   _assertIsNumber,
   _assertTypeOf,
-  _randomInt,
-  _randomArrayItem,
-  _createDeterministicRandom,
-  _inRange,
   _stringMapValues,
   _stringMapEntries,
   _objectKeys,
-  _capitalize,
-  _upperFirst,
-  _lowerFirst,
-  _split,
-  _removeWhitespace,
-  _substringBefore,
-  _substringBeforeLast,
-  _substringAfter,
-  _substringAfterLast,
-  _substringBetweenLast,
-  _replaceAll,
-  _nl2br,
-  _truncate,
-  _truncateMiddle,
-  _pick,
-  _omit,
-  _filterFalsyValues,
-  _filterUndefinedValues,
-  _filterNullishValues,
-  _filterEmptyArrays,
-  _filterEmptyValues,
-  _filterObject,
-  _undefinedIfEmpty,
-  _isObject,
-  _isPrimitive,
-  _mapKeys,
-  _mapValues,
-  _mapObject,
-  _objectNullValuesToUndefined,
-  _deepEquals,
-  _deepCopy,
-  _isEmptyObject,
-  _isEmpty,
-  _merge,
-  _deepTrim,
-  _sortObjectDeep,
-  _sortObject,
-  _get,
-  _set,
-  _has,
-  _unset,
-  _mask,
-  _invert,
-  _invertMap,
-  _by,
-  _groupBy,
-  _sortBy,
-  _sortNumbers,
-  _toFixed,
-  _toPrecision,
-  _round,
-  _findLast,
-  _takeWhile,
-  _takeRightWhile,
-  _dropWhile,
-  _dropRightWhile,
-  _countBy,
-  _intersection,
-  _difference,
-  _shuffle,
-  _mapToObject,
-  _findKeyByValue,
-  _range,
-  _uniq,
-  _uniqBy,
-  _flatten,
-  _flattenDeep,
-  _chunk,
-  SimpleMovingAverage,
-  _average,
-  _averageWeighted,
-  _percentile,
-  _median,
   _debounce,
   _throttle,
   _Debounce,
@@ -424,25 +273,17 @@ export {
   _passthroughPredicate,
   _passNothingPredicate,
   _noop,
-  pBatch,
   ErrorMode,
-  pFilter,
-  pProps,
-  pDelay,
   pDefer,
-  pHang,
-  pState,
   AggregatedError,
   pRetry,
   pTimeout,
-  pTuple,
   _Retry,
   _Timeout,
   _tryCatch,
   _TryCatch,
   _try,
   pTry,
-  _jsonParseIfPossible,
   _stringifyAny,
   _ms,
   _since,
@@ -450,22 +291,11 @@ export {
   _gb,
   _mb,
   _kb,
-  _snakeCase,
-  _camelCase,
-  _kebabCase,
-  _sum,
-  _sumBy,
-  _clamp,
-  _last,
   mergeJsonSchemaObjects,
   jsonSchema,
   JsonSchemaAnyBuilder,
   JSON_SCHEMA_ORDER,
   generateJsonSchemaFromData,
-  _parseQueryString,
-  _defineLazyProperty,
-  _defineLazyProps,
-  _lazyValue,
   commonLoggerMinLevel,
   commonLoggerNoop,
   commonLogLevelNumber,

package/src/math/math.util.ts

@@ -47,6 +47,27 @@ export function _percentile(values: number[], pc: number): number {
   return _averageWeighted([sorted[floorPos]!, sorted[ceilPos]!], [1 - dec, dec])
 }
 
+/**
+ * A tiny bit more efficient function than calling _percentile individually.
+ */
+export function _percentiles(values: number[], pcs: number[]): Record<number, number> {
+  const r = {} as Record<number, number>
+
+  const sorted = _sortNumbers(values)
+
+  pcs.forEach(pc => {
+    // Floating pos in the range of [0; length - 1]
+    const pos = ((values.length - 1) * pc) / 100
+    const dec = pos % 1
+    const floorPos = Math.floor(pos)
+    const ceilPos = Math.ceil(pos)
+
+    r[pc] = _averageWeighted([sorted[floorPos]!, sorted[ceilPos]!], [1 - dec, dec])
+  })
+
+  return r
+}
+
 /**
  * @example
  *

package/src/math/sma.ts

@@ -2,7 +2,7 @@
  * Implements a Simple Moving Average algorithm.
  */
 export class SimpleMovingAverage {
-  constructor(public size: number, public data: number[] = []) {}
+  constructor(public readonly size: number, public readonly data: number[] = []) {}
 
   /**
    * Next index of array to push to

package/src/math/stack.util.ts

@@ -0,0 +1,94 @@
+import { _average, _percentile, _percentiles, _range } from '../index'
+
+/**
+ * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
+ * Like an array of a fixed size. When it runs out of space - it starts writing on top of itself
+ * from index 0.
+ *
+ *
+ */
+export class Stack<T> {
+  constructor(public readonly size: number) {}
+
+  /**
+   * Index of a slot to get written TO next.
+   * Currently this slot contains OLDEST item (if any).
+   */
+  private nextIndex = 0
+
+  readonly items: T[] = []
+
+  push(item: T): this {
+    this.items[this.nextIndex] = item
+    this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1
+    return this
+  }
+
+  /**
+   * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
+   */
+  fill(item: T): this {
+    _range(this.size).forEach(i => (this.items[i] = item))
+    return this
+  }
+
+  /**
+   * Returns last items in the right order.
+   * Unlike raw `items` property that returns "items buffer" as-is (not ordered properly).
+   */
+  get itemsOrdered(): T[] {
+    if (this.items.length < this.size) {
+      // Buffer is not filled yet, just return it as-is
+      return this.items
+    }
+
+    // Buffer was filled and started to "overwrite itself", will need to return 2 slices
+    return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)]
+  }
+}
+
+/**
+ * Fixed-size FILO stack of Numbers.
+ * Has convenience stat methods, e.g percentile, avg, etc.
+ */
+export class NumberStack extends Stack<number> {
+  avg(): number {
+    // _assert(this.items.length, 'NumberStack.avg cannot be called on empty stack')
+    return _average(this.items)
+  }
+
+  /**
+   * Returns null if Stack is empty.
+   */
+  avgOrNull(): number | null {
+    return this.items.length === 0 ? null : _average(this.items)
+  }
+
+  median(): number {
+    return _percentile(this.items, 50)
+  }
+
+  medianOrNull(): number | null {
+    return this.items.length === 0 ? null : _percentile(this.items, 50)
+  }
+
+  /**
+   * `pc` is a number from 0 to 100 inclusive.
+   */
+  percentile(pc: number): number {
+    // _assert(this.items.length, 'NumberStack.percentile cannot be called on empty stack')
+    return _percentile(this.items, pc)
+  }
+
+  /**
+   * `pc` is a number from 0 to 100 inclusive.
+   * Returns null if Stack is empty.
+   */
+  percentileOrNull(pc: number): number | null {
+    return this.items.length === 0 ? null : _percentile(this.items, pc)
+  }
+
+  percentiles(pcs: number[]): Record<number, number> {
+    return _percentiles(this.items, pcs)
+  }
+}

package/src/number/number.util.ts

@@ -65,7 +65,7 @@ export function _toFixed(n: number, fractionDigits: number): number {
  * _toPrecision(1634.56, 1)
  * // 2000
  *
- * _toPrecision(1234.56, 2)
+ * _toPrecision(1634.56, 2)
  * // 1600
  */
 export function _toPrecision(n: number, precision: number): number {

package/src/seq/seq.ts

@@ -1,4 +1,11 @@
-import { AbortableMapper, AbortablePredicate, END, SKIP } from '../types'
+import {
+  AbortableAsyncMapper,
+  AbortableAsyncPredicate,
+  AbortableMapper,
+  AbortablePredicate,
+  END,
+  SKIP,
+} from '../types'
 
 /**
  * Inspired by Kotlin Sequences.
@@ -8,7 +15,7 @@ import { AbortableMapper, AbortablePredicate, END, SKIP } from '../types'
  *
  * @experimental
  */
-export class Seq<T> implements Iterable<T> {
+export class Sequence<T> implements Iterable<T> {
   private constructor(initialValue: T | typeof END, private nextFn: AbortableMapper<T, T>) {
     this.currentValue = initialValue
   }
@@ -22,29 +29,29 @@ export class Seq<T> implements Iterable<T> {
     }
   }
 
-  static create<T>(initialValue: T | typeof END, nextFn: AbortableMapper<T, T>): Seq<T> {
-    return new Seq(initialValue, nextFn)
+  static create<T>(initialValue: T | typeof END, nextFn: AbortableMapper<T, T>): Sequence<T> {
+    return new Sequence(initialValue, nextFn)
   }
 
-  static range(minIncl: number, maxExcl: number, step = 1): Seq<number> {
+  static range(minIncl: number, maxExcl: number, step = 1): Sequence<number> {
     const max = maxExcl - step
-    return new Seq(minIncl, n => (n < max ? n + step : END))
+    return new Sequence(minIncl, n => (n < max ? n + step : END))
   }
 
-  static from<T>(a: Iterable<T>): Seq<T> {
+  static from<T>(a: Iterable<T>): Sequence<T> {
     const it = a[Symbol.iterator]()
     const v = it.next()
-    if (v.done) return new Seq<any>(END, () => {})
+    if (v.done) return new Sequence<any>(END, () => {})
 
-    return new Seq(v.value, () => {
+    return new Sequence(v.value, () => {
       const v = it.next()
       if (v.done) return END
       return v.value
     })
   }
 
-  static empty<T = any>(): Seq<T> {
-    return new Seq(END as any, () => {})
+  static empty<T = any>(): Sequence<T> {
+    return new Sequence(END as any, () => {})
   }
 
   private currentValue: T | typeof END
@@ -138,6 +145,120 @@ export class Seq<T> implements Iterable<T> {
 /**
  * Convenience function to create a Sequence.
  */
-export function _seq<T>(initialValue: T | typeof END, nextFn: AbortableMapper<T, T>): Seq<T> {
-  return Seq.create(initialValue, nextFn)
+export function _seq<T>(initialValue: T | typeof END, nextFn: AbortableMapper<T, T>): Sequence<T> {
+  return Sequence.create(initialValue, nextFn)
+}
+
+/* eslint-disable no-await-in-loop */
+
+/**
+ * Experimental.
+ * Feasibility to be proven.
+ *
+ * @experimental
+ */
+export class AsyncSequence<T> implements AsyncIterable<T> {
+  private constructor(initialValue: T | typeof END, private nextFn: AbortableAsyncMapper<T, T>) {
+    this.currentValue = initialValue
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: async () => {
+        const value = await this.next()
+        return value === END ? { done: true, value: undefined } : { value }
+      },
+    }
+  }
+
+  static create<T>(
+    initialValue: T | typeof END,
+    nextFn: AbortableAsyncMapper<T, T>,
+  ): AsyncSequence<T> {
+    return new AsyncSequence(initialValue, nextFn)
+  }
+
+  static async from<T>(a: AsyncIterable<T>): Promise<AsyncSequence<T>> {
+    const it = a[Symbol.asyncIterator]()
+    const v = await it.next()
+    if (v.done) return new AsyncSequence<any>(END, () => {})
+
+    return new AsyncSequence(v.value, async () => {
+      const v = await it.next()
+      if (v.done) return END
+      return v.value
+    })
+  }
+
+  static empty<T = any>(): AsyncSequence<T> {
+    return new AsyncSequence(END as any, () => {})
+  }
+
+  private currentValue: T | typeof END
+  private sentInitialValue = false
+  private i = -1
+
+  async next(): Promise<T | typeof END> {
+    if (this.currentValue === END) return END
+
+    this.i++
+
+    let v: T | typeof SKIP | typeof END
+
+    if (!this.sentInitialValue) {
+      this.sentInitialValue = true
+      v = this.currentValue
+    } else {
+      v = await this.nextFn(this.currentValue, this.i)
+    }
+
+    // console.log(`_seq`, v)
+
+    if (v === SKIP) return await this.next()
+
+    return (this.currentValue = v)
+  }
+
+  // Final functions - return final value, not a chained sequence
+  async find(predicate: AbortableAsyncPredicate<T>): Promise<T | undefined> {
+    do {
+      const v = await this.next()
+      if (v === END) return // not found, end of sequence
+      const r = await predicate(v, this.i)
+      if (r === END) return
+      if (r) return v
+      // otherwise proceed
+    } while (true) // eslint-disable-line no-constant-condition
+  }
+
+  async some(predicate: AbortableAsyncPredicate<T>): Promise<boolean> {
+    do {
+      const v = await this.next()
+      if (v === END) return false
+      const r = await predicate(v, this.i)
+      if (r === END) return false
+      if (r) return true
+    } while (true) // eslint-disable-line no-constant-condition
+  }
+
+  async every(predicate: AbortableAsyncPredicate<T>): Promise<boolean> {
+    do {
+      const v = await this.next()
+      if (v === END) return true
+      const r = await predicate(v, this.i)
+      if (r === END) return true
+      if (!r) return false
+    } while (true) // eslint-disable-line no-constant-condition
+  }
+
+  async toArray(): Promise<T[]> {
+    const a: T[] = []
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const v = await this.next()
+      if (v === END) return a
+      a.push(v)
+    }
+  }
 }