@naturalcycles/js-lib 14.117.0 → 14.118.0

package/dist/array/array.util.js

@@ -160,24 +160,24 @@ function _findLast(items, predicate) {
 exports._findLast = _findLast;
 function _takeWhile(items, predicate) {
     let proceed = true;
-    return items.filter((v, index) => (proceed = proceed && predicate(v, index)));
+    return items.filter((v, index) => (proceed &&= predicate(v, index)));
 }
 exports._takeWhile = _takeWhile;
 function _takeRightWhile(items, predicate) {
     let proceed = true;
-    return [...items].reverse().filter((v, index) => (proceed = proceed && predicate(v, index)));
+    return [...items].reverse().filter((v, index) => (proceed &&= predicate(v, index)));
 }
 exports._takeRightWhile = _takeRightWhile;
 function _dropWhile(items, predicate) {
     let proceed = false;
-    return items.filter((v, index) => (proceed = proceed || !predicate(v, index)));
+    return items.filter((v, index) => (proceed ||= !predicate(v, index)));
 }
 exports._dropWhile = _dropWhile;
 function _dropRightWhile(items, predicate) {
     let proceed = false;
     return [...items]
         .reverse()
-        .filter((v, index) => (proceed = proceed || !predicate(v, index)))
+        .filter((v, index) => (proceed ||= !predicate(v, index)))
         .reverse();
 }
 exports._dropRightWhile = _dropRightWhile;

package/dist/datetime/dateInterval.js

@@ -49,6 +49,7 @@ class DateInterval {
      */
     includes(d, incl = '[]') {
         d = localDate_1.LocalDate.of(d);
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         return d.isAfter(this.start, incl[0] === '[') && d.isBefore(this.end, incl[1] === ']');
     }
     intersects(int, inclusive = true) {

package/dist/datetime/localDate.js

@@ -112,6 +112,7 @@ class LocalDate {
         const $min = LocalDate.of(min);
         const $max = LocalDate.of(max).startOf(stepUnit);
         let current = $min.startOf(stepUnit);
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (current.isAfter($min, incl[0] === '[')) {
             // ok
         }
@@ -170,6 +171,7 @@ class LocalDate {
     }
     isBetween(min, max, incl = '[)') {
         let r = this.cmp(min);
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (r < 0 || (r === 0 && incl[0] === '('))
             return false;
         r = this.cmp(max);

package/dist/datetime/localTime.js

@@ -347,6 +347,7 @@ class LocalTime {
     }
     isBetween(min, max, incl = '[)') {
         let r = this.cmp(min);
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (r < 0 || (r === 0 && incl[0] === '('))
             return false;
         r = this.cmp(max);
@@ -525,9 +526,7 @@ function getWeekYear(date) {
     else if (date.getTime() >= startOfThisYear.getTime()) {
         return year;
     }
-    else {
-        return year - 1;
-    }
+    return year - 1;
 }
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
 function startOfWeek(date, mutate = false) {

package/dist/datetime/timeInterval.js

@@ -59,6 +59,7 @@ class TimeInterval {
     }
     includes(d, incl = '[)') {
         d = localTime_1.LocalTime.parseToUnixTimestamp(d);
+        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
         if (d < this.$start || (d === this.$start && incl[0] === '('))
             return false;
         if (d > this.$end || (d === this.$end && incl[1] === ')'))

package/dist/decorators/asyncMemo.decorator.d.ts

@@ -6,11 +6,11 @@ export interface AsyncMemoOptions {
      * Function that creates an instance of `MemoCache`.
      * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`.
      */
-    cacheFactory?: () => AsyncMemoCache;
+    cacheFactory?(): AsyncMemoCache;
     /**
      * Provide a custom implementation of CacheKey function.
      */
-    cacheKeyFn?: (args: any[]) => any;
+    cacheKeyFn?(args: any[]): any;
     /**
      * Default true.
      *

package/dist/decorators/createPromiseDecorator.d.ts

@@ -4,15 +4,15 @@ export interface PromiseDecoratorCfg<RES = any, PARAMS = any> {
      * Called BEFORE the original function.
      * If Promise is returned - it will be awaited.
      */
-    beforeFn?: (r: PromiseDecoratorResp<PARAMS>) => void | Promise<void>;
+    beforeFn?(r: PromiseDecoratorResp<PARAMS>): void | Promise<void>;
     /**
      * Called just AFTER the original function.
      * The output of this hook will be passed further,
      * so, pay attention to pass through (or modify) the result.
      */
-    thenFn?: (r: PromiseDecoratorResp<PARAMS> & {
+    thenFn?(r: PromiseDecoratorResp<PARAMS> & {
         res: RES;
-    }) => RES;
+    }): RES;
     /**
      * Called on Promise.reject.
      * If `catchFn` is not present - will re-throw the error,
@@ -20,14 +20,14 @@ export interface PromiseDecoratorCfg<RES = any, PARAMS = any> {
      * If `catchFn` is present - it's responsible for handling or re-throwing the error.
      * Whatever `catchFn` returns - passed to the original output.
      */
-    catchFn?: (r: PromiseDecoratorResp<PARAMS> & {
+    catchFn?(r: PromiseDecoratorResp<PARAMS> & {
         err: any;
-    }) => RES;
+    }): RES;
     /**
      * Fires AFTER thenFn / catchFn, like a usual Promise.finally().
      * Doesn't have access to neither res nor err (same as Promise.finally).
      */
-    finallyFn?: (r: PromiseDecoratorResp<PARAMS>) => any;
+    finallyFn?(r: PromiseDecoratorResp<PARAMS>): any;
 }
 export interface PromiseDecoratorResp<PARAMS> {
     decoratorParams: PARAMS;

package/dist/decorators/logMethod.decorator.js

@@ -59,11 +59,9 @@ function _LogMethod(opt = {}) {
                         throw err;
                     });
                 }
-                else {
-                    // not a Promise
-                    logFinished(logger, callSignature, started, sma, logResultFn, res);
-                    return res;
-                }
+                // not a Promise
+                logFinished(logger, callSignature, started, sma, logResultFn, res);
+                return res;
             }
             catch (err) {
                 logFinished(logger, callSignature, started, sma, logResultFn, undefined, err);
@@ -74,6 +72,7 @@ function _LogMethod(opt = {}) {
     };
 }
 exports._LogMethod = _LogMethod;
+// eslint-disable-next-line max-params
 function logFinished(logger, callSignature, started, sma, logResultFn, res, err) {
     const millis = Date.now() - started;
     const t = ['<<', callSignature, 'took', (0, time_util_1._ms)(millis)];

package/dist/decorators/memo.decorator.d.ts

@@ -6,11 +6,11 @@ export interface MemoOptions {
      * Function that creates an instance of `MemoCache`.
      * e.g LRUMemoCache from `@naturalcycles/nodejs-lib`
      */
-    cacheFactory?: () => MemoCache;
+    cacheFactory?(): MemoCache;
     /**
      * Provide a custom implementation of CacheKey function.
      */
-    cacheKeyFn?: (args: any[]) => any;
+    cacheKeyFn?(args: any[]): any;
     /**
      * Defaults to true.
      * Set to false to skip caching errors.

package/dist/error/tryCatch.d.ts

@@ -5,7 +5,7 @@ export interface TryCatchOptions {
      * The value returned from the function will be returned from the wrapped method (!).
      * onError function may be asynchronous.
      */
-    onError?: (err: Error) => any;
+    onError?(err: Error): any;
     /**
      * @default false
      */

package/dist/http/fetcher.d.ts

@@ -0,0 +1,146 @@
+/// <reference lib="dom" />
+import { CommonLogger } from '../log/commonLogger';
+import type { Promisable } from '../typeFest';
+import type { HttpMethod, HttpStatusFamily } from './http.model';
+export interface FetcherNormalizedCfg extends FetcherCfg, FetcherNormalizedOptions {
+    logger: CommonLogger;
+}
+export interface FetcherCfg {
+    baseUrl?: string;
+    /**
+     * Default rule is that you **are allowed** to mutate req, res, res.retryStatus
+     * properties of hook function arguments.
+     * If you throw an error from the hook - it will be re-thrown as-is.
+     */
+    hooks?: {
+        /**
+         * Allows to mutate req.
+         */
+        beforeRequest?(req: FetcherRequest): Promisable<void>;
+        /**
+         * Allows to mutate res.
+         * If you set `res.err` - it will be thrown.
+         */
+        beforeResponse?(res: FetcherResponse): Promisable<void>;
+        /**
+         * Allows to mutate res.retryStatus to override retry behavior.
+         */
+        beforeRetry?(res: FetcherResponse): Promisable<void>;
+    };
+    debug?: boolean;
+    logRequest?: boolean;
+    logRequestBody?: boolean;
+    logResponse?: boolean;
+    logResponseBody?: boolean;
+    logger?: CommonLogger;
+}
+export interface FetcherRetryStatus {
+    retryAttempt: number;
+    retryTimeout: number;
+    retryStopped: boolean;
+}
+export interface FetcherRetryOptions {
+    count: number;
+    timeout: number;
+    timeoutMax: number;
+    timeoutMultiplier: number;
+}
+export interface FetcherNormalizedOptions extends FetcherOptions {
+    method: HttpMethod;
+    throwHttpErrors: boolean;
+    timeoutSeconds: number;
+    retry: FetcherRetryOptions;
+    retryPost: boolean;
+    retry4xx: boolean;
+    retry5xx: boolean;
+}
+export interface FetcherOptions {
+    method?: HttpMethod;
+    throwHttpErrors?: boolean;
+    /**
+     * Default: 30.
+     *
+     * Timeout applies to both get the response and retrieve the body (e.g `await res.json()`),
+     * so both should finish within this single timeout (not each).
+     */
+    timeoutSeconds?: number;
+    json?: any;
+    text?: string;
+    requestInit?: RequestInit & {
+        method?: HttpMethod;
+    };
+    mode?: FetcherMode;
+    /**
+     * Default is 2 retries (3 tries in total).
+     * Pass `retry: { count: 0 }` to disable retries.
+     */
+    retry?: Partial<FetcherRetryOptions>;
+    /**
+     * Defaults to false.
+     * Set to true to allow retrying `post` requests.
+     */
+    retryPost?: boolean;
+    /**
+     * Defaults to false.
+     */
+    retry4xx?: boolean;
+    /**
+     * Defaults to true.
+     */
+    retry5xx?: boolean;
+}
+export interface FetcherRequest {
+    url: string;
+    init: RequestInit & {
+        method: HttpMethod;
+    };
+    opt: FetcherNormalizedOptions;
+}
+export interface FetcherSuccessResponse<BODY = unknown> extends FetcherResponse<BODY> {
+    err?: undefined;
+    fetchResponse: Response;
+    body: BODY;
+}
+export interface FetcherErrorResponse<BODY = unknown> extends FetcherResponse<BODY> {
+    err: Error;
+}
+export interface FetcherResponse<BODY = unknown> {
+    err?: Error;
+    req: FetcherRequest;
+    fetchResponse?: Response;
+    statusFamily?: HttpStatusFamily;
+    body?: BODY;
+    retryStatus: FetcherRetryStatus;
+}
+export type FetcherMode = 'json' | 'text';
+/**
+ * Experimental wrapper around Fetch.
+ * Works in both Browser and Node, using `globalThis.fetch`.
+ *
+ * @experimental
+ */
+export declare class Fetcher {
+    private constructor();
+    cfg: FetcherNormalizedCfg;
+    static create(cfg?: FetcherCfg & FetcherOptions): Fetcher;
+    getJson<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
+    postJson<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
+    getText(url: string, opt?: FetcherOptions): Promise<string>;
+    postText(url: string, opt?: FetcherOptions): Promise<string>;
+    fetch<T = unknown>(url: string, opt?: FetcherOptions): Promise<T>;
+    rawFetch<T = unknown>(url: string, rawOpt?: FetcherOptions): Promise<FetcherResponse<T>>;
+    private processRetry;
+    /**
+     * Default is yes,
+     * unless there's reason not to (e.g method is POST).
+     */
+    private shouldRetry;
+    private getStatusFamily;
+    /**
+     * Returns url without baseUrl and before ?queryString
+     */
+    private getShortUrl;
+    private normalizeCfg;
+    private normalizeOptions;
+}
+export declare function getFetcher(cfg?: FetcherCfg & FetcherOptions): Fetcher;

package/dist/http/fetcher.js

@@ -0,0 +1,298 @@
+"use strict";
+/// <reference lib="dom"/>
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFetcher = exports.Fetcher = void 0;
+const error_util_1 = require("../error/error.util");
+const http_error_1 = require("../error/http.error");
+const number_util_1 = require("../number/number.util");
+const object_util_1 = require("../object/object.util");
+const pDelay_1 = require("../promise/pDelay");
+const json_util_1 = require("../string/json.util");
+const stringifyAny_1 = require("../string/stringifyAny");
+const time_util_1 = require("../time/time.util");
+const types_1 = require("../types");
+const defRetryOptions = {
+    count: 2,
+    timeout: 500,
+    timeoutMax: 30000,
+    timeoutMultiplier: 2,
+};
+/**
+ * Experimental wrapper around Fetch.
+ * Works in both Browser and Node, using `globalThis.fetch`.
+ *
+ * @experimental
+ */
+class Fetcher {
+    constructor(cfg = {}) {
+        this.cfg = this.normalizeCfg(cfg);
+    }
+    static create(cfg = {}) {
+        return new Fetcher(cfg);
+    }
+    async getJson(url, opt = {}) {
+        return await this.fetch(url, {
+            ...opt,
+            mode: 'json',
+        });
+    }
+    async postJson(url, opt = {}) {
+        return await this.fetch(url, {
+            ...opt,
+            method: 'post',
+            mode: 'json',
+        });
+    }
+    async getText(url, opt = {}) {
+        return await this.fetch(url, {
+            ...opt,
+            mode: 'text',
+        });
+    }
+    async postText(url, opt = {}) {
+        return await this.fetch(url, {
+            ...opt,
+            method: 'post',
+            mode: 'text',
+        });
+    }
+    async fetch(url, opt = {}) {
+        const res = await this.rawFetch(url, opt);
+        if (res.err) {
+            if (res.req.opt.throwHttpErrors)
+                throw res.err;
+            return res;
+        }
+        return res.body;
+    }
+    async rawFetch(url, rawOpt = {}) {
+        const { baseUrl, logger } = this.cfg;
+        const opt = this.normalizeOptions(rawOpt);
+        const { method, timeoutSeconds, mode } = opt;
+        const req = {
+            url,
+            init: {
+                ...this.cfg.requestInit,
+                method,
+            },
+            opt,
+        };
+        // setup url
+        if (baseUrl) {
+            if (url.startsWith('/')) {
+                console.warn(`Fetcher: url should not start with / when baseUrl is specified`);
+                url = url.slice(1);
+            }
+            req.url = `${baseUrl}/${url}`;
+        }
+        // setup request body
+        if (opt.json !== undefined) {
+            req.init.body = JSON.stringify(opt.json);
+        }
+        else if (opt.text !== undefined) {
+            req.init.body = opt.text;
+        }
+        // setup timeout
+        let timeout;
+        if (timeoutSeconds) {
+            const abortController = new AbortController();
+            req.init.signal = abortController.signal;
+            timeout = setTimeout(() => {
+                abortController.abort(`timeout of ${timeoutSeconds} sec`);
+            }, timeoutSeconds * 1000);
+        }
+        if (opt.requestInit) {
+            (0, types_1._objectAssign)(req.init, opt.requestInit);
+        }
+        await this.cfg.hooks?.beforeRequest?.(req);
+        const res = {
+            req,
+            retryStatus: {
+                retryAttempt: 0,
+                retryStopped: false,
+                retryTimeout: opt.retry.timeout,
+            },
+        };
+        const shortUrl = this.getShortUrl(req.url);
+        const signature = [method.toUpperCase(), shortUrl].join(' ');
+        /* eslint-disable no-await-in-loop */
+        while (!res.retryStatus.retryStopped) {
+            const started = Date.now();
+            if (this.cfg.logRequest) {
+                const { retryAttempt } = res.retryStatus;
+                logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${opt.retry.count}`]
+                    .filter(Boolean)
+                    .join(' '));
+                if (this.cfg.logRequestBody && req.init.body) {
+                    logger.log(req.init.body); // todo: check if we can _inspect it
+                }
+            }
+            res.fetchResponse = await globalThis.fetch(req.url, req.init);
+            res.statusFamily = this.getStatusFamily(res);
+            if (res.fetchResponse.ok) {
+                if (mode === 'json') {
+                    // if no body: set responseBody as {}
+                    // do not throw a "cannot parse null as Json" error
+                    res.body = res.fetchResponse.body ? await res.fetchResponse.json() : {};
+                }
+                else if (mode === 'text') {
+                    res.body = res.fetchResponse.body ? await res.fetchResponse.text() : '';
+                }
+                clearTimeout(timeout);
+                res.retryStatus.retryStopped = true;
+                if (this.cfg.logResponse) {
+                    const { retryAttempt } = res.retryStatus;
+                    logger.log([
+                        ' <<',
+                        res.fetchResponse.status,
+                        signature,
+                        retryAttempt && `try#${retryAttempt + 1}/${opt.retry.count}`,
+                        (0, time_util_1._since)(started),
+                    ]
+                        .filter(Boolean)
+                        .join(' '));
+                    if (this.cfg.logResponseBody) {
+                        logger.log(res.body);
+                    }
+                }
+            }
+            else {
+                clearTimeout(timeout);
+                const body = (0, json_util_1._jsonParseIfPossible)(await res.fetchResponse.text());
+                const errObj = (0, error_util_1._anyToErrorObject)(body);
+                const originalMessage = errObj.message;
+                errObj.message = [[res.fetchResponse.status, signature].join(' '), originalMessage].join('\n');
+                res.err = new http_error_1.HttpError(errObj.message, (0, object_util_1._filterNullishValues)({
+                    ...errObj.data,
+                    originalMessage,
+                    httpStatusCode: res.fetchResponse.status,
+                    // These properties are provided to be used in e.g custom Sentry error grouping
+                    // Actually, disabled now, to avoid unnecessary error printing when both msg and data are printed
+                    // Enabled, cause `data` is not printed by default when error is HttpError
+                    // method: req.method,
+                    url: req.url,
+                    // tryCount: req.tryCount,
+                }));
+                if (this.cfg.logResponse) {
+                    const { retryAttempt } = res.retryStatus;
+                    logger.error([
+                        [
+                            ' <<',
+                            res.fetchResponse.status,
+                            signature,
+                            retryAttempt && `try#${retryAttempt + 1}/${opt.retry.count}`,
+                            (0, time_util_1._since)(started),
+                        ]
+                            .filter(Boolean)
+                            .join(' '),
+                        (0, stringifyAny_1._stringifyAny)(body),
+                    ].join('\n'));
+                }
+                await this.processRetry(res);
+            }
+        }
+        await this.cfg.hooks?.beforeResponse?.(res);
+        return res;
+    }
+    async processRetry(res) {
+        const { retryStatus } = res;
+        if (!this.shouldRetry(res)) {
+            retryStatus.retryStopped = true;
+        }
+        await this.cfg.hooks?.beforeRetry?.(res);
+        const { count, timeoutMultiplier, timeoutMax } = res.req.opt.retry;
+        if (retryStatus.retryAttempt >= count) {
+            retryStatus.retryStopped = true;
+        }
+        if (retryStatus.retryStopped)
+            return;
+        retryStatus.retryTimeout = (0, number_util_1._clamp)(retryStatus.retryTimeout * timeoutMultiplier, 0, timeoutMax);
+        await (0, pDelay_1.pDelay)(retryStatus.retryTimeout);
+    }
+    /**
+     * Default is yes,
+     * unless there's reason not to (e.g method is POST).
+     */
+    shouldRetry(res) {
+        const { retryPost, retry4xx, retry5xx } = res.req.opt;
+        const { method } = res.req.init;
+        if (method === 'post' && !retryPost)
+            return false;
+        const { statusFamily } = res;
+        if (statusFamily === '5xx' && !retry5xx)
+            return false;
+        if (statusFamily === '4xx' && !retry4xx)
+            return false;
+        return true; // default is true
+    }
+    getStatusFamily(res) {
+        const status = res.fetchResponse?.status;
+        if (!status)
+            return;
+        if (status >= 500)
+            return '5xx';
+        if (status >= 400)
+            return '4xx';
+        if (status >= 300)
+            return '3xx';
+        if (status >= 200)
+            return '2xx';
+        if (status >= 100)
+            return '1xx';
+    }
+    /**
+     * Returns url without baseUrl and before ?queryString
+     */
+    getShortUrl(url) {
+        const { baseUrl } = this.cfg;
+        if (!baseUrl)
+            return url;
+        return url.split('?')[0].slice(baseUrl.length);
+    }
+    normalizeCfg(cfg) {
+        if (cfg.baseUrl?.endsWith('/')) {
+            console.warn(`Fetcher: baseUrl should not end with /`);
+            cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
+        }
+        const { debug } = cfg;
+        return {
+            timeoutSeconds: 30,
+            method: 'get',
+            throwHttpErrors: true,
+            retryPost: false,
+            retry4xx: false,
+            retry5xx: true,
+            logger: console,
+            logRequest: debug,
+            logRequestBody: debug,
+            logResponse: debug,
+            logResponseBody: debug,
+            ...cfg,
+            retry: {
+                ...defRetryOptions,
+                ...cfg.retry,
+            },
+        };
+    }
+    normalizeOptions(opt) {
+        const { timeoutSeconds, throwHttpErrors, method, retryPost, retry4xx, retry5xx, retry } = this.cfg;
+        return {
+            timeoutSeconds,
+            throwHttpErrors,
+            method,
+            retryPost,
+            retry4xx,
+            retry5xx,
+            ...opt,
+            retry: {
+                ...retry,
+                ...(0, object_util_1._filterUndefinedValues)(opt.retry || {}),
+            },
+        };
+    }
+}
+exports.Fetcher = Fetcher;
+function getFetcher(cfg = {}) {
+    return Fetcher.create(cfg);
+}
+exports.getFetcher = getFetcher;

package/dist/http/http.model.d.ts

@@ -0,0 +1,2 @@
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head';
+export type HttpStatusFamily = '5xx' | '4xx' | '3xx' | '2xx' | '1xx';

package/dist/http/http.model.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -74,4 +74,6 @@ export * from './datetime/localDate';
 export * from './datetime/localTime';
 export * from './datetime/dateInterval';
 export * from './datetime/timeInterval';
+export * from './http/http.model';
+export * from './http/fetcher';
 export { is };

package/dist/index.js

@@ -79,3 +79,5 @@ tslib_1.__exportStar(require("./datetime/localDate"), exports);
 tslib_1.__exportStar(require("./datetime/localTime"), exports);
 tslib_1.__exportStar(require("./datetime/dateInterval"), exports);
 tslib_1.__exportStar(require("./datetime/timeInterval"), exports);
+tslib_1.__exportStar(require("./http/http.model"), exports);
+tslib_1.__exportStar(require("./http/fetcher"), exports);

package/dist/object/deepEquals.js

@@ -54,6 +54,7 @@ function _deepEquals(a, b) {
         }
         return true;
     }
+    // eslint-disable-next-line no-self-compare
     return a !== a && b !== b;
 }
 exports._deepEquals = _deepEquals;