@ahoo-wang/fetcher 3.0.2 → 3.0.5

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { Fetcher } from './fetcher';
 /**
  * Creates a new type by making specified properties of an existing type optional.
  *
@@ -35,27 +36,228 @@ export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
  */
 export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 /**
- * Interface representing a named capable entity
- * Types implementing this interface must provide a name property
+ * Creates a new type by removing all readonly properties from an existing type.
+ *
+ * This utility type takes a type T and produces a new type that excludes all properties
+ * that are marked as readonly in the original type. This is useful when you need to create
+ * a mutable version of an interface or when working with data that should be modifiable.
+ *
+ * @template T - The original type from which to remove readonly properties
+ * @returns A new type containing only the mutable (non-readonly) properties of T
+ *
+ * @example
+ * interface User {
+ *   readonly id: number;
+ *   name: string;
+ *   readonly createdAt: Date;
+ *   email: string;
+ * }
+ *
+ * type MutableUser = RemoveReadonlyFields<User>;
+ * // Result: { name: string; email: string; }
+ * // 'id' and 'createdAt' are excluded because they are readonly
+ *
+ * @example
+ * // Usage in function parameters
+ * function updateUser(user: RemoveReadonlyFields<User>) {
+ *   // user.id and user.createdAt are not available here
+ *   user.name = 'New Name'; // OK
+ *   user.email = 'new@email.com'; // OK
+ * }
+ */
+export type RemoveReadonlyFields<T> = {
+    [K in keyof T as Equal<Pick<T, K>, Readonly<Pick<T, K>>> extends true ? never : K]: T[K];
+};
+/**
+ * Utility type to check if two types X and Y are exactly equal.
+ *
+ * This type uses conditional types and function type inference to determine
+ * strict type equality. It returns true if X and Y are identical types,
+ * false otherwise. This is particularly useful in mapped types for filtering
+ * based on type properties.
+ *
+ * @template X - First type to compare
+ * @template Y - Second type to compare
+ * @returns true if X and Y are the same type, false otherwise
+ *
+ * @internal This is an internal utility type used by other type definitions
+ */
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * Interface representing a named capable entity.
+ *
+ * This interface defines a contract for objects that have an identifiable name.
+ * Any type implementing this interface must provide a string property called 'name'
+ * that uniquely identifies the entity within its context.
+ *
+ * @interface NamedCapable
+ *
+ * @property {string} name - A unique identifier for the entity, used for
+ *   identification, logging, and user-facing display purposes.
+ *
+ * @example
+ * class Service implements NamedCapable {
+ *   name = 'UserService';
+ *
+ *   async getUser(id: number) {
+ *     // Implementation
+ *   }
+ * }
+ *
+ * @example
+ * const services: NamedCapable[] = [
+ *   { name: 'AuthService' },
+ *   { name: 'DataService' }
+ * ];
+ *
+ * services.forEach(service => {
+ *   console.log(`Initializing ${service.name}`);
+ * });
  */
 export interface NamedCapable {
     /**
-     * The name of the entity
+     * The name of the entity.
+     *
+     * This property serves as a unique identifier for the implementing object.
+     * It should be descriptive and follow consistent naming conventions
+     * within the application context.
      */
     name: string;
 }
 /**
- * Global extension of Response interface
- * Adds type-safe json() method support to Response objects
+ * Global extension of the native Response interface.
+ *
+ * This declaration augments the standard Web API Response interface to provide
+ * enhanced type safety for JSON parsing operations. The extended json() method
+ * allows specifying the expected return type, enabling better TypeScript
+ * inference and compile-time type checking.
+ *
+ * @interface Response
  */
 declare global {
     interface Response {
         /**
-         * Parse response body as JSON in a type-safe manner
-         * @template T The type of returned data, defaults to any
-         * @returns Promise<T> The parsed JSON data
+         * Parses the response body as JSON with type safety.
+         *
+         * This method extends the native Response.json() method to support generic
+         * type parameters, allowing developers to specify the expected shape of
+         * the parsed JSON data. This provides compile-time type checking and
+         * better IDE support.
+         *
+         * @template T - The expected type of the parsed JSON data. Defaults to 'any' for backward compatibility.
+         * @returns {Promise<T>} A promise that resolves to the parsed JSON data of type T.
+         *
+         * @throws {SyntaxError} If the response body is not valid JSON.
+         * @throws {TypeError} If the response has no body or the body cannot be parsed.
+         *
+         * @example
+         * interface User {
+         *   id: number;
+         *   name: string;
+         *   email: string;
+         * }
+         *
+         * const response = await fetch('/api/user/123');
+         * const user: User = await response.json<User>();
+         * console.log(user.name); // TypeScript knows this is a string
+         *
+         * @example
+         * // Without type parameter (defaults to any)
+         * const data = await response.json();
+         * // data is of type 'any'
+         *
+         * @example
+         * // Error handling
+         * try {
+         *   const result = await response.json<{ success: boolean; data: string[] }>();
+         *   if (result.success) {
+         *     result.data.forEach(item => console.log(item));
+         *   }
+         * } catch (error) {
+         *   console.error('Failed to parse JSON:', error);
+         * }
          */
         json<T = any>(): Promise<T>;
     }
 }
+/**
+ * Interface for configuring Fetcher instances.
+ *
+ * This interface defines a contract for objects that can configure a Fetcher instance
+ * with specific interceptors, middleware, or other customizations. Implementations of
+ * this interface provide a standardized way to apply configuration to Fetcher objects,
+ * enabling modular and reusable configuration patterns.
+ *
+ * @interface FetcherConfigurer
+ *
+ * @example
+ * ```typescript
+ * class AuthConfigurer implements FetcherConfigurer {
+ *   configure(fetcher: Fetcher): void {
+ *     // Add authentication interceptors
+ *     fetcher.interceptors.request.use(new AuthRequestInterceptor());
+ *     fetcher.interceptors.response.use(new AuthResponseInterceptor());
+ *   }
+ * }
+ *
+ * // Usage
+ * const fetcher = new Fetcher({ baseURL: '/api' });
+ * const configurer = new AuthConfigurer();
+ * configurer.configure(fetcher);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple configurers can be applied
+ * const configurers: FetcherConfigurer[] = [
+ *   new AuthConfigurer(),
+ *   new LoggingConfigurer(),
+ *   new RetryConfigurer()
+ * ];
+ *
+ * const fetcher = new Fetcher({ baseURL: '/api' });
+ * configurers.forEach(configurer => configurer.configure(fetcher));
+ * ```
+ */
+export interface FetcherConfigurer {
+    /**
+     * Configures the provided Fetcher instance.
+     *
+     * This method should apply all necessary configuration to the Fetcher instance,
+     * such as adding interceptors, setting default headers, or configuring other
+     * behavior. The method should be idempotent - calling it multiple times on
+     * the same Fetcher instance should not cause issues.
+     *
+     * @param fetcher - The Fetcher instance to configure
+     *
+     * @example
+     * ```typescript
+     * applyTo(fetcher: Fetcher): void {
+     *   // Add request interceptor for authentication
+     *   fetcher.interceptors.request.use({
+     *     onFulfilled: config => {
+     *       config.headers = {
+     *         ...config.headers,
+     *         'Authorization': `Bearer ${getToken()}`
+     *       };
+     *       return config;
+     *     }
+     *   });
+     *
+     *   // Add response interceptor for error handling
+     *   fetcher.interceptors.response.use({
+     *     onRejected: error => {
+     *       if (error.response?.status === 401) {
+     *         // Handle unauthorized
+     *         redirectToLogin();
+     *       }
+     *       return Promise.reject(error);
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    applyTo(fetcher: Fetcher): void;
+}
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACvD,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,QAAQ;QAChB;;;;WAIG;QACH,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;KAC7B;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACvD,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;KACnC,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GACjE,KAAK,GACL,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,IACb,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAC/D,IAAI,GACJ,KAAK,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,QAAQ;QAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAwCG;QACH,IAAI,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;KAC7B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC"}

package/dist/urlBuilder.d.ts

@@ -54,8 +54,8 @@ export declare class UrlBuilder implements BaseURLCapable {
      *
      * This is typically the root of your API endpoint (e.g., 'https://api.example.com').
      */
-    readonly baseURL: string;
-    readonly urlTemplateResolver: UrlTemplateResolver;
+    baseURL: string;
+    urlTemplateResolver: UrlTemplateResolver;
     /**
      * Initializes a new UrlBuilder instance.
      *

package/dist/urlBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"urlBuilder.d.ts","sourceRoot":"","sources":["../src/urlBuilder.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAEL,KAAK,mBAAmB,EACxB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,gBAAgB;IAKhE;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM;IAc9C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;CAGjD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB"}
+{"version":3,"file":"urlBuilder.d.ts","sourceRoot":"","sources":["../src/urlBuilder.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAEL,KAAK,mBAAmB,EACxB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,mBAAmB,CAAC;IAEzC;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,gBAAgB;IAKhE;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM;IAc9C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;CAGjD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher",
-  "version": "3.0.2",
+  "version": "3.0.5",
   "description": "Fetcher is not just another HTTP client—it's a complete ecosystem designed for modern web development with native LLM\nstreaming API support. Built on the native Fetch API, Fetcher provides an Axios-like experience with powerful features\nwhile maintaining an incredibly small footprint.",
   "keywords": [
     "fetch",