@naturalcycles/js-lib 14.74.0 → 14.77.0

package/dist/seq/seq.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._seq = exports.Seq = void 0;
+exports.AsyncSequence = exports._seq = exports.Sequence = void 0;
 const types_1 = require("../types");
 /**
  * Inspired by Kotlin Sequences.
@@ -10,7 +10,7 @@ const types_1 = require("../types");
  *
  * @experimental
  */
-class Seq {
+class Sequence {
     constructor(initialValue, nextFn) {
         this.nextFn = nextFn;
         this.sentInitialValue = false;
@@ -26,18 +26,18 @@ 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 : types_1.END));
+        return new Sequence(minIncl, n => (n < max ? n + step : types_1.END));
     }
     static from(a) {
         const it = a[Symbol.iterator]();
         const v = it.next();
         if (v.done)
-            return new Seq(types_1.END, () => { });
-        return new Seq(v.value, () => {
+            return new Sequence(types_1.END, () => { });
+        return new Sequence(v.value, () => {
             const v = it.next();
             if (v.done)
                 return types_1.END;
@@ -45,7 +45,7 @@ class Seq {
         });
     }
     static empty() {
-        return new Seq(types_1.END, () => { });
+        return new Sequence(types_1.END, () => { });
     }
     next() {
         if (this.currentValue === types_1.END)
@@ -130,12 +130,129 @@ 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 === types_1.END)
+                return;
+            fn(v, ++i);
+        }
+    }
 }
-exports.Seq = Seq;
+exports.Sequence = Sequence;
 /**
  * Convenience function to create a Sequence.
  */
 function _seq(initialValue, nextFn) {
-    return Seq.create(initialValue, nextFn);
+    return Sequence.create(initialValue, nextFn);
 }
 exports._seq = _seq;
+/* eslint-disable no-await-in-loop */
+/**
+ * Experimental.
+ * Feasibility to be proven.
+ *
+ * @experimental
+ */
+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 === types_1.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(types_1.END, () => { });
+        return new AsyncSequence(v.value, async () => {
+            const v = await it.next();
+            if (v.done)
+                return types_1.END;
+            return v.value;
+        });
+    }
+    static empty() {
+        return new AsyncSequence(types_1.END, () => { });
+    }
+    async next() {
+        if (this.currentValue === types_1.END)
+            return types_1.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 === types_1.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 === types_1.END)
+                return; // not found, end of sequence
+            const r = await predicate(v, this.i);
+            if (r === types_1.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 === types_1.END)
+                return false;
+            const r = await predicate(v, this.i);
+            if (r === types_1.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 === types_1.END)
+                return true;
+            const r = await predicate(v, this.i);
+            if (r === types_1.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 === types_1.END)
+                return a;
+            a.push(v);
+        }
+    }
+}
+exports.AsyncSequence = AsyncSequence;

package/dist/string/stringifyAny.js

@@ -44,17 +44,19 @@ 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 ((0, error_util_1._isErrorObject)(obj)) {
             if ((0, error_util_1._isHttpErrorObject)(obj)) {

package/dist/unit/size.util.d.ts

@@ -5,3 +5,9 @@ export declare function _kb(b: number): number;
  * Byte size to Human byte size string
  */
 export declare function _hb(b?: number): string;
+/**
+ * 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 declare function _hc(c?: number): string;

package/dist/unit/size.util.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._hb = exports._kb = exports._mb = exports._gb = void 0;
+exports._hc = exports._hb = exports._kb = exports._mb = exports._gb = void 0;
 function _gb(b) {
-    return Math.round(b / (1024 * 1024 * 1024));
+    return Math.round(b / 1024 ** 3);
 }
 exports._gb = _gb;
 function _mb(b) {
-    return Math.round(b / (1024 * 1024));
+    return Math.round(b / 1024 ** 2);
 }
 exports._mb = _mb;
 function _kb(b) {
@@ -17,12 +17,35 @@ exports._kb = _kb;
  * Byte size to Human byte size string
  */
 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`;
 }
 exports._hb = _hb;
+/**
+ * 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.
+ */
+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';
+}
+exports._hc = _hc;

package/dist-esm/decorators/logMethod.decorator.js

@@ -1,4 +1,4 @@
-import { SimpleMovingAverage, _stringifyAny } from '..';
+import { SimpleMovingAverage, _stringifyAny, _assert } from '..';
 import { _ms } from '../time/time.util';
 import { _getArgsSignature, _getMethodSignature } from './decorator.util';
 /**
@@ -17,9 +17,7 @@ import { _getArgsSignature, _getMethodSignature } from './decorator.util';
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export function _LogMethod(opt = {}) {
     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);
         const { avg, noLogArgs, logStart, logResult, noLogResultLength, logger = console } = opt;

package/dist-esm/decorators/timeout.decorator.js

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

package/dist-esm/error/try.js

@@ -1,3 +1,4 @@
+import { AppError } from './app.error';
 /**
  * Calls a function, returns a Tuple of [error, value].
  * Allows to write shorter code that avoids `try/catch`.
@@ -38,3 +39,45 @@ export async function pTry(promise) {
         return [err, undefined];
     }
 }
+/**
+ * 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(fn) {
+    try {
+        fn();
+        // Unexpected!
+        throw new UnexpectedPassError();
+    }
+    catch (err) {
+        if (err instanceof UnexpectedPassError)
+            throw err; // re-throw
+        return 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(promise) {
+    try {
+        await promise;
+        // Unexpected!
+        throw new UnexpectedPassError();
+    }
+    catch (err) {
+        if (err instanceof UnexpectedPassError)
+            throw err; // re-throw
+        return err; // this is expected!
+    }
+}

package/dist-esm/index.js

@@ -3,24 +3,24 @@ export * from './lazy';
 export * from './string/url.util';
 export * from './array/range';
 import { _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';
-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/debounce';
+export * from './decorators/debounce.decorator';
+export * from './decorators/decorator.util';
+export * from './decorators/logMethod.decorator';
+export * from './decorators/memo.decorator';
+export * from './decorators/memoFn';
+export * from './decorators/retry.decorator';
+export * from './decorators/timeout.decorator';
+export * from './error/app.error';
+export * from './error/assert';
 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 { _TryCatch, _tryCatch } from './error/tryCatch';
-import { generateJsonSchemaFromData } from './json-schema/from-data/generateJsonSchemaFromData';
-import { JSON_SCHEMA_ORDER } from './json-schema/jsonSchema.cnst';
-import { mergeJsonSchemaObjects } from './json-schema/jsonSchema.util';
+export * from './json-schema/from-data/generateJsonSchemaFromData';
+export * from './json-schema/jsonSchema.cnst';
+export * from './json-schema/jsonSchema.util';
 import { jsonSchema, JsonSchemaAnyBuilder, } from './json-schema/jsonSchemaBuilder';
 export * from './math/math.util';
 export * from './math/sma';
@@ -40,19 +40,19 @@ import { pMap } from './promise/pMap';
 export * from './promise/pProps';
 import { pRetry } from './promise/pRetry';
 export * from './promise/pState';
-import { pTimeout } from './promise/pTimeout';
+import { pTimeout, pTimeoutFn } from './promise/pTimeout';
 export * from './promise/pTuple';
 export * from './string/case';
 export * from './string/json.util';
 export * from './string/string.util';
 import { _stringifyAny } from './string/stringifyAny';
-import { _ms, _since } from './time/time.util';
+export * from './time/time.util';
 import { END, SKIP, _noop, _objectKeys, _passNothingPredicate, _passthroughMapper, _passthroughPredicate, _passUndefinedMapper, _stringMapEntries, _stringMapValues, } from './types';
-import { _gb, _hb, _kb, _mb } from './unit/size.util';
+export * from './unit/size.util';
 import { is } from './vendor/is';
 import { commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, } from './log/commonLogger';
-import { _safeJsonStringify } from './string/safeJsonStringify';
+export * from './string/safeJsonStringify';
 import { PQueue } from './promise/pQueue';
 export * from './seq/seq';
 export * from './math/stack.util';
-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, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pTimeout, _Retry, _Timeout, _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, };
+export { is, _createPromiseDecorator, _stringMapValues, _stringMapEntries, _objectKeys, pMap, _passthroughMapper, _passUndefinedMapper, _passthroughPredicate, _passNothingPredicate, _noop, ErrorMode, pDefer, AggregatedError, pRetry, pTimeout, pTimeoutFn, _tryCatch, _TryCatch, _stringifyAny, jsonSchema, JsonSchemaAnyBuilder, commonLoggerMinLevel, commonLoggerNoop, commonLogLevelNumber, commonLoggerPipe, commonLoggerPrefix, commonLoggerCreate, PQueue, END, SKIP, };

package/dist-esm/promise/pRetry.js

@@ -5,7 +5,7 @@ import { _since, _stringifyAny } from '..';
  */
 // eslint-disable-next-line @typescript-eslint/ban-types
 export function pRetry(fn, opt = {}) {
-    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, } = opt;
+    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name = fn.name, } = opt;
     let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt;
     if (opt.logAll) {
         logFirstAttempt = logRetries = logFailures = true;
@@ -13,7 +13,7 @@ export function pRetry(fn, opt = {}) {
     if (opt.logNone) {
         logSuccess = logFirstAttempt = logRetries = logFailures = false;
     }
-    const fname = ['pRetry', fn.name].filter(Boolean).join('.');
+    const fname = ['pRetry', name].filter(Boolean).join('.');
     return async function (...args) {
         let delay = initialDelay;
         let attempt = 0;
@@ -33,9 +33,9 @@ export function pRetry(fn, opt = {}) {
                 }
                 catch (err) {
                     if (logFailures) {
-                        logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:\n${_stringifyAny(err, {
+                        logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, _stringifyAny(err, {
                             includeErrorData: true,
-                        })}`);
+                        }));
                     }
                     if (attempt >= maxAttempts || (predicate && !predicate(err, attempt, maxAttempts))) {
                         // Give up

package/dist-esm/promise/pTimeout.js

@@ -1,37 +1,49 @@
+import { AppError } from '../error/app.error';
+export class TimeoutError extends AppError {
+}
 /**
  * Decorates a Function with a timeout.
  * Throws an Error if the Function is not resolved in a certain time.
  * If the Function rejects - passes this rejection further.
  */
-export function pTimeout(fn, opt) {
-    // const fname = fn.name || 'function'
+export function pTimeoutFn(fn, opt) {
+    opt.name || (opt.name = fn.name);
+    return async function pTimeoutInternalFn(...args) {
+        return await pTimeout(fn.apply(this, args), opt);
+    };
+}
+/**
+ * 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(promise, opt) {
+    // todo: check how we can automatically infer function name (only applicable to named functions)
     const { timeout, name, onTimeout } = opt;
-    return async function (...args) {
-        // 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());
                 }
-                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);
+                catch (err) {
+                    reject(err);
+                }
+                return;
             }
-        });
-    };
+            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);
+        }
+    });
 }