openapi-typesafe-fetch 0.0.0 → 1.0.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+import { OperationRequestBodyContent, MediaType, HttpMethod, PathsWithMethod, RequiredKeysOf, Writable, IsOperationRequestBodyOptional, FilterKeys, Readable, SuccessResponse, ResponseObjectMap, ErrorResponse } from 'openapi-typesafe-helpers';
+
+/** Options for each client instance */
+interface ClientOptions extends Omit<RequestInit, "headers"> {
+  /** set the common root URL for all API requests */
+  baseUrl?: string;
+  /** custom fetch (defaults to globalThis.fetch) */
+  fetch?: (input: Request) => Promise<Response>;
+  /** custom Request (defaults to globalThis.Request) */
+  Request?: typeof Request;
+  /** global querySerializer */
+  querySerializer?: QuerySerializer<unknown> | QuerySerializerOptions;
+  /** global bodySerializer */
+  bodySerializer?: BodySerializer<unknown>;
+  /** global pathSerializer */
+  pathSerializer?: PathSerializer;
+  headers?: HeadersOptions;
+  /** 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 OtherFetchClientOptions 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>,
+) => string;
+
+/** @see https://swagger.io/docs/specification/serialization/#query */
+type QuerySerializerOptions = {
+  /** 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 */
+  object?: {
+    /** default: "deepObject" */
+    style: "form" | "deepObject";
+    /** default: true */
+    explode: boolean;
+  };
+  /**
+   * The `allowReserved` keyword specifies whether the reserved characters
+   * `:/?#[]@!$&'()*+,;=` in parameter values are allowed to be sent as they
+   * are, or should be percent-encoded. By default, allowReserved is `false`,
+   * and reserved characters are percent-encoded.
+   * @see https://swagger.io/docs/specification/serialization/#query
+   */
+  allowReserved?: boolean;
+};
+
+type BodySerializer<T> = (body: OperationRequestBodyContent<T>) => any;
+
+type PathSerializer = (pathname: string, pathParams: Record<string, unknown>) => string;
+
+type BodyType<T = unknown> = {
+  json: T;
+  text: Awaited<ReturnType<Response["text"]>>;
+  blob: Awaited<ReturnType<Response["blob"]>>;
+  arrayBuffer: Awaited<ReturnType<Response["arrayBuffer"]>>;
+  stream: Response["body"];
+};
+type ParseAs = keyof BodyType;
+type ParseAsResponse<T, Options> = Options extends {
+  parseAs: ParseAs;
+}
+  ? BodyType<T>[Options["parseAs"]]
+  : T;
+
+interface DefaultParamsOption {
+  params?: {
+    query?: Record<string, unknown>;
+  };
+}
+
+type ParamsOption<T> = T extends {
+  parameters: any;
+}
+  ? RequiredKeysOf<T["parameters"]> extends never
+    ? { params?: T["parameters"] }
+    : { params: T["parameters"] }
+  : DefaultParamsOption;
+
+/** `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> =
+  IsAny<T> extends true
+    ? { 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> =
+  | {
+      data: ParseAsResponse<Readable<SuccessResponse<ResponseObjectMap<T>, Media>>, Options>;
+      error?: never;
+      response: Response;
+    }
+  | {
+      data?: never;
+      error: Readable<ErrorResponse<ResponseObjectMap<T>, Media>>;
+      response: Response;
+    };
+
+type RequestOptions<T> = ParamsOption<T> &
+  RequestBodyOption<T> & {
+    baseUrl?: string;
+    querySerializer?: QuerySerializer<T> | QuerySerializerOptions;
+    bodySerializer?: BodySerializer<T>;
+    pathSerializer?: PathSerializer;
+    parseAs?: ParseAs;
+    fetch?: ClientOptions["fetch"];
+    headers?: HeadersOptions;
+    middleware?: Middleware[];
+  };
+
+type MergedOptions<T = unknown> = {
+  baseUrl: string;
+  parseAs: ParseAs;
+  querySerializer: QuerySerializer<T>;
+  bodySerializer: BodySerializer<T>;
+  pathSerializer: PathSerializer;
+  fetch: typeof globalThis.fetch;
+};
+
+interface MiddlewareRequestParams {
+  query?: Record<string, unknown>;
+  header?: Record<string, unknown>;
+  path?: Record<string, unknown>;
+  cookie?: Record<string, unknown>;
+}
+
+interface MiddlewareCallbackParams {
+  /** Current Request object */
+  request: Request;
+  /** The original OpenAPI schema path (including curly braces) */
+  readonly schemaPath: string;
+  /** OpenAPI parameters as provided from openapi-typesafe-fetch */
+  readonly params: MiddlewareRequestParams;
+  /** Unique ID for this request */
+  readonly id: string;
+  /** createClient options (read-only) */
+  readonly options: MergedOptions;
+}
+
+type MiddlewareOnRequest = (
+  options: MiddlewareCallbackParams,
+) => void | Request | Response | undefined | Promise<Request | Response | undefined | void>;
+type MiddlewareOnResponse = (
+  options: MiddlewareCallbackParams & { response: Response },
+) => void | Response | undefined | Promise<Response | undefined | void>;
+type MiddlewareOnError = (
+  options: MiddlewareCallbackParams & { error: unknown },
+) => void | Response | Error | Promise<void | Response | Error>;
+
+type Middleware =
+  | {
+      onRequest: MiddlewareOnRequest;
+      onResponse?: MiddlewareOnResponse;
+      onError?: MiddlewareOnError;
+    }
+  | {
+      onRequest?: MiddlewareOnRequest;
+      onResponse: MiddlewareOnResponse;
+      onError?: MiddlewareOnError;
+    }
+  | {
+      onRequest?: MiddlewareOnRequest;
+      onResponse?: MiddlewareOnResponse;
+      onError: MiddlewareOnError;
+    };
+
+/** The init of one operation, `undefined` too when nothing in it is required. */
+type OperationInit<Operation> =
+  RequiredKeysOf<FetchOptions<Operation>> extends never ? FetchOptions<Operation> | undefined : FetchOptions<Operation>;
+
+/**
+ * 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>>;
+
+/**
+ * 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 OperationInits<Operation> = Operation extends unknown ? OperationInit<Operation> : never;
+
+/** For each init of a union, whether it may be left out: nothing in it is required. */
+type InitOptionality<Init> = Init extends unknown ? (RequiredKeysOf<Init> extends never ? true : false) : never;
+
+/**
+ * `true` when the init may be left out: nothing in it is required. For a union of inits (a union
+ * of paths, or `Parameters<typeof client.request>`), only when each of them may be left out: a
+ * call to one of the paths sends the init it gets, and a path parameter left out stays `{id}` in
+ * the URL.
+ */
+type IsInitOptional<Init> = InitOptionality<Init> extends true ? true : false;
+
+// 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).
+// - Reads `InitOptionality` and names the addition: through `IsInitOptional`, or with the addition
+//   written out in both branches, TypeScript gave `never` for `Parameters` of the methods.
+type InitParam<Init> = InitOptionality<Init> extends true ? [WithAnyKeys<Init>?] : [WithAnyKeys<Init>];
+
+/** The init with any other key (`[key: string]: unknown`), added after inference. */
+type WithAnyKeys<Init> = Init & { [key: string]: unknown };
+
+/**
+ * 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>,
+  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<PathOperation<Paths, Path, Method>, Init, Media>>;
+
+type ClientRequestMethod<Paths extends {}, Media extends MediaType> = <
+  Method extends HttpMethod,
+  Path extends PathsWithMethod<Paths, Method>,
+  Init extends MaybeOptionalInit<Paths[Path], Method>,
+>(
+  method: Method,
+  url: Path,
+  ...init: InitParam<Init>
+) => 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]: <
+    Init extends MaybeOptionalInit<PathInfo, Method>,
+  >(
+    ...init: InitParam<Init>
+  ) => Promise<FetchResponse<PathInfo[Method], Init, Media>>;
+};
+
+interface Client<Paths extends {}, Media extends MediaType = MediaType> {
+  request: ClientRequestMethod<Paths, Media>;
+  /** Call a GET endpoint */
+  GET: ClientMethod<Paths, "get", Media>;
+  /** Call a PUT endpoint */
+  PUT: ClientMethod<Paths, "put", Media>;
+  /** Call a POST endpoint */
+  POST: ClientMethod<Paths, "post", Media>;
+  /** Call a DELETE endpoint */
+  DELETE: ClientMethod<Paths, "delete", Media>;
+  /** Call a OPTIONS endpoint */
+  OPTIONS: ClientMethod<Paths, "options", Media>;
+  /** Call a HEAD endpoint */
+  HEAD: ClientMethod<Paths, "head", Media>;
+  /** Call a PATCH endpoint */
+  PATCH: ClientMethod<Paths, "patch", Media>;
+  /** Call a TRACE endpoint */
+  TRACE: ClientMethod<Paths, "trace", Media>;
+  /** Call a QUERY endpoint (OpenAPI 3.2) */
+  QUERY: ClientMethod<Paths, "query", Media>;
+  /** Register middleware */
+  use(...middleware: Middleware[]): void;
+  /** Unregister middleware */
+  eject(...middleware: Middleware[]): void;
+}
+
+type ClientPathsWithMethod<CreatedClient extends Client<any, any>, Method extends HttpMethod> =
+  CreatedClient extends Client<infer Paths, infer _Media> ? PathsWithMethod<Paths, Method> : never;
+
+type MethodResponse<
+  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>
+    ? 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?: OtherFetchClientOptions,
+): Client<Paths, Media>;
+
+type PathBasedClient<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 createPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
+  clientOptions?: ClientOptions,
+): PathBasedClient<Paths, Media>;
+declare function createPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(
+  clientOptions?: OtherFetchClientOptions,
+): PathBasedClient<Paths, Media>;
+
+/** Serialize primitive params to string */
+declare function serializePrimitiveParam(
+  name: string,
+  value: string,
+  options?: { allowReserved?: boolean },
+): string;
+
+/** Serialize object param to string */
+declare function serializeObjectParam(
+  name: string,
+  value: Record<string, unknown>,
+  options: {
+    style: "simple" | "label" | "matrix" | "form" | "deepObject";
+    explode: boolean;
+    allowReserved?: boolean;
+  },
+): string;
+
+/** Serialize array param to string */
+declare function serializeArrayParam(
+  name: string,
+  value: unknown[],
+  options: {
+    style: "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited";
+    explode: boolean;
+    allowReserved?: boolean;
+  },
+): string;
+
+/** Serialize query params to string */
+declare function createQuerySerializer<T = unknown>(
+  options?: QuerySerializerOptions,
+): (queryParams: T) => string;
+
+/**
+ * Handle different OpenAPI 3.x serialization styles
+ * @type {import("./index.js").defaultPathSerializer}
+ * @see https://swagger.io/docs/specification/serialization/#path
+ */
+declare function defaultPathSerializer(pathname: string, pathParams: Record<string, unknown>): string;
+
+/**
+ * Serialize body object to string; with a form content type in `headers`, as URL-encoded form data.
+ */
+declare function defaultBodySerializer<T>(body: T, headers?: HeadersOptions): string;
+
+/** Construct URL string from baseUrl and handle path and query params */
+declare function createFinalURL<O>(
+  pathname: string,
+  options: {
+    baseUrl: string;
+    params: {
+      query?: Record<string, unknown>;
+      path?: Record<string, unknown>;
+    };
+    querySerializer: QuerySerializer<O>;
+    pathSerializer: PathSerializer;
+  },
+): string;
+
+/** Merge headers a and b, with b taking priority */
+declare function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]): Headers;
+
+/** Remove trailing slash from url */
+declare function removeTrailingSlash(url: string): string;
+
+export { createFinalURL, createPathBasedClient, createQuerySerializer, createClient as default, defaultBodySerializer, defaultPathSerializer, mergeHeaders, removeTrailingSlash, serializeArrayParam, serializeObjectParam, serializePrimitiveParam, wrapAsPathBasedClient };
+export type { BodySerializer, Client, ClientForPath, ClientMethod, ClientOptions, ClientPathsWithMethod, ClientRequestMethod, DefaultParamsOption, FetchOptions, FetchResponse, HeadersOptions, IsInitOptional, MaybeOptionalInit, MergedOptions, MethodResponse, Middleware, MiddlewareCallbackParams, MiddlewareRequestParams, OtherFetchClientOptions, ParamsOption, ParseAs, ParseAsResponse, PathBasedClient, PathOperation, PathSerializer, QuerySerializer, QuerySerializerOptions, RequestBodyOption, RequestOptions };