@naturalcycles/js-lib 14.253.0 → 14.255.0

package/dist/array/array.util.d.ts

@@ -161,11 +161,15 @@ export declare function _intersection<T>(a1: T[], a2: T[] | Set<T>): T[];
  */
 export declare function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean;
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export declare function _difference<T>(source: T[], ...diffs: T[][]): T[];
+export declare function _difference<T>(a1: T[], a2: T[] | Set<T>): T[];
 /**
  * Returns the sum of items, or 0 for empty array.
  */

package/dist/array/array.util.js

@@ -318,16 +318,17 @@ function _intersectsWith(a1, a2) {
     return a1.some(v => a2set.has(v));
 }
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-function _difference(source, ...diffs) {
-    let a = source;
-    for (const b of diffs) {
-        a = a.filter(c => !b.includes(c));
-    }
-    return a;
+function _difference(a1, a2) {
+    const a2set = a2 instanceof Set ? a2 : new Set(a2);
+    return a1.filter(v => !a2set.has(v));
 }
 /**
  * Returns the sum of items, or 0 for empty array.

package/dist/env.js

@@ -9,6 +9,7 @@ exports.isClientSide = isClientSide;
  * Will return `false` in the Browser.
  */
 function isServerSide() {
+    // eslint-disable-next-line unicorn/prefer-global-this
     return typeof window === 'undefined';
 }
 /**
@@ -18,5 +19,6 @@ function isServerSide() {
  * Will return `false` in Node.js.
  */
 function isClientSide() {
+    // eslint-disable-next-line unicorn/prefer-global-this
     return typeof window !== 'undefined';
 }

package/dist/error/error.util.js

@@ -219,10 +219,9 @@ function _isErrorLike(o) {
 function _errorDataAppend(err, data) {
     if (!data)
         return err;
-    err.data = {
-        ...err.data,
-        ...data,
-    };
+    err.data ||= {}; // create err.data if it doesn't exist
+    // Using Object.assign instead of ...data to not override err.data's non-enumerable properties
+    Object.assign(err.data, data);
     return err;
 }
 /**

package/dist/error/tryCatch.js

@@ -29,7 +29,7 @@ function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError((0, index_1._anyToError)(err)); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError((0, index_1._anyToError)(err));
                 }
                 catch { }
             }

package/dist/http/fetcher.d.ts

@@ -3,7 +3,7 @@
 /// <reference lib="dom.iterable" preserve="true" />
 import { HttpRequestError } from '../error/error.util';
 import { ErrorDataTuple } from '../types';
-import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeRetryHook, FetcherCfg, FetcherNormalizedCfg, FetcherOptions, FetcherResponse, RequestInitNormalized } from './fetcher.model';
+import type { FetcherAfterResponseHook, FetcherBeforeRequestHook, FetcherBeforeRetryHook, FetcherCfg, FetcherNormalizedCfg, FetcherOnErrorHook, FetcherOptions, FetcherResponse, RequestInitNormalized } from './fetcher.model';
 /**
  * Experimental wrapper around Fetch.
  * Works in both Browser and Node, using `globalThis.fetch`.
@@ -24,6 +24,7 @@ export declare class Fetcher {
     onBeforeRequest(hook: FetcherBeforeRequestHook): this;
     onAfterResponse(hook: FetcherAfterResponseHook): this;
     onBeforeRetry(hook: FetcherBeforeRetryHook): this;
+    onError(hook: FetcherOnErrorHook): this;
     cfg: FetcherNormalizedCfg;
     static create(cfg?: FetcherCfg & FetcherOptions): Fetcher;
     get: <T = unknown>(url: string, opt?: FetcherOptions) => Promise<T>;

package/dist/http/fetcher.js

@@ -98,6 +98,11 @@ class Fetcher {
         (this.cfg.hooks.beforeRetry ||= []).push(hook);
         return this;
     }
+    onError(hook) {
+        ;
+        (this.cfg.hooks.onError ||= []).push(hook);
+        return this;
+    }
     static create(cfg = {}) {
         return new Fetcher(cfg);
     }
@@ -195,12 +200,12 @@ class Fetcher {
                     abortController.abort(new error_util_1.TimeoutError(`request timed out after ${timeoutSeconds} sec`));
                 }, timeoutSeconds * 1000);
             }
-            if (this.cfg.logRequest) {
+            if (req.logRequest) {
                 const { retryAttempt } = res.retryStatus;
                 logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`]
                     .filter(Boolean)
                     .join(' '));
-                if (this.cfg.logRequestBody && req.init.body) {
+                if (req.logRequestBody && req.init.body) {
                     logger.log(req.init.body); // todo: check if we can _inspect it
                 }
             }
@@ -248,6 +253,13 @@ class Fetcher {
                 await this.onNotOkResponse(res);
             }
         }
+        if (res.err) {
+            (0, error_util_1._errorDataAppend)(res.err, req.errorData);
+            req.onError?.(res.err);
+            for (const hook of this.cfg.hooks.onError || []) {
+                await hook(res.err);
+            }
+        }
         for (const hook of this.cfg.hooks.afterResponse || []) {
             await hook(res);
         }
@@ -294,7 +306,7 @@ class Fetcher {
         }
         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 || !req.throwHttpErrors) && this.cfg.logResponse) {
+        if ((!res.err || !req.throwHttpErrors) && req.logResponse) {
             const { retryAttempt } = res.retryStatus;
             const { logger } = this.cfg;
             logger.log([
@@ -306,7 +318,7 @@ class Fetcher {
             ]
                 .filter(Boolean)
                 .join(' '));
-            if (this.cfg.logResponseBody && res.body !== undefined) {
+            if (req.logResponseBody && res.body !== undefined) {
                 logger.log(res.body);
             }
         }
@@ -542,6 +554,7 @@ class Fetcher {
             },
             hooks: {},
             throwHttpErrors: true,
+            errorData: {},
         }, (0, object_util_1._omit)(cfg, ['method', 'credentials', 'headers', 'redirect', 'logger']));
         norm.init.headers = (0, object_util_1._mapKeys)(norm.init.headers, k => k.toLowerCase());
         return norm;
@@ -561,6 +574,7 @@ class Fetcher {
                 'logResponseBody',
                 'debug',
                 'throwHttpErrors',
+                'errorData',
             ]),
             started: Date.now(),
             ...(0, object_util_1._omit)(opt, ['method', 'headers', 'credentials']),

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

@@ -1,16 +1,22 @@
 /// <reference lib="es2022" preserve="true" />
 /// <reference lib="dom" preserve="true" />
+import type { ErrorData } from '../error/error.model';
 import type { CommonLogger } from '../log/commonLogger';
 import type { Promisable } from '../typeFest';
 import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types';
 import type { HttpMethod, HttpStatusFamily } from './http.model';
-export interface FetcherNormalizedCfg extends Required<FetcherCfg>, Omit<FetcherRequest, 'started' | 'fullUrl' | 'logRequest' | 'logRequestBody' | 'logResponse' | 'logResponseBody' | 'debug' | 'redirect' | 'credentials' | 'throwHttpErrors'> {
+export interface FetcherNormalizedCfg extends Required<FetcherCfg>, Omit<FetcherRequest, 'started' | 'fullUrl' | 'logRequest' | 'logRequestBody' | 'logResponse' | 'logResponseBody' | 'debug' | 'redirect' | 'credentials' | 'throwHttpErrors' | 'errorData'> {
     logger: CommonLogger;
     searchParams: Record<string, any>;
 }
 export type FetcherBeforeRequestHook = (req: FetcherRequest) => Promisable<void>;
 export type FetcherAfterResponseHook = <BODY = unknown>(res: FetcherResponse<BODY>) => Promisable<void>;
 export type FetcherBeforeRetryHook = <BODY = unknown>(res: FetcherResponse<BODY>) => Promisable<void>;
+/**
+ * Allows to mutate the error.
+ * Cannot cancel/prevent the error - AfterResponseHook can be used for that instead.
+ */
+export type FetcherOnErrorHook = (err: Error) => Promisable<void>;
 export interface FetcherCfg {
     /**
      * Should **not** contain trailing slash.
@@ -35,7 +41,17 @@ export interface FetcherCfg {
          * Allows to mutate res.retryStatus to override retry behavior.
          */
         beforeRetry?: FetcherBeforeRetryHook[];
+        onError?: FetcherOnErrorHook[];
     };
+    /**
+     * If Fetcher has an error - `errorData` object will be appended to the error data.
+     * Like this:
+     *
+     * _errorDataAppend(err, cfg.errorData)
+     *
+     * So you, for example, can append a `fingerprint` to any error thrown from this fetcher.
+     */
+    errorData?: ErrorData | undefined;
     /**
      * If true - enables all possible logging.
      */
@@ -188,6 +204,20 @@ export interface FetcherOptions {
      * Set to false to not throw on `!Response.ok`, but simply return `Response.body` as-is (json parsed, etc).
      */
     throwHttpErrors?: boolean;
+    /**
+     * If Fetcher has an error - `errorData` object will be appended to the error data.
+     * Like this:
+     *
+     * _errorDataAppend(err, cfg.errorData)
+     *
+     * So you, for example, can append a `fingerprint` to any error thrown from this fetcher.
+     */
+    errorData?: ErrorData;
+    /**
+     * Allows to mutate the error.
+     * Cannot cancel/prevent the error - AfterResponseHook can be used for that instead.
+     */
+    onError?: FetcherOnErrorHook;
 }
 export type RequestInitNormalized = Omit<RequestInit, 'method' | 'headers'> & {
     method: HttpMethod;

package/dist/number/number.util.js

@@ -56,6 +56,7 @@ function _isBetween(x, min, max, incl = '[)') {
     return x > min && x < max;
 }
 function _clamp(x, minIncl, maxIncl) {
+    // eslint-disable-next-line unicorn/prefer-math-min-max
     return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x;
 }
 /**

package/dist/object/object.util.js

@@ -366,6 +366,7 @@ function _get(obj = {}, path = '') {
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
 function _set(obj, path, value) {
+    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
     if (!obj || Object(obj) !== obj || !path)
         return obj; // When obj is not an object
     // If not yet an array, get the keys from the string-path
@@ -377,7 +378,9 @@ function _set(obj, path, value) {
     }
     // eslint-disable-next-line unicorn/no-array-reduce
     ;
-    path.slice(0, -1).reduce((a, c, i) => Object(a[c]) === a[c] // Does the key exist and is its value an object?
+    path.slice(0, -1).reduce((a, c, i) => 
+    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
+    Object(a[c]) === a[c] // Does the key exist and is its value an object?
         ? // Yes: then follow that path
             a[c]
         : // No: create the key. Is the next key a potential array-index?

package/dist/types.d.ts

@@ -1,4 +1,18 @@
 import type { Promisable } from './typeFest';
+declare const __brand: unique symbol;
+interface Brand<B> {
+    [__brand]: B;
+}
+/**
+ * Helper to create "Branded" types.
+ *
+ * Example:
+ * export type MyId = Branded<string, 'MyId'>
+ *
+ * MyId can be assigned to a string,
+ * but string cannot be assigned to MyId without casting it (`as MyId`).
+ */
+export type Branded<T, B> = T & Brand<B>;
 /**
  * Map from String to String (or <T>).
  *
@@ -292,3 +306,4 @@ export interface CommonClient extends AsyncDisposable {
     disconnect: () => Promise<void>;
     ping: () => Promise<void>;
 }
+export {};

package/dist-esm/array/array.util.js

@@ -277,16 +277,17 @@ export function _intersectsWith(a1, a2) {
     return a1.some(v => a2set.has(v));
 }
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _difference(source, ...diffs) {
-    let a = source;
-    for (const b of diffs) {
-        a = a.filter(c => !b.includes(c));
-    }
-    return a;
+export function _difference(a1, a2) {
+    const a2set = a2 instanceof Set ? a2 : new Set(a2);
+    return a1.filter(v => !a2set.has(v));
 }
 /**
  * Returns the sum of items, or 0 for empty array.

package/dist-esm/env.js

@@ -5,6 +5,7 @@
  * Will return `false` in the Browser.
  */
 export function isServerSide() {
+    // eslint-disable-next-line unicorn/prefer-global-this
     return typeof window === 'undefined';
 }
 /**
@@ -14,5 +15,6 @@ export function isServerSide() {
  * Will return `false` in Node.js.
  */
 export function isClientSide() {
+    // eslint-disable-next-line unicorn/prefer-global-this
     return typeof window !== 'undefined';
 }

package/dist-esm/error/error.util.js

@@ -204,12 +204,12 @@ export function _isErrorLike(o) {
  * }
  */
 export function _errorDataAppend(err, data) {
+    var _a;
     if (!data)
         return err;
-    err.data = {
-        ...err.data,
-        ...data,
-    };
+    (_a = err).data || (_a.data = {}); // create err.data if it doesn't exist
+    // Using Object.assign instead of ...data to not override err.data's non-enumerable properties
+    Object.assign(err.data, data);
     return err;
 }
 /**

package/dist-esm/error/tryCatch.js

@@ -25,7 +25,7 @@ export function _tryCatch(fn, opt = {}) {
             }
             if (onError) {
                 try {
-                    return await onError(_anyToError(err)); // eslint-disable-line @typescript-eslint/return-await
+                    return await onError(_anyToError(err));
                 }
                 catch { }
             }

package/dist-esm/http/fetcher.js

@@ -4,7 +4,7 @@
 var _a;
 import { isServerSide } from '../env';
 import { _assertErrorClassOrRethrow, _assertIsError } from '../error/assert';
-import { _anyToError, _anyToErrorObject, _errorLikeToErrorObject, HttpRequestError, TimeoutError, UnexpectedPassError, } from '../error/error.util';
+import { _anyToError, _anyToErrorObject, _errorDataAppend, _errorLikeToErrorObject, HttpRequestError, TimeoutError, UnexpectedPassError, } from '../error/error.util';
 import { _clamp } from '../number/number.util';
 import { _filterNullishValues, _filterUndefinedValues, _mapKeys, _merge, _omit, _pick, } from '../object/object.util';
 import { pDelay } from '../promise/pDelay';
@@ -90,6 +90,12 @@ export class Fetcher {
         ((_b = this.cfg.hooks).beforeRetry || (_b.beforeRetry = [])).push(hook);
         return this;
     }
+    onError(hook) {
+        var _b;
+        ;
+        ((_b = this.cfg.hooks).onError || (_b.onError = [])).push(hook);
+        return this;
+    }
     static create(cfg = {}) {
         return new _a(cfg);
     }
@@ -187,12 +193,12 @@ export class Fetcher {
                     abortController.abort(new TimeoutError(`request timed out after ${timeoutSeconds} sec`));
                 }, timeoutSeconds * 1000);
             }
-            if (this.cfg.logRequest) {
+            if (req.logRequest) {
                 const { retryAttempt } = res.retryStatus;
                 logger.log([' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`]
                     .filter(Boolean)
                     .join(' '));
-                if (this.cfg.logRequestBody && req.init.body) {
+                if (req.logRequestBody && req.init.body) {
                     logger.log(req.init.body); // todo: check if we can _inspect it
                 }
             }
@@ -240,6 +246,13 @@ export class Fetcher {
                 await this.onNotOkResponse(res);
             }
         }
+        if (res.err) {
+            _errorDataAppend(res.err, req.errorData);
+            req.onError?.(res.err);
+            for (const hook of this.cfg.hooks.onError || []) {
+                await hook(res.err);
+            }
+        }
         for (const hook of this.cfg.hooks.afterResponse || []) {
             await hook(res);
         }
@@ -286,7 +299,7 @@ export class Fetcher {
         }
         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 || !req.throwHttpErrors) && this.cfg.logResponse) {
+        if ((!res.err || !req.throwHttpErrors) && req.logResponse) {
             const { retryAttempt } = res.retryStatus;
             const { logger } = this.cfg;
             logger.log([
@@ -298,7 +311,7 @@ export class Fetcher {
             ]
                 .filter(Boolean)
                 .join(' '));
-            if (this.cfg.logResponseBody && res.body !== undefined) {
+            if (req.logResponseBody && res.body !== undefined) {
                 logger.log(res.body);
             }
         }
@@ -534,6 +547,7 @@ export class Fetcher {
             },
             hooks: {},
             throwHttpErrors: true,
+            errorData: {},
         }, _omit(cfg, ['method', 'credentials', 'headers', 'redirect', 'logger']));
         norm.init.headers = _mapKeys(norm.init.headers, k => k.toLowerCase());
         return norm;
@@ -554,6 +568,7 @@ export class Fetcher {
                 'logResponseBody',
                 'debug',
                 'throwHttpErrors',
+                'errorData',
             ]),
             started: Date.now(),
             ..._omit(opt, ['method', 'headers', 'credentials']),

package/dist-esm/number/number.util.js

@@ -45,6 +45,7 @@ export function _isBetween(x, min, max, incl = '[)') {
     return x > min && x < max;
 }
 export function _clamp(x, minIncl, maxIncl) {
+    // eslint-disable-next-line unicorn/prefer-math-min-max
     return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x;
 }
 /**

package/dist-esm/object/object.util.js

@@ -337,6 +337,7 @@ export function _get(obj = {}, path = '') {
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
 export function _set(obj, path, value) {
+    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
     if (!obj || Object(obj) !== obj || !path)
         return obj; // When obj is not an object
     // If not yet an array, get the keys from the string-path
@@ -348,7 +349,9 @@ export function _set(obj, path, value) {
     }
     // eslint-disable-next-line unicorn/no-array-reduce
     ;
-    path.slice(0, -1).reduce((a, c, i) => Object(a[c]) === a[c] // Does the key exist and is its value an object?
+    path.slice(0, -1).reduce((a, c, i) => 
+    // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
+    Object(a[c]) === a[c] // Does the key exist and is its value an object?
         ? // Yes: then follow that path
             a[c]
         : // No: create the key. Is the next key a potential array-index?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.253.0",
+  "version": "14.255.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/array/array.util.ts

@@ -331,16 +331,17 @@ export function _intersectsWith<T>(a1: T[], a2: T[] | Set<T>): boolean {
 }
 
 /**
+ * Returns array1 minus array2.
+ *
  * @example
  * _difference([2, 1], [2, 3])
  * // [1]
+ *
+ * Passing second array as Set is more performant (it'll skip turning the array into Set in-place).
  */
-export function _difference<T>(source: T[], ...diffs: T[][]): T[] {
-  let a = source
-  for (const b of diffs) {
-    a = a.filter(c => !b.includes(c))
-  }
-  return a
+export function _difference<T>(a1: T[], a2: T[] | Set<T>): T[] {
+  const a2set = a2 instanceof Set ? a2 : new Set(a2)
+  return a1.filter(v => !a2set.has(v))
 }
 
 /**

package/src/env.ts

@@ -5,6 +5,7 @@
  * Will return `false` in the Browser.
  */
 export function isServerSide(): boolean {
+  // eslint-disable-next-line unicorn/prefer-global-this
   return typeof window === 'undefined'
 }
 
@@ -15,5 +16,6 @@ export function isServerSide(): boolean {
  * Will return `false` in Node.js.
  */
 export function isClientSide(): boolean {
+  // eslint-disable-next-line unicorn/prefer-global-this
   return typeof window !== 'undefined'
 }

package/src/error/error.util.ts

@@ -265,11 +265,9 @@ export function _isErrorLike(o: any): o is ErrorLike {
  */
 export function _errorDataAppend<ERR>(err: ERR, data?: ErrorData): ERR {
   if (!data) return err
-  ;(err as any).data = {
-    ...(err as any).data,
-    ...data,
-  }
-
+  ;(err as any).data ||= {} // create err.data if it doesn't exist
+  // Using Object.assign instead of ...data to not override err.data's non-enumerable properties
+  Object.assign((err as any).data, data)
   return err
 }
 

package/src/error/tryCatch.ts

@@ -56,7 +56,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
 
       if (onError) {
         try {
-          return await onError(_anyToError(err)) // eslint-disable-line @typescript-eslint/return-await
+          return await onError(_anyToError(err))
         } catch {}
       }
       // returns undefined, but doesn't rethrow

package/src/http/fetcher.model.ts

@@ -1,6 +1,7 @@
 /// <reference lib="es2022" preserve="true" />
 /// <reference lib="dom" preserve="true" />
 
+import type { ErrorData } from '../error/error.model'
 import type { CommonLogger } from '../log/commonLogger'
 import type { Promisable } from '../typeFest'
 import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types'
@@ -20,6 +21,7 @@ export interface FetcherNormalizedCfg
       | 'redirect'
       | 'credentials'
       | 'throwHttpErrors'
+      | 'errorData'
     > {
   logger: CommonLogger
   searchParams: Record<string, any>
@@ -32,6 +34,11 @@ export type FetcherAfterResponseHook = <BODY = unknown>(
 export type FetcherBeforeRetryHook = <BODY = unknown>(
   res: FetcherResponse<BODY>,
 ) => Promisable<void>
+/**
+ * Allows to mutate the error.
+ * Cannot cancel/prevent the error - AfterResponseHook can be used for that instead.
+ */
+export type FetcherOnErrorHook = (err: Error) => Promisable<void>
 
 export interface FetcherCfg {
   /**
@@ -58,8 +65,20 @@ export interface FetcherCfg {
      * Allows to mutate res.retryStatus to override retry behavior.
      */
     beforeRetry?: FetcherBeforeRetryHook[]
+
+    onError?: FetcherOnErrorHook[]
   }
 
+  /**
+   * If Fetcher has an error - `errorData` object will be appended to the error data.
+   * Like this:
+   *
+   * _errorDataAppend(err, cfg.errorData)
+   *
+   * So you, for example, can append a `fingerprint` to any error thrown from this fetcher.
+   */
+  errorData?: ErrorData | undefined
+
   /**
    * If true - enables all possible logging.
    */
@@ -241,6 +260,22 @@ export interface FetcherOptions {
    * Set to false to not throw on `!Response.ok`, but simply return `Response.body` as-is (json parsed, etc).
    */
   throwHttpErrors?: boolean
+
+  /**
+   * If Fetcher has an error - `errorData` object will be appended to the error data.
+   * Like this:
+   *
+   * _errorDataAppend(err, cfg.errorData)
+   *
+   * So you, for example, can append a `fingerprint` to any error thrown from this fetcher.
+   */
+  errorData?: ErrorData
+
+  /**
+   * Allows to mutate the error.
+   * Cannot cancel/prevent the error - AfterResponseHook can be used for that instead.
+   */
+  onError?: FetcherOnErrorHook
 }
 
 export type RequestInitNormalized = Omit<RequestInit, 'method' | 'headers'> & {

package/src/http/fetcher.ts

@@ -8,6 +8,7 @@ import { ErrorLike, ErrorObject } from '../error/error.model'
 import {
   _anyToError,
   _anyToErrorObject,
+  _errorDataAppend,
   _errorLikeToErrorObject,
   HttpRequestError,
   TimeoutError,
@@ -34,6 +35,7 @@ import type {
   FetcherBeforeRetryHook,
   FetcherCfg,
   FetcherNormalizedCfg,
+  FetcherOnErrorHook,
   FetcherOptions,
   FetcherRequest,
   FetcherResponse,
@@ -135,6 +137,11 @@ export class Fetcher {
     return this
   }
 
+  onError(hook: FetcherOnErrorHook): this {
+    ;(this.cfg.hooks.onError ||= []).push(hook)
+    return this
+  }
+
   cfg: FetcherNormalizedCfg
 
   static create(cfg: FetcherCfg & FetcherOptions = {}): Fetcher {
@@ -273,14 +280,14 @@ export class Fetcher {
         }, timeoutSeconds * 1000) as any as number
       }
 
-      if (this.cfg.logRequest) {
+      if (req.logRequest) {
         const { retryAttempt } = res.retryStatus
         logger.log(
           [' >>', signature, retryAttempt && `try#${retryAttempt + 1}/${req.retry.count + 1}`]
             .filter(Boolean)
             .join(' '),
         )
-        if (this.cfg.logRequestBody && req.init.body) {
+        if (req.logRequestBody && req.init.body) {
           logger.log(req.init.body) // todo: check if we can _inspect it
         }
       }
@@ -335,6 +342,16 @@ export class Fetcher {
       }
     }
 
+    if (res.err) {
+      _errorDataAppend(res.err, req.errorData)
+
+      req.onError?.(res.err)
+
+      for (const hook of this.cfg.hooks.onError || []) {
+        await hook(res.err)
+      }
+    }
+
     for (const hook of this.cfg.hooks.afterResponse || []) {
       await hook(res)
     }
@@ -384,7 +401,7 @@ export class Fetcher {
     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 || !req.throwHttpErrors) && this.cfg.logResponse) {
+    if ((!res.err || !req.throwHttpErrors) && req.logResponse) {
       const { retryAttempt } = res.retryStatus
       const { logger } = this.cfg
       logger.log(
@@ -399,7 +416,7 @@ export class Fetcher {
           .join(' '),
       )
 
-      if (this.cfg.logResponseBody && res.body !== undefined) {
+      if (req.logResponseBody && res.body !== undefined) {
         logger.log(res.body)
       }
     }
@@ -664,6 +681,7 @@ export class Fetcher {
         },
         hooks: {},
         throwHttpErrors: true,
+        errorData: {},
       },
       _omit(cfg, ['method', 'credentials', 'headers', 'redirect', 'logger']),
     )
@@ -688,6 +706,7 @@ export class Fetcher {
         'logResponseBody',
         'debug',
         'throwHttpErrors',
+        'errorData',
       ]),
       started: Date.now(),
       ..._omit(opt, ['method', 'headers', 'credentials']),

package/src/number/number.util.ts

@@ -57,6 +57,7 @@ export function _isBetween<T extends number | string>(
 }
 
 export function _clamp(x: number, minIncl: number, maxIncl: number): number {
+  // eslint-disable-next-line unicorn/prefer-math-min-max
   return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x
 }
 

package/src/object/object.util.ts

@@ -400,6 +400,7 @@ type PropertyPath = Many<PropertyKey>
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
 export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any): T {
+  // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
   if (!obj || Object(obj) !== obj || !path) return obj as any // When obj is not an object
 
   // If not yet an array, get the keys from the string-path
@@ -416,6 +417,7 @@ export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any
       c,
       i, // Iterate all of them except the last one
     ) =>
+      // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
       Object(a[c]) === a[c] // Does the key exist and is its value an object?
         ? // Yes: then follow that path
           a[c]

package/src/types.ts

@@ -1,5 +1,22 @@
 import type { Promisable } from './typeFest'
 
+declare const __brand: unique symbol
+
+interface Brand<B> {
+  [__brand]: B
+}
+
+/**
+ * Helper to create "Branded" types.
+ *
+ * Example:
+ * export type MyId = Branded<string, 'MyId'>
+ *
+ * MyId can be assigned to a string,
+ * but string cannot be assigned to MyId without casting it (`as MyId`).
+ */
+export type Branded<T, B> = T & Brand<B>
+
 /**
  * Map from String to String (or <T>).
  *