@zayne-labs/callapi 1.8.20 → 1.8.21

package/dist/esm/{common-Vd9i_nPc.d.ts → common-C-kIzPcz.d.ts}

@@ -215,32 +215,107 @@ declare class ValidationError extends Error {
 type AllowedQueryParamValues = UnmaskType<boolean | number | string>;
 type Params = UnmaskType<Record<string, AllowedQueryParamValues> | AllowedQueryParamValues[]>;
 type Query = UnmaskType<Record<string, AllowedQueryParamValues>>;
-type InitURLOrURLObject = AnyString | URL;
+type InitURLOrURLObject = AnyString | RouteKeyMethodsURLUnion | URL;
 interface URLOptions {
   /**
-   * Base URL to be prepended to all request URLs
+   * Base URL to be prepended to all request URLs.
+   *
+   * When provided, this will be prepended to relative URLs. Absolute URLs (starting with http/https) will not be prepended by the baseURL.
+   *
    */
   baseURL?: string;
   /**
-   * Resolved request URL
+   * Resolved request URL after processing baseURL, parameters, and query strings.
+   *
+   * This is the final URL that will be used for the HTTP request, computed from
+   * baseURL, initURL, params, and query parameters.
+   *
+   * @readonly
    */
   readonly fullURL?: string;
   /**
-   * The url string passed to the callApi instance
+   * The original URL string passed to the callApi instance.
+   *
+   * This preserves the original URL as provided, including any method modifiers like "@get/" or "@post/".
+   *
+   * @readonly
    */
   readonly initURL?: string;
   /**
-   * The URL string passed to the callApi instance, but normalized (removed any method modifiers etc)
+   * The URL string after normalization, with method modifiers removed.
+   *
+   * Method modifiers like "@get/", "@post/" are stripped to create a clean URL
+   * for parameter substitution and final URL construction.
+   *
+   * @readonly
+   *
+   *
    */
   readonly initURLNormalized?: string;
   /**
-   * Parameters to be appended to the URL (i.e: /:id)
+   * Parameters to be substituted into URL path segments.
+   *
+   * Supports both object-style (named parameters) and array-style (positional parameters)
+   * for flexible URL parameter substitution.
+   *
+   * @example
+   * ```typescript
+   * // Object-style parameters (recommended)
+   * const namedParams: URLOptions = {
+   *   initURL: "/users/:userId/posts/:postId",
+   *   params: { userId: "123", postId: "456" }
+   * };
+   * // Results in: /users/123/posts/456
    *
-   * If url is defined as `/path/:id`, params will be `{ id: string }`
+   * // Array-style parameters (positional)
+   * const positionalParams: URLOptions = {
+   *   initURL: "/users/:userId/posts/:postId",
+   *   params: ["123", "456"]  // Maps in order: userId=123, postId=456
+   * };
+   * // Results in: /users/123/posts/456
+   *
+   * // Single parameter
+   * const singleParam: URLOptions = {
+   *   initURL: "/users/:id",
+   *   params: { id: "user-123" }
+   * };
+   * // Results in: /users/user-123
+   * ```
    */
   params?: Params;
   /**
-   * Query parameters to append to the URL.
+   * Query parameters to append to the URL as search parameters.
+   *
+   * These will be serialized into the URL query string using standard
+   * URL encoding practices.
+   *
+   * @example
+   * ```typescript
+   * // Basic query parameters
+   * const queryOptions: URLOptions = {
+   *   initURL: "/users",
+   *   query: {
+   *     page: 1,
+   *     limit: 10,
+   *     search: "john doe",
+   *     active: true
+   *   }
+   * };
+   * // Results in: /users?page=1&limit=10&search=john%20doe&active=true
+   *
+   * // Filtering and sorting
+   * const filterOptions: URLOptions = {
+   *   initURL: "/products",
+   *   query: {
+   *     category: "electronics",
+   *     minPrice: 100,
+   *     maxPrice: 500,
+   *     sortBy: "price",
+   *     order: "asc"
+   *   }
+   * };
+   * // Results in: /products?category=electronics&minPrice=100&maxPrice=500&sortBy=price&order=asc
+   * ```
    */
   query?: Query;
 }
@@ -327,9 +402,8 @@ interface CallApiSchema {
 }
 declare const routeKeyMethods: ["delete", "get", "patch", "post", "put"];
 type RouteKeyMethods = (typeof routeKeyMethods)[number];
-type RouteKeyMethodsURLUnion = `${RouteKeyMethods}/`;
-type PossibleRouteKey = AnyString | RouteKeyMethodsURLUnion;
-type BaseCallApiSchemaRoutes = Partial<Record<PossibleRouteKey, CallApiSchema>>;
+type RouteKeyMethodsURLUnion = `@${RouteKeyMethods}/`;
+type BaseCallApiSchemaRoutes = Partial<Record<AnyString | RouteKeyMethodsURLUnion, CallApiSchema>>;
 type BaseCallApiSchemaAndConfig = {
   config?: CallApiSchemaConfig;
   routes: BaseCallApiSchemaRoutes;
@@ -468,134 +542,566 @@ declare global {
 //#endregion
 //#region src/hooks.d.ts
 type PluginExtraOptions<TPluginOptions = unknown> = {
+  /** Plugin-specific options passed to the plugin configuration */
   options: Partial<TPluginOptions>;
 };
 interface Hooks<TData = DefaultDataType, TErrorData = DefaultDataType, TPluginOptions = unknown> {
   /**
-   * Hook that will be called when any error occurs within the request/response lifecycle, regardless of whether the error is from the api or not.
-   * It is basically a combination of `onRequestError` and `onResponseError` hooks
+   * Hook called when any error occurs within the request/response lifecycle.
+   *
+   * This is a unified error handler that catches both request errors (network failures,
+   * timeouts, etc.) and response errors (HTTP error status codes). It's essentially
+   * a combination of `onRequestError` and `onResponseError` hooks.
+   *
+   * @param context - Error context containing error details, request info, and response (if available)
+   * @returns Promise or void - Hook can be async or sync
    */
   onError?: (context: ErrorContext<TErrorData> & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called just before the request is being made.
+   * Hook called just before the HTTP request is sent.
+   *
+   * This is the ideal place to modify request headers, add authentication,
+   * implement request logging, or perform any setup before the network call.
+   *
+   * @param context - Request context with mutable request object and configuration
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onRequest?: (context: RequestContext & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   *  Hook that will be called when an error occurs during the fetch request.
+   * Hook called when an error occurs during the fetch request itself.
+   *
+   * This handles network-level errors like connection failures, timeouts,
+   * DNS resolution errors, or other issues that prevent getting an HTTP response.
+   * Note that HTTP error status codes (4xx, 5xx) are handled by `onResponseError`.
+   *
+   * @param context - Request error context with error details and null response
+   * @returns Promise or void - Hook can be async or sync
    */
   onRequestError?: (context: RequestErrorContext & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when upload stream progress is tracked
+   * Hook called during upload stream progress tracking.
+   *
+   * This hook is triggered when uploading data (like file uploads) and provides
+   * progress information about the upload. Useful for implementing progress bars
+   * or upload status indicators.
+   *
+   * @param context - Request stream context with progress event and request instance
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onRequestStream?: (context: RequestStreamContext & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when any response is received from the api, whether successful or not
+   * Hook called when any HTTP response is received from the API.
+   *
+   * This hook is triggered for both successful (2xx) and error (4xx, 5xx) responses.
+   * It's useful for response logging, metrics collection, or any processing that
+   * should happen regardless of response status.
+   *
+   * @param context - Response context with either success data or error information
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onResponse?: (context: ResponseContext<TData, TErrorData> & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   *  Hook that will be called when an error response is received from the api.
+   * Hook called when an HTTP error response (4xx, 5xx) is received from the API.
+   *
+   * This handles server-side errors where an HTTP response was successfully received
+   * but indicates an error condition. Different from `onRequestError` which handles
+   * network-level failures.
+   *
+   * @param context - Response error context with HTTP error details and response
+   * @returns Promise or void - Hook can be async or sync
    */
   onResponseError?: (context: ResponseErrorContext<TErrorData> & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when download stream progress is tracked
+   * Hook called during download stream progress tracking.
+   *
+   * This hook is triggered when downloading data (like file downloads) and provides
+   * progress information about the download. Useful for implementing progress bars
+   * or download status indicators.
+   *
+   * @param context - Response stream context with progress event and response
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onResponseStream?: (context: ResponseStreamContext & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when a request is retried.
+   * Hook called when a request is being retried.
+   *
+   * This hook is triggered before each retry attempt, providing information about
+   * the previous failure and the current retry attempt number. Useful for implementing
+   * custom retry logic, exponential backoff, or retry logging.
+   *
+   * @param context - Retry context with error details and retry attempt count
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onRetry?: (response: RetryContext<TErrorData> & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when a successful response is received from the api.
+   * Hook called when a successful response (2xx status) is received from the API.
+   *
+   * This hook is triggered only for successful responses and provides access to
+   * the parsed response data. Ideal for success logging, caching, or post-processing
+   * of successful API responses.
+   *
+   * @param context - Success context with parsed response data and response object
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onSuccess?: (context: SuccessContext<TData> & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
   /**
-   * Hook that will be called when a validation error occurs.
+   * Hook called when a validation error occurs.
+   *
+   * This hook is triggered when request or response data fails validation against
+   * a defined schema. It provides access to the validation error details and can
+   * be used for custom error handling, logging, or fallback behavior.
+   *
+   * @param context - Validation error context with error details and response (if available)
+   * @returns Promise or void - Hook can be async or sync
+   *
    */
   onValidationError?: (context: ValidationErrorContext & PluginExtraOptions<TPluginOptions>) => Awaitable<unknown>;
 }
 type HooksOrHooksArray<TData = DefaultDataType, TErrorData = DefaultDataType, TMoreOptions = unknown> = { [Key in keyof Hooks<TData, TErrorData, TMoreOptions>]: Hooks<TData, TErrorData, TMoreOptions>[Key] | Array<Hooks<TData, TErrorData, TMoreOptions>[Key]> };
+interface HookConfigOptions {
+  /**
+   * Controls the execution mode of all composed hooks (main + plugin hooks).
+   *
+   * - **"parallel"**: All hooks execute simultaneously via Promise.all() for better performance
+   * - **"sequential"**: All hooks execute one by one in registration order via await in a loop
+   *
+   * This affects how ALL hooks execute together, regardless of their source (main or plugin).
+   *
+   * Use `hookRegistrationOrder` to control the registration order of main vs plugin hooks.
+   *
+   * @default "parallel"
+   *
+   * @example
+   * ```ts
+   * // Parallel execution (default) - all hooks run simultaneously
+   * hooksExecutionMode: "parallel"
+   *
+   * // Sequential execution - hooks run one after another
+   * hooksExecutionMode: "sequential"
+   *
+   * // Use case: Hooks have dependencies and must run in order
+   * const client = callApi.create({
+   *   hooksExecutionMode: "sequential",
+   *   hookRegistrationOrder: "mainFirst",
+   *   plugins: [transformPlugin],
+   *   onRequest: (ctx) => {
+   *     // This runs first, then transform plugin runs
+   *     ctx.request.headers["x-request-id"] = generateId();
+   *   }
+   * });
+   *
+   * // Use case: Independent operations can run in parallel for speed
+   * const client = callApi.create({
+   *   hooksExecutionMode: "parallel", // Default
+   *   plugins: [metricsPlugin, cachePlugin, loggingPlugin],
+   *   onRequest: (ctx) => {
+   *     // All hooks (main + plugins) run simultaneously
+   *     addRequestTimestamp(ctx.request);
+   *   }
+   * });
+   *
+   * // Use case: Error handling hooks that need sequential processing
+   * const client = callApi.create({
+   *   hooksExecutionMode: "sequential",
+   *   onError: [
+   *     (ctx) => logError(ctx.error),      // Log first
+   *     (ctx) => reportError(ctx.error),   // Then report
+   *     (ctx) => cleanupResources(ctx)     // Finally cleanup
+   *   ]
+   * });
+   * ```
+   */
+  hooksExecutionMode?: "parallel" | "sequential";
+  /**
+   * Controls the registration order of main hooks relative to plugin hooks.
+   *
+   * - **"pluginsFirst"**: Plugin hooks register first, then main hooks (default)
+   * - **"mainFirst"**: Main hooks register first, then plugin hooks
+   *
+   * This determines the order hooks are added to the registry, which affects
+   * their execution sequence when using sequential execution mode.
+   *
+   * @default "pluginsFirst"
+   *
+   * @example
+   * ```ts
+   * // Plugin hooks register first (default behavior)
+   * hookRegistrationOrder: "pluginsFirst"
+   *
+   * // Main hooks register first
+   * hookRegistrationOrder: "mainFirst"
+   *
+   * // Use case: Main validation before plugin processing
+   * const client = callApi.create({
+   *   hookRegistrationOrder: "mainFirst",
+   *   hooksExecutionMode: "sequential",
+   *   plugins: [transformPlugin],
+   *   onRequest: (ctx) => {
+   *     // This main hook runs first in sequential mode
+   *     if (!ctx.request.headers.authorization) {
+   *       throw new Error("Authorization required");
+   *     }
+   *   }
+   * });
+   *
+   * // Use case: Plugin setup before main logic (default)
+   * const client = callApi.create({
+   *   hookRegistrationOrder: "pluginsFirst", // Default
+   *   hooksExecutionMode: "sequential",
+   *   plugins: [setupPlugin],
+   *   onRequest: (ctx) => {
+   *     // Plugin runs first, then this main hook
+   *     console.log("Request prepared:", ctx.request.url);
+   *   }
+   * });
+   *
+   * // Use case: Parallel mode (registration order less important)
+   * const client = callApi.create({
+   *   hookRegistrationOrder: "pluginsFirst",
+   *   hooksExecutionMode: "parallel", // All run simultaneously
+   *   plugins: [metricsPlugin, cachePlugin],
+   *   onRequest: (ctx) => {
+   *     // All hooks run in parallel regardless of registration order
+   *     addRequestId(ctx.request);
+   *   }
+   * });
+   * ```
+   */
+  hooksRegistrationOrder?: "mainFirst" | "pluginsFirst";
+}
 type RequestContext = {
   /**
-   * Config object passed to createFetchClient
+   * Base configuration object passed to createFetchClient.
+   *
+   * Contains the foundational configuration that applies to all requests
+   * made by this client instance, such as baseURL, default headers, and
+   * global options.
    */
   baseConfig: BaseCallApiExtraOptions & CallApiRequestOptions;
   /**
-   * Config object passed to the callApi instance
+   * Instance-specific configuration object passed to the callApi instance.
+   *
+   * Contains configuration specific to this particular API call, which
+   * can override or extend the base configuration.
    */
   config: CallApiExtraOptions & CallApiRequestOptions;
   /**
-   * Merged options consisting of extra options from createFetchClient, the callApi instance and default options.
+   * Merged options combining base config, instance config, and default options.
    *
+   * This is the final resolved configuration that will be used for the request,
+   * with proper precedence applied (instance > base > defaults).
    */
   options: CallApiExtraOptionsForHooks;
   /**
-   * Merged request consisting of request options from createFetchClient, the callApi instance and default request options.
+   * Merged request object ready to be sent.
+   *
+   * Contains the final request configuration including URL, method, headers,
+   * body, and other fetch options. This object can be modified in onRequest
+   * hooks to customize the outgoing request.
    */
   request: CallApiRequestOptionsForHooks;
 };
 type ValidationErrorContext = UnmaskType<RequestContext & {
+  /** Validation error containing details about what failed validation */
   error: ValidationError;
+  /** HTTP response object if validation failed on response, null if on request */
   response: Response | null;
 }>;
 type SuccessContext<TData> = UnmaskType<RequestContext & {
+  /** Parsed response data with the expected success type */
   data: TData;
+  /** HTTP response object for the successful request */
   response: Response;
 }>;
 type ResponseContext<TData, TErrorData> = UnmaskType<RequestContext & (Prettify<CallApiResultSuccessVariant<TData>> | Prettify<Extract<CallApiResultErrorVariant<TErrorData>, {
   error: PossibleHTTPError<TErrorData>;
 }>>)>;
 type RequestErrorContext = RequestContext & {
+  /** Error that occurred during the request (network, timeout, etc.) */
   error: PossibleJavaScriptOrValidationError;
+  /** Always null for request errors since no response was received */
   response: null;
 };
 type ErrorContext<TErrorData> = UnmaskType<RequestContext & ({
+  /** HTTP error with response data */
   error: PossibleHTTPError<TErrorData>;
+  /** HTTP response object containing error status */
   response: Response;
 } | {
+  /** Request-level error (network, timeout, validation, etc.) */
   error: PossibleJavaScriptOrValidationError;
+  /** Response object if available, null for request errors */
   response: Response | null;
 })>;
 type ResponseErrorContext<TErrorData> = UnmaskType<Extract<ErrorContext<TErrorData>, {
   error: PossibleHTTPError<TErrorData>;
 }> & RequestContext>;
 type RetryContext<TErrorData> = UnmaskType<ErrorContext<TErrorData> & {
+  /** Current retry attempt number (1-based, so 1 = first retry) */
   retryAttemptCount: number;
 }>;
 type RequestStreamContext = UnmaskType<RequestContext & {
+  /** Progress event containing loaded/total bytes information */
   event: StreamProgressEvent;
+  /** The actual Request instance being uploaded */
   requestInstance: Request;
 }>;
 type ResponseStreamContext = UnmaskType<RequestContext & {
+  /** Progress event containing loaded/total bytes information */
   event: StreamProgressEvent;
+  /** HTTP response object being downloaded */
   response: Response;
 }>;
 //#endregion
 //#region src/dedupe.d.ts
 type DedupeOptions = {
   /**
-   * Defines the scope of the deduplication cache, can be set to "global" | "local".
-   * - If set to "global", the deduplication cache will be shared across all requests, regardless of whether they shared the same `createFetchClient` or not.
-   * - If set to "local", the deduplication cache will be scoped to the current request.
+   * Controls the scope of request deduplication caching.
+   *
+   * - `"global"`: Shares deduplication cache across all `createFetchClient` instances with the same `dedupeCacheScopeKey`.
+   *   Useful for applications with multiple API clients that should share deduplication state.
+   * - `"local"`: Limits deduplication to requests within the same `createFetchClient` instance.
+   *   Provides better isolation and is recommended for most use cases.
+   *
+   *
+   * **Real-world Scenarios:**
+   * - Use `"global"` when you have multiple API clients (user service, auth service, etc.) that might make overlapping requests
+   * - Use `"local"` (default) for single-purpose clients or when you want strict isolation between different parts of your app
+   *
+   * @example
+   * ```ts
+   * // Local scope - each client has its own deduplication cache
+   * const userClient = createFetchClient({ baseURL: "/api/users" });
+   * const postClient = createFetchClient({ baseURL: "/api/posts" });
+   * // These clients won't share deduplication state
+   *
+   * // Global scope - share cache across related clients
+   * const userClient = createFetchClient({
+   *   baseURL: "/api/users",
+   *   dedupeCacheScope: "global",
+   * });
+   * const postClient = createFetchClient({
+   *   baseURL: "/api/posts",
+   *   dedupeCacheScope: "global",
+   * });
+   * // These clients will share deduplication state
+   * ```
+   *
    * @default "local"
    */
   dedupeCacheScope?: "global" | "local";
   /**
-   * Unique key to namespace the deduplication cache when `dedupeCacheScope` is set to `"global"`.
+   * Unique namespace for the global deduplication cache when using `dedupeCacheScope: "global"`.
+   *
+   * This creates logical groupings of deduplication caches. All instances with the same key
+   * will share the same cache namespace, allowing fine-grained control over which clients
+   * share deduplication state.
+   *
+   * **Best Practices:**
+   * - Use descriptive names that reflect the logical grouping (e.g., "user-service", "analytics-api")
+   * - Keep scope keys consistent across related API clients
+   * - Consider using different scope keys for different environments (dev, staging, prod)
+   * - Avoid overly broad scope keys that might cause unintended cache sharing
+   *
+   * **Cache Management:**
+   * - Each scope key maintains its own independent cache
+   * - Caches are automatically cleaned up when no references remain
+   * - Consider the memory implications of multiple global scopes
+   *
+   * @example
+   * ```ts
+   * // Group related API clients together
+   * const userClient = createFetchClient({
+   *   baseURL: "/api/users",
+   *   dedupeCacheScope: "global",
+   *   dedupeCacheScopeKey: "user-service"
+   * });
+   * const profileClient = createFetchClient({
+   *   baseURL: "/api/profiles",
+   *   dedupeCacheScope: "global",
+   *   dedupeCacheScopeKey: "user-service" // Same scope - will share cache
+   * });
+   *
+   * // Separate analytics client with its own cache
+   * const analyticsClient = createFetchClient({
+   *   baseURL: "/api/analytics",
+   *   dedupeCacheScope: "global",
+   *   dedupeCacheScopeKey: "analytics-service" // Different scope
+   * });
+   *
+   * // Environment-specific scoping
+   * const apiClient = createFetchClient({
+   *   dedupeCacheScope: "global",
+   *   dedupeCacheScopeKey: `api-${process.env.NODE_ENV}` // "api-development", "api-production", etc.
+   * });
+   * ```
    *
-   * CallApi instances sharing this key will use the same cache for deduplication.
    * @default "default"
    */
   dedupeCacheScopeKey?: "default" | AnyString;
   /**
-   * Custom request key to be used to identify a request within the selected deduplication cache.
-   * @default the full request url + string formed from the request options
+   * Custom key generator for request deduplication.
+   *
+   * Override the default key generation strategy to control exactly which requests
+   * are considered duplicates. The default key combines URL, method, body, and
+   * relevant headers (excluding volatile ones like 'Date', 'Authorization', etc.).
+   *
+   * **Default Key Generation:**
+   * The auto-generated key includes:
+   * - Full request URL (including query parameters)
+   * - HTTP method (GET, POST, etc.)
+   * - Request body (for POST/PUT/PATCH requests)
+   * - Stable headers (excludes Date, Authorization, User-Agent, etc.)
+   *
+   * **Custom Key Best Practices:**
+   * - Include only the parts of the request that should affect deduplication
+   * - Avoid including volatile data (timestamps, random IDs, etc.)
+   * - Consider performance - simpler keys are faster to compute and compare
+   * - Ensure keys are deterministic for the same logical request
+   * - Use consistent key formats across your application
+   *
+   * **Performance Considerations:**
+   * - Function-based keys are computed on every request - keep them lightweight
+   * - String keys are fastest but least flexible
+   * - Consider caching expensive key computations if needed
+   *
+   * @example
+   * ```ts
+   * import { callApi } from "@zayne-labs/callapi";
+   *
+   * // Simple static key - useful for singleton requests
+   * const config = callApi("/api/config", {
+   *   dedupeKey: "app-config",
+   *   dedupeStrategy: "defer" // Share the same config across all requests
+   * });
+   *
+   * // URL and method only - ignore headers and body
+   * const userData = callApi("/api/user/123", {
+   *   dedupeKey: (context) => `${context.options.method}:${context.options.fullURL}`
+   * });
+   *
+   * // Include specific headers in deduplication
+   * const apiCall = callApi("/api/data", {
+   *   dedupeKey: (context) => {
+   *     const authHeader = context.request.headers.get("Authorization");
+   *     return `${context.options.fullURL}-${authHeader}`;
+   *   }
+   * });
+   *
+   * // User-specific deduplication
+   * const userSpecificCall = callApi("/api/dashboard", {
+   *   dedupeKey: (context) => {
+   *     const userId = context.options.fullURL.match(/user\/(\d+)/)?.[1];
+   *     return `dashboard-${userId}`;
+   *   }
+   * });
+   *
+   * // Ignore certain query parameters
+   * const searchCall = callApi("/api/search?q=test&timestamp=123456", {
+   *   dedupeKey: (context) => {
+   *     const url = new URL(context.options.fullURL);
+   *     url.searchParams.delete("timestamp"); // Remove volatile param
+   *     return `search:${url.toString()}`;
+   *   }
+   * });
+   * ```
+   *
+   * @default Auto-generated from request details
    */
-  dedupeKey?: string;
+  dedupeKey?: string | ((context: RequestContext) => string);
   /**
-   * Defines the deduplication strategy for the request, can be set to "none" | "defer" | "cancel".
-   * - If set to "cancel", the previous pending request with the same request key will be cancelled and lets the new request through.
-   * - If set to "defer", all new request with the same request key will be share the same response, until the previous one is completed.
-   * - If set to "none", deduplication is disabled.
+   * Strategy for handling duplicate requests.
+   *
+   * **Strategy Details:**
+   * - `"cancel"`: Aborts any in-flight request with the same key when a new request starts.
+   *   The previous request will throw an AbortError, and the new request proceeds normally.
+   *   Best for scenarios where only the latest request matters.
+   *
+   * - `"defer"`: Returns the existing promise for duplicate requests, effectively sharing
+   *   the same response across multiple callers. All callers receive the same result.
+   *   Ideal for expensive operations that shouldn't be repeated.
+   *
+   * - `"none"`: Disables request deduplication entirely. Every request executes independently
+   *   regardless of similarity. Use when you need guaranteed request execution.
+   *
+   * **Real-world Use Cases:**
+   *
+   * **Cancel Strategy:**
+   * - Search-as-you-type functionality (cancel previous searches)
+   * - Real-time data updates (only latest request matters)
+   * - User navigation (cancel previous page loads)
+   * - Form submissions where rapid clicks should cancel previous attempts
+   *
+   * **Defer Strategy:**
+   * - Configuration/settings loading (share across components)
+   * - User profile data (multiple components need same data)
+   * - Expensive computations or reports
+   * - Authentication token refresh (prevent multiple refresh attempts)
+   *
+   * **None Strategy:**
+   * - Analytics events (every event should be sent)
+   * - Logging requests (each log entry is unique)
+   * - File uploads (each upload is independent)
+   * - Critical business operations that must not be deduplicated
+   *
+   *
+   * @example
+   * ```ts
+   * // Cancel strategy - search functionality
+   * const searchClient = createFetchClient({
+   *   baseURL: "/api/search",
+   *   dedupeStrategy: "cancel" // Cancel previous searches
+   * });
+   *
+   * // Defer strategy - shared configuration
+   * const configClient = createFetchClient({
+   *   dedupeStrategy: "defer" // Share config across components
+   * });
+   *
+   * // Multiple components requesting config simultaneously
+   * const config1 = configClient("/api/config"); // Makes actual request
+   * const config2 = configClient("/api/config"); // Returns same promise as config1
+   * const config3 = configClient("/api/config"); // Returns same promise as config1
+   * // All three will resolve with the same response
+   *
+   * // None strategy - analytics
+   * const analyticsClient = createFetchClient({
+   *   baseURL: "/api/analytics",
+   *   dedupeStrategy: "none" // Every event must be sent
+   * });
+   *
+   * // Real-world search example with cancel
+   * const handleSearch = async (query: string) => {
+   *   try {
+   *     const results = await callApi("/api/search", {
+   *       method: "POST",
+   *       body: { query },
+   *       dedupeStrategy: "cancel",
+   *       dedupeKey: "search" // All searches share the same key
+   *     });
+   *     updateUI(results);
+   *   } catch (error) {
+   *     if (error.name === "AbortError") {
+   *       // Previous search was cancelled - this is expected
+   *       return;
+   *     }
+   *     handleError(error);
+   *   }
+   * };
+   *
+   * // Authentication token refresh with defer
+   * const refreshToken = () => callApi("/api/auth/refresh", {
+   *   dedupeStrategy: "defer",
+   *   dedupeKey: "token-refresh" // Ensure only one refresh happens
+   * });
+   * ```
+   *
    * @default "cancel"
    */
   dedupeStrategy?: "cancel" | "defer" | "none";
@@ -659,7 +1165,9 @@ interface RetryOptions<TErrorData> {
  */
 type MakeSchemaOptionRequiredIfDefined<TSchemaOption extends CallApiSchema[keyof CallApiSchema], TObject> = undefined extends InferSchemaResult<TSchemaOption, undefined> ? TObject : Required<TObject>;
 type ApplyURLBasedConfig<TSchemaConfig extends CallApiSchemaConfig, TSchemaRouteKeys extends string> = TSchemaConfig["prefix"] extends string ? `${TSchemaConfig["prefix"]}${TSchemaRouteKeys}` : TSchemaConfig["baseURL"] extends string ? `${TSchemaConfig["baseURL"]}${TSchemaRouteKeys}` : TSchemaRouteKeys;
-type ApplyStrictConfig<TSchemaConfig extends CallApiSchemaConfig, TSchemaRouteKeys extends string> = TSchemaConfig["strict"] extends true ? TSchemaRouteKeys : TSchemaRouteKeys | InitURLOrURLObject;
+type ApplyStrictConfig<TSchemaConfig extends CallApiSchemaConfig, TSchemaRouteKeys extends string> = TSchemaConfig["strict"] extends true ? TSchemaRouteKeys :
+// eslint-disable-next-line perfectionist/sort-union-types -- Don't sort union types
+TSchemaRouteKeys | Exclude<InitURLOrURLObject, RouteKeyMethodsURLUnion>;
 type ApplySchemaConfiguration<TSchemaConfig extends CallApiSchemaConfig, TSchemaRouteKeys extends string> = ApplyStrictConfig<TSchemaConfig, ApplyURLBasedConfig<TSchemaConfig, TSchemaRouteKeys>>;
 type InferAllRouteKeys<TBaseSchemaRoutes extends BaseCallApiSchemaRoutes, TSchemaConfig extends CallApiSchemaConfig> = ApplySchemaConfiguration<TSchemaConfig, Extract<keyof TBaseSchemaRoutes, string>>;
 type InferInitURL<TBaseSchemaRoutes extends BaseCallApiSchemaRoutes, TSchemaConfig extends CallApiSchemaConfig> = keyof TBaseSchemaRoutes extends never ? InitURLOrURLObject : InferAllRouteKeys<TBaseSchemaRoutes, TSchemaConfig>;
@@ -785,59 +1293,183 @@ type CallApiRequestOptionsForHooks = Omit<CallApiRequestOptions, "headers"> & {
   headers: Record<string, string | undefined>;
 };
 type FetchImpl = UnmaskType<(input: string | Request | URL, init?: RequestInit) => Promise<Response>>;
-type SharedExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType, TResultMode extends ResultModeUnion = ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion = DefaultThrowOnError, TResponseType extends ResponseTypeUnion = ResponseTypeUnion, TPluginArray extends CallApiPlugin[] = DefaultPluginArray> = DedupeOptions & HooksOrHooksArray<TData, TErrorData, Partial<InferPluginOptions<TPluginArray>>> & Partial<InferPluginOptions<TPluginArray>> & ResultModeOption<TErrorData, TResultMode> & RetryOptions<TErrorData> & ThrowOnErrorOption<TErrorData, TThrowOnError> & URLOptions & {
+type SharedExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType, TResultMode extends ResultModeUnion = ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion = DefaultThrowOnError, TResponseType extends ResponseTypeUnion = ResponseTypeUnion, TPluginArray extends CallApiPlugin[] = DefaultPluginArray> = DedupeOptions & HookConfigOptions & HooksOrHooksArray<TData, TErrorData, Partial<InferPluginOptions<TPluginArray>>> & Partial<InferPluginOptions<TPluginArray>> & ResultModeOption<TErrorData, TResultMode> & RetryOptions<TErrorData> & ThrowOnErrorOption<TErrorData, TThrowOnError> & URLOptions & {
   /**
-   * Authorization header value.
+   * Automatically add an Authorization header value.
+   *
+   * Supports multiple authentication patterns:
+   * - String: Direct authorization header value
+   * - Auth object: Structured authentication configuration
+   * - null: Explicitly removes authorization
+   *
+   * @example
+   * ```ts
+   * // Bearer token authentication
+   * auth: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+   *
+   * // Basic authentication
+   * auth: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
+   *
+   * // Using Auth object for dynamic authentication
+   * auth: {
+   *   type: "bearer",
+   *   token: () => getAccessToken()
+   * }
+   *
+   * // Remove inherited auth from base config
+   * auth: null
+   * ```
    */
   auth?: string | Auth | null;
   /**
-   * Base URL for the request.
+   * Base URL for all API requests. Will be prepended to relative URLs.
+   *
+   * @example
+   * ```ts
+   * // Set base URL for all requests
+   * baseURL: "https://api.example.com/v1"
+   *
+   * // Then use relative URLs in requests
+   * callApi("/users") // → https://api.example.com/v1/users
+   * callApi("/posts/123") // → https://api.example.com/v1/posts/123
+   *
+   * // Environment-specific base URLs
+   * baseURL: process.env.NODE_ENV === "production"
+   *   ? "https://api.example.com"
+   *   : "http://localhost:3000/api"
+   * ```
    */
   baseURL?: string;
   /**
-   * Custom function to serialize the body object into a string.
+   * Custom function to serialize request body objects into strings.
+   *
+   * Useful for custom serialization formats or when the default JSON
+   * serialization doesn't meet your needs.
+   *
+   * @example
+   * ```ts
+   * // Custom form data serialization
+   * bodySerializer: (data) => {
+   *   const formData = new URLSearchParams();
+   *   Object.entries(data).forEach(([key, value]) => {
+   *     formData.append(key, String(value));
+   *   });
+   *   return formData.toString();
+   * }
+   *
+   * // XML serialization
+   * bodySerializer: (data) => {
+   *   return `<request>${Object.entries(data)
+   *     .map(([key, value]) => `<${key}>${value}</${key}>`)
+   *     .join('')}</request>`;
+   * }
+   *
+   * // Custom JSON with specific formatting
+   * bodySerializer: (data) => JSON.stringify(data, null, 2)
+   * ```
    */
   bodySerializer?: (bodyData: Record<string, unknown>) => string;
   /**
-   * Whether or not to clone the response, so response.json() and the like can be read again else where.
+   * Whether to clone the response so it can be read multiple times.
+   *
+   * By default, response streams can only be consumed once. Enable this when you need
+   * to read the response in multiple places (e.g., in hooks and main code).
+   *
    * @see https://developer.mozilla.org/en-US/docs/Web/API/Response/clone
    * @default false
    */
   cloneResponse?: boolean;
   /**
-   * Custom fetch implementation
+   * Custom fetch implementation to replace the default fetch function.
+   *
+   * Useful for testing, adding custom behavior, or using alternative HTTP clients
+   * that implement the fetch API interface.
+   *
+   * @example
+   * ```ts
+   * // Use node-fetch in Node.js environments
+   * import fetch from 'node-fetch';
+   *
+   * // Mock fetch for testing
+   * customFetchImpl: async (url, init) => {
+   *   return new Response(JSON.stringify({ mocked: true }), {
+   *     status: 200,
+   *     headers: { 'Content-Type': 'application/json' }
+   *   });
+   * }
+   *
+   * // Add custom logging to all requests
+   * customFetchImpl: async (url, init) => {
+   *   console.log(`Fetching: ${url}`);
+   *   const response = await fetch(url, init);
+   *   console.log(`Response: ${response.status}`);
+   *   return response;
+   * }
+   *
+   * // Use with custom HTTP client
+   * customFetchImpl: async (url, init) => {
+   *   // Convert to your preferred HTTP client format
+   *   return await customHttpClient.request({
+   *     url: url.toString(),
+   *     method: init?.method || 'GET',
+   *     headers: init?.headers,
+   *     body: init?.body
+   *   });
+   * }
+   * ```
    */
   customFetchImpl?: FetchImpl;
   /**
-   * Default HTTP error message to use if none is provided from a response.
+   * Default HTTP error message when server doesn't provide one.
+   *
+   * Can be a static string or a function that receives error context
+   * to generate dynamic error messages based on the response.
+   *
    * @default "Failed to fetch data from server!"
+   *
+   * @example
+   * ```ts
+   * // Static error message
+   * defaultHTTPErrorMessage: "API request failed. Please try again."
+   *
+   * // Dynamic error message based on status code
+   * defaultHTTPErrorMessage: ({ response }) => {
+   *   switch (response.status) {
+   *     case 401: return "Authentication required. Please log in.";
+   *     case 403: return "Access denied. Insufficient permissions.";
+   *     case 404: return "Resource not found.";
+   *     case 429: return "Too many requests. Please wait and try again.";
+   *     case 500: return "Server error. Please contact support.";
+   *     default: return `Request failed with status ${response.status}`;
+   *   }
+   * }
+   *
+   * // Include error data in message
+   * defaultHTTPErrorMessage: ({ errorData, response }) => {
+   *   const userMessage = errorData?.message || "Unknown error occurred";
+   *   return `${userMessage} (Status: ${response.status})`;
+   * }
+   * ```
    */
   defaultHTTPErrorMessage?: string | ((context: Pick<HTTPError<TErrorData>, "errorData" | "response">) => string);
   /**
-   * If true, forces the calculation of the total byte size from the request or response body, in case the content-length header is not present or is incorrect.
+   * Forces calculation of total byte size from request/response body streams.
+   *
+   * Useful when the Content-Length header is missing or incorrect, and you need
+   * accurate size information for progress tracking or bandwidth monitoring.
+   *
    * @default false
+   *
    */
   forcefullyCalculateStreamSize?: boolean | {
     request?: boolean;
     response?: boolean;
   };
   /**
-   * Defines the mode in which the composed hooks are executed".
-   * - If set to "parallel", main and plugin hooks will be executed in parallel.
-   * - If set to "sequential", the plugin hooks will be executed first, followed by the main hook.
-   * @default "parallel"
-   */
-  mergedHooksExecutionMode?: "parallel" | "sequential";
-  /**
-   * - Controls what order in which the composed hooks execute
-   * @default "mainHooksAfterPlugins"
-   */
-  mergedHooksExecutionOrder?: "mainHooksAfterPlugins" | "mainHooksBeforePlugins";
-  /**
-   * - An optional field you can fill with additional information,
-   * to associate with the request, typically used for logging or tracing.
+   * Optional metadata field for associating additional information with requests.
    *
-   * - A good use case for this, would be to use the info to handle specific cases in any of the shared interceptors.
+   * Useful for logging, tracing, or handling specific cases in shared interceptors.
+   * The meta object is passed through to all hooks and can be accessed in error handlers.
    *
    * @example
    * ```ts
@@ -854,61 +1486,321 @@ type SharedExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType, T
    * 	url: "https://example.com/api/data",
    * 	meta: { userId: "123" },
    * });
+   *
+   * // Use case: Request tracking
+   * const result = await callMainApi({
+   *   url: "https://example.com/api/data",
+   *   meta: {
+   *     requestId: generateId(),
+   *     source: "user-dashboard",
+   *     priority: "high"
+   *   }
+   * });
+   *
+   * // Use case: Feature flags
+   * const client = callApi.create({
+   *   baseURL: "https://api.example.com",
+   *   meta: {
+   *     features: ["newUI", "betaFeature"],
+   *     experiment: "variantA"
+   *   }
+   * });
    * ```
    */
   meta?: GlobalMeta;
   /**
-   * Custom function to parse the response string
+   * Custom function to parse response strings into objects.
+   *
+   * Useful when the API returns non-JSON responses or when you need
+   * custom parsing logic for specific response formats.
+   *
+   * @example
+   * ```ts
+   * // Parse XML responses
+   * responseParser: (responseString) => {
+   *   const parser = new DOMParser();
+   *   const doc = parser.parseFromString(responseString, "text/xml");
+   *   return xmlToObject(doc);
+   * }
+   *
+   * // Parse CSV responses
+   * responseParser: (responseString) => {
+   *   const lines = responseString.split('\n');
+   *   const headers = lines[0].split(',');
+   *   const data = lines.slice(1).map(line => {
+   *     const values = line.split(',');
+   *     return headers.reduce((obj, header, index) => {
+   *       obj[header] = values[index];
+   *       return obj;
+   *     }, {});
+   *   });
+   *   return { data };
+   * }
+   *
+   * // Parse custom format with error handling
+   * responseParser: async (responseString) => {
+   *   try {
+   *     // Custom parsing logic
+   *     const parsed = customFormat.parse(responseString);
+   *     return { success: true, data: parsed };
+   *   } catch (error) {
+   *     return { success: false, error: error.message };
+   *   }
+   * }
+   * ```
    */
   responseParser?: (responseString: string) => Awaitable<Record<string, unknown>>;
   /**
-   * Expected response type, affects how response is parsed
+   * Expected response type, determines how the response body is parsed.
+   *
+   * Different response types trigger different parsing methods:
+   * - **"json"**: Parses as JSON using response.json()
+   * - **"text"**: Returns as plain text using response.text()
+   * - **"blob"**: Returns as Blob using response.blob()
+   * - **"arrayBuffer"**: Returns as ArrayBuffer using response.arrayBuffer()
+   * - **"stream"**: Returns the response body stream directly
+   *
    * @default "json"
+   *
+   * @example
+   * ```ts
+   * // JSON API responses (default)
+   * responseType: "json"
+   *
+   * // Plain text responses
+   * responseType: "text"
+   * // Usage: const csvData = await callApi("/export.csv", { responseType: "text" });
+   *
+   * // File downloads
+   * responseType: "blob"
+   * // Usage: const file = await callApi("/download/file.pdf", { responseType: "blob" });
+   *
+   * // Binary data
+   * responseType: "arrayBuffer"
+   * // Usage: const buffer = await callApi("/binary-data", { responseType: "arrayBuffer" });
+   *
+   * // Streaming responses
+   * responseType: "stream"
+   * // Usage: const stream = await callApi("/large-dataset", { responseType: "stream" });
+   * ```
    */
   responseType?: TResponseType;
   /**
-   * Mode of the result, can influence how results are handled or returned.
-   * Can be set to "all" | "onlySuccess" | "onlyError" | "onlyResponse".
+   * Controls what data is included in the returned result object.
+   *
+   * Different modes return different combinations of data, error, and response:
+   * - **"all"**: Returns { data, error, response } - complete result information
+   * - **"allWithException"**: Returns { data, error, response } but throws on errors
+   * - **"onlySuccess"**: Returns only data (null for errors), never throws
+   * - **"onlySuccessWithException"**: Returns only data but throws on errors
+   *
    * @default "all"
+   *
+   * @example
+   * ```ts
+   * // Complete result with all information (default)
+   * resultMode: "all"
+   * const { data, error, response } = await callApi("/users");
+   * if (error) {
+   *   console.error("Request failed:", error);
+   * } else {
+   *   console.log("Users:", data);
+   * }
+   *
+   * // Complete result but throws on errors
+   * resultMode: "allWithException"
+   * try {
+   *   const { data, response } = await callApi("/users", { resultMode: "allWithException" });
+   *   console.log("Users:", data);
+   * } catch (error) {
+   *   console.error("Request failed:", error);
+   * }
+   *
+   * // Only data, returns null on errors
+   * resultMode: "onlySuccess"
+   * const users = await callApi("/users", { resultMode: "onlySuccess" });
+   * if (users) {
+   *   console.log("Users:", users);
+   * } else {
+   *   console.log("Request failed");
+   * }
+   *
+   * // Only data with null, throws on errors
+   * resultMode: "onlySuccessWithException"
+   * try {
+   *   const users = await callApi("/users", { resultMode: "onlySuccessWithException" });
+   *   console.log("Users:", users);
+   * } catch (error) {
+   *   console.error("Request failed:", error);
+   * }
+   * ```
    */
   resultMode?: TResultMode;
   /**
-   * If true or the function returns true, throws errors instead of returning them
-   * The function is passed the error object and can be used to conditionally throw the error
+   * Controls whether errors are thrown as exceptions or returned in the result.
+   *
+   * Can be a boolean or a function that receives the error and decides whether to throw.
+   * When true, errors are thrown as exceptions instead of being returned in the result object.
+   *
    * @default false
+   *
+   * @example
+   * ```ts
+   * // Always throw errors
+   * throwOnError: true
+   * try {
+   *   const data = await callApi("/users");
+   *   console.log("Users:", data);
+   * } catch (error) {
+   *   console.error("Request failed:", error);
+   * }
+   *
+   * // Never throw errors (default)
+   * throwOnError: false
+   * const { data, error } = await callApi("/users");
+   * if (error) {
+   *   console.error("Request failed:", error);
+   * }
+   *
+   * // Conditionally throw based on error type
+   * throwOnError: (error) => {
+   *   // Throw on client errors (4xx) but not server errors (5xx)
+   *   return error.response?.status >= 400 && error.response?.status < 500;
+   * }
+   *
+   * // Throw only on specific status codes
+   * throwOnError: (error) => {
+   *   const criticalErrors = [401, 403, 404];
+   *   return criticalErrors.includes(error.response?.status);
+   * }
+   *
+   * // Throw on validation errors but not network errors
+   * throwOnError: (error) => {
+   *   return error.type === "validation";
+   * }
+   * ```
    */
   throwOnError?: TThrowOnError;
   /**
-   * Request timeout in milliseconds
+   * Request timeout in milliseconds. Request will be aborted if it takes longer.
+   *
+   * Useful for preventing requests from hanging indefinitely and providing
+   * better user experience with predictable response times.
+   *
+   * @example
+   * ```ts
+   * // 5 second timeout
+   * timeout: 5000
+   *
+   * // Different timeouts for different endpoints
+   * const quickApi = createFetchClient({ timeout: 3000 }); // 3s for fast endpoints
+   * const slowApi = createFetchClient({ timeout: 30000 }); // 30s for slow operations
+   *
+   * // Per-request timeout override
+   * await callApi("/quick-data", { timeout: 1000 });
+   * await callApi("/slow-report", { timeout: 60000 });
+   *
+   * // No timeout (use with caution)
+   * timeout: 0
+   * ```
    */
   timeout?: number;
 };
 type BaseCallApiExtraOptions<TBaseData = DefaultDataType, TBaseErrorData = DefaultDataType, TBaseResultMode extends ResultModeUnion = ResultModeUnion, TBaseThrowOnError extends ThrowOnErrorUnion = DefaultThrowOnError, TBaseResponseType extends ResponseTypeUnion = ResponseTypeUnion, TBasePluginArray extends CallApiPlugin[] = DefaultPluginArray, TBaseSchemaAndConfig extends BaseCallApiSchemaAndConfig = BaseCallApiSchemaAndConfig> = SharedExtraOptions<TBaseData, TBaseErrorData, TBaseResultMode, TBaseThrowOnError, TBaseResponseType, TBasePluginArray> & {
   /**
-   * An array of base callApi plugins. It allows you to extend the behavior of the library.
+   * Array of base CallApi plugins to extend library functionality.
+   *
+   * Base plugins are applied to all instances created from this base configuration
+   * and provide foundational functionality like authentication, logging, or caching.
+   *
+   * @example
+   * ```ts
+   * // Add logging plugin
+   *
+   * // Create base client with common plugins
+   * const callApi = createFetchClient({
+   *   baseURL: "https://api.example.com",
+   *   plugins: [loggerPlugin({ enabled: true })]
+   * });
+   *
+   * // All requests inherit base plugins
+   * await callApi("/users");
+   * await callApi("/posts");
+   *
+   * ```
    */
   plugins?: TBasePluginArray;
   /**
-   * Base schemas for the client.
+   * Base validation schemas for the client configuration.
+   *
+   * Defines validation rules for requests and responses that apply to all
+   * instances created from this base configuration. Provides type safety
+   * and runtime validation for API interactions.
    */
   schema?: TBaseSchemaAndConfig;
   /**
-   * Specifies which configuration parts should skip automatic merging between base and main configs.
-   * Use this when you need manual control over how configs are combined.
+   * Controls which configuration parts skip automatic merging between base and instance configs.
    *
-   * @enum
-   * - `"all"` - Disables automatic merging for both request and options
-   * - `"options"` - Disables automatic merging of options only
-   * - `"request"` - Disables automatic merging of request only
+   * By default, CallApi automatically merges base configuration with instance configuration.
+   * This option allows you to disable automatic merging for specific parts when you need
+   * manual control over how configurations are combined.
    *
-   * **Example**
+   * @enum
+   * - **"all"**: Disables automatic merging for both request options and extra options
+   * - **"options"**: Disables automatic merging of extra options only (hooks, plugins, etc.)
+   * - **"request"**: Disables automatic merging of request options only (headers, body, etc.)
    *
+   * @example
    * ```ts
+   * // Skip all automatic merging - full manual control
+   * const client = callApi.create((ctx) => ({
+   *   skipAutoMergeFor: "all",
+   *
+   *   // Manually decide what to merge
+   *   baseURL: ctx.options.baseURL, // Keep base URL
+   *   timeout: 5000, // Override timeout
+   *   headers: {
+   *     ...ctx.request.headers, // Merge headers manually
+   *     "X-Custom": "value" // Add custom header
+   *   }
+   * }));
+   *
+   * // Skip options merging - manual plugin/hook control
+   * const client = callApi.create((ctx) => ({
+   *   skipAutoMergeFor: "options",
+   *
+   *   // Manually control which plugins to use
+   *   plugins: [
+   *     ...ctx.options.plugins?.filter(p => p.name !== "unwanted") || [],
+   *     customPlugin
+   *   ],
+   *
+   *   // Request options still auto-merge
+   *   method: "POST"
+   * }));
+   *
+   * // Skip request merging - manual request control
+   * const client = callApi.create((ctx) => ({
+   *   skipAutoMergeFor: "request",
+   *
+   *   // Extra options still auto-merge (plugins, hooks, etc.)
+   *
+   *   // Manually control request options
+   *   headers: {
+   *     "Content-Type": "application/json",
+   *     // Don't merge base headers
+   *   },
+   *   method: ctx.request.method || "GET"
+   * }));
+   *
+   * // Use case: Conditional merging based on request
    * const client = createFetchClient((ctx) => ({
    *   skipAutoMergeFor: "options",
    *
-   *   // Now you can manually merge options in your config function
-   *   ...ctx.options,
+   *   // Only use auth plugin for protected routes
+   *   plugins: ctx.initURL.includes("/protected/")
+   *     ? [...(ctx.options.plugins || []), authPlugin]
+   *     : ctx.options.plugins?.filter(p => p.name !== "auth") || []
    * }));
    * ```
    */
@@ -916,20 +1808,35 @@ type BaseCallApiExtraOptions<TBaseData = DefaultDataType, TBaseErrorData = Defau
 };
 type CallApiExtraOptions<TData = DefaultDataType, TErrorData = DefaultDataType, TResultMode extends ResultModeUnion = ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion = DefaultThrowOnError, TResponseType extends ResponseTypeUnion = ResponseTypeUnion, TBasePluginArray extends CallApiPlugin[] = DefaultPluginArray, TPluginArray extends CallApiPlugin[] = DefaultPluginArray, TBaseSchemaRoutes extends BaseCallApiSchemaRoutes = BaseCallApiSchemaRoutes, TSchema extends CallApiSchema = CallApiSchema, TBaseSchemaConfig extends CallApiSchemaConfig = CallApiSchemaConfig, TSchemaConfig extends CallApiSchemaConfig = CallApiSchemaConfig, TCurrentRouteSchemaKey extends string = string> = SharedExtraOptions<TData, TErrorData, TResultMode, TThrowOnError, TResponseType, TPluginArray> & {
   /**
-   * An array of instance CallApi plugins. It allows you to extend the behavior of the library.
+   * Array of instance-specific CallApi plugins or a function to configure plugins.
+   *
+   * Instance plugins are added to the base plugins and provide functionality
+   * specific to this particular API instance. Can be a static array or a function
+   * that receives base plugins and returns the instance plugins.
+   *
    */
   plugins?: TPluginArray | ((context: {
     basePlugins: Writeable<TBasePluginArray, "deep">;
   }) => TPluginArray);
   /**
-   * Schemas for the callapi instance
+   * Instance-specific validation schemas or a function to configure schemas.
+   *
+   * Defines validation rules specific to this API instance, extending or
+   * overriding base schemas. Can be a static schema object or a function
+   * that receives base schema context and returns instance schemas.
+   *
    */
   schema?: TSchema | ((context: {
     baseSchema: Writeable<TBaseSchemaRoutes, "deep">;
     currentRouteSchema: GetCurrentRouteSchema<TBaseSchemaRoutes, TCurrentRouteSchemaKey>;
   }) => TSchema);
   /**
-   * Schema config for the callapi instance
+   * Instance-specific schema configuration or a function to configure schema behavior.
+   *
+   * Controls how validation schemas are applied and behave for this specific
+   * API instance. Can override base schema configuration or extend it with
+   * instance-specific validation rules.
+   *
    */
   schemaConfig?: TSchemaConfig | ((context: {
     baseSchemaConfig: Writeable<TBaseSchemaConfig, "deep">;
@@ -946,4 +1853,4 @@ type CallApiParameters<TData = DefaultDataType, TErrorData = DefaultDataType, TR
 type CallApiResult<TData, TErrorData, TResultMode extends ResultModeUnion, TThrowOnError extends ThrowOnErrorUnion, TResponseType extends ResponseTypeUnion> = Promise<GetCallApiResult<TData, TErrorData, TResultMode, TThrowOnError, TResponseType>>;
 //#endregion
 export { AnyFunction, AnyString, ApplyStrictConfig, ApplyURLBasedConfig, BaseCallApiConfig, BaseCallApiExtraOptions, BaseCallApiSchemaAndConfig, BaseCallApiSchemaRoutes, CallApiConfig, CallApiExtraOptions, CallApiExtraOptionsForHooks, CallApiParameters, CallApiPlugin, CallApiRequestOptions, CallApiRequestOptionsForHooks, CallApiResult, CallApiResultErrorVariant, CallApiResultSuccessVariant, CallApiSchema, CallApiSchemaConfig, DedupeOptions, DefaultDataType, DefaultPluginArray, DefaultThrowOnError, ErrorContext, GetCurrentRouteSchema, GetCurrentRouteSchemaKey, HTTPError, Hooks, HooksOrHooksArray, InferInitURL, InferParamsFromRoute, InferSchemaResult, PluginExtraOptions, PluginHooks, PluginHooksWithMoreOptions, PluginInitContext, PossibleHTTPError, PossibleJavaScriptError, PossibleJavaScriptOrValidationError, PossibleValidationError, Register, RequestContext, RequestStreamContext, ResponseContext, ResponseErrorContext, ResponseStreamContext, ResponseTypeUnion, ResultModeUnion, RetryOptions, SuccessContext, ThrowOnErrorUnion, URLOptions, ValidationError, Writeable };
-//# sourceMappingURL=common-Vd9i_nPc.d.ts.map
+//# sourceMappingURL=common-C-kIzPcz.d.ts.map