@naturalcycles/js-lib 14.73.0 → 14.76.0

package/dist-esm/seq/seq.js

@@ -1,4 +1,4 @@
-import { END, SKIP } from '../types';
+import { END, SKIP, } from '../types';
 /**
  * Inspired by Kotlin Sequences.
  * Similar to arrays, but with lazy evaluation, abortable.
@@ -7,7 +7,7 @@ import { END, SKIP } from '../types';
  *
  * @experimental
  */
-export class Seq {
+export class Sequence {
     constructor(initialValue, nextFn) {
         this.nextFn = nextFn;
         this.sentInitialValue = false;
@@ -23,18 +23,18 @@ export class Seq {
         };
     }
     static create(initialValue, nextFn) {
-        return new Seq(initialValue, nextFn);
+        return new Sequence(initialValue, nextFn);
     }
     static range(minIncl, maxExcl, step = 1) {
         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(a) {
         const it = a[Symbol.iterator]();
         const v = it.next();
         if (v.done)
-            return new Seq(END, () => { });
-        return new Seq(v.value, () => {
+            return new Sequence(END, () => { });
+        return new Sequence(v.value, () => {
             const v = it.next();
             if (v.done)
                 return END;
@@ -42,7 +42,7 @@ export class Seq {
         });
     }
     static empty() {
-        return new Seq(END, () => { });
+        return new Sequence(END, () => { });
     }
     next() {
         if (this.currentValue === END)
@@ -127,10 +127,126 @@ export class Seq {
             a.push(v);
         }
     }
+    forEach(fn) {
+        let i = -1;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const v = this.next();
+            if (v === END)
+                return;
+            fn(v, ++i);
+        }
+    }
 }
 /**
  * Convenience function to create a Sequence.
  */
 export function _seq(initialValue, nextFn) {
-    return Seq.create(initialValue, nextFn);
+    return Sequence.create(initialValue, nextFn);
+}
+/* eslint-disable no-await-in-loop */
+/**
+ * Experimental.
+ * Feasibility to be proven.
+ *
+ * @experimental
+ */
+export class AsyncSequence {
+    constructor(initialValue, nextFn) {
+        this.nextFn = nextFn;
+        this.sentInitialValue = false;
+        this.i = -1;
+        this.currentValue = initialValue;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const value = await this.next();
+                return value === END ? { done: true, value: undefined } : { value };
+            },
+        };
+    }
+    static create(initialValue, nextFn) {
+        return new AsyncSequence(initialValue, nextFn);
+    }
+    static async from(a) {
+        const it = a[Symbol.asyncIterator]();
+        const v = await it.next();
+        if (v.done)
+            return new AsyncSequence(END, () => { });
+        return new AsyncSequence(v.value, async () => {
+            const v = await it.next();
+            if (v.done)
+                return END;
+            return v.value;
+        });
+    }
+    static empty() {
+        return new AsyncSequence(END, () => { });
+    }
+    async next() {
+        if (this.currentValue === END)
+            return END;
+        this.i++;
+        let v;
+        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) {
+        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) {
+        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) {
+        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() {
+        const a = [];
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const v = await this.next();
+            if (v === END)
+                return a;
+            a.push(v);
+        }
+    }
 }

package/dist-esm/string/stringifyAny.js

@@ -41,17 +41,19 @@ export function _stringifyAny(obj, opt = {}) {
         //
         // Error or ErrorObject
         //
+        // 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
+        // }
+        s = [obj.name, obj.message].join(': ');
         if (opt.includeErrorStack && obj.stack) {
-            // Stack includes message
-            s = obj.stack;
-        }
-        else {
-            // 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
-            // }
-            s = [obj.name, obj.message].join(': ');
+            // 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
+            s = [s, ...obj.stack.split('\n').slice(1)].join('\n');
         }
         if (_isErrorObject(obj)) {
             if (_isHttpErrorObject(obj)) {

package/dist-esm/unit/size.util.js

@@ -1,8 +1,8 @@
 export function _gb(b) {
-    return Math.round(b / (1024 * 1024 * 1024));
+    return Math.round(b / 1024 ** 3);
 }
 export function _mb(b) {
-    return Math.round(b / (1024 * 1024));
+    return Math.round(b / 1024 ** 2);
 }
 export function _kb(b) {
     return Math.round(b / 1024);
@@ -11,11 +11,33 @@ export function _kb(b) {
  * Byte size to Human byte size string
  */
 export function _hb(b = 0) {
-    if (b < 800)
-        return `${Math.round(b)} byte(s)`;
-    if (b < 800 * 1024)
-        return `${Math.round(b / 1024)} Kb`;
-    if (b < 800 * 1024 * 1024)
-        return `${Math.round(b / 1024 / 1024)} Mb`;
-    return `${Math.round(b / 1024 / 1024 / 1024)} Gb`;
+    if (b < 1024)
+        return `${Math.round(b)} byte`;
+    if (b < 1024 ** 2)
+        return `${(b / 1024).toPrecision(3)} Kb`;
+    if (b < 1024 ** 3)
+        return `${(b / 1024 ** 2).toPrecision(3)} Mb`;
+    if (b < 1024 ** 4)
+        return `${(b / 1024 ** 3).toPrecision(3)} Gb`;
+    if (b < 1024 ** 5)
+        return `${(b / 1024 ** 4).toPrecision(3)} Tb`;
+    return `${Math.round(b / 1024 ** 4)} Tb`;
+}
+/**
+ * hc stands for "human count", similar to "human bytes" `_hb` function.
+ * Helpful to print big numbers, as it adds `K` (kilo), `M` (mega), etc to make
+ * them more readable.
+ */
+export function _hc(c = 0) {
+    if (c < 10 ** 4)
+        return String(c);
+    if (c < 10 ** 6)
+        return (c / 10 ** 3).toPrecision(3) + ' K';
+    if (c < 10 ** 9)
+        return (c / 10 ** 6).toPrecision(3) + ' M'; // million
+    if (c < 10 ** 12)
+        return (c / 10 ** 9).toPrecision(3) + ' B'; // billion
+    if (c < 10 ** 15)
+        return (c / 10 ** 12).toPrecision(3) + ' T'; // trillion
+    return Math.round(c / 10 ** 12) + ' T';
 }

package/package.json

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

package/src/decorators/logMethod.decorator.ts

@@ -1,4 +1,4 @@
-import { SimpleMovingAverage, _stringifyAny, CommonLogger } from '..'
+import { SimpleMovingAverage, _stringifyAny, CommonLogger, _assert } from '..'
 import { _ms } from '../time/time.util'
 import { _getArgsSignature, _getMethodSignature } from './decorator.util'
 
@@ -69,9 +69,7 @@ export interface LogMethodOptions {
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
   return (target, key, descriptor) => {
-    if (typeof descriptor.value !== 'function') {
-      throw new TypeError('@_LogMethod can be applied only to methods')
-    }
+    _assert(typeof descriptor.value === 'function', '@_LogMethod can be applied only to methods')
 
     const originalFn = descriptor.value
     const keyStr = String(key)

package/src/decorators/timeout.decorator.ts

@@ -1,10 +1,21 @@
+import { _assert } from '../error/assert'
 import { pTimeout, PTimeoutOptions } from '../promise/pTimeout'
+import { _getMethodSignature } from './decorator.util'
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Timeout(opt: PTimeoutOptions): MethodDecorator {
   return (target, key, descriptor) => {
+    _assert(typeof descriptor.value === 'function', '@_Timeout can be applied only to methods')
+
     const originalFn = descriptor.value
-    descriptor.value = pTimeout(originalFn as any, opt)
+    const keyStr = String(key)
+
+    descriptor.value = async function (this: typeof target, ...args: any[]) {
+      const ctx = this
+      opt.name ||= _getMethodSignature(ctx, keyStr)
+      return await pTimeout(originalFn.apply(this, args), opt)
+    } as any
+
     return descriptor
   }
 }

package/src/error/try.ts

@@ -1,3 +1,6 @@
+import { AnyFunction } from '../types'
+import { AppError } from './app.error'
+
 /**
  * Calls a function, returns a Tuple of [error, value].
  * Allows to write shorter code that avoids `try/catch`.
@@ -42,3 +45,44 @@ export async function pTry<ERR = unknown, RETURN = void>(
     return [err as ERR, undefined as any]
   }
 }
+
+/**
+ * It is thrown when Error was expected, but didn't happen
+ * ("pass" happened instead).
+ * "Pass" means "no error".
+ */
+export class UnexpectedPassError extends AppError {
+  constructor() {
+    super('_expectedError passed unexpectedly')
+  }
+}
+
+/**
+ * Calls `fn`, expects is to throw, catches the expected error and returns.
+ * If error was NOT thrown - throws UnexpectedPassError instead.
+ */
+export function _expectedError<ERR = Error>(fn: AnyFunction): ERR {
+  try {
+    fn()
+    // Unexpected!
+    throw new UnexpectedPassError()
+  } catch (err) {
+    if (err instanceof UnexpectedPassError) throw err // re-throw
+    return err as ERR // this is expected!
+  }
+}
+
+/**
+ * Awaits passed `promise`, expects is to throw (reject), catches the expected error and returns.
+ * If error was NOT thrown - throws UnexpectedPassError instead.
+ */
+export async function pExpectedError<ERR = Error>(promise: Promise<any>): Promise<ERR> {
+  try {
+    await promise
+    // Unexpected!
+    throw new UnexpectedPassError()
+  } catch (err) {
+    if (err instanceof UnexpectedPassError) throw err // re-throw
+    return err as ERR // this is expected!
+  }
+}

package/src/index.ts

@@ -7,26 +7,17 @@ import {
   PromiseDecoratorResp,
   _createPromiseDecorator,
 } from './decorators/createPromiseDecorator'
-import { _debounce, _throttle } from './decorators/debounce'
-import { _Debounce, _Throttle } from './decorators/debounce.decorator'
-import { _getArgsSignature } from './decorators/decorator.util'
-import { _LogMethod } from './decorators/logMethod.decorator'
-import { _Memo } from './decorators/memo.decorator'
+export * from './decorators/debounce'
+export * from './decorators/debounce.decorator'
+export * from './decorators/decorator.util'
+export * from './decorators/logMethod.decorator'
+export * from './decorators/memo.decorator'
 import { MemoCache } from './decorators/memo.util'
-import { _memoFn } from './decorators/memoFn'
-import { _Retry } from './decorators/retry.decorator'
-import { _Timeout } from './decorators/timeout.decorator'
-import { AppError } from './error/app.error'
-import {
-  AssertionError,
-  _assert,
-  _assertDeepEquals,
-  _assertEquals,
-  _assertIsError,
-  _assertIsNumber,
-  _assertIsString,
-  _assertTypeOf,
-} from './error/assert'
+export * from './decorators/memoFn'
+export * from './decorators/retry.decorator'
+export * from './decorators/timeout.decorator'
+export * from './error/app.error'
+export * from './error/assert'
 import {
   Admin401ErrorData,
   Admin403ErrorData,
@@ -37,11 +28,11 @@ import {
 } from './error/error.model'
 export * from './error/error.util'
 import { ErrorMode } from './error/errorMode'
-import { HttpError } from './error/http.error'
-import { _try, pTry } from './error/try'
+export * from './error/http.error'
+export * from './error/try'
 import { TryCatchOptions, _TryCatch, _tryCatch } from './error/tryCatch'
-import { generateJsonSchemaFromData } from './json-schema/from-data/generateJsonSchemaFromData'
-import { JSON_SCHEMA_ORDER } from './json-schema/jsonSchema.cnst'
+export * from './json-schema/from-data/generateJsonSchemaFromData'
+export * from './json-schema/jsonSchema.cnst'
 import {
   JsonSchema,
   JsonSchemaAllOf,
@@ -61,7 +52,7 @@ import {
   JsonSchemaString,
   JsonSchemaTuple,
 } from './json-schema/jsonSchema.model'
-import { mergeJsonSchemaObjects } from './json-schema/jsonSchema.util'
+export * from './json-schema/jsonSchema.util'
 import {
   jsonSchema,
   JsonSchemaAnyBuilder,
@@ -85,13 +76,13 @@ import { pMap, PMapOptions } from './promise/pMap'
 export * from './promise/pProps'
 import { pRetry, PRetryOptions } from './promise/pRetry'
 export * from './promise/pState'
-import { pTimeout, PTimeoutOptions } from './promise/pTimeout'
+import { pTimeout, pTimeoutFn, PTimeoutOptions } from './promise/pTimeout'
 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'
+export * from './time/time.util'
 import {
   Class,
   ConditionalExcept,
@@ -144,7 +135,7 @@ import {
   _stringMapEntries,
   _stringMapValues,
 } from './types'
-import { _gb, _hb, _kb, _mb } from './unit/size.util'
+export * from './unit/size.util'
 import { is } from './vendor/is'
 import {
   CommonLogLevel,
@@ -158,7 +149,7 @@ import {
   CommonLogWithLevelFunction,
   commonLoggerCreate,
 } from './log/commonLogger'
-import { _safeJsonStringify } from './string/safeJsonStringify'
+export * from './string/safeJsonStringify'
 import { PQueue, PQueueCfg } from './promise/pQueue'
 export * from './seq/seq'
 export * from './math/stack.util'
@@ -245,28 +236,10 @@ export type {
 
 export {
   is,
-  _Memo,
-  _memoFn,
-  _LogMethod,
-  _getArgsSignature,
   _createPromiseDecorator,
-  AppError,
-  HttpError,
-  AssertionError,
-  _assert,
-  _assertEquals,
-  _assertDeepEquals,
-  _assertIsError,
-  _assertIsString,
-  _assertIsNumber,
-  _assertTypeOf,
   _stringMapValues,
   _stringMapEntries,
   _objectKeys,
-  _debounce,
-  _throttle,
-  _Debounce,
-  _Throttle,
   pMap,
   _passthroughMapper,
   _passUndefinedMapper,
@@ -278,31 +251,18 @@ export {
   AggregatedError,
   pRetry,
   pTimeout,
-  _Retry,
-  _Timeout,
+  pTimeoutFn,
   _tryCatch,
   _TryCatch,
-  _try,
-  pTry,
   _stringifyAny,
-  _ms,
-  _since,
-  _hb,
-  _gb,
-  _mb,
-  _kb,
-  mergeJsonSchemaObjects,
   jsonSchema,
   JsonSchemaAnyBuilder,
-  JSON_SCHEMA_ORDER,
-  generateJsonSchemaFromData,
   commonLoggerMinLevel,
   commonLoggerNoop,
   commonLogLevelNumber,
   commonLoggerPipe,
   commonLoggerPrefix,
   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/stack.util.ts

@@ -1,4 +1,4 @@
-import { _average, _percentile, _range } from '../index'
+import { _average, _percentile, _percentiles, _range } from '../index'
 
 /**
  * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
@@ -64,6 +64,14 @@ export class NumberStack extends Stack<number> {
     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.
    */
@@ -80,11 +88,7 @@ export class NumberStack extends Stack<number> {
     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)
+  percentiles(pcs: number[]): Record<number, number> {
+    return _percentiles(this.items, pcs)
   }
 }

package/src/promise/pTimeout.ts

@@ -1,5 +1,8 @@
+import { AppError } from '../error/app.error'
 import { AnyFunction } from '../types'
 
+export class TimeoutError extends AppError {}
+
 export interface PTimeoutOptions {
   /**
    * Timeout in milliseconds.
@@ -24,37 +27,46 @@ export interface PTimeoutOptions {
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export function pTimeout<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
-  // const fname = fn.name || 'function'
+export function pTimeoutFn<T extends AnyFunction>(fn: T, opt: PTimeoutOptions): T {
+  opt.name ||= fn.name
+
+  return async function pTimeoutInternalFn(this: any, ...args: any[]) {
+    return await pTimeout(fn.apply(this, args), opt)
+  } as any
+}
+
+/**
+ * Decorates a Function with a timeout and immediately calls it.
+ * Throws an Error if the Function is not resolved in a certain time.
+ * If the Function rejects - passes this rejection further.
+ */
+export async function pTimeout<T>(promise: Promise<T>, opt: PTimeoutOptions): Promise<T> {
+  // todo: check how we can automatically infer function name (only applicable to named functions)
   const { timeout, name, onTimeout } = opt
 
-  return async function (this: any, ...args: any[]) {
-    // eslint-disable-next-line no-async-promise-executor
-    return await new Promise(async (resolve, reject) => {
-      // Prepare the timeout timer
-      const timer = setTimeout(() => {
-        if (onTimeout) {
-          try {
-            resolve(onTimeout())
-          } catch (err) {
-            reject(err)
-          }
-          return
+  // eslint-disable-next-line no-async-promise-executor
+  return await new Promise(async (resolve, reject) => {
+    // Prepare the timeout timer
+    const timer = setTimeout(() => {
+      if (onTimeout) {
+        try {
+          resolve(onTimeout())
+        } catch (err) {
+          reject(err)
         }
-
-        reject(
-          new Error(`"${name || fn.name || 'pTimeout function'}" timed out after ${timeout} ms`),
-        )
-      }, timeout)
-
-      // Execute the Function
-      try {
-        resolve(await fn.apply(this, args))
-      } catch (err) {
-        reject(err)
-      } finally {
-        clearTimeout(timer)
+        return
       }
-    })
-  } as any
+
+      reject(new TimeoutError(`"${name || 'pTimeout function'}" timed out after ${timeout} ms`))
+    }, timeout)
+
+    // Execute the Function
+    try {
+      resolve(await promise)
+    } catch (err) {
+      reject(err)
+    } finally {
+      clearTimeout(timer)
+    }
+  })
 }