@naturalcycles/js-lib 14.70.2 → 14.74.0

package/dist-esm/seq/seq.js

@@ -0,0 +1,136 @@
+import { END, SKIP } from '../types';
+/**
+ * Inspired by Kotlin Sequences.
+ * Similar to arrays, but with lazy evaluation, abortable.
+ * Can be useful when it's not feasible/performant to create an array of values to iterate upfront
+ * (e.g to construct 1000 Dayjs instances only to find that 2 of them were needed).
+ *
+ * @experimental
+ */
+export class Seq {
+    constructor(initialValue, nextFn) {
+        this.nextFn = nextFn;
+        this.sentInitialValue = false;
+        this.i = -1;
+        this.currentValue = initialValue;
+    }
+    [Symbol.iterator]() {
+        return {
+            next: () => {
+                const value = this.next();
+                return value === END ? { done: true, value: undefined } : { value };
+            },
+        };
+    }
+    static create(initialValue, nextFn) {
+        return new Seq(initialValue, nextFn);
+    }
+    static range(minIncl, maxExcl, step = 1) {
+        const max = maxExcl - step;
+        return new Seq(minIncl, n => (n < max ? n + step : END));
+    }
+    static from(a) {
+        const it = a[Symbol.iterator]();
+        const v = it.next();
+        if (v.done)
+            return new Seq(END, () => { });
+        return new Seq(v.value, () => {
+            const v = it.next();
+            if (v.done)
+                return END;
+            return v.value;
+        });
+    }
+    static empty() {
+        return new Seq(END, () => { });
+    }
+    next() {
+        if (this.currentValue === END)
+            return END;
+        this.i++;
+        let v;
+        if (!this.sentInitialValue) {
+            this.sentInitialValue = true;
+            v = this.currentValue;
+        }
+        else {
+            v = this.nextFn(this.currentValue, this.i);
+        }
+        // console.log(`_seq`, v)
+        if (v === SKIP)
+            return this.next();
+        return (this.currentValue = v);
+    }
+    // Chainable functions - return another (chained) Sequence
+    // map<OUT>(mapper: Mapper<T, OUT | typeof SKIP | typeof END>): Seq<OUT> {
+    //   if (this.currentValue === END) return this as any
+    //
+    //   // Iterate until first valid value, to have as `initialValue` of the new Sequence
+    //   let v: OUT | typeof SKIP | typeof END
+    //
+    //   while (true) {
+    //     v = mapper(this.currentValue, ++this.i)
+    //     if (v === SKIP) continue
+    //     if (v === END) return this as any
+    //   }
+    //
+    //   return new Seq<OUT>(v as OUT, (current, i) => {
+    //     const v = mapper(current, i)
+    //
+    //   })
+    // }
+    // Final functions - return final value, not a chained sequence
+    find(predicate) {
+        do {
+            const v = this.next();
+            if (v === END)
+                return; // not found, end of sequence
+            const r = predicate(v, this.i);
+            if (r === END)
+                return;
+            if (r)
+                return v;
+            // otherwise proceed
+        } while (true); // eslint-disable-line no-constant-condition
+    }
+    some(predicate) {
+        do {
+            const v = this.next();
+            if (v === END)
+                return false;
+            const r = predicate(v, this.i);
+            if (r === END)
+                return false;
+            if (r)
+                return true;
+        } while (true); // eslint-disable-line no-constant-condition
+    }
+    every(predicate) {
+        do {
+            const v = this.next();
+            if (v === END)
+                return true;
+            const r = predicate(v, this.i);
+            if (r === END)
+                return true;
+            if (!r)
+                return false;
+        } while (true); // eslint-disable-line no-constant-condition
+    }
+    toArray() {
+        const a = [];
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const v = this.next();
+            if (v === END)
+                return a;
+            a.push(v);
+        }
+    }
+}
+/**
+ * Convenience function to create a Sequence.
+ */
+export function _seq(initialValue, nextFn) {
+    return Seq.create(initialValue, nextFn);
+}

package/dist-esm/types.js

@@ -1,3 +1,11 @@
+/**
+ * Symbol to indicate END of Sequence.
+ */
+export const END = Symbol('END');
+/**
+ * Symbol to indicate SKIP of item (e.g in AbortableMapper)
+ */
+export const SKIP = Symbol('SKIP');
 export const _passthroughMapper = item => item;
 export const _passUndefinedMapper = () => undefined;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.70.2",
+  "version": "14.74.0",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/error/try.ts

@@ -24,6 +24,9 @@ export function _try<ERR = unknown, RETURN = void>(
   }
 }
 
+// todo: remove when eslint starts to know about Awaited
+/* eslint-disable no-undef */
+
 /**
  * Like _try, but for Promises.
  *
@@ -32,7 +35,7 @@ export function _try<ERR = unknown, RETURN = void>(
  */
 export async function pTry<ERR = unknown, RETURN = void>(
   promise: Promise<RETURN>,
-): Promise<[err: ERR | null, value: RETURN]> {
+): Promise<[err: ERR | null, value: Awaited<RETURN>]> {
   try {
     return [null, await promise]
   } catch (err) {

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 {
@@ -173,7 +98,6 @@ import {
   ConditionalPick,
   Merge,
   Promisable,
-  PromiseValue,
   ReadonlyDeep,
   Simplify,
 } from './typeFest'
@@ -205,6 +129,12 @@ import {
   UnixTimestamp,
   ValueOf,
   ValuesOf,
+  AbortableMapper,
+  AbortableAsyncPredicate,
+  AbortableAsyncMapper,
+  AbortablePredicate,
+  END,
+  SKIP,
   _noop,
   _objectKeys,
   _passNothingPredicate,
@@ -230,8 +160,14 @@ import {
 } from './log/commonLogger'
 import { _safeJsonStringify } from './string/safeJsonStringify'
 import { PQueue, PQueueCfg } from './promise/pQueue'
+export * from './seq/seq'
+export * from './math/stack.util'
 
 export type {
+  AbortableMapper,
+  AbortablePredicate,
+  AbortableAsyncPredicate,
+  AbortableAsyncMapper,
   PQueueCfg,
   MemoCache,
   PromiseDecoratorCfg,
@@ -270,7 +206,6 @@ export type {
   Merge,
   ReadonlyDeep,
   Promisable,
-  PromiseValue,
   Simplify,
   ConditionalPick,
   ConditionalExcept,
@@ -325,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,
@@ -415,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,
@@ -441,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,
@@ -465,4 +304,6 @@ export {
   commonLoggerCreate,
   _safeJsonStringify,
   PQueue,
+  END,
+  SKIP,
 }

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/promise/pBatch.ts

@@ -1,5 +1,4 @@
-import { BatchResult, ErrorMode } from '..'
-import { AsyncMapper } from '../types'
+import { AbortableAsyncMapper, BatchResult, ErrorMode } from '..'
 import { AggregatedError } from './AggregatedError'
 import { pMap } from './pMap'
 
@@ -8,7 +7,7 @@ import { pMap } from './pMap'
  */
 export async function pBatch<IN, OUT>(
   iterable: Iterable<IN | PromiseLike<IN>>,
-  mapper: AsyncMapper<IN, OUT>,
+  mapper: AbortableAsyncMapper<IN, OUT>,
   opt?: { concurrency?: number },
 ): Promise<BatchResult<OUT>> {
   try {

package/src/promise/pFilter.ts

@@ -1,9 +1,9 @@
-import { AsyncPredicate } from '../types'
+import { AbortableAsyncPredicate } from '../types'
 import { pMap, PMapOptions } from './pMap'
 
 export async function pFilter<T>(
   iterable: Iterable<T | PromiseLike<T>>,
-  filterFn: AsyncPredicate<T>,
+  filterFn: AbortableAsyncPredicate<T>,
   opt?: PMapOptions,
 ): Promise<T[]> {
   const values = await pMap(