@superutils/fetch 1.5.16 → 1.5.18

package/dist/index.d.ts

@@ -1,8 +1,6 @@
-import * as _superutils_core from '@superutils/core';
-import { ValueOrPromise, DropFirst } from '@superutils/core';
-import * as _superutils_promise from '@superutils/promise';
 import { RetryOptions, RetryIfFunc, TimeoutOptions, IPromisE_Timeout, DeferredAsyncOptions } from '@superutils/promise';
 export { DeferredAsyncOptions, OnEarlyFinalize, OnFinalize, ResolveError, ResolveIgnored, RetryIfFunc, RetryOptions, TIMEOUT_FALLBACK, TIMEOUT_MAX, TimeoutOptions, TimeoutPromise } from '@superutils/promise';
+import { ValueOrPromise, DropFirst } from '@superutils/core';
 
 /** Commonly used content types for easier access */
 declare const ContentType: {
@@ -279,6 +277,13 @@ type FetchCustomOptions = {
     abortCtrl?: AbortController;
     body?: PostArgs[1];
     errMsgs?: FetchErrMsgs;
+    /**
+     * If set to `true`, the global `fetch.defaults` (including global headers, interceptors,
+     * and timeout settings) will not be merged into the options for this request.
+     *
+     * Default: `false`
+     */
+    ignoreGlobalDefaults?: boolean;
     /**
      * Custom fetch function to use instead of the global `fetch`.
      * Useful for testing or using a different fetch implementation (e.g. `node-fetch` in older Node versions).
@@ -314,7 +319,7 @@ type FetchFunc = (...args: FetchArgs) => Promise<Response>;
  */
 type FetchOptions = Omit<RequestInit, 'body'> & FetchCustomOptions;
 /** Default fetch options */
-type FetchOptionsDefault = Omit<FetchOptionsInterceptor, 'abortCtrl' | 'as' | 'body' | 'method' | 'signal' | 'timeout' | 'headers'> & {
+type FetchOptionsDefault = Omit<FetchOptionsInterceptor, 'abortCtrl' | 'as' | 'body' | 'ignoreGlobalDefaults' | 'method' | 'signal' | 'timeout' | 'headers'> & {
     /**
      * Request headers.
      *
@@ -645,6 +650,75 @@ commonOptions?: PostOptions & CommonOptions, commonDeferOptions?: DeferredAsyncO
     deferred<ThisArg, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] | undefined, DefaultOptions extends ExcludePostOptions<FixedOptions> | undefined = ExcludePostOptions<FixedOptions> | undefined, Delay extends CommonDelay | number = number>(deferOptions?: DeferredAsyncOptions<ThisArg, Delay>, defaultUrl?: DefaultUrl, defaultData?: DefaultData, defaultOptions?: DefaultOptions): <T extends ClientData<FixedOptions> = never, Options_1 extends ExcludePostOptions<FixedOptions> | undefined = ExcludePostOptions<FixedOptions> | undefined, TReturn = GetFetchResult<[FixedOptions, Options_1, DefaultOptions, CommonOptions], T>>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, Options_1>) => IPromise_Fetch<TReturn>;
 };
 
+/**
+ * Configuration for the ApiClient instance.
+ */
+type ApiClientConfig<
+/** Options that are enforced for every request and cannot be overridden. */
+FixedOptions extends ApiClientFetchOptions, 
+/** Default options that can be overridden by individual request calls. */
+CommonOptions extends ExcludeOptions<FixedOptions, ApiClientFetchOptions>, CommonDelay extends number> = {
+    commonOptions?: CommonOptions;
+    commonDeferOptions?: DeferredAsyncOptions<unknown, CommonDelay>;
+    errorPrefix?: string;
+    fixedOptions?: FixedOptions;
+    withBaseClients?: boolean;
+};
+type ApiClientFetchOptions = Omit<FetchOptions, 'method'>;
+/**
+ * A fully encapsulated and isolated API client factory.
+ *
+ * ApiClient creates a sandboxed environment for a specific API service. It provides
+ * complete isolation by ignoring global `fetch.defaults` by default, ensuring that instance-specific
+ * configurations remain clean and predictable. It bundles RESTful methods and execution
+ * controls (like debounce/throttle) into a single, cohesive unit.
+ *
+ * ### Key Features:
+ * - **Isolation**: Instance-specific options are scoped to this client and isolated from other instances.
+ * - **Base Resolution**: Automatic path joining when `apiBaseUrl` is provided.
+ * - **Unified Error Handling**: Optional `errorPrefix` to namespace errors for easier debugging.
+ * - **Method Suite**: Integrated `delete`, `get`, `head`, `options`, `patch`, `post` and `put` methods.
+ *
+ * ### Precedence & Merging Nuances
+ * - **Options follow a strict hierarchy**: `fixedOptions` > `call options` > `commonOptions`.
+ * - Global `fetch.defaults` are ignored by default.
+ * - **Headers**: Merged by key. Specifying headers in a call overrides common headers with the
+ *   same name, but does NOT remove or replace the entire header set.
+ * - **Interceptors**: Cumulative. Interceptors from all levels are concatenated and executed
+ *   sequentially (Common -> Call -> Fixed). They cannot be overridden or replaced.
+ * - **Error Messages**: Merged by key, allowing per-service or per-call customization of
+ *   specific error strings without losing the rest of the global message set.
+ */
+declare class ApiClient<FixedOptions extends ApiClientFetchOptions = {}, // "{}" is required to correct infer common options
+CommonOptions extends ExcludeOptions<FixedOptions, ApiClientFetchOptions> = ExcludeOptions<FixedOptions, ApiClientFetchOptions>, CommonDelay extends number = number> {
+    apiBaseUrl?: string | undefined;
+    /** The base GET-style client. Defaults to GET method. */
+    readonly client: ReturnType<typeof createClient<FixedOptions, CommonOptions, CommonDelay>>;
+    /** The base POST-style client. Defaults to POST method and supports request bodies. */
+    readonly postClient: ReturnType<typeof createPostClient<FixedOptions, CommonOptions, CommonDelay>>;
+    /** Alias for postClient with DELETE method. */
+    readonly delete: typeof this.postClient;
+    /** Alias for client with GET method. */
+    readonly get: typeof this.client;
+    /** Alias for client with HEAD method. */
+    readonly head: typeof this.client;
+    /** Alias for client with OPTIONS method. */
+    readonly options: typeof this.client;
+    /** Alias for postClient with POST method. */
+    readonly post: typeof this.postClient;
+    /** Alias for postClient with PUT method. */
+    readonly put: typeof this.postClient;
+    /** Alias for postClient with PATCH method. */
+    readonly patch: typeof this.postClient;
+    /**
+     * Creates a new ApiClient instance.
+     *
+     * @param apiBaseUrl - The base URL for the API. Relative paths passed to methods will be appended to this.
+     * @param config - Optional configuration for headers, interceptors, and default behavior.
+     */
+    constructor(apiBaseUrl?: string | undefined, config?: ApiClientConfig<FixedOptions, CommonOptions, CommonDelay>);
+}
+
 /**
  * Gracefully executes interceptors and returns the processed value.
  * If the value is not transformed (by returning a new value) by the interceptors,
@@ -662,9 +736,11 @@ commonOptions?: PostOptions & CommonOptions, commonDeferOptions?: DeferredAsyncO
  */
 declare const executeInterceptors: <T, TArgs extends unknown[]>(value: T, signal?: AbortSignal, interceptors?: Interceptor<T, TArgs>[], ...args: TArgs) => Promise<T>;
 
+declare const defaultErrorMsgs: Required<FetchErrMsgs>;
+declare const POST_METHODS: string[];
 declare const fetch$1: {
     <T = unknown, TOptions extends FetchOptions = FetchOptions, TAs extends FetchAs = TOptions["as"] extends FetchAs ? TOptions["as"] : FetchAs.response, TReturn = FetchResult<T>[TAs]>(url: FetchArgs[0], options?: FetchOptions & TOptions): IPromise_Fetch<TReturn>;
-    /** Default fetch options */
+    /** Global default fetch options */
     defaults: FetchOptionsDefault;
 };
 
@@ -683,183 +759,6 @@ declare const fetch$1: {
  */
 declare const mergeOptions: (...allOptions: (FetchOptions | undefined)[]) => FetchOptionsInterceptor;
 
-declare const methods: {
-    /** Make HTTP requests with method GET */
-    get: {
-        <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: FetchArgs[0], options?: TOptions | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, Delay extends number, DefaultUrl extends FetchArgs[0] | undefined = URL | RequestInfo | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: DefaultUrl extends undefined ? [url: URL | RequestInfo, options?: TOptions | undefined] : [options?: TOptions | undefined]) => IPromise_Fetch<Result>;
-    };
-    /** Make HTTP requests with method HEAD */
-    head: {
-        <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: FetchArgs[0], options?: TOptions | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, Delay extends number, DefaultUrl extends FetchArgs[0] | undefined = URL | RequestInfo | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: DefaultUrl extends undefined ? [url: URL | RequestInfo, options?: TOptions | undefined] : [options?: TOptions | undefined]) => IPromise_Fetch<Result>;
-    };
-    /** Make HTTP requests with method OPTIONS */
-    options: {
-        <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: FetchArgs[0], options?: TOptions | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, Delay extends number, DefaultUrl extends FetchArgs[0] | undefined = URL | RequestInfo | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, TOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: string;
-        }, TOptions, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<FetchOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: DefaultUrl extends undefined ? [url: URL | RequestInfo, options?: TOptions | undefined] : [options?: TOptions | undefined]) => IPromise_Fetch<Result>;
-    };
-    /** Make HTTP requests with method DELETE */
-    delete: {
-        <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: "delete";
-        }, Options, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: PostArgs[0], data?: PostArgs[1], options?: Options | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Delay extends number = number>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TReturn = GetFetchResult<[{
-            method: "delete";
-        }, Options, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, Options, [url: URL | RequestInfo, data: PostBody | (() => _superutils_core.ValueOrPromise<PostBody>), options: PostOptions], undefined extends DefaultUrl ? DefaultUrl & undefined : DefaultUrl, undefined extends DefaultData ? DefaultData & undefined : DefaultData>) => IPromise_Fetch<TReturn>;
-    };
-    /** Make HTTP requests with method PATCH */
-    patch: {
-        <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: "patch";
-        }, Options, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: PostArgs[0], data?: PostArgs[1], options?: Options | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Delay extends number = number>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TReturn = GetFetchResult<[{
-            method: "patch";
-        }, Options, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, Options, [url: URL | RequestInfo, data: PostBody | (() => _superutils_core.ValueOrPromise<PostBody>), options: PostOptions], undefined extends DefaultUrl ? DefaultUrl & undefined : DefaultUrl, undefined extends DefaultData ? DefaultData & undefined : DefaultData>) => IPromise_Fetch<TReturn>;
-    };
-    /** Make HTTP requests with method POST */
-    post: {
-        <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: "post";
-        }, Options, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: PostArgs[0], data?: PostArgs[1], options?: Options | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Delay extends number = number>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TReturn = GetFetchResult<[{
-            method: "post";
-        }, Options, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, Options, [url: URL | RequestInfo, data: PostBody | (() => _superutils_core.ValueOrPromise<PostBody>), options: PostOptions], undefined extends DefaultUrl ? DefaultUrl & undefined : DefaultUrl, undefined extends DefaultData ? DefaultData & undefined : DefaultData>) => IPromise_Fetch<TReturn>;
-    };
-    /** Make HTTP requests with method PUT */
-    put: {
-        <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Result = GetFetchResult<[{
-            method: "put";
-        }, Options, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(url: PostArgs[0], data?: PostArgs[1], options?: Options | undefined): IPromise_Fetch<Result>;
-        deferred<ThisArg, DefaultUrl extends PostArgs[0] | undefined, DefaultData extends PostArgs[1] | undefined, DefaultOptions extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, Delay extends number = number>(deferOptions?: _superutils_promise.DeferredAsyncOptions<ThisArg, Delay> | undefined, defaultUrl?: DefaultUrl | undefined, defaultData?: DefaultData | undefined, defaultOptions?: DefaultOptions | undefined): <T extends unknown = never, Options extends ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined = ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined, TReturn = GetFetchResult<[{
-            method: "put";
-        }, Options, DefaultOptions, ({
-            headers?: HeadersInit | undefined;
-        } & Omit<PostOptions, "headers" | "method"> & Partial<Record<"method", never>>) | undefined], T>>(...args: PostDeferredCbArgs<DefaultUrl, DefaultData, Options, [url: URL | RequestInfo, data: PostBody | (() => _superutils_core.ValueOrPromise<PostBody>), options: PostOptions], undefined extends DefaultUrl ? DefaultUrl & undefined : DefaultUrl, undefined extends DefaultData ? DefaultData & undefined : DefaultData>) => IPromise_Fetch<TReturn>;
-    };
-};
 /**
  * A `fetch()` replacement that simplifies data fetching with automatic JSON parsing, request timeouts, retries,
  * and handy interceptors that also work as transformers. It also includes deferred and throttled request
@@ -982,6 +881,6 @@ declare const methods: {
  * })
  * ```
  */
-declare const fetch: typeof fetch$1 & typeof methods;
+declare const fetch: typeof fetch$1 & ApiClient;
 
-export { type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type OnDownloadProgress, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, executeInterceptors, fetch, mergeOptions };
+export { ApiClient, type ApiClientConfig, type ApiClientFetchOptions, type ClientData, ContentType, type ExcludeOptions, type ExcludePostOptions, type ExtractAs, type FetchArgs, type FetchArgsInterceptor, FetchAs, type FetchCustomOptions, type FetchErrMsgs, FetchError, type FetchFunc, type FetchInterceptorError, type FetchInterceptorRequest, type FetchInterceptorResponse, type FetchInterceptorResult, type FetchInterceptors, type FetchInterceptorsMerged, type FetchOptions, type FetchOptionsDefault, type FetchOptionsInterceptor, type FetchResult, type FetchRetryOptions, type GetFetchResult, type IPromise_Fetch, type Interceptor, type OnDownloadProgress, POST_METHODS, type PostArgs, type PostBody, type PostDeferredCbArgs, type PostOptions, createClient, createPostClient, fetch as default, defaultErrorMsgs, executeInterceptors, fetch, mergeOptions };

package/dist/index.js

@@ -7,6 +7,9 @@ import {
   TimeoutPromise
 } from "@superutils/promise";
 
+// src/ApiClient.ts
+import { isStr } from "@superutils/core";
+
 // src/createClient.ts
 import { deferredCallback } from "@superutils/promise";
 
@@ -310,18 +313,19 @@ var defaultErrorMsgs = Object.freeze({
   timedout: "Request timed out",
   requestFailed: "Request failed with status code:"
 });
+var POST_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
 var fetch = (url, options = {}) => {
   var _a, _b, _c;
   if (!isObj2(options)) options = {};
   let response;
   const opts = mergeOptions_default(
     { errMsgs: defaultErrorMsgs },
-    fetch.defaults,
+    options.ignoreGlobalDefaults ? void 0 : fetch.defaults,
     options
   );
   opts.abortCtrl = opts.abortCtrl instanceof AbortController ? opts.abortCtrl : new AbortController();
   (_a = opts.as) != null ? _a : opts.as = "response" /* response */;
-  (_b = opts.method) != null ? _b : opts.method = "get";
+  (_b = opts.method) != null ? _b : opts.method = "GET";
   (_c = opts.signal) != null ? _c : opts.signal = opts.abortCtrl.signal;
   const { abortCtrl, as: parseAs, headers, onAbort, onTimeout } = opts;
   opts.onAbort = async () => {
@@ -343,7 +347,7 @@ var fetch = (url, options = {}) => {
     );
   };
   return PromisE_timeout(opts, async () => {
-    var _a2, _b2, _c2, _d;
+    var _a2, _b2, _c2, _d, _e;
     try {
       opts.body = await fallbackIfFails4(
         opts.body,
@@ -360,9 +364,7 @@ var fetch = (url, options = {}) => {
       (_b2 = opts.signal) != null ? _b2 : opts.signal = abortCtrl.signal;
       if (validateUrl && !isUrlValid(url, false))
         throw new Error(errMsgs.invalidUrl);
-      const stringify = ["delete", "patch", "post", "put"].includes(
-        `${opts.method}`.toLowerCase()
-      ) && !["undefined", "string"].includes(typeof body) && isObj2(body, true) && headers.get("content-type") === ContentType.APPLICATION_JSON;
+      const stringify = POST_METHODS.includes(`${opts.method}`.toUpperCase()) && !["undefined", "string"].includes(typeof body) && isObj2(body, true) && headers.get("content-type") === ContentType.APPLICATION_JSON;
       if (stringify) opts.body = JSON.stringify(opts.body);
       response = await getResponse_default(url, opts);
       response = await executeInterceptors_default(
@@ -384,7 +386,9 @@ var fetch = (url, options = {}) => {
           [],
           void 0
         );
-        throw new Error(jsonError, { cause: jsonError });
+        throw new Error((_d = jsonError == null ? void 0 : jsonError.message) != null ? _d : jsonError, {
+          cause: jsonError
+        });
       }
       let result = getResult_default(
         response,
@@ -404,7 +408,7 @@ var fetch = (url, options = {}) => {
       result = await executeInterceptors_default(
         result,
         abortCtrl.signal,
-        (_d = opts.interceptors) == null ? void 0 : _d.result,
+        (_e = opts.interceptors) == null ? void 0 : _e.result,
         url,
         opts
       );
@@ -457,7 +461,6 @@ var createClient = (fixedOptions, commonOptions, commonDeferOptions) => {
   function client(url, options) {
     var _a;
     const mergedOptions = mergeOptions_default(
-      fetch_default.defaults,
       commonOptions,
       options,
       fixedOptions
@@ -471,7 +474,6 @@ var createClient = (fixedOptions, commonOptions, commonDeferOptions) => {
     const fetchCb = (...args) => {
       var _a, _b;
       const mergedOptions = mergeOptions_default(
-        fetch_default.defaults,
         commonOptions,
         defaultOptions,
         defaultUrl === void 0 ? args[1] : args[0],
@@ -510,7 +512,7 @@ var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
     );
     (_a = mergedOptions.as) != null ? _a : mergedOptions.as = "json" /* json */;
     mergedOptions.body = data != null ? data : mergedOptions.body;
-    (_b = mergedOptions.method) != null ? _b : mergedOptions.method = "post";
+    (_b = mergedOptions.method) != null ? _b : mergedOptions.method = "POST";
     const headers = mergedOptions.headers;
     if (!headers.get("content-type")) {
       headers.set("content-type", ContentType.APPLICATION_JSON);
@@ -524,7 +526,6 @@ var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
       if (defaultUrl !== void 0) args.splice(0, 0, defaultUrl);
       if (defaultData !== void 0) args.splice(1, 0, defaultData);
       const mergedOptions = mergeOptions_default(
-        fetch_default.defaults,
         commonOptions,
         defaultOptions,
         args[2],
@@ -549,36 +550,107 @@ var createPostClient = (fixedOptions, commonOptions, commonDeferOptions) => {
 };
 var createPostClient_default = createPostClient;
 
-// src/index.ts
-var methods = {
-  /** Make HTTP requests with method GET */
-  get: createClient_default({ method: "get" }),
-  /** Make HTTP requests with method HEAD */
-  head: createClient_default({ method: "head" }),
-  /** Make HTTP requests with method OPTIONS */
-  options: createClient_default({ method: "options" }),
-  /** Make HTTP requests with method DELETE */
-  delete: createPostClient_default({ method: "delete" }),
-  /** Make HTTP requests with method PATCH */
-  patch: createPostClient_default({ method: "patch" }),
-  /** Make HTTP requests with method POST */
-  post: createPostClient_default({ method: "post" }),
-  /** Make HTTP requests with method PUT */
-  put: createPostClient_default({ method: "put" })
+// src/ApiClient.ts
+var ApiClient = class {
+  /**
+   * Creates a new ApiClient instance.
+   *
+   * @param apiBaseUrl - The base URL for the API. Relative paths passed to methods will be appended to this.
+   * @param config - Optional configuration for headers, interceptors, and default behavior.
+   */
+  constructor(apiBaseUrl, config = {}) {
+    this.apiBaseUrl = apiBaseUrl;
+    const {
+      errorPrefix,
+      fixedOptions = {},
+      commonOptions = {},
+      commonDeferOptions = {},
+      withBaseClients = true
+    } = config;
+    const interceptors = {};
+    if (errorPrefix)
+      interceptors.error = [
+        (err) => {
+          err.message = `${errorPrefix} ${err.message}`;
+          return err;
+        }
+      ];
+    if (isStr(this.apiBaseUrl)) {
+      interceptors.request = [
+        (url) => {
+          const useBaseUrl = isStr(url) && !url.startsWith("http://") && !url.startsWith("https://") && !url.startsWith(this.apiBaseUrl);
+          if (useBaseUrl) url = `${this.apiBaseUrl}${url}`;
+          return url;
+        }
+      ];
+    }
+    const getMethods = [
+      withBaseClients ? "client" : "",
+      "get",
+      "head",
+      "options"
+    ].filter(Boolean);
+    const postMethods = [
+      withBaseClients ? "postClient" : "",
+      "delete",
+      "patch",
+      "post",
+      "put"
+    ].filter(Boolean);
+    const methods = [...getMethods, ...postMethods].reduce(
+      (obj, method) => {
+        const isBaseClient = method.toLowerCase().includes("client");
+        const _createClient = getMethods.includes(method) ? createClient_default : createPostClient_default;
+        return {
+          [method]: {
+            enumerable: false,
+            value: _createClient(
+              mergeOptions_default(fixedOptions, {
+                interceptors,
+                method: isBaseClient ? void 0 : method.toUpperCase()
+              }),
+              { ignoreGlobalDefaults: true, ...commonOptions },
+              commonDeferOptions
+            ),
+            writable: false
+          },
+          ...obj
+        };
+      },
+      {}
+    );
+    Object.defineProperties(this, methods);
+  }
 };
+var ApiClient_default = ApiClient;
+
+// src/index.ts
 var fetch2 = fetch_default;
-fetch2.delete = methods.delete;
-fetch2.get = methods.get;
-fetch2.head = methods.head;
-fetch2.options = methods.options;
-fetch2.patch = methods.patch;
-fetch2.post = methods.post;
-fetch2.put = methods.put;
+var globalClient = new ApiClient_default(void 0, {
+  commonOptions: { ignoreGlobalDefaults: false },
+  withBaseClients: false
+});
+Object.defineProperties(
+  fetch2,
+  ["delete", "get", "head", "options", "patch", "post", "put"].reduce(
+    (obj, method) => ({
+      [method]: {
+        enumerable: false,
+        value: globalClient[method],
+        writable: false
+      },
+      ...obj
+    }),
+    {}
+  )
+);
 var index_default = fetch2;
 export {
+  ApiClient,
   ContentType,
   FetchAs,
   FetchError,
+  POST_METHODS,
   ResolveError,
   ResolveIgnored,
   TIMEOUT_FALLBACK,
@@ -587,6 +659,7 @@ export {
   createClient,
   createPostClient,
   index_default as default,
+  defaultErrorMsgs,
   executeInterceptors,
   fetch2 as fetch,
   mergeOptions

package/package.json

@@ -5,8 +5,8 @@
 	},
 	"description": "A lightweight `fetch` wrapper for browsers and Node.js, designed to simplify data fetching and reduce boilerplate.",
 	"dependencies": {
-		"@superutils/core": "^1.2.15",
-		"@superutils/promise": "^1.3.14"
+		"@superutils/core": "^1.2.16",
+		"@superutils/promise": "^1.3.15"
 	},
 	"files": [
 		"dist",
@@ -53,6 +53,6 @@
 	"module": "./dist/index.js",
 	"type": "module",
 	"types": "./dist/index.d.ts",
-	"version": "1.5.16",
-	"gitHead": "7be3be6fb4a8cb1955ee5f704fc49bbb792bd961"
+	"version": "1.5.18",
+	"gitHead": "5bf3601096002f3ff4913a967dd77ed9798ea2e9"
 }