@naturalcycles/js-lib 14.157.1 → 14.158.0

package/dist/error/assert.d.ts

@@ -33,6 +33,12 @@ export declare function _assertEquals<T>(actual: any, expected: T, message?: str
  */
 export declare function _assertDeepEquals<T>(actual: any, expected: T, message?: string, errorData?: ErrorData): asserts actual is T;
 export declare function _assertIsError<ERR extends Error = Error>(err: any, errorClass?: Class<ERR>): asserts err is ERR;
+/**
+ * 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 declare function _assertErrorClassOrRethrow<ERR extends Error>(err: any, errorClass: Class<ERR>): asserts err is ERR;
 export declare function _assertIsErrorObject<DATA_TYPE extends ErrorData = ErrorData>(obj: any): asserts obj is ErrorObject<DATA_TYPE>;
 export declare function _assertIsString(v: any, message?: string): asserts v is string;
 export declare function _assertIsNumber(v: any, message?: string): asserts v is number;

package/dist/error/assert.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AssertionError = exports._assertTypeOf = exports._assertIsNumber = exports._assertIsString = exports._assertIsErrorObject = exports._assertIsError = exports._assertDeepEquals = exports._assertEquals = exports._assert = void 0;
+exports.AssertionError = exports._assertTypeOf = exports._assertIsNumber = exports._assertIsString = exports._assertIsErrorObject = exports._assertErrorClassOrRethrow = exports._assertIsError = exports._assertDeepEquals = exports._assertEquals = exports._assert = void 0;
 const __1 = require("..");
 const app_error_1 = require("./app.error");
 /**
@@ -84,6 +84,18 @@ function _assertIsError(err, errorClass = Error) {
     }
 }
 exports._assertIsError = _assertIsError;
+/**
+ * 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.
+ */
+function _assertErrorClassOrRethrow(err, errorClass) {
+    if (!(err instanceof errorClass)) {
+        // re-throw
+        throw err;
+    }
+}
+exports._assertErrorClassOrRethrow = _assertErrorClassOrRethrow;
 function _assertIsErrorObject(obj) {
     if (!(0, __1._isErrorObject)(obj)) {
         const msg = [`expected to be ErrorObject`, `actual typeof: ${typeof obj}`].join('\n');

package/dist/error/httpRequestError.d.ts

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

package/dist/error/try.d.ts

@@ -1,5 +1,5 @@
 import type { Class } from '../typeFest';
-import type { AnyFunction } from '../types';
+import type { AnyFunction, ErrorDataTuple } from '../types';
 import { AppError } from './app.error';
 /**
  * Calls a function, returns a Tuple of [error, value].
@@ -8,9 +8,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.
@@ -23,14 +20,11 @@ import { AppError } from './app.error';
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export declare function _try<ERR = Error, RETURN = void>(fn: () => RETURN): [err: ERR | null, value: RETURN];
+export declare function _try<T, ERR extends Error = Error>(fn: () => T, errorClass?: Class<ERR>): ErrorDataTuple<T, ERR>;
 /**
  * Like _try, but for Promises.
- *
- * Also, intentionally types second return item as non-optional,
- * but you should check for `err` presense first!
  */
-export declare function pTry<ERR = Error, RETURN = void>(promise: Promise<RETURN>): Promise<[err: ERR | null, value: Awaited<RETURN>]>;
+export declare function pTry<T, ERR extends Error = Error>(promise: Promise<T>, errorClass?: Class<ERR>): Promise<ErrorDataTuple<Awaited<T>, ERR>>;
 /**
  * It is thrown when Error was expected, but didn't happen
  * ("pass" happened instead).
@@ -61,3 +55,7 @@ export declare function pExpectedError<ERR = Error>(promise: Promise<any>, error
  * Shortcut function to simplify error snapshot-matching in tests.
  */
 export declare function pExpectedErrorString<ERR = Error>(promise: Promise<any>, errorClass?: Class<ERR>): Promise<string>;
+/**
+ * Shortcut function to simplify error snapshot-matching in tests.
+ */
+export declare function _expectedErrorString<ERR = Error>(fn: AnyFunction, errorClass?: Class<ERR>): string;

package/dist/error/try.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pExpectedErrorString = exports.pExpectedError = exports._expectedError = exports.UnexpectedPassError = exports.pTry = exports._try = void 0;
+exports._expectedErrorString = exports.pExpectedErrorString = exports.pExpectedError = exports._expectedError = exports.UnexpectedPassError = exports.pTry = exports._try = void 0;
 const stringifyAny_1 = require("../string/stringifyAny");
 const app_error_1 = require("./app.error");
+const assert_1 = require("./assert");
 /**
  * Calls a function, returns a Tuple of [error, value].
  * Allows to write shorter code that avoids `try/catch`.
@@ -10,9 +11,6 @@ const app_error_1 = require("./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,27 +23,30 @@ const app_error_1 = require("./app.error");
  * if (err) ...do something...
  * v // go ahead and use v
  */
-function _try(fn) {
+function _try(fn, errorClass) {
     try {
         return [null, fn()];
     }
     catch (err) {
-        return [err, undefined];
+        if (errorClass) {
+            (0, assert_1._assertErrorClassOrRethrow)(err, errorClass);
+        }
+        return [err, null];
     }
 }
 exports._try = _try;
 /**
  * Like _try, but for Promises.
- *
- * Also, intentionally types second return item as non-optional,
- * but you should check for `err` presense first!
  */
-async function pTry(promise) {
+async function pTry(promise, errorClass) {
     try {
         return [null, await promise];
     }
     catch (err) {
-        return [err, undefined];
+        if (errorClass) {
+            (0, assert_1._assertErrorClassOrRethrow)(err, errorClass);
+        }
+        return [err, null];
     }
 }
 exports.pTry = pTry;
@@ -114,6 +115,15 @@ exports.pExpectedError = pExpectedError;
  * Shortcut function to simplify error snapshot-matching in tests.
  */
 async function pExpectedErrorString(promise, errorClass) {
-    return (0, stringifyAny_1._stringifyAny)(await pExpectedError(promise, errorClass));
+    const err = await pExpectedError(promise, errorClass);
+    return (0, stringifyAny_1._stringifyAny)(err);
 }
 exports.pExpectedErrorString = pExpectedErrorString;
+/**
+ * Shortcut function to simplify error snapshot-matching in tests.
+ */
+function _expectedErrorString(fn, errorClass) {
+    const err = _expectedError(fn, errorClass);
+    return (0, stringifyAny_1._stringifyAny)(err);
+}
+exports._expectedErrorString = _expectedErrorString;

package/dist/http/fetcher.d.ts

@@ -1,6 +1,17 @@
 /// <reference lib="dom" />
 /// <reference lib="dom.iterable" />
-import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeRetryHook, FetcherCfg, FetcherNormalizedCfg, FetcherOptions, FetcherResponse } from './fetcher.model';
+import { HttpRequestError } from '../error/httpRequestError';
+import { ErrorDataTuple } from '../types';
+import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeRetryHook, FetcherCfg, FetcherNormalizedCfg, FetcherOptions, FetcherResponse, FetcherMockFunction, RequestInitNormalized } from './fetcher.model';
+/**
+ * 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 declare function setGlobalFetcherMock(fn: FetcherMockFunction | null): void;
 /**
  * Experimental wrapper around Fetch.
  * Works in both Browser and Node, using `globalThis.fetch`.
@@ -39,17 +50,27 @@ export declare class Fetcher {
      */
     getReadableStream(url: string, opt?: FetcherOptions): Promise<ReadableStream<Uint8Array>>;
     fetch<T = unknown>(opt: FetcherOptions): Promise<T>;
+    /**
+     * 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.
+     */
+    tryFetch<T = unknown>(opt: FetcherOptions): Promise<ErrorDataTuple<T, HttpRequestError>>;
     /**
      * 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.
      */
     doFetch<T = unknown>(opt: FetcherOptions): Promise<FetcherResponse<T>>;
     private onOkResponse;
     /**
      * This method exists to be able to easily mock it.
      */
-    callNativeFetch(url: string, init: RequestInit): Promise<Response>;
+    callNativeFetch(url: string, init: RequestInitNormalized): Promise<Response>;
     private onNotOkResponse;
     private processRetry;
     private getRetryTimeout;

package/dist/http/fetcher.js

@@ -2,8 +2,9 @@
 /// <reference lib="dom"/>
 /// <reference lib="dom.iterable"/>
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFetcher = exports.Fetcher = void 0;
+exports.getFetcher = exports.Fetcher = exports.setGlobalFetcherMock = void 0;
 const env_1 = require("../env");
+const assert_1 = require("../error/assert");
 const error_util_1 = require("../error/error.util");
 const httpRequestError_1 = require("../error/httpRequestError");
 const number_util_1 = require("../number/number.util");
@@ -28,6 +29,19 @@ 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.
+ */
+function setGlobalFetcherMock(fn) {
+    globalFetcherMock = fn;
+}
+exports.setGlobalFetcherMock = setGlobalFetcherMock;
 /**
  * Experimental wrapper around Fetch.
  * Works in both Browser and Node, using `globalThis.fetch`.
@@ -112,10 +126,27 @@ 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) {
+            (0, assert_1._assertErrorClassOrRethrow)(res.err, httpRequestError_1.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) {
         const req = this.normalizeOptions(opt);
@@ -267,6 +298,10 @@ 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) {
@@ -283,6 +318,11 @@ class Fetcher {
                 cause = (0, error_util_1._anyToErrorObject)(body);
             }
         }
+        cause ||= {
+            name: 'Error',
+            message: 'Fetch failed',
+            data: {},
+        };
         const message = [res.fetchResponse?.status, res.signature].filter(Boolean).join(' ');
         res.err = new httpRequestError_1.HttpRequestError(message, (0, object_util_1._filterNullishValues)({
             responseStatusCode: res.fetchResponse?.status || 0,
@@ -441,7 +481,7 @@ class Fetcher {
         const norm = (0, object_util_1._merge)({
             baseUrl: '',
             inputUrl: '',
-            responseType: 'void',
+            responseType: 'json',
             searchParams: {},
             timeoutSeconds: 30,
             retryPost: false,

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

@@ -205,3 +205,9 @@ export interface FetcherErrorResponse<BODY = unknown> {
 }
 export type FetcherResponse<BODY = unknown> = FetcherSuccessResponse<BODY> | FetcherErrorResponse<BODY>;
 export type FetcherResponseType = 'json' | 'text' | 'void' | '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>;

package/dist/types.d.ts

@@ -207,3 +207,14 @@ export declare function _typeCast<T>(v: any): asserts v is T;
  * Type-safe Object.assign that checks that part is indeed a Partial<T>
  */
 export declare const _objectAssign: <T extends AnyObject>(target: T, part: Partial<T>) => T;
+/**
+ * Defines a tuple of [err, data]
+ * where only 1 of them exists.
+ * Either error exists and data is null
+ * Or error is null and data is defined.
+ * This forces you to check `if (err)`, which lets
+ * TypeScript infer the existence of `data`.
+ *
+ * Functions like pTry use that.
+ */
+export type ErrorDataTuple<T = unknown, ERR = Error> = [err: null, data: T] | [err: ERR, data: null];

package/dist-esm/error/assert.js

@@ -68,6 +68,17 @@ export function _assertIsError(err, errorClass = 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, errorClass) {
+    if (!(err instanceof errorClass)) {
+        // re-throw
+        throw err;
+    }
+}
 export function _assertIsErrorObject(obj) {
     if (!_isErrorObject(obj)) {
         const msg = [`expected to be ErrorObject`, `actual typeof: ${typeof obj}`].join('\n');

package/dist-esm/error/try.js

@@ -1,5 +1,6 @@
 import { _stringifyAny } from '../string/stringifyAny';
 import { AppError } from './app.error';
+import { _assertErrorClassOrRethrow } from './assert';
 /**
  * Calls a function, returns a Tuple of [error, value].
  * Allows to write shorter code that avoids `try/catch`.
@@ -7,9 +8,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.
@@ -22,26 +20,29 @@ import { AppError } from './app.error';
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export function _try(fn) {
+export function _try(fn, errorClass) {
     try {
         return [null, fn()];
     }
     catch (err) {
-        return [err, undefined];
+        if (errorClass) {
+            _assertErrorClassOrRethrow(err, errorClass);
+        }
+        return [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(promise) {
+export async function pTry(promise, errorClass) {
     try {
         return [null, await promise];
     }
     catch (err) {
-        return [err, undefined];
+        if (errorClass) {
+            _assertErrorClassOrRethrow(err, errorClass);
+        }
+        return [err, null];
     }
 }
 /**
@@ -106,5 +107,13 @@ export async function pExpectedError(promise, errorClass) {
  * Shortcut function to simplify error snapshot-matching in tests.
  */
 export async function pExpectedErrorString(promise, errorClass) {
-    return _stringifyAny(await pExpectedError(promise, errorClass));
+    const err = await pExpectedError(promise, errorClass);
+    return _stringifyAny(err);
+}
+/**
+ * Shortcut function to simplify error snapshot-matching in tests.
+ */
+export function _expectedErrorString(fn, errorClass) {
+    const err = _expectedError(fn, errorClass);
+    return _stringifyAny(err);
 }

package/dist-esm/http/fetcher.js

@@ -1,6 +1,7 @@
 /// <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';
@@ -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,10 +109,27 @@ 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;
@@ -252,6 +282,10 @@ 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) {
@@ -269,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,
@@ -431,7 +470,7 @@ export class Fetcher {
         const norm = _merge({
             baseUrl: '',
             inputUrl: '',
-            responseType: 'void',
+            responseType: 'json',
             searchParams: {},
             timeoutSeconds: 30,
             retryPost: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.157.1",
+  "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

@@ -186,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>
 
@@ -266,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>

package/src/http/fetcher.ts

@@ -2,6 +2,7 @@
 /// <reference lib="dom.iterable"/>
 
 import { isServerSide } from '../env'
+import { _assertErrorClassOrRethrow } from '../error/assert'
 import { ErrorLike, ErrorObject } from '../error/error.model'
 import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject } from '../error/error.util'
 import { HttpRequestError } from '../error/httpRequestError'
@@ -19,7 +20,7 @@ import { pTimeout, TimeoutError } from '../promise/pTimeout'
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util'
 import { _stringifyAny } from '../string/stringifyAny'
 import { _ms, _since } from '../time/time.util'
-import { NumberOfMilliseconds } from '../types'
+import { ErrorDataTuple, NumberOfMilliseconds } from '../types'
 import type {
   FetcherAfterResponseHook,
   FetcherBeforeRequestHook,
@@ -31,6 +32,8 @@ import type {
   FetcherResponse,
   FetcherResponseType,
   FetcherRetryOptions,
+  FetcherMockFunction,
+  RequestInitNormalized,
 } from './fetcher.model'
 import { HTTP_METHODS } from './http.model'
 import type { HttpStatusFamily } from './http.model'
@@ -51,6 +54,20 @@ const defRetryOptions: FetcherRetryOptions = {
   timeoutMultiplier: 2,
 }
 
+let globalFetcherMock: FetcherMockFunction | null = 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: FetcherMockFunction | null): void {
+  globalFetcherMock = fn
+}
+
 /**
  * Experimental wrapper around Fetch.
  * Works in both Browser and Node, using `globalThis.fetch`.
@@ -169,10 +186,28 @@ 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<T = unknown>(opt: FetcherOptions): Promise<ErrorDataTuple<T, HttpRequestError>> {
+    const res = await this.doFetch<T>(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<T = unknown>(opt: FetcherOptions): Promise<FetcherResponse<T>> {
     const req = this.normalizeOptions(opt)
@@ -344,12 +379,17 @@ export class Fetcher {
   /**
    * This method exists to be able to easily mock it.
    */
-  async callNativeFetch(url: string, init: RequestInit): Promise<Response> {
+  async callNativeFetch(url: string, init: RequestInitNormalized): Promise<Response> {
+    // 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)
   }
 
   private async onNotOkResponse(res: FetcherResponse): Promise<void> {
-    let cause: ErrorObject | undefined
+    let cause: ErrorObject
 
     if (res.err) {
       // This is only possible on JSON.parse error, or CORS error,
@@ -363,6 +403,12 @@ export class Fetcher {
       }
     }
 
+    cause ||= {
+      name: 'Error',
+      message: 'Fetch failed',
+      data: {},
+    }
+
     const message = [res.fetchResponse?.status, res.signature].filter(Boolean).join(' ')
 
     res.err = new HttpRequestError(
@@ -545,7 +591,7 @@ export class Fetcher {
       {
         baseUrl: '',
         inputUrl: '',
-        responseType: 'void',
+        responseType: 'json',
         searchParams: {},
         timeoutSeconds: 30,
         retryPost: false,

package/src/types.ts

@@ -278,3 +278,15 @@ export const _objectAssign = Object.assign as <T extends AnyObject>(
   target: T,
   part: Partial<T>,
 ) => T
+
+/**
+ * Defines a tuple of [err, data]
+ * where only 1 of them exists.
+ * Either error exists and data is null
+ * Or error is null and data is defined.
+ * This forces you to check `if (err)`, which lets
+ * TypeScript infer the existence of `data`.
+ *
+ * Functions like pTry use that.
+ */
+export type ErrorDataTuple<T = unknown, ERR = Error> = [err: null, data: T] | [err: ERR, data: null]