openapi-typesafe-fetch 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/index.d.cts

@@ -15,28 +15,59 @@ interface ClientOptions extends Omit<RequestInit, "headers"> {
   /** global pathSerializer */
   pathSerializer?: PathSerializer;
   headers?: HeadersOptions;
-  /** RequestInit extension object to pass as 2nd argument to fetch when supported (defaults to undefined) */
+  /**
+   * RequestInit extension object to pass as 2nd argument to fetch when supported (defaults to
+   * undefined)
+   */
   requestInitExt?: Record<string, unknown>;
 }
 
+/**
+ * `ClientOptions` for a Fetch API implementation with its own types, such as the `undici` package
+ * (upstream #2562). TypeScript cannot relate its `Request` and `Response` to the DOM lib's
+ * (`duplex`, `RequestDestination`, `BodyInit` differ), so only what the client needs is checked: a
+ * `fetch` that returns a promise and a `Request` class that takes a URL. Pass the `fetch` and the
+ * `Request` of the same implementation; middleware and results still use the DOM types. The
+ * `createClient` overload with `ClientOptions` comes first, so an inline `fetch` gets a typed
+ * `Request` input.
+ */
+interface CustomFetchClientOptions extends Omit<ClientOptions, "fetch" | "Request"> {
+  /** `fetch` of another implementation (for example `fetch` from `undici`) */
+  fetch?: (input: never, init?: never) => PromiseLike<object>;
+  /** `Request` of the same implementation (for example `Request` from `undici`) */
+  Request?: new (
+    input: string,
+    init: never,
+  ) => object;
+}
+
 type HeadersOptions =
   | Required<RequestInit>["headers"]
   | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined>;
 
 type QuerySerializer<T> = (
-  query: T extends { parameters: any } ? NonNullable<T["parameters"]["query"]> : Record<string, unknown>,
+  // biome-ignore lint/suspicious/noExplicitAny: T["parameters"]["query"] needs an any constraint
+  query: T extends { parameters: any }
+    ? NonNullable<T["parameters"]["query"]>
+    : Record<string, unknown>,
 ) => string;
 
 /** @see https://swagger.io/docs/specification/serialization/#query */
 type QuerySerializerOptions = {
-  /** Set serialization for arrays. @see https://swagger.io/docs/specification/serialization/#query */
+  /**
+   * Set serialization for arrays.
+   * @see https://swagger.io/docs/specification/serialization/#query
+   */
   array?: {
     /** default: "form" */
     style: "form" | "spaceDelimited" | "pipeDelimited";
     /** default: true */
     explode: boolean;
   };
-  /** Set serialization for objects. @see https://swagger.io/docs/specification/serialization/#query */
+  /**
+   * Set serialization for objects.
+   * @see https://swagger.io/docs/specification/serialization/#query
+   */
   object?: {
     /** default: "deepObject" */
     style: "form" | "deepObject";
@@ -53,6 +84,8 @@ type QuerySerializerOptions = {
   allowReserved?: boolean;
 };
 
+// The result is the fetch body; openapi-fetch types it as `any` (ADR-030).
+// biome-ignore lint/suspicious/noExplicitAny: openapi-fetch's type, kept for parity
 type BodySerializer<T> = (body: OperationRequestBodyContent<T>) => any;
 
 type PathSerializer = (pathname: string, pathParams: Record<string, unknown>) => string;
@@ -78,25 +111,38 @@ interface DefaultParamsOption {
 }
 
 type ParamsOption<T> = T extends {
-  parameters: any;
+  parameters: unknown;
 }
   ? RequiredKeysOf<T["parameters"]> extends never
     ? { params?: T["parameters"] }
     : { params: T["parameters"] }
   : DefaultParamsOption;
 
-// Writable<T> strips $Read markers (readOnly properties excluded from request body)
+/** `true` for `any`: the operation of `createClient<any>()`, which says nothing about its body. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+// Writable<T> strips $Read markers (readOnly properties excluded from request body).
+// An `any` operation is checked first: a conditional type on `any` takes both branches, which
+// gave `{ body?: never } | { body: any }` and so a required init (upstream #2526).
 type RequestBodyOption<T> =
-  Writable<OperationRequestBodyContent<T>> extends never
-    ? { body?: never }
-    : IsOperationRequestBodyOptional<T> extends true
-      ? { body?: Writable<OperationRequestBodyContent<T>> }
-      : { body: Writable<OperationRequestBodyContent<T>> };
+  IsAny<T> extends true
+    ? // biome-ignore lint/suspicious/noExplicitAny: an any schema takes any body (upstream #2526)
+      { body?: any }
+    : Writable<OperationRequestBodyContent<T>> extends never
+      ? { body?: never }
+      : IsOperationRequestBodyOptional<T> extends true
+        ? { body?: Writable<OperationRequestBodyContent<T>> }
+        : { body: Writable<OperationRequestBodyContent<T>> };
 
 type FetchOptions<T> = RequestOptions<T> & Omit<RequestInit, "body" | "headers">;
 
 // Readable<T> strips $Write markers (writeOnly properties excluded from response)
-type FetchResponse<T extends Record<string | number, any>, Options, Media extends MediaType> =
+type FetchResponse<
+  // biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+  T extends Record<string | number, any>,
+  Options,
+  Media extends MediaType,
+> =
   | {
       data: ParseAsResponse<Readable<SuccessResponse<ResponseObjectMap<T>, Media>>, Options>;
       error?: never;
@@ -145,7 +191,7 @@ interface MiddlewareCallbackParams {
   readonly params: MiddlewareRequestParams;
   /** Unique ID for this request */
   readonly id: string;
-  /** createClient options (read-only) */
+  /** The options of this request after merging the client and request options (read-only) */
   readonly options: MergedOptions;
 }
 
@@ -176,29 +222,79 @@ type Middleware =
       onError: MiddlewareOnError;
     };
 
-/** This type helper makes the 2nd function param required if params/requestBody are required; otherwise, optional */
-type MaybeOptionalInit<Params, Location extends keyof Params> =
-  RequiredKeysOf<FetchOptions<FilterKeys<Params, Location>>> extends never
-    ? FetchOptions<FilterKeys<Params, Location>> | undefined
-    : FetchOptions<FilterKeys<Params, Location>>;
+/**
+ * This type helper makes the 2nd function param required if params/requestBody are required;
+ * otherwise, optional. `Location` is any key: with `Paths extends {}` a method is not known to be a
+ * key of `Paths[Path]` (upstream #2267). For a union of operations, the union of their inits: one
+ * deep type of every init gave TS2589 on hundreds of paths (upstream #1882).
+ */
+type MaybeOptionalInit<Params, Location extends PropertyKey> = OperationInits<
+  FilterKeys<Params, Location>
+>;
+
+/**
+ * The inits of the operations, and `undefined` only when none of them requires anything. One
+ * operation's init is `undefined` too when nothing in it is required, as in openapi-fetch. For a
+ * union of operations (a union of paths, or `Parameters<typeof client.request>`), `undefined`
+ * would make the whole init optional, although a call to one of the paths sends the init it gets,
+ * and a path parameter left out stays `{id}` in the URL.
+ * One conditional type, as openapi-fetch's, not a union with a conditional `undefined`: while the
+ * operation is generic, a union made `FetchResponse` distribute over its members, so the `data` of
+ * a generic wrapper's call no longer related to `FetchResponse<Paths[Path][Method], Init, Media>`.
+ */
+type OperationInits<Operation> =
+  RequiredKeysOf<OperationFetchOptions<Operation>> extends never
+    ? OperationFetchOptions<Operation> | undefined
+    : OperationFetchOptions<Operation>;
+
+/**
+ * Each operation's init. A distributive alias, not `extends infer Operation`: while the path is
+ * not known, TypeScript reads an `infer` type as `unknown`, so the init lost its type as the
+ * contextual type of an argument and a literal such as `"available"` widened to `string`
+ * (swr-openapi's `Exact<Init>` checks).
+ */
+type OperationFetchOptions<Operation> = Operation extends unknown ? FetchOptions<Operation> : never;
 
 // The final init param to accept.
 // - Determines if the param is optional or not.
 // - Performs arbitrary [key: string] addition.
-// Note: the addition MUST happen after all the inference happens (otherwise TS can’t infer if init is required or not).
+// Note: the addition MUST happen after all the inference happens (otherwise TS can’t infer if
+// init is required or not).
+// - The condition is openapi-fetch's. TypeScript relates two conditional types only when their
+//   `extends` types are the same and their check types relate, so a client type written against
+//   openapi-fetch's `InitParam` (a wrapper, a cast) accepted this client only with this condition.
+//   A union of inits is required through `MaybeOptionalInit`, which then leaves out `undefined`.
+// - The addition is a named alias: written out in both branches, TypeScript gave `never` for
+//   `Parameters` of the methods.
 type InitParam<Init> =
-  RequiredKeysOf<Init> extends never ? [(Init & { [key: string]: unknown })?] : [Init & { [key: string]: unknown }];
+  RequiredKeysOf<Init> extends never ? [WithAnyKeys<Init>?] : [WithAnyKeys<Init>];
 
-type ClientMethod<
-  Paths extends Record<string, Record<HttpMethod, {}>>,
-  Method extends HttpMethod,
-  Media extends MediaType,
-> = <Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>>(
+/** The init with any other key (`[key: string]: unknown`), added after inference. */
+type WithAnyKeys<Init> = Init & { [key: string]: unknown };
+
+/**
+ * @internal Exported for openapi-typesafe-react-query only; not part of the API (ADR-034).
+ * The operation of `Method` on `Path`. Not `Paths[Path][Method]`: `Paths` is only `{}`, because
+ * the generated `interface paths` has no index signature and failed a `Record<string, …>`
+ * constraint with TS2344 (upstream #2267), so TypeScript does not know `Method` is a key. For a
+ * union of paths or methods, the union of their operations; a method a path lacks (`put?: never`)
+ * adds none.
+ */
+type PathOperation<Paths, Path, Method> = Extract<
+  FilterKeys<Paths[Path & keyof Paths], Method>,
+  // biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+  Record<string | number, any>
+>;
+
+type ClientMethod<Paths extends {}, Method extends HttpMethod, Media extends MediaType> = <
+  Path extends PathsWithMethod<Paths, Method>,
+  Init extends MaybeOptionalInit<Paths[Path], Method>,
+>(
   url: Path,
   ...init: InitParam<Init>
-) => Promise<FetchResponse<Paths[Path][Method], Init, Media>>;
+) => Promise<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>;
 
-type ClientRequestMethod<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <
+type ClientRequestMethod<Paths extends {}, Media extends MediaType> = <
   Method extends HttpMethod,
   Path extends PathsWithMethod<Paths, Method>,
   Init extends MaybeOptionalInit<Paths[Path], Method>,
@@ -206,11 +302,21 @@ type ClientRequestMethod<Paths extends Record<string, Record<HttpMethod, {}>>, M
   method: Method,
   url: Path,
   ...init: InitParam<Init>
-) => Promise<FetchResponse<Paths[Path][Method], Init, Media>>;
+) => Promise<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>;
 
 // Only HTTP method keys become calls: `parameters` and `additionalOperations` are not methods.
-type ClientForPath<PathInfo extends Record<string | number, any>, Media extends MediaType> = {
-  [Method in keyof PathInfo as Method extends HttpMethod ? Uppercase<Method> : never]: <
+// They are left out by `Pick`, which keeps the `?` of a method, not by the key remapping: that is
+// openapi-fetch's, and TypeScript relates two generic mapped types only when their key remappings
+// are the same, so a path-based client type written like openapi-fetch's failed a cast (TS2352).
+type ClientForPath<
+  // biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+  PathInfo extends Record<string | number, any>,
+  Media extends MediaType,
+> = PathMethodCalls<Pick<PathInfo, HttpMethod & keyof PathInfo>, Media>;
+
+// biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+type PathMethodCalls<PathInfo extends Record<string | number, any>, Media extends MediaType> = {
+  [Method in keyof PathInfo as Uppercase<string & Method>]: <
     Init extends MaybeOptionalInit<PathInfo, Method>,
   >(
     ...init: InitParam<Init>
@@ -243,34 +349,56 @@ interface Client<Paths extends {}, Media extends MediaType = MediaType> {
   eject(...middleware: Middleware[]): void;
 }
 
-type ClientPathsWithMethod<CreatedClient extends Client<any, any>, Method extends HttpMethod> =
+type ClientPathsWithMethod<
+  // biome-ignore lint/suspicious/noExplicitAny: matches a client of any paths, as in openapi-fetch
+  CreatedClient extends Client<any, any>,
+  Method extends HttpMethod,
+> =
   CreatedClient extends Client<infer Paths, infer _Media> ? PathsWithMethod<Paths, Method> : never;
 
 type MethodResponse<
+  // biome-ignore lint/suspicious/noExplicitAny: matches a client of any paths, as in openapi-fetch
   CreatedClient extends Client<any, any>,
   Method extends HttpMethod,
   Path extends ClientPathsWithMethod<CreatedClient, Method>,
   Options = {},
 > =
-  CreatedClient extends Client<infer Paths extends { [key: string]: any }, infer Media extends MediaType>
+  CreatedClient extends Client<
+    // biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+    infer Paths extends { [key: string]: any },
+    infer Media extends MediaType
+  >
     ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>["data"]>
     : never;
 
 declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(
   clientOptions?: ClientOptions,
 ): Client<Paths, Media>;
+declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(
+  clientOptions?: CustomFetchClientOptions,
+): Client<Paths, Media>;
 
-type PathBasedClient<Paths extends Record<string | number, any>, Media extends MediaType = MediaType> = {
+type PathBasedClient<
+  // biome-ignore lint/suspicious/noExplicitAny: unknown rejects the generated interfaces
+  Paths extends Record<string | number, any>,
+  Media extends MediaType = MediaType,
+> = {
   [Path in keyof Paths]: ClientForPath<Paths[Path], Media>;
 };
 
-declare function wrapAsPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
-  client: Client<Paths, Media>,
-): PathBasedClient<Paths, Media>;
+declare function wrapAsPathBasedClient<
+  Paths extends {},
+  Media extends MediaType = MediaType,
+>(client: Client<Paths, Media>): PathBasedClient<Paths, Media>;
 
-declare function createPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
-  clientOptions?: ClientOptions,
-): PathBasedClient<Paths, Media>;
+declare function createPathBasedClient<
+  Paths extends {},
+  Media extends MediaType = MediaType,
+>(clientOptions?: ClientOptions): PathBasedClient<Paths, Media>;
+declare function createPathBasedClient<
+  Paths extends {},
+  Media extends MediaType = MediaType,
+>(clientOptions?: CustomFetchClientOptions): PathBasedClient<Paths, Media>;
 
 /** Serialize primitive params to string */
 declare function serializePrimitiveParam(
@@ -311,12 +439,85 @@ declare function createQuerySerializer<T = unknown>(
  * @type {import("./index.js").defaultPathSerializer}
  * @see https://swagger.io/docs/specification/serialization/#path
  */
-declare function defaultPathSerializer(pathname: string, pathParams: Record<string, unknown>): string;
+declare function defaultPathSerializer(
+  pathname: string,
+  pathParams: Record<string, unknown>,
+): string;
+
+/** Bodies that `fetch` sends as they are, so `defaultBodySerializer` returns them unchanged. */
+type RawRequestBody = FormData | Blob | URLSearchParams | ArrayBuffer | ArrayBufferView;
+
+/**
+ * The result of `defaultBodySerializer` for a body of type `Body`: the body itself when it is raw,
+ * `undefined` for `undefined` (`JSON.stringify` gives it back), `ObjectResult` for an object, and a
+ * string otherwise. `unknown` (and `any`) may be any of these.
+ */
+type SerializedBody<Body, ObjectResult> = unknown extends Body
+  ? RawRequestBody | string | FormData | undefined
+  : Body extends RawRequestBody
+    ? Body
+    : Body extends undefined
+      ? undefined
+      : Body extends object
+        ? ObjectResult
+        : string;
+
+/** The `Content-Type` values that make `defaultBodySerializer` turn an object into `FormData`. */
+type MultipartMediaType = "multipart/form-data" | `multipart/form-data;${string}`;
+
+/** `Headers` drops the spaces and tabs in front of a value before the media type is read. */
+type TrimmedStart<Text extends string> = Text extends ` ${infer Rest}` | `\t${infer Rest}`
+  ? TrimmedStart<Rest>
+  : Text;
+
+/**
+ * The `Content-Type` of headers written as a record, in any letter case of the name: `never` when
+ * the record has none, `unknown` when the type does not tell (`Headers`, pairs, a string record).
+ */
+type ContentTypeOf<GivenHeaders> = GivenHeaders extends undefined
+  ? never
+  : GivenHeaders extends readonly unknown[] | { get(name: string): unknown }
+    ? unknown
+    : string extends keyof GivenHeaders
+      ? unknown
+      : ContentTypeEntries<GivenHeaders>[keyof GivenHeaders];
+
+/** For each entry of a header record: its value when it is the `Content-Type`, else `never`. */
+type ContentTypeEntries<Record> = { [Name in keyof Record]: ContentTypeEntry<Name, Record[Name]> };
+
+/** The value of a header record entry when its name is `Content-Type` in any letter case. */
+type ContentTypeEntry<Name, Value> =
+  Lowercase<Name & string> extends "content-type" ? Value : never;
+
+/**
+ * What an object becomes with a `Content-Type` of type `ContentType`: `FormData` for a multipart
+ * one, a string for any other one or for none, and either when the type is not a literal.
+ */
+type ObjectBodyResult<ContentType> = [ContentType] extends [never]
+  ? string
+  : ContentType extends null | undefined
+    ? string
+    : ContentType extends string
+      ? string extends ContentType
+        ? string | FormData
+        : Lowercase<TrimmedStart<ContentType>> extends MultipartMediaType
+          ? FormData
+          : string
+      : string | FormData;
 
 /**
- * Serialize body object to string; with a form content type in `headers`, as URL-encoded form data.
+ * Serialize a request body. A raw body (`FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer`, a
+ * typed array) is returned as it is. With `headers`: a form `Content-Type` gives URL-encoded form
+ * data, a `multipart/form-data` one turns an object into `FormData`, and another non-JSON one keeps
+ * a string as it is. Anything else is JSON. Without `headers` an object can only become JSON.
+ * Headers written as a record literal tell the result type of an object body: `FormData` for a
+ * multipart `Content-Type`, `string` for another one or none. Other headers: `string | FormData`.
  */
-declare function defaultBodySerializer<T>(body: T, headers?: HeadersOptions): string;
+declare function defaultBodySerializer<T>(body: T): SerializedBody<T, string>;
+declare function defaultBodySerializer<
+  T,
+  const GivenHeaders extends HeadersOptions | undefined,
+>(body: T, headers: GivenHeaders): SerializedBody<T, ObjectBodyResult<ContentTypeOf<GivenHeaders>>>;
 
 /** Construct URL string from baseUrl and handle path and query params */
 declare function createFinalURL<O>(
@@ -338,7 +539,5 @@ declare function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]): He
 /** Remove trailing slash from url */
 declare function removeTrailingSlash(url: string): string;
 
-// @ts-ignore
-export = createClient;
-export { createFinalURL, createPathBasedClient, createQuerySerializer, defaultBodySerializer, defaultPathSerializer, mergeHeaders, removeTrailingSlash, serializeArrayParam, serializeObjectParam, serializePrimitiveParam, wrapAsPathBasedClient };
-export type { BodySerializer, Client, ClientForPath, ClientMethod, ClientOptions, ClientPathsWithMethod, ClientRequestMethod, DefaultParamsOption, FetchOptions, FetchResponse, HeadersOptions, MaybeOptionalInit, MergedOptions, MethodResponse, Middleware, MiddlewareCallbackParams, MiddlewareRequestParams, ParamsOption, ParseAs, ParseAsResponse, PathBasedClient, PathSerializer, QuerySerializer, QuerySerializerOptions, RequestBodyOption, RequestOptions };
+export { createFinalURL, createPathBasedClient, createQuerySerializer, createClient as default, defaultBodySerializer, defaultPathSerializer, mergeHeaders, removeTrailingSlash, serializeArrayParam, serializeObjectParam, serializePrimitiveParam, wrapAsPathBasedClient };
+export type { BodySerializer, Client, ClientForPath, ClientMethod, ClientOptions, ClientPathsWithMethod, ClientRequestMethod, CustomFetchClientOptions, DefaultParamsOption, FetchOptions, FetchResponse, HeadersOptions, MaybeOptionalInit, MergedOptions, MethodResponse, Middleware, MiddlewareCallbackParams, MiddlewareRequestParams, ParamsOption, ParseAs, ParseAsResponse, PathBasedClient, PathOperation, PathSerializer, QuerySerializer, QuerySerializerOptions, RequestBodyOption, RequestOptions };