@naturalcycles/js-lib 14.134.0 → 14.136.0

package/dist/decorators/logMethod.decorator.js

@@ -80,10 +80,10 @@ function logFinished(logger, callSignature, started, sma, logResultFn, res, err)
         t.push(`(avg ${(0, time_util_1._ms)(sma.push(millis))})`);
     }
     if (err !== undefined) {
-        t.push('ERROR:', (0, __1._stringifyAny)(err, { includeErrorData: true }));
+        t.push('ERROR:', err);
     }
     else if (logResultFn) {
         t.push(...logResultFn(res));
     }
-    logger.log(t.filter(Boolean).join(' '));
+    logger.log(...t.filter(Boolean));
 }

package/dist/env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Use it to detect SSR/Node.js environment.
+ *
+ * Will return `true` in Node.js.
+ * Will return `false` in the Browser.
+ */
+export declare function isServerSide(): boolean;
+/**
+ * Use it to detect Browser (not SSR/Node) environment.
+ *
+ * Will return `true` in the Browser.
+ * Will return `false` in Node.js.
+ */
+export declare function isClientSide(): boolean;

package/dist/env.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isClientSide = exports.isServerSide = void 0;
+/**
+ * Use it to detect SSR/Node.js environment.
+ *
+ * Will return `true` in Node.js.
+ * Will return `false` in the Browser.
+ */
+function isServerSide() {
+    return typeof window === 'undefined';
+}
+exports.isServerSide = isServerSide;
+/**
+ * Use it to detect Browser (not SSR/Node) environment.
+ *
+ * Will return `true` in the Browser.
+ * Will return `false` in Node.js.
+ */
+function isClientSide() {
+    return typeof window !== 'undefined';
+}
+exports.isClientSide = isClientSide;

package/dist/error/error.util.d.ts

@@ -36,4 +36,4 @@ export declare function _isErrorObject(o: any): o is ErrorObject;
  *   })
  * }
  */
-export declare function _errorDataAppend(err: any, data: ErrorData): void;
+export declare function _errorDataAppend(err: any, data?: ErrorData): void;

package/dist/error/error.util.js

@@ -155,6 +155,8 @@ exports._isErrorObject = _isErrorObject;
  * }
  */
 function _errorDataAppend(err, data) {
+    if (!data)
+        return;
     err.data = {
         ...err.data,
         ...data,

package/dist/error/tryCatch.js

@@ -24,9 +24,7 @@ function _tryCatch(fn, opt = {}) {
         }
         catch (err) {
             if (logError) {
-                logger.warn(`tryCatch.${fname} error in ${(0, index_1._since)(started)}:\n${(0, index_1._stringifyAny)(err, {
-                    includeErrorData: true,
-                })}`);
+                logger.warn(`tryCatch.${fname} error in ${(0, index_1._since)(started)}:`, err);
             }
             if (onError) {
                 try {

package/dist/http/fetcher.d.ts

@@ -38,6 +38,8 @@ export declare class Fetcher {
      * Never throws, returns `err` property in the response instead.
      */
     rawFetch<T = unknown>(url: string, rawOpt?: FetcherOptions): Promise<FetcherResponse<T>>;
+    private onOkResponse;
+    private onNotOkResponse;
     private processRetry;
     /**
      * Default is yes,

package/dist/http/fetcher.js

@@ -2,6 +2,7 @@
 /// <reference lib="dom"/>
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFetcher = exports.Fetcher = void 0;
+const env_1 = require("../env");
 const error_util_1 = require("../error/error.util");
 const http_error_1 = require("../error/http.error");
 const number_util_1 = require("../number/number.util");
@@ -94,7 +95,7 @@ class Fetcher {
     async rawFetch(url, rawOpt = {}) {
         const { logger } = this.cfg;
         const req = this.normalizeOptions(url, rawOpt);
-        const { timeoutSeconds, mode, init: { method }, } = req;
+        const { timeoutSeconds, init: { method }, } = req;
         // setup timeout
         let timeout;
         if (timeoutSeconds) {
@@ -107,6 +108,10 @@ class Fetcher {
         for await (const hook of this.cfg.hooks.beforeRequest || []) {
             await hook(req);
         }
+        const isFullUrl = req.url.includes('://');
+        const fullUrl = isFullUrl ? new URL(req.url) : undefined;
+        const shortUrl = fullUrl ? this.getShortUrl(fullUrl) : req.url;
+        const signature = [method, shortUrl].join(' ');
         const res = {
             req,
             retryStatus: {
@@ -114,10 +119,8 @@ class Fetcher {
                 retryStopped: false,
                 retryTimeout: req.retry.timeout,
             },
+            signature,
         };
-        const fullUrl = new URL(req.url);
-        const shortUrl = this.getShortUrl(fullUrl);
-        const signature = [method, shortUrl].join(' ');
         /* eslint-disable no-await-in-loop */
         while (!res.retryStatus.retryStopped) {
             const started = Date.now();
@@ -141,95 +144,11 @@ class Fetcher {
             }
             res.statusFamily = this.getStatusFamily(res);
             if (res.fetchResponse?.ok) {
-                if (mode === 'json') {
-                    if (res.fetchResponse.body) {
-                        const text = await res.fetchResponse.text();
-                        if (text) {
-                            try {
-                                res.body = text;
-                                res.body = JSON.parse(text, req.jsonReviver);
-                            }
-                            catch (err) {
-                                const { message } = (0, error_util_1._anyToError)(err);
-                                res.err = new http_error_1.HttpError([signature, message].join('\n'), {
-                                    httpStatusCode: 0,
-                                    url: req.url,
-                                });
-                                res.ok = false;
-                            }
-                        }
-                        else {
-                            // Body had a '' (empty string)
-                            res.body = {};
-                        }
-                    }
-                    else {
-                        // if no body: set responseBody as {}
-                        // do not throw a "cannot parse null as Json" error
-                        res.body = {};
-                    }
-                }
-                else if (mode === 'text') {
-                    res.body = res.fetchResponse.body ? await res.fetchResponse.text() : '';
-                }
-                else if (mode === 'arrayBuffer') {
-                    res.body = res.fetchResponse.body ? await res.fetchResponse.arrayBuffer() : {};
-                }
-                else if (mode === 'blob') {
-                    res.body = res.fetchResponse.body ? await res.fetchResponse.blob() : {};
-                }
-                clearTimeout(timeout);
-                res.retryStatus.retryStopped = true;
-                // res.err can happen on JSON.parse error
-                if (!res.err && this.cfg.logResponse) {
-                    const { retryAttempt } = res.retryStatus;
-                    logger.log([
-                        ' <<',
-                        res.fetchResponse.status,
-                        signature,
-                        retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`,
-                        (0, time_util_1._since)(started),
-                    ]
-                        .filter(Boolean)
-                        .join(' '));
-                    if (this.cfg.logResponseBody) {
-                        logger.log(res.body);
-                    }
-                }
+                await this.onOkResponse(res, started, timeout);
             }
             else {
                 // !res.ok
-                clearTimeout(timeout);
-                let errObj;
-                if (res.fetchResponse) {
-                    const body = (0, json_util_1._jsonParseIfPossible)(await res.fetchResponse.text());
-                    errObj = (0, error_util_1._anyToErrorObject)(body);
-                }
-                else if (res.err) {
-                    errObj = (0, error_util_1._errorToErrorObject)(res.err);
-                }
-                else {
-                    errObj = {};
-                }
-                const originalMessage = errObj.message;
-                errObj.message = [
-                    [res.fetchResponse?.status, signature].filter(Boolean).join(' '),
-                    originalMessage,
-                ]
-                    .filter(Boolean)
-                    .join('\n');
-                res.err = new http_error_1.HttpError(errObj.message, (0, object_util_1._filterNullishValues)({
-                    ...errObj.data,
-                    originalMessage,
-                    httpStatusCode: res.fetchResponse?.status || 0,
-                    // 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,
-                }));
-                await this.processRetry(res);
+                await this.onNotOkResponse(res, timeout);
             }
         }
         for await (const hook of this.cfg.hooks.afterResponse || []) {
@@ -237,6 +156,99 @@ class Fetcher {
         }
         return res;
     }
+    async onOkResponse(res, started, timeout) {
+        const { req } = res;
+        const { mode } = res.req;
+        if (mode === 'json') {
+            if (res.fetchResponse.body) {
+                const text = await res.fetchResponse.text();
+                if (text) {
+                    try {
+                        res.body = text;
+                        res.body = JSON.parse(text, req.jsonReviver);
+                    }
+                    catch (err) {
+                        const { message } = (0, error_util_1._anyToError)(err);
+                        res.err = new http_error_1.HttpError([res.signature, message].join('\n'), {
+                            httpStatusCode: 0,
+                            url: req.url,
+                        });
+                        res.ok = false;
+                    }
+                }
+                else {
+                    // Body had a '' (empty string)
+                    res.body = {};
+                }
+            }
+            else {
+                // if no body: set responseBody as {}
+                // do not throw a "cannot parse null as Json" error
+                res.body = {};
+            }
+        }
+        else if (mode === 'text') {
+            res.body = res.fetchResponse.body ? await res.fetchResponse.text() : '';
+        }
+        else if (mode === 'arrayBuffer') {
+            res.body = res.fetchResponse.body ? await res.fetchResponse.arrayBuffer() : {};
+        }
+        else if (mode === 'blob') {
+            res.body = res.fetchResponse.body ? await res.fetchResponse.blob() : {};
+        }
+        clearTimeout(timeout);
+        res.retryStatus.retryStopped = true;
+        // res.err can happen on JSON.parse error
+        if (!res.err && this.cfg.logResponse) {
+            const { retryAttempt } = res.retryStatus;
+            const { logger } = this.cfg;
+            logger.log([
+                ' <<',
+                res.fetchResponse.status,
+                res.signature,
+                retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`,
+                (0, time_util_1._since)(started),
+            ]
+                .filter(Boolean)
+                .join(' '));
+            if (this.cfg.logResponseBody) {
+                logger.log(res.body);
+            }
+        }
+    }
+    async onNotOkResponse(res, timeout) {
+        clearTimeout(timeout);
+        let errObj;
+        if (res.fetchResponse) {
+            const body = (0, json_util_1._jsonParseIfPossible)(await res.fetchResponse.text());
+            errObj = (0, error_util_1._anyToErrorObject)(body);
+        }
+        else if (res.err) {
+            errObj = (0, error_util_1._errorToErrorObject)(res.err);
+        }
+        else {
+            errObj = {};
+        }
+        const originalMessage = errObj.message;
+        errObj.message = [
+            [res.fetchResponse?.status, res.signature].filter(Boolean).join(' '),
+            originalMessage,
+        ]
+            .filter(Boolean)
+            .join('\n');
+        res.err = new http_error_1.HttpError(errObj.message, (0, object_util_1._filterNullishValues)({
+            ...errObj.data,
+            originalMessage,
+            httpStatusCode: res.fetchResponse?.status || 0,
+            // 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: res.req.url,
+            // tryCount: req.tryCount,
+        }));
+        await this.processRetry(res);
+    }
     async processRetry(res) {
         const { retryStatus } = res;
         if (!this.shouldRetry(res)) {
@@ -307,7 +319,7 @@ class Fetcher {
         if (!this.cfg.logWithSearchParams) {
             shortUrl = shortUrl.split('?')[0];
         }
-        if (!this.cfg.logWithPrefixUrl && baseUrl && shortUrl.startsWith(baseUrl)) {
+        if (!this.cfg.logWithBaseUrl && baseUrl && shortUrl.startsWith(baseUrl)) {
             shortUrl = shortUrl.slice(baseUrl.length);
         }
         return shortUrl;
@@ -334,7 +346,7 @@ class Fetcher {
             logRequestBody: debug,
             logResponse: debug,
             logResponseBody: debug,
-            logWithPrefixUrl: true,
+            logWithBaseUrl: (0, env_1.isServerSide)(),
             logWithSearchParams: true,
             retry: { ...defRetryOptions },
             init: {

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

@@ -43,10 +43,19 @@ export interface FetcherCfg {
     logResponse?: boolean;
     logResponseBody?: boolean;
     /**
-     * Default to true.
-     * Set to false to exclude `prefixUrl` from logs (both success and error)
+     * Controls if `baseUrl` should be included in logs (both success and error).
+     *
+     * Defaults to `true` on ServerSide and `false` on ClientSide.
+     *
+     * Reasoning.
+     *
+     * ClientSide often uses one main "backend host".
+     * Not including baseUrl improves Sentry error grouping.
+     *
+     * ServerSide often uses one Fetcher instance per 3rd-party API.
+     * Not including baseUrl can introduce confusion of "which API is it?".
      */
-    logWithPrefixUrl?: boolean;
+    logWithBaseUrl?: boolean;
     /**
      * Default to true.
      * Set to false to strip searchParams from url when logging (both success and error)
@@ -138,6 +147,7 @@ export interface FetcherSuccessResponse<BODY = unknown> {
     req: FetcherRequest;
     statusFamily?: HttpStatusFamily;
     retryStatus: FetcherRetryStatus;
+    signature: string;
 }
 export interface FetcherErrorResponse<BODY = unknown> {
     ok: false;
@@ -147,6 +157,7 @@ export interface FetcherErrorResponse<BODY = unknown> {
     req: FetcherRequest;
     statusFamily?: HttpStatusFamily;
     retryStatus: FetcherRetryStatus;
+    signature: string;
 }
 export type FetcherResponse<BODY = unknown> = FetcherSuccessResponse<BODY> | FetcherErrorResponse<BODY>;
 export type FetcherMode = 'json' | 'text' | 'void' | 'arrayBuffer' | 'blob';

package/dist/index.d.ts

@@ -61,6 +61,7 @@ export * from './unit/size.util';
 export * from './log/commonLogger';
 export * from './string/safeJsonStringify';
 export * from './promise/pQueue';
+export * from './promise/abortable';
 export * from './seq/seq';
 export * from './math/stack.util';
 export * from './string/leven';
@@ -72,6 +73,7 @@ export * from './datetime/localDate';
 export * from './datetime/localTime';
 export * from './datetime/dateInterval';
 export * from './datetime/timeInterval';
+export * from './env';
 export * from './http/http.model';
 export * from './http/fetcher';
 export * from './http/fetcher.model';

package/dist/index.js

@@ -65,6 +65,7 @@ tslib_1.__exportStar(require("./unit/size.util"), exports);
 tslib_1.__exportStar(require("./log/commonLogger"), exports);
 tslib_1.__exportStar(require("./string/safeJsonStringify"), exports);
 tslib_1.__exportStar(require("./promise/pQueue"), exports);
+tslib_1.__exportStar(require("./promise/abortable"), exports);
 tslib_1.__exportStar(require("./seq/seq"), exports);
 tslib_1.__exportStar(require("./math/stack.util"), exports);
 tslib_1.__exportStar(require("./string/leven"), exports);
@@ -76,6 +77,7 @@ 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("./env"), exports);
 tslib_1.__exportStar(require("./http/http.model"), exports);
 tslib_1.__exportStar(require("./http/fetcher"), exports);
 tslib_1.__exportStar(require("./http/fetcher.model"), exports);

package/dist/promise/abortable.d.ts

@@ -0,0 +1,20 @@
+import { AnyFunction } from '../types';
+/**
+ * Similar to AbortController and AbortSignal.
+ * Similar to pDefer and Promise.
+ * Similar to Subject and Observable.
+ *
+ * Minimal interface for something that can be aborted in the future,
+ * but not necessary.
+ * Allows to listen to `onAbort` event.
+ *
+ * @experimental
+ */
+export declare class Abortable {
+    onAbort?: AnyFunction<any> | undefined;
+    constructor(onAbort?: AnyFunction<any> | undefined);
+    aborted: boolean;
+    abort(): void;
+    clear(): void;
+}
+export declare function abortable(onAbort?: AnyFunction): Abortable;

package/dist/promise/abortable.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortable = exports.Abortable = void 0;
+/**
+ * Similar to AbortController and AbortSignal.
+ * Similar to pDefer and Promise.
+ * Similar to Subject and Observable.
+ *
+ * Minimal interface for something that can be aborted in the future,
+ * but not necessary.
+ * Allows to listen to `onAbort` event.
+ *
+ * @experimental
+ */
+class Abortable {
+    constructor(onAbort) {
+        this.onAbort = onAbort;
+        this.aborted = false;
+    }
+    abort() {
+        if (this.aborted)
+            return;
+        this.aborted = true;
+        this.onAbort?.();
+        this.onAbort = undefined; // cleanup listener
+    }
+    clear() {
+        this.onAbort = undefined;
+    }
+}
+exports.Abortable = Abortable;
+// convenience function
+function abortable(onAbort) {
+    return new Abortable(onAbort);
+}
+exports.abortable = abortable;

package/dist/promise/pDefer.d.ts

@@ -3,7 +3,20 @@
  */
 export interface DeferredPromise<T = void> extends Promise<T> {
     resolve: (a?: T) => void;
-    reject: (e?: Error) => void;
+    reject: (err?: Error) => void;
+    /**
+     * Can be overridden.
+     * Otherwise will reject with "Aborted" or "Aborted: $reason" on abort().
+     *
+     * @experimental
+     */
+    abort: (reason?: string) => void;
+    /**
+     * Rejects the promise with `new Error('Aborted: $reason')`.
+     *
+     * @experimental
+     */
+    rejectAborted: (reason?: string) => void;
 }
 /**
  * Returns DeferredPromise - a Promise that has .resolve() and .reject() methods.

package/dist/promise/pDefer.js

@@ -14,6 +14,8 @@ function pDefer() {
     });
     promise.resolve = resolve;
     promise.reject = reject;
+    promise.rejectAborted = reason => reject(new Error(['Aborted', reason].filter(Boolean).join(': ')));
+    promise.abort = reason => promise.rejectAborted(reason);
     return promise;
 }
 exports.pDefer = pDefer;

package/dist/promise/pDelay.d.ts

@@ -1 +1,19 @@
+import type { PromisableFunction } from '../types';
+import { DeferredPromise } from './pDefer';
+/**
+ * Promisified version of setTimeout.
+ *
+ * Can return a value.
+ * If value is instanceof Error - rejects the Promise instead of resolving.
+ */
 export declare function pDelay<T>(ms?: number, value?: T): Promise<T>;
+/**
+ * Promisified version of setTimeout.
+ *
+ * Wraps the passed function with try/catch,
+ * catch will propagate to pDelayFn rejection,
+ * otherwise pDelayFn will resolve with returned value.
+ *
+ * On abort() - clears the Timeout and immediately resolves the Promise with void.
+ */
+export declare function pDelayFn<T>(ms: number | undefined, fn: PromisableFunction<T>): DeferredPromise<T>;

package/dist/promise/pDelay.js

@@ -1,7 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pDelay = void 0;
+exports.pDelayFn = exports.pDelay = void 0;
+const pDefer_1 = require("./pDefer");
+/**
+ * Promisified version of setTimeout.
+ *
+ * Can return a value.
+ * If value is instanceof Error - rejects the Promise instead of resolving.
+ */
 async function pDelay(ms = 0, value) {
-    return await new Promise(resolve => setTimeout(() => resolve(value), ms));
+    return await new Promise((resolve, reject) => setTimeout(value instanceof Error ? reject : resolve, ms, value));
 }
 exports.pDelay = pDelay;
+/* eslint-disable @typescript-eslint/promise-function-async */
+/**
+ * Promisified version of setTimeout.
+ *
+ * Wraps the passed function with try/catch,
+ * catch will propagate to pDelayFn rejection,
+ * otherwise pDelayFn will resolve with returned value.
+ *
+ * On abort() - clears the Timeout and immediately resolves the Promise with void.
+ */
+function pDelayFn(ms = 0, fn) {
+    const p = (0, pDefer_1.pDefer)();
+    const timer = setTimeout(async () => {
+        try {
+            p.resolve(await fn());
+        }
+        catch (err) {
+            p.reject(err);
+        }
+    }, ms);
+    p.abort = () => {
+        clearTimeout(timer);
+        // p.rejectAborted(reason) // nope
+        p.resolve();
+    };
+    return p;
+}
+exports.pDelayFn = pDelayFn;

package/dist/promise/pRetry.d.ts

@@ -68,14 +68,6 @@ export interface PRetryOptions {
      * Default to `console`
      */
     logger?: CommonLogger;
-    /**
-     * Defaults to true.
-     * If true - preserves the stack trace in case of a Timeout (usually - very useful!).
-     * It has a certain perf cost.
-     *
-     * @experimental
-     */
-    keepStackTrace?: boolean;
     /**
      * Will be merged with `err.data` object.
      */