@tahanabavi/typefetch 1.3.0 → 1.4.1

package/dist/index.d.ts

@@ -1,56 +1,158 @@
 import { z } from 'zod';
 
 /**
- * Generic request schema:
- *
- * request: z.object({
- *   path: z.object({ ... }).optional(),
- *   query: z.object({ ... }).optional(),
- *   body: z.object({ ... }).optional(),
- * })
+ * Base types for Zod schemas representing request and response structures.
+ * These are abstract—each concrete endpoint will define its own Zod object for these.
  */
 type RequestSchema = z.ZodTypeAny;
 type ResponseSchema = z.ZodTypeAny;
+/**
+ * EndpointDef
+ * ============
+ * Defines the structure of a **single API endpoint**, including:
+ * - HTTP method and path
+ * - request/response validation schemas
+ * - optional authentication requirement
+ * - optional mock or static mock data
+ * - optional custom headers and body format
+ */
 type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
+    /** HTTP method used by this endpoint */
     method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** URL path for this endpoint, e.g. "/users/:id" */
     path: string;
+    /** Whether this endpoint requires an Authorization token */
     auth?: boolean;
+    /** Zod schema describing the expected request structure */
     request: TReq;
+    /** Zod schema describing the expected response structure */
     response: TRes;
+    /**
+     * Mock data support — enables quick testing or local dev mode:
+     * - Either a function returning a mock response object
+     * - Or a static mock response object
+     */
     mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
+    /**
+     * Optional custom headers. Can be:
+     * - A fixed record of header key/values
+     * - A function returning headers derived from the input data
+     */
     headers?: Record<string, string> | ((input: z.infer<TReq>) => Record<string, string>);
+    /**
+     * Defines how the request body should be sent:
+     * - `"json"` (default): serialized as JSON
+     * - `"form-data"`: multipart form
+     */
     bodyType?: "json" | "form-data";
 };
+/**
+ * Contracts
+ * =========
+ * A collection of modules, each containing one or more endpoints.
+ * This defines a **hierarchical API contract**.
+ *
+ * For example:
+ * {
+ *   users: {
+ *     getUser: EndpointDef(...),
+ *     updateUser: EndpointDef(...)
+ *   },
+ *   posts: {
+ *     createPost: EndpointDef(...),
+ *     listPosts: EndpointDef(...)
+ *   }
+ * }
+ */
 type Contracts = {
     [ModuleName: string]: {
         [EndpointName: string]: EndpointDef<RequestSchema, ResponseSchema>;
     };
 };
+/**
+ * Context passed to all middleware functions.
+ * Contains the current request URL and initialization object
+ * (headers, method, body, etc.).
+ */
 interface MiddlewareContext {
     url: string;
     init: RequestInit;
 }
+/**
+ * The `next()` function type signature used inside middleware.
+ * When called, it executes the next function in the chain
+ * or finally performs the fetch request.
+ */
 type MiddlewareNext = () => Promise<Response>;
+/**
+ * Middleware
+ * ==========
+ * Defines the standard structure for a request middleware.
+ * Middlewares can intercept, modify, or even short-circuit requests.
+ *
+ * @example Logging Example:
+ * const logMiddleware: Middleware = async (ctx, next) => {
+ *   console.log("Request:", ctx.url);
+ *   const res = await next();
+ *   console.log("Response:", res.status);
+ *   return res;
+ * };
+ */
 type Middleware<Options = any> = (ctx: MiddlewareContext, next: MiddlewareNext, options?: Options) => Promise<Response>;
+/**
+ * ErrorLike
+ * =========
+ * Represents the normalized error shape used across the client.
+ * Provides consistency for error handling modules such as RichError.
+ */
 type ErrorLike = {
     message: string;
     status?: number;
     code?: string;
     [key: string]: any;
 };
+/**
+ * Convenience alias that pins both generic types
+ * to `z.ZodTypeAny`, simplifying the contract declarations.
+ */
 type EndpointDefZ = EndpointDef<RequestSchema, ResponseSchema>;
 /**
- * For each endpoint we expose a method:
- *   (input: z.infer<Endpoint["request"]>) => Promise<z.infer<Endpoint["response"]>>
+ * RequestOptions
+ * ==============
+ * Per-request options passed to the client execution:
+ * - Optional AbortSignal (for cancellation)
+ * - Optional timeout (in milliseconds)
+ */
+type RequestOptions = {
+    signal?: AbortSignal;
+    timeout?: number;
+};
+/**
+ * EndpointMethods
+ * ================
+ * Automatically generated method signatures for all endpoints
+ * within a module, based on the Zod contract definitions.
  *
- * So VSCode will show you:
- *   { path?: { ... }, query?: { ... }, body?: { ... } }
+ * Each endpoint method:
+ * - Validates input against its request schema
+ * - Returns a Promise of the parsed and validated response type
  */
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
-    [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
+    [K in keyof M]: (input: z.infer<M[K]["request"]>, // Auto‑derived input type from Zod schema
+    options?: RequestOptions) => Promise<z.infer<M[K]["response"]>>;
 };
+/**
+ * TokenProvider
+ * =============
+ * Specifies the contract for a function that supplies authentication tokens.
+ * Can be synchronous or async, e.g. fetching from localStorage or refreshing with an API.
+ */
 type TokenProvider = () => string | Promise<string>;
 
+/**
+ * A richer extension of the native Error class that captures
+ * additional API error details such as HTTP status, code, and field errors.
+ */
 declare class RichError extends Error implements ErrorLike {
     status?: number;
     code?: string;
@@ -62,7 +164,15 @@ declare class RichError extends Error implements ErrorLike {
     });
 }
 /**
- * Strongly-typed HTTP client built from Zod contracts.
+ * ApiClient
+ * =========
+ * A robust, strongly-typed HTTP client that automatically builds API endpoint
+ * methods from Zod-based contracts, providing:
+ * - Input and response validation via Zod
+ * - Middleware support
+ * - Token-based authentication
+ * - Error normalization (RichError)
+ * - Optional caching, retries, and mock data
  */
 declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private config;
@@ -74,6 +184,7 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private mockDelay;
     private responseWrapper?;
     private tokenProvider?;
+    private retryConfig?;
     private _modules;
     constructor(config: {
         baseUrl: string;
@@ -86,91 +197,64 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
         };
     }, contracts: C);
     /**
-     * Builds the strongly-typed `modules` API from the provided contracts.
-     * Must be called once after constructing the client.
+     * Builds all API methods (`modules`) dynamically from the Zod contract definition.
+     * After `init()` is called, each endpoint can be invoked through `client.modules.moduleName.endpointName()`.
      */
     init(): void;
-    /**
-     * Type-safe entrypoint for calling API endpoints.
-     * Populated by `init()` based on the `contracts` passed to the constructor.
-     */
+    /** Provides access to initialized modules after calling `init()`. */
     get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
-    /**
-     * Registers a middleware in the pipeline.
-     * Middlewares are executed in reverse order of registration.
-     */
+    /** Registers a new middleware in the client’s pipeline. */
     use<T>(middleware: Middleware<T>, options?: T): void;
-    /**
-     * Registers a global error handler.
-     * The handler is invoked for normalized errors before they are re-thrown.
-     */
+    /** Sets a global error handler function to unify error behavior. */
     onError(handler: (error: E) => void): void;
-    /**
-     * Registers a transformation function applied to all successful responses
-     * after Zod parsing.
-     */
+    /** Defines a global transform function applied to all validated responses. */
     useResponseTransform(fn: (data: any) => any): void;
-    /**
-     * Enables or disables mock mode. When enabled, endpoints with `mockData`
-     * return mocked responses instead of performing network requests.
-     */
+    /** Configures the retry logic (max attempts, backoff mode, etc.). */
+    setRetryConfig(config: ApiClient<C>["retryConfig"]): void;
+    /** Provides a custom token provider that returns tokens dynamically. */
+    setTokenProvider(provider: TokenProvider): void;
+    /** Enables mock responses instead of network requests. */
     setMockMode(enabled: boolean, delay?: {
         min: number;
         max: number;
     }): void;
-    /**
-     * Registers a schema wrapper for APIs that wrap data in an envelope.
-     * Example: { success, data, message, code, ... }.
-     */
+    /** Registers a wrapper schema for APIs that nest response data (e.g. `{ data, success, message }`). */
     setResponseWrapper(wrapper: (successResponse: z.ZodTypeAny) => z.ZodTypeAny): void;
-    /**
-     * Sets or updates the token provider used for authenticated endpoints.
-     * Overrides any static token provided in the constructor.
-     */
-    setTokenProvider(provider: TokenProvider): void;
-    /**
-     * Returns the current token, preferring the tokenProvider if present,
-     * otherwise falling back to the static token from the constructor.
-     */
+    /** Retrieves the current auth token, using a provider if available. */
     getCurrentToken(): Promise<string | undefined>;
     /**
-     * Executes a single endpoint request.
-     *
-     * Expected request shape (new style):
-     *   z.object({
-     *     path: z.object({...}).optional(),
-     *     query: z.object({...}).optional(),
-     *     body: z.any().optional(),
-     *     header: z.object({...}).optional(),
-     *   })
-     *
-     * If the parsed request does not contain `path`, `header`,`query` or `body`,
-     * the entire input is treated as the legacy flat request body.
+     * Core request entry point used by auto-generated endpoint methods.
+     * Handles caching, deduplication, and mock mode routing.
      */
     private request;
     /**
-     * Builds final URL and body from endpoint + request input.
-     * Supports both structured `{ path, query, body, headers }` and legacy flat input.
+     * Full HTTP request workflow:
+     * - Token injection
+     * - Timeout support
+     * - Middleware pipeline
+     * - Fetch + response handling
+     * - Zod parsing + transformation
+     * - Caching
      */
+    private performRequestLogic;
+    /** Executes a function with retry logic and configurable backoff strategy. */
+    private executeWithRetry;
+    /** Calculates retry delay intervals for various backoff strategies. */
+    private getBackoffDelay;
+    /** Builds the final URL and request body from the endpoint definition and input payload. */
     private buildUrlAndBody;
-    /**
-     * Returns a mocked response based on `endpoint.mockData`,
-     * respecting the configured mock delay and response wrapper.
-     */
-    private handleMockRequest;
-    /**
-     * Returns a random delay in milliseconds within the current mock delay range.
-     */
-    private getRandomDelay;
-    /**
-     * Creates a RichError instance from a partial error description.
-     */
+    /** Creates and returns a RichError from details. */
     private createError;
     /**
-     * Normalizes unknown errors into a RichError instance.
-     * Zod validation errors are converted into a standardized validation error.
+     * Converts any thrown error to a standardized RichError instance.
+     * Also flattens Zod validation errors into readable messages.
      */
     private normalizeError;
+    /**
+     * Handles mock-mode requests by simulating a delayed network call
+     * and returning validated mock data.
+     */
+    private handleMockRequest;
 }
 
 type LoggingOptions = {
@@ -186,14 +270,99 @@ type RetryOptions = {
 };
 declare const retryMiddleware: (options?: RetryOptions) => Middleware;
 
+/**
+ * TokenManagementOptions
+ * ======================
+ * Configuration structure for supplying credentials to the authentication layer.
+ *
+ * @property refreshToken A required asynchronous function responsible for
+ *                        obtaining a current, valid access token string. This allows
+ *                        for token fetching from storage or re-issuance upon expiry.
+ */
 type AuthOptions = {
     refreshToken?: () => Promise<string>;
 };
+/**
+ * AuthenticationInjectorMiddleware
+ * ==================================
+ * This middleware operates early in the request pipeline to ensure every
+ * outgoing request is properly authorized by prepending an Authorization header.
+ *
+ * Core Logic:
+ * -----------
+ * 1. It checks if an explicit `refreshToken` supplier was configured in its options.
+ * 2. If present, it synchronously calls this supplier to obtain the latest token.
+ * 3. The resulting token is formatted as a standard 'Bearer' token and merged
+ *    into the request's `init.headers`.
+ * 4. The request context (`ctx`) is then passed downstream.
+ *
+ * Note on Error Handling:
+ * -----------------------
+ * Any failure during the token retrieval process (e.g., if `refreshToken` throws)
+ * results in the error being caught, and the request proceeds **without** an
+ * Authorization header. This design defers failure response handling to
+ * subsequent middleware or the final network fetcher.
+ *
+ * @param ctx The current request context object, including mutable `init` properties.
+ * @param next The function to execute the rest of the middleware chain.
+ * @param options The specific configuration passed to this middleware instance.
+ *
+ * @returns The final `Response` object after the network call completes.
+ *
+ * @example
+ * // Assuming token retrieval logic is defined elsewhere
+ * const tokenSupplier = () => fetchTokenFromSecureStorage();
+ *
+ * client.addInterceptor(
+ *   authMiddleware({ refreshToken: tokenSupplier })
+ * );
+ */
 declare const authMiddleware: Middleware<AuthOptions>;
 
+/**
+ * CacheOptions
+ * ============
+ * Options for configuring the cache middleware.
+ * - `ttl` (Time To Live): Duration (in milliseconds) to keep cached GET responses.
+ *   After this time, cached data expires and a fresh network call is performed.
+ */
 type CacheOptions = {
     ttl?: number;
 };
+/**
+ * cacheMiddleware
+ * ===============
+ * A generic caching middleware for GET requests in the ApiClient.
+ * It stores successful responses in memory based on URL and method,
+ * returning cached data for subsequent identical requests until the TTL expires.
+ *
+ * Purpose:
+ * --------
+ * - Reduces redundant network calls
+ * - Improves performance for frequently fetched resources
+ * - Useful for lightweight front-end caching (not suitable for sensitive data)
+ *
+ * Behavior:
+ * ---------
+ * 1. Only applies to `GET` requests; all other HTTP methods bypass caching.
+ * 2. Caches the parsed JSON response in a simple in-memory Map.
+ * 3. On subsequent requests:
+ *    - If the cache entry exists and hasn’t expired, returns a synthetic
+ *      `Response` object built from cached JSON.
+ *    - Otherwise performs the network call and refreshes the cache.
+ *
+ * @param options - Optional cache configuration (TTL in ms)
+ *
+ * @returns Middleware function compatible with the ApiClient pipeline.
+ *
+ * @example
+ * client.use(
+ *   cacheMiddleware({ ttl: 120000 }) // cache GET results for 2 minutes
+ * );
+ *
+ * @note Each middleware instance maintains its own internal cache
+ *       and is memory-scoped (not persistent between reloads).
+ */
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
 declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery extends z.ZodRawShape = {}, TBody extends z.ZodTypeAny = z.ZodUndefined>() => (defs: {
@@ -218,4 +387,4 @@ declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery exten
     headers: any;
 }> extends infer T_9 ? { [k_5 in keyof T_9]: T_9[k_5]; } : never>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, makeRequestSchema, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestOptions, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, makeRequestSchema, retryMiddleware };