@naturalcycles/js-lib 14.134.0 → 14.136.0

package/dist-esm/promise/pDelay.js

@@ -1,3 +1,37 @@
+import { pDefer } from './pDefer';
+/**
+ * Promisified version of setTimeout.
+ *
+ * Can return a value.
+ * If value is instanceof Error - rejects the Promise instead of resolving.
+ */
 export 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));
+}
+/* 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.
+ */
+export function pDelayFn(ms = 0, fn) {
+    const p = 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;
 }

package/dist-esm/promise/pRetry.js

@@ -1,5 +1,4 @@
-import { _since, _stringifyAny } from '..';
-import { TimeoutError } from './pTimeout';
+import { _errorDataAppend, _since, pDelay, pTimeout } from '..';
 /**
  * Returns a Function (!), enhanced with retry capabilities.
  * Implements "Exponential back-off strategy" by multiplying the delay by `delayMultiplier` with each try.
@@ -10,8 +9,8 @@ export function pRetryFn(fn, opt = {}) {
     };
 }
 export async function pRetry(fn, opt = {}) {
-    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name, keepStackTrace = true, timeout, } = opt;
-    const fakeError = keepStackTrace ? new Error('RetryError') : undefined;
+    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name, timeout, } = opt;
+    const fakeError = timeout ? new Error('TimeoutError') : undefined;
     let { logFirstAttempt = false, logRetries = true, logFailures = false, logSuccess = false } = opt;
     if (opt.logAll) {
         logSuccess = logFirstAttempt = logRetries = logFailures = true;
@@ -22,66 +21,44 @@ export async function pRetry(fn, opt = {}) {
     const fname = name || fn.name || 'pRetry function';
     let delay = initialDelay;
     let attempt = 0;
-    let timer;
-    let timedOut = false;
-    return await new Promise((resolve, reject) => {
-        const rejectWithTimeout = () => {
-            timedOut = true; // to prevent more tries
-            const err = new TimeoutError(`"${fname}" timed out after ${timeout} ms`, opt.errorData);
-            if (fakeError) {
-                // keep original stack
-                err.stack = fakeError.stack.replace('Error: RetryError', 'TimeoutError');
+    /* eslint-disable no-await-in-loop, no-constant-condition */
+    while (true) {
+        const started = Date.now();
+        try {
+            attempt++;
+            if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
+                logger.log(`${fname} attempt #${attempt}...`);
             }
-            reject(err);
-        };
-        const next = async () => {
-            if (timedOut)
-                return;
+            let result;
             if (timeout) {
-                timer = setTimeout(rejectWithTimeout, timeout);
+                await pTimeout(async () => await fn(attempt), {
+                    timeout,
+                    name: fname,
+                    errorData: opt.errorData,
+                    fakeError,
+                });
             }
-            const started = Date.now();
-            try {
-                attempt++;
-                if ((attempt === 1 && logFirstAttempt) || (attempt > 1 && logRetries)) {
-                    logger.log(`${fname} attempt #${attempt}...`);
-                }
-                const r = await fn(attempt);
-                clearTimeout(timer);
-                if (logSuccess) {
-                    logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`);
-                }
-                resolve(r);
+            else {
+                result = await fn(attempt);
             }
-            catch (err) {
-                clearTimeout(timer);
-                if (logFailures) {
-                    logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, _stringifyAny(err, {
-                        includeErrorData: true,
-                    }));
-                }
-                if (attempt >= maxAttempts ||
-                    (predicate && !predicate(err, attempt, maxAttempts))) {
-                    // Give up
-                    if (fakeError) {
-                        // Preserve the original call stack
-                        Object.defineProperty(err, 'stack', {
-                            value: err.stack +
-                                '\n    --' +
-                                fakeError.stack.replace('Error: RetryError', ''),
-                        });
-                    }
-                    ;
-                    err.data = Object.assign(Object.assign({}, err.data), opt.errorData);
-                    reject(err);
-                }
-                else {
-                    // Retry after delay
-                    delay *= delayMultiplier;
-                    setTimeout(next, delay);
-                }
+            if (logSuccess) {
+                logger.log(`${fname} attempt #${attempt} succeeded in ${_since(started)}`);
             }
-        };
-        void next();
-    });
+            return result;
+        }
+        catch (err) {
+            if (logFailures) {
+                logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, err);
+            }
+            if (attempt >= maxAttempts || (predicate && !predicate(err, attempt, maxAttempts))) {
+                // Give up
+                _errorDataAppend(err, opt.errorData);
+                throw err;
+            }
+            // Retry after delay
+            delay *= delayMultiplier;
+            await pDelay(delay);
+            // back to while(true) loop
+        }
+    }
 }

package/dist-esm/promise/pTimeout.js

@@ -1,4 +1,5 @@
 import { AppError } from '../error/app.error';
+import { _errorDataAppend } from '../error/error.util';
 export class TimeoutError extends AppError {
     constructor(message, data = {}, opt) {
         super(message, data, opt, 'TimeoutError');
@@ -24,23 +25,23 @@ export function pTimeoutFn(fn, opt) {
  * If the Function rejects - passes this rejection further.
  */
 export async function pTimeout(fn, opt) {
-    const { timeout, name = fn.name || 'pTimeout function', onTimeout, keepStackTrace = true } = opt;
-    const fakeError = keepStackTrace ? new Error('TimeoutError') : undefined;
+    const { timeout, name = fn.name || 'pTimeout function', onTimeout } = opt;
+    const fakeError = opt.fakeError || new Error('TimeoutError');
     // eslint-disable-next-line no-async-promise-executor
     return await new Promise(async (resolve, reject) => {
         // Prepare the timeout timer
         const timer = setTimeout(() => {
             const err = new TimeoutError(`"${name}" timed out after ${timeout} ms`, opt.errorData);
-            if (fakeError)
-                err.stack = fakeError.stack; // keep original stack
+            // keep original stack
+            err.stack = fakeError.stack.replace('Error: TimeoutError', 'TimeoutError: ' + err.message);
             if (onTimeout) {
                 try {
                     resolve(onTimeout(err));
                 }
                 catch (err) {
-                    if (fakeError)
-                        err.stack = fakeError.stack; // keep original stack
-                    err.data = Object.assign(Object.assign({}, err.data), opt.errorData);
+                    // keep original stack
+                    err.stack = fakeError.stack.replace('Error: TimeoutError', err.name + ': ' + err.message);
+                    _errorDataAppend(err, opt.errorData);
                     reject(err);
                 }
                 return;

package/dist-esm/string/stringifyAny.js

@@ -82,11 +82,6 @@ export function _stringifyAny(obj, opt = {}) {
                 // `replace` here works ONCE, exactly as we need it
                 s = s.replace('HttpError', `HttpError(${obj.data.httpStatusCode})`);
             }
-            // Here we ensure it has `data`
-            const { data } = obj;
-            if (opt.includeErrorData && Object.keys(data).length > 0) {
-                s = [s, _stringifyAny(data, opt)].join('\n');
-            }
         }
         else if (typeof obj.code === 'string') {
             // Error that has no `data`, but has `code` property

package/package.json

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

package/src/decorators/logMethod.decorator.ts

@@ -155,10 +155,10 @@ function logFinished(
   }
 
   if (err !== undefined) {
-    t.push('ERROR:', _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/src/env.ts

@@ -0,0 +1,19 @@
+/**
+ * Use it to detect SSR/Node.js environment.
+ *
+ * Will return `true` in Node.js.
+ * Will return `false` in the Browser.
+ */
+export function isServerSide(): boolean {
+  return typeof window === 'undefined'
+}
+
+/**
+ * Use it to detect Browser (not SSR/Node) environment.
+ *
+ * Will return `true` in the Browser.
+ * Will return `false` in Node.js.
+ */
+export function isClientSide(): boolean {
+  return typeof window !== 'undefined'
+}

package/src/error/error.util.ts

@@ -181,7 +181,9 @@ export function _isErrorObject(o: any): o is ErrorObject {
  *   })
  * }
  */
-export function _errorDataAppend(err: any, data: ErrorData): void {
+export function _errorDataAppend(err: any, data?: ErrorData): void {
+  if (!data) return
+
   err.data = {
     ...err.data,
     ...data,

package/src/error/tryCatch.ts

@@ -1,5 +1,5 @@
 import type { CommonLogger } from '../index'
-import { _anyToError, _since, _stringifyAny } from '../index'
+import { _anyToError, _since } from '../index'
 import type { AnyFunction } from '../types'
 
 export interface TryCatchOptions {
@@ -51,11 +51,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
       return r
     } catch (err) {
       if (logError) {
-        logger.warn(
-          `tryCatch.${fname} error in ${_since(started)}:\n${_stringifyAny(err, {
-            includeErrorData: true,
-          })}`,
-        )
+        logger.warn(`tryCatch.${fname} error in ${_since(started)}:`, err)
       }
 
       if (onError) {

package/src/http/fetcher.model.ts

@@ -49,10 +49,19 @@ export interface FetcherCfg {
   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.
@@ -165,6 +174,7 @@ export interface FetcherSuccessResponse<BODY = unknown> {
   req: FetcherRequest
   statusFamily?: HttpStatusFamily
   retryStatus: FetcherRetryStatus
+  signature: string
 }
 
 export interface FetcherErrorResponse<BODY = unknown> {
@@ -175,6 +185,7 @@ export interface FetcherErrorResponse<BODY = unknown> {
   req: FetcherRequest
   statusFamily?: HttpStatusFamily
   retryStatus: FetcherRetryStatus
+  signature: string
 }
 
 export type FetcherResponse<BODY = unknown> =

package/src/http/fetcher.ts

@@ -1,5 +1,6 @@
 /// <reference lib="dom"/>
 
+import { isServerSide } from '../env'
 import { ErrorObject } from '../error/error.model'
 import { _anyToError, _anyToErrorObject, _errorToErrorObject } from '../error/error.util'
 import { HttpError } from '../error/http.error'
@@ -151,7 +152,6 @@ export class Fetcher {
     const req = this.normalizeOptions(url, rawOpt)
     const {
       timeoutSeconds,
-      mode,
       init: { method },
     } = req
 
@@ -169,6 +169,11 @@ export class Fetcher {
       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: {
@@ -176,12 +181,9 @@ export class Fetcher {
         retryStopped: false,
         retryTimeout: req.retry.timeout,
       },
+      signature,
     } as FetcherResponse<any>
 
-    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()
@@ -209,109 +211,129 @@ export 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 } = _anyToError(err)
-                res.err = new 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}`,
-              _since(started),
-            ]
-              .filter(Boolean)
-              .join(' '),
-          )
-
-          if (this.cfg.logResponseBody) {
-            logger.log(res.body)
-          }
-        }
+        await this.onOkResponse(
+          res as FetcherResponse<T> & { fetchResponse: Response },
+          started,
+          timeout,
+        )
       } else {
         // !res.ok
-        clearTimeout(timeout)
+        await this.onNotOkResponse(res, timeout)
+      }
+    }
+
+    for await (const hook of this.cfg.hooks.afterResponse || []) {
+      await hook(res)
+    }
 
-        let errObj: ErrorObject
+    return res
+  }
 
-        if (res.fetchResponse) {
-          const body = _jsonParseIfPossible(await res.fetchResponse.text())
-          errObj = _anyToErrorObject(body)
-        } else if (res.err) {
-          errObj = _errorToErrorObject(res.err)
+  private async onOkResponse(
+    res: FetcherResponse<any> & { fetchResponse: Response },
+    started: number,
+    timeout?: number,
+  ): Promise<void> {
+    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 } = _anyToError(err)
+            res.err = new HttpError([res.signature, message].join('\n'), {
+              httpStatusCode: 0,
+              url: req.url,
+            })
+            res.ok = false
+          }
         } else {
-          errObj = {} as ErrorObject
+          // 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() : {}
+    }
 
-        const originalMessage = errObj.message
-        errObj.message = [
-          [res.fetchResponse?.status, signature].filter(Boolean).join(' '),
-          originalMessage,
+    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}`,
+          _since(started),
         ]
           .filter(Boolean)
-          .join('\n')
-
-        res.err = new HttpError(
-          errObj.message,
-
-          _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,
-          }),
-        )
+          .join(' '),
+      )
 
-        await this.processRetry(res)
+      if (this.cfg.logResponseBody) {
+        logger.log(res.body)
       }
     }
+  }
 
-    for await (const hook of this.cfg.hooks.afterResponse || []) {
-      await hook(res)
+  private async onNotOkResponse(res: FetcherResponse, timeout?: number): Promise<void> {
+    clearTimeout(timeout)
+
+    let errObj: ErrorObject
+
+    if (res.fetchResponse) {
+      const body = _jsonParseIfPossible(await res.fetchResponse.text())
+      errObj = _anyToErrorObject(body)
+    } else if (res.err) {
+      errObj = _errorToErrorObject(res.err)
+    } else {
+      errObj = {} as ErrorObject
     }
 
-    return res
+    const originalMessage = errObj.message
+    errObj.message = [
+      [res.fetchResponse?.status, res.signature].filter(Boolean).join(' '),
+      originalMessage,
+    ]
+      .filter(Boolean)
+      .join('\n')
+
+    res.err = new HttpError(
+      errObj.message,
+
+      _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)
   }
 
   private async processRetry(res: FetcherResponse): Promise<void> {
@@ -388,7 +410,7 @@ export class Fetcher {
       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)
     }
 
@@ -419,7 +441,7 @@ export class Fetcher {
         logRequestBody: debug,
         logResponse: debug,
         logResponseBody: debug,
-        logWithPrefixUrl: true,
+        logWithBaseUrl: isServerSide(),
         logWithSearchParams: true,
         retry: { ...defRetryOptions },
         init: {

package/src/index.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/src/promise/abortable.ts

@@ -0,0 +1,34 @@
+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 class Abortable {
+  constructor(public onAbort?: AnyFunction) {}
+
+  aborted = false
+
+  abort(): void {
+    if (this.aborted) return
+    this.aborted = true
+    this.onAbort?.()
+    this.onAbort = undefined // cleanup listener
+  }
+
+  clear(): void {
+    this.onAbort = undefined
+  }
+}
+
+// convenience function
+export function abortable(onAbort?: AnyFunction): Abortable {
+  return new Abortable(onAbort)
+}