docs: Update JSDoc of API Handler interfaces

docs/examples/examples.ts

@@ -88,7 +88,9 @@ async function example3() {
  fetchBooks: Endpoint<Books, BooksQueryParams>;
  }
 
- const api = createApiFetcher<Endpoints, typeof endpoints>({
+ type EndpointsConfiguration = typeof endpoints;
+
+ const api = createApiFetcher<Endpoints, EndpointsConfiguration>({
  apiUrl: '',
  endpoints,
  });
@@ -151,7 +153,9 @@ async function example4() {
  fetchBooks: Endpoint<Books, BooksQueryParams>;
  }
 
- const api = createApiFetcher<Endpoints, typeof endpoints>({
+ type EndpointsConfiguration = typeof endpoints;
+
+ const api = createApiFetcher<Endpoints, EndpointsConfiguration>({
  apiUrl: '',
  endpoints,
  flattenResponse: true,
@@ -177,11 +181,13 @@ async function example4() {
 
 // createApiFetcher() - direct API request() call to a custom endpoint with flattenResponse == false
 async function example5() {
- interface Endpoints5 {
+ interface MyEndpoints {
  fetchBooks: Endpoint<Books, BooksQueryParams>;
  }
 
- const api = createApiFetcher<Endpoints5, typeof endpoints>({
+ type EndpointsConfiguration = typeof endpoints;
+
+ const api = createApiFetcher<MyEndpoints, EndpointsConfiguration>({
  apiUrl: '',
  endpoints,
  });

src/api-handler.ts

@@ -68,7 +68,7 @@ import { createRequestHandler } from './request-handler';
  */
 function createApiFetcher<
  EndpointsMethods extends object,
- EndpointsCfg = never,
+ EndpointsSettings = never,
 >(config: ApiHandlerConfig<EndpointsMethods>) {
  const endpoints = config.endpoints;
  const requestHandler = createRequestHandler(config);
@@ -154,7 +154,7 @@ function createApiFetcher<
 
  return new Proxy(apiHandler, {
  get: (_target, prop: string) => get(prop),
- }) as ApiHandlerMethods<EndpointsMethods, EndpointsCfg>;
+ }) as ApiHandlerMethods<EndpointsMethods, EndpointsSettings>;
 }
 
 export { createApiFetcher };

src/types/api-handler.ts

@@ -43,7 +43,7 @@ export declare type UrlPathParams<T = unknown> =
  * The overloads allow customization of the returned data type (`ReturnedData`), query parameters (`T`),
  * and URL path parameters (`T2`).
  *
- * @template ResponseData - The type of the response data (default: `APIResponse`).
+ * @template ResponseData - The type of the response data (default: `DefaultResponse`).
  * @template QueryParams - The type of the query parameters (default: `QueryParamsOrBody`).
  * @template PathParams - The type of the URL path parameters (default: `UrlPathParams`).
  *
@@ -61,14 +61,14 @@ export declare type Endpoint<
  /**
  * Endpoint with default `ResponseData`, `QueryParams`, and `PathParams`.
  *
- * @param {QueryParams} [queryParams] - Optional query parameters for the request.
+ * @param {QueryParams} [queryParamsOrBody] - Optional query parameters for the request.
  * @param {PathParams} [urlPathParams] - Optional URL path parameters for the request.
  * @param {StructuredConfig<RequestConfig<ResponseData>>} [requestConfig] - Optional configuration for the request.
  * @returns {Promise<FetchResponse<ResponseData>>} - A promise resolving to the fetch response.
  */
  | {
  (
- queryParams?: QueryParams,
+ queryParamsOrBody?: QueryParams,
  urlPathParams?: PathParams,
  requestConfig?: RequestConfig<ResponseData>,
  ): Promise<FetchResponse<ResponseData>>;
@@ -79,55 +79,94 @@ export declare type Endpoint<
  * @template ReturnedData - The type of data returned in the response.
  * @template T - The type of query parameters.
  * @template T2 - The type of URL path parameters.
- * @param {T} [queryParams] - Optional query parameters for the request.
+ * @param {T} [queryParamsOrBody] - Optional query parameters for the request.
  * @param {T2} [urlPathParams] - Optional URL path parameters for the request.
  * @param {StructuredConfig<RequestConfig<ResponseData>>} [requestConfig] - Optional configuration for the request.
  * @returns {Promise<FetchResponse<ReturnedData>>} - A promise resolving to the customized fetch response.
  */
  | {
  <ReturnedData = ResponseData, T = QueryParams, T2 = PathParams>(
- queryParams?: T,
+ queryParamsOrBody?: T,
  urlPathParams?: T2,
  requestConfig?: RequestConfig<ReturnedData>,
  ): Promise<FetchResponse<ReturnedData>>;
  };
 
 type EndpointDefaults = Endpoint<DefaultResponse>;
 
+/**
+ * Maps the method names from `EndpointsMethods` to their corresponding `Endpoint` type definitions.
+ *
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ */
 type EndpointsRecord<EndpointsMethods> = {
  [K in keyof EndpointsMethods]: EndpointsMethods[K] extends Endpoint<
  infer ResponseData,
  infer QueryParams,
  infer UrlPathParams
  >
- ? Endpoint<ResponseData, QueryParams, UrlPathParams>
- : Endpoint<DefaultResponse>;
+ ? Endpoint<ResponseData, QueryParams, UrlPathParams> // Method exists in a provided interface
+ : Endpoint<DefaultResponse>; // Method is not defined. Provide defaults
 };
 
-type DefaultEndpoints<EndpointsCfg> = {
- [K in keyof EndpointsCfg]: EndpointDefaults;
+/**
+ * Defines default endpoints based on the provided `EndpointsSettings`.
+ *
+ * This type provides default implementations for endpoints in `EndpointsSettings`, using `EndpointDefaults`.
+ *
+ * @template EndpointsSettings - The configuration object for endpoints.
+ */
+type DefaultEndpoints<EndpointsSettings> = {
+ [K in keyof EndpointsSettings]: EndpointDefaults;
 };
 
 type RequestConfigUrlRequired = Omit<RequestConfig, 'url'> & { url: string };
 
+/**
+ * Configuration for API endpoints, where each key is an endpoint name or string, and the value is the request configuration.
+ *
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ */
 export type EndpointsConfig<EndpointsMethods> = Record<
  keyof EndpointsMethods | string,
  RequestConfigUrlRequired
 >;
 
-type EndpointsConfigPart<EndpointsCfg, EndpointsMethods extends object> = [
- EndpointsCfg,
+/**
+ * Part of the endpoints configuration, derived from `EndpointsSettings` based on the `EndpointsMethods`.
+ *
+ * This type handles defaulting to endpoints configuration when particular Endpoints Methods are not provided.
+ *
+ * @template EndpointsSettings - The configuration object for endpoints.
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ */
+type EndpointsConfigPart<EndpointsSettings, EndpointsMethods extends object> = [
+ EndpointsSettings,
 ] extends [never]
  ? unknown
- : DefaultEndpoints<Omit<EndpointsCfg, keyof EndpointsMethods>>;
+ : DefaultEndpoints<Omit<EndpointsSettings, keyof EndpointsMethods>>;
 
+/**
+ * Provides the methods available from the API handler, combining endpoint record types, endpoints configuration,
+ * and default methods.
+ *
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ * @template EndpointsSettings - The configuration object for endpoints.
+ */
 export type ApiHandlerMethods<
  EndpointsMethods extends object,
- EndpointsCfg,
-> = EndpointsRecord<EndpointsMethods> &
- EndpointsConfigPart<EndpointsCfg, EndpointsMethods> &
- ApiHandlerDefaultMethods<EndpointsMethods>;
+ EndpointsSettings,
+> = EndpointsRecord<EndpointsMethods> & // Provided interface
+ EndpointsConfigPart<EndpointsSettings, EndpointsMethods> & // Derived defaults from 'endpoints'
+ ApiHandlerDefaultMethods<EndpointsMethods>; // Returned API Handler methods
 
+/**
+ * Defines the default methods available within the API handler.
+ *
+ * This includes configuration, endpoint settings, request handler, instance retrieval, and a generic request method.
+ *
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ */
 export type ApiHandlerDefaultMethods<EndpointsMethods> = {
  config: ApiHandlerConfig<EndpointsMethods>;
  endpoints: EndpointsConfig<EndpointsMethods>;
@@ -141,6 +180,11 @@ export type ApiHandlerDefaultMethods<EndpointsMethods> = {
  ) => Promise<FetchResponse<ResponseData>>;
 };
 
+/**
+ * Configuration for the API handler, including API URL and endpoints.
+ *
+ * @template EndpointsMethods - The object containing endpoint method definitions.
+ */
 export interface ApiHandlerConfig<EndpointsMethods>
  extends RequestHandlerConfig {
  apiUrl: string;