@naturalcycles/js-lib 14.157.0 → 14.158.0

package/dist-esm/http/fetcher.js

@@ -1,15 +1,16 @@
 /// <reference lib="dom"/>
 /// <reference lib="dom.iterable"/>
 import { isServerSide } from '../env';
+import { _assertErrorClassOrRethrow } from '../error/assert';
 import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject } from '../error/error.util';
 import { HttpRequestError } from '../error/httpRequestError';
 import { _clamp } from '../number/number.util';
 import { _filterNullishValues, _filterUndefinedValues, _mapKeys, _merge, _omit, _pick, } from '../object/object.util';
 import { pDelay } from '../promise/pDelay';
-import { TimeoutError } from '../promise/pTimeout';
+import { pTimeout, TimeoutError } from '../promise/pTimeout';
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util';
 import { _stringifyAny } from '../string/stringifyAny';
-import { _since } from '../time/time.util';
+import { _ms, _since } from '../time/time.util';
 import { HTTP_METHODS } from './http.model';
 const acceptByResponseType = {
     text: 'text/plain',
@@ -25,6 +26,18 @@ const defRetryOptions = {
     timeoutMax: 30000,
     timeoutMultiplier: 2,
 };
+let globalFetcherMock = null;
+/**
+ * Allows to mock Fetcher.callNativeFetch globally (for all Fetcher instances out there).
+ *
+ * Call it with `null` to reset/unmock.
+ *
+ * Please note that jest.spyOn(someFetcher, 'callNativeFetch') has higher priority than
+ * a global mock, so it'll run instead of a global mock.
+ */
+export function setGlobalFetcherMock(fn) {
+    globalFetcherMock = fn;
+}
 /**
  * Experimental wrapper around Fetch.
  * Works in both Browser and Node, using `globalThis.fetch`.
@@ -96,29 +109,33 @@ export class Fetcher {
         }
         return res.body;
     }
+    /**
+     * Like pTry - returns a [err, data] tuple (aka ErrorDataTuple).
+     * err, if defined, is strictly HttpRequestError.
+     * UPD: actually not, err is typed as Error, as it feels unsafe to guarantee error type.
+     * UPD: actually yes - it will return HttpRequestError, and throw if there's an error
+     * of any other type.
+     */
+    async tryFetch(opt) {
+        const res = await this.doFetch(opt);
+        if (res.err) {
+            _assertErrorClassOrRethrow(res.err, HttpRequestError);
+            return [res.err, null];
+        }
+        return [null, res.body];
+    }
     /**
      * Returns FetcherResponse.
      * Never throws, returns `err` property in the response instead.
      * Use this method instead of `throwHttpErrors: false` or try-catching.
+     *
+     * Note: responseType defaults to `void`, so, override it if you expect different.
      */
     async doFetch(opt) {
         var _a, _b;
         const req = this.normalizeOptions(opt);
         const { logger } = this.cfg;
         const { timeoutSeconds, init: { method }, } = req;
-        // setup timeout
-        let timeout;
-        if (timeoutSeconds) {
-            const abortController = new AbortController();
-            req.init.signal = abortController.signal;
-            timeout = setTimeout(() => {
-                // Apparently, providing a `string` reason to abort() causes Undici to throw `invalid_argument` error,
-                // so, we're wrapping it in a TimeoutError instance
-                abortController.abort(new TimeoutError(`request timed out after ${timeoutSeconds} sec`));
-                // abortController.abort(`timeout of ${timeoutSeconds} sec`)
-                // abortController.abort()
-            }, timeoutSeconds * 1000);
-        }
         for (const hook of this.cfg.hooks.beforeRequest || []) {
             await hook(req);
         }
@@ -137,6 +154,18 @@ export class Fetcher {
         };
         while (!res.retryStatus.retryStopped) {
             req.started = Date.now();
+            // setup timeout
+            let timeoutId;
+            if (timeoutSeconds) {
+                const abortController = new AbortController();
+                req.init.signal = abortController.signal;
+                timeoutId = setTimeout(() => {
+                    // console.log(`actual request timed out in ${_since(req.started)}`)
+                    // Apparently, providing a `string` reason to abort() causes Undici to throw `invalid_argument` error,
+                    // so, we're wrapping it in a TimeoutError instance
+                    abortController.abort(new TimeoutError(`request timed out after ${timeoutSeconds} sec`));
+                }, timeoutSeconds * 1000);
+            }
             if (this.cfg.logRequest) {
                 const { retryAttempt } = res.retryStatus;
                 logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`]
@@ -160,14 +189,30 @@ export class Fetcher {
                 // important to set it to undefined, otherwise it can keep the previous value (from previous try)
                 res.fetchResponse = undefined;
             }
+            finally {
+                clearTimeout(timeoutId);
+                // Separate Timeout will be introduced to "download and parse the body"
+            }
             res.statusFamily = this.getStatusFamily(res);
             res.statusCode = (_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status;
             if ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.ok) {
-                await this.onOkResponse(res, timeout);
+                try {
+                    // We are applying a separate Timeout (as long as original Timeout for now) to "download and parse the body"
+                    await pTimeout(async () => await this.onOkResponse(res), {
+                        timeout: timeoutSeconds * 1000 || Number.POSITIVE_INFINITY,
+                        name: 'Fetcher.onOkResponse',
+                    });
+                }
+                catch (err) {
+                    // onOkResponse can still fail, e.g when loading/parsing json, text or doing other response manipulation
+                    res.err = _anyToError(err);
+                    res.ok = false;
+                    await this.onNotOkResponse(res);
+                }
             }
             else {
                 // !res.ok
-                await this.onNotOkResponse(res, timeout);
+                await this.onNotOkResponse(res);
             }
         }
         for (const hook of this.cfg.hooks.afterResponse || []) {
@@ -175,31 +220,17 @@ export class Fetcher {
         }
         return res;
     }
-    async onOkResponse(res, timeout) {
+    async onOkResponse(res) {
         const { req } = res;
         const { responseType } = res.req;
+        // This function is subject to a separate timeout to "download and parse the data"
         if (responseType === 'json') {
             if (res.fetchResponse.body) {
                 const text = await res.fetchResponse.text();
                 if (text) {
-                    try {
-                        res.body = text;
-                        res.body = _jsonParse(text, req.jsonReviver);
-                    }
-                    catch (err) {
-                        // Error while parsing json
-                        // res.err = _anyToError(err, HttpRequestError, {
-                        //   requestUrl: res.req.url,
-                        //   requestBaseUrl: this.cfg.baseUrl,
-                        //   requestMethod: res.req.init.method,
-                        //   requestSignature: res.signature,
-                        //   requestDuration: Date.now() - started,
-                        //   responseStatusCode: res.fetchResponse.status,
-                        // } satisfies HttpRequestErrorData)
-                        res.err = _anyToError(err);
-                        res.ok = false;
-                        return await this.onNotOkResponse(res, timeout);
-                    }
+                    res.body = text;
+                    res.body = _jsonParse(text, req.jsonReviver);
+                    // Error while parsing json can happen - it'll be handled upstream
                 }
                 else {
                     // Body had a '' (empty string)
@@ -224,12 +255,10 @@ export class Fetcher {
         else if (responseType === 'readableStream') {
             res.body = res.fetchResponse.body;
             if (res.body === null) {
-                res.err = new Error(`fetchResponse.body is null`);
-                res.ok = false;
-                return await this.onNotOkResponse(res, timeout);
+                // Error is to be handled upstream
+                throw new Error(`fetchResponse.body is null`);
             }
         }
-        clearTimeout(timeout);
         res.retryStatus.retryStopped = true;
         // res.err can happen on `failed to fetch` type of error, e.g JSON.parse, CORS, unexpected redirect
         if (!res.err && this.cfg.logResponse) {
@@ -253,11 +282,14 @@ export class Fetcher {
      * This method exists to be able to easily mock it.
      */
     async callNativeFetch(url, init) {
+        // If global mock is defined - call it instead of the native Fetch
+        if (globalFetcherMock) {
+            return await globalFetcherMock(url, init);
+        }
         return await globalThis.fetch(url, init);
     }
-    async onNotOkResponse(res, timeout) {
+    async onNotOkResponse(res) {
         var _a, _b;
-        clearTimeout(timeout);
         let cause;
         if (res.err) {
             // This is only possible on JSON.parse error, or CORS error,
@@ -271,6 +303,11 @@ export class Fetcher {
                 cause = _anyToErrorObject(body);
             }
         }
+        cause || (cause = {
+            name: 'Error',
+            message: 'Fetch failed',
+            data: {},
+        });
         const message = [(_a = res.fetchResponse) === null || _a === void 0 ? void 0 : _a.status, res.signature].filter(Boolean).join(' ');
         res.err = new HttpRequestError(message, _filterNullishValues({
             responseStatusCode: ((_b = res.fetchResponse) === null || _b === void 0 ? void 0 : _b.status) || 0,
@@ -324,7 +361,11 @@ export class Fetcher {
             return;
         retryStatus.retryAttempt++;
         retryStatus.retryTimeout = _clamp(retryStatus.retryTimeout * timeoutMultiplier, 0, timeoutMax);
-        await pDelay(this.getRetryTimeout(res));
+        const timeout = this.getRetryTimeout(res);
+        if (res.req.debug) {
+            this.cfg.logger.log(` .. ${res.signature} waiting ${_ms(timeout)}`);
+        }
+        await pDelay(timeout);
     }
     getRetryTimeout(res) {
         var _a;
@@ -380,8 +421,9 @@ export class Fetcher {
         if (statusFamily === 3 && !retry3xx)
             return false;
         // should not retry on `unexpected redirect` in error.cause.cause
-        if ((_e = (_d = (_c = (_b = res.err) === null || _b === void 0 ? void 0 : _b.cause) === null || _c === void 0 ? void 0 : _c.cause) === null || _d === void 0 ? void 0 : _d.message) === null || _e === void 0 ? void 0 : _e.includes('unexpected redirect'))
+        if ((_e = (_d = (_c = (_b = res.err) === null || _b === void 0 ? void 0 : _b.cause) === null || _c === void 0 ? void 0 : _c.cause) === null || _d === void 0 ? void 0 : _d.message) === null || _e === void 0 ? void 0 : _e.includes('unexpected redirect')) {
             return false;
+        }
         return true; // default is true
     }
     getStatusFamily(res) {
@@ -421,14 +463,14 @@ export class Fetcher {
     normalizeCfg(cfg) {
         var _a;
         if ((_a = cfg.baseUrl) === null || _a === void 0 ? void 0 : _a.endsWith('/')) {
-            console.warn(`Fetcher: baseUrl should not end with /`);
+            console.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`);
             cfg.baseUrl = cfg.baseUrl.slice(0, cfg.baseUrl.length - 1);
         }
         const { debug = false } = cfg;
         const norm = _merge({
             baseUrl: '',
             inputUrl: '',
-            responseType: 'void',
+            responseType: 'json',
             searchParams: {},
             timeoutSeconds: 30,
             retryPost: false,
@@ -469,6 +511,7 @@ export class Fetcher {
             'logRequestBody',
             'logResponse',
             'logResponseBody',
+            'debug',
         ])), { started: Date.now() }), _omit(opt, ['method', 'headers', 'credentials'])), { inputUrl: opt.url || '', fullUrl: opt.url || '', retry: Object.assign(Object.assign({}, this.cfg.retry), _filterUndefinedValues(opt.retry || {})), init: _merge(Object.assign(Object.assign({}, this.cfg.init), { method: opt.method || this.cfg.init.method, credentials: opt.credentials || this.cfg.init.credentials, redirect: opt.redirect || this.cfg.init.redirect || 'follow' }), {
                 headers: _mapKeys(opt.headers || {}, k => k.toLowerCase()),
             }) });

package/package.json

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

package/src/error/assert.ts

@@ -102,6 +102,21 @@ export function _assertIsError<ERR extends Error = Error>(
   }
 }
 
+/**
+ * Asserts that passed object is indeed an Error of defined ErrorClass.
+ * If yes - returns peacefully (with TypeScript assertion).
+ * In not - throws (re-throws) that error up.
+ */
+export function _assertErrorClassOrRethrow<ERR extends Error>(
+  err: any,
+  errorClass: Class<ERR>,
+): asserts err is ERR {
+  if (!(err instanceof errorClass)) {
+    // re-throw
+    throw err
+  }
+}
+
 export function _assertIsErrorObject<DATA_TYPE extends ErrorData = ErrorData>(
   obj: any,
 ): asserts obj is ErrorObject<DATA_TYPE> {

package/src/error/httpRequestError.ts

@@ -19,7 +19,14 @@ import type { ErrorObject, HttpRequestErrorData } from './error.model'
  * (by default).
  */
 export class HttpRequestError extends AppError<HttpRequestErrorData> {
-  constructor(message: string, data: HttpRequestErrorData, cause?: ErrorObject) {
+  constructor(message: string, data: HttpRequestErrorData, cause: ErrorObject) {
     super(message, data, cause, 'HttpRequestError')
   }
+
+  /**
+   * Cause is strictly-defined for HttpRequestError,
+   * so it always has a cause.
+   * (for dev convenience)
+   */
+  override cause!: ErrorObject
 }

package/src/error/try.ts

@@ -1,7 +1,8 @@
 import { _stringifyAny } from '../string/stringifyAny'
 import type { Class } from '../typeFest'
-import type { AnyFunction } from '../types'
+import type { AnyFunction, ErrorDataTuple } from '../types'
 import { AppError } from './app.error'
+import { _assertErrorClassOrRethrow } from './assert'
 
 /**
  * Calls a function, returns a Tuple of [error, value].
@@ -10,9 +11,6 @@ import { AppError } from './app.error'
  *
  * Similar to pTry, but for sync functions.
  *
- * For convenience, second argument type is non-optional,
- * so you can use it without `!`. But you SHOULD always check `if (err)` first!
- *
  * ERR is typed as Error, not `unknown`. While unknown would be more correct,
  * according to recent TypeScript, Error gives more developer convenience.
  * In our code we NEVER throw non-errors.
@@ -25,29 +23,35 @@ import { AppError } from './app.error'
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export function _try<ERR = Error, RETURN = void>(
-  fn: () => RETURN,
-): [err: ERR | null, value: RETURN] {
+export function _try<T, ERR extends Error = Error>(
+  fn: () => T,
+  errorClass?: Class<ERR>,
+): ErrorDataTuple<T, ERR> {
   try {
     return [null, fn()]
   } catch (err) {
-    return [err as ERR, undefined as any]
+    if (errorClass) {
+      _assertErrorClassOrRethrow(err, errorClass)
+    }
+
+    return [err as ERR, null]
   }
 }
 
 /**
  * Like _try, but for Promises.
- *
- * Also, intentionally types second return item as non-optional,
- * but you should check for `err` presense first!
  */
-export async function pTry<ERR = Error, RETURN = void>(
-  promise: Promise<RETURN>,
-): Promise<[err: ERR | null, value: Awaited<RETURN>]> {
+export async function pTry<T, ERR extends Error = Error>(
+  promise: Promise<T>,
+  errorClass?: Class<ERR>,
+): Promise<ErrorDataTuple<Awaited<T>, ERR>> {
   try {
     return [null, await promise]
   } catch (err) {
-    return [err as ERR, undefined as any]
+    if (errorClass) {
+      _assertErrorClassOrRethrow(err, errorClass)
+    }
+    return [err as ERR, null]
   }
 }
 
@@ -122,5 +126,17 @@ export async function pExpectedErrorString<ERR = Error>(
   promise: Promise<any>,
   errorClass?: Class<ERR>,
 ): Promise<string> {
-  return _stringifyAny(await pExpectedError<ERR>(promise, errorClass))
+  const err = await pExpectedError<ERR>(promise, errorClass)
+  return _stringifyAny(err)
+}
+
+/**
+ * Shortcut function to simplify error snapshot-matching in tests.
+ */
+export function _expectedErrorString<ERR = Error>(
+  fn: AnyFunction,
+  errorClass?: Class<ERR>,
+): string {
+  const err = _expectedError<ERR>(fn, errorClass)
+  return _stringifyAny(err)
 }

package/src/http/fetcher.model.ts

@@ -1,6 +1,6 @@
 import type { CommonLogger } from '../log/commonLogger'
 import type { Promisable } from '../typeFest'
-import type { AnyObject, Reviver, UnixTimestampMillisNumber } from '../types'
+import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types'
 import type { HttpMethod, HttpStatusFamily } from './http.model'
 
 export interface FetcherNormalizedCfg
@@ -13,6 +13,7 @@ export interface FetcherNormalizedCfg
       | 'logRequestBody'
       | 'logResponse'
       | 'logResponseBody'
+      | 'debug'
       | 'redirect'
       | 'credentials'
     > {
@@ -93,14 +94,14 @@ export interface FetcherCfg {
 
 export interface FetcherRetryStatus {
   retryAttempt: number
-  retryTimeout: number
+  retryTimeout: NumberOfMilliseconds
   retryStopped: boolean
 }
 
 export interface FetcherRetryOptions {
   count: number
-  timeout: number
-  timeoutMax: number
+  timeout: NumberOfMilliseconds
+  timeoutMax: NumberOfMilliseconds
   timeoutMultiplier: number
 }
 
@@ -185,7 +186,7 @@ export interface FetcherOptions {
   // init?: Partial<RequestInitNormalized>
 
   headers?: Record<string, any>
-  responseType?: FetcherResponseType // default to 'void'
+  responseType?: FetcherResponseType // default to 'json'
 
   searchParams?: Record<string, any>
 
@@ -219,6 +220,10 @@ export interface FetcherOptions {
   logRequestBody?: boolean
   logResponse?: boolean
   logResponseBody?: boolean
+  /**
+   * If true - enables all possible logging.
+   */
+  debug?: boolean
 }
 
 export type RequestInitNormalized = Omit<RequestInit, 'method' | 'headers'> & {
@@ -261,3 +266,10 @@ export type FetcherResponseType =
   | 'arrayBuffer'
   | 'blob'
   | 'readableStream'
+
+/**
+ * Function that mocks `Fetcher.callNativeFetch` globally.
+ *
+ * url is `fullUrl` (includes baseUrl and all).
+ */
+export type FetcherMockFunction = (url: string, init: RequestInitNormalized) => Promise<Response>