@naturalcycles/js-lib 14.70.1 → 14.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.70.1",
+  "version": "14.73.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/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,90 @@
+import { _average, _percentile, _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)
+  }
+
+  /**
+   * `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)
+  }
+
+  median(): number {
+    return _percentile(this.items, 50)
+  }
+
+  medianOrNull(): number | null {
+    return this.items.length === 0 ? null : _percentile(this.items, 50)
+  }
+}

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(

package/src/promise/pMap.ts

@@ -7,8 +7,7 @@ Improvements:
 - Compatible with pProps (that had typings issues)
  */
 
-import { ErrorMode } from '..'
-import { AsyncMapper } from '../types'
+import { AbortableAsyncMapper, END, ErrorMode, SKIP } from '..'
 import { AggregatedError } from './AggregatedError'
 
 export interface PMapOptions {
@@ -57,37 +56,38 @@ export interface PMapOptions {
  */
 export async function pMap<IN, OUT>(
   iterable: Iterable<IN | PromiseLike<IN>>,
-  mapper: AsyncMapper<IN, OUT>,
+  mapper: AbortableAsyncMapper<IN, OUT>,
   opt: PMapOptions = {},
 ): Promise<OUT[]> {
   return new Promise<OUT[]>((resolve, reject) => {
     const { concurrency = Number.POSITIVE_INFINITY, errorMode = ErrorMode.THROW_IMMEDIATELY } = opt
 
-    const ret: OUT[] = []
+    const ret: (OUT | typeof SKIP)[] = []
     const iterator = iterable[Symbol.iterator]()
     const errors: Error[] = []
-    let isRejected = false
+    let isSettled = false
     let isIterableDone = false
     let resolvingCount = 0
     let currentIndex = 0
 
-    const next = () => {
-      if (isRejected) {
+    const next = (skipped = false) => {
+      if (isSettled) {
         return
       }
 
       const nextItem = iterator.next()
       const i = currentIndex
-      currentIndex++
+      if (!skipped) currentIndex++
 
       if (nextItem.done) {
         isIterableDone = true
 
         if (resolvingCount === 0) {
+          const r = ret.filter(r => r !== SKIP) as OUT[]
           if (errors.length && errorMode === ErrorMode.THROW_AGGREGATED) {
-            reject(new AggregatedError(errors, ret))
+            reject(new AggregatedError(errors, r))
           } else {
-            resolve(ret)
+            resolve(r)
           }
         }
 
@@ -100,13 +100,18 @@ export async function pMap<IN, OUT>(
         .then(async element => await mapper(element, i))
         .then(
           value => {
+            if (value === END) {
+              isSettled = true
+              return resolve(ret.filter(r => r !== SKIP) as OUT[])
+            }
+
             ret[i] = value
             resolvingCount--
             next()
           },
           err => {
             if (errorMode === ErrorMode.THROW_IMMEDIATELY) {
-              isRejected = true
+              isSettled = true
               reject(err)
             } else {
               errors.push(err)

package/src/promise/pProps.ts

@@ -10,6 +10,9 @@ Improvements:
 
 import { pMap, PMapOptions } from './pMap'
 
+// todo: remove when eslint starts to know about Awaited
+/* eslint-disable no-undef */
+
 /**
  * Promise.all for Object instead of Array.
  * Supports concurrency.
@@ -17,13 +20,9 @@ import { pMap, PMapOptions } from './pMap'
 export async function pProps<T>(
   input: { [K in keyof T]: T[K] | Promise<T[K]> },
   opt?: PMapOptions,
-): Promise<T> {
+): Promise<{ [K in keyof T]: Awaited<T[K]> }> {
+  const r = {} as { [K in keyof T]: Awaited<T[K]> }
   const keys = Object.keys(input) as (keyof T)[]
-  const values = await pMap(Object.values(input), r => r, opt)
-
-  const r = {} as T
-  values.forEach((v, i) => {
-    r[keys[i]!] = v
-  })
+  await pMap(Object.values(input), (v, i) => (r[keys[i]!] = v), opt)
   return r
 }