@shipworthy/openapi-fetch 0.0.0-stage → 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,450 @@
+//#region src/helpers.d.ts
+type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+/** 2XX statuses */
+type OkStatus = 200 | 201 | 202 | 203 | 204 | 206 | 207 | "2XX";
+/** 4XX and 5XX statuses */
+type ErrorStatus = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | "5XX" | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 444 | 450 | 451 | 497 | 498 | 499 | "4XX" | "default";
+/** Get a union of OK Statuses */
+type OKStatusUnion<T> = FilterKeys<T, OkStatus>;
+/** Get first error status, in order */
+type FirstErrorStatus<T> = T extends {
+  500: any;
+} ? T[500] : T extends {
+  501: any;
+} ? T[501] : T extends {
+  502: any;
+} ? T[502] : T extends {
+  503: any;
+} ? T[503] : T extends {
+  504: any;
+} ? T[504] : T extends {
+  505: any;
+} ? T[505] : T extends {
+  506: any;
+} ? T[506] : T extends {
+  507: any;
+} ? T[507] : T extends {
+  508: any;
+} ? T[508] : T extends {
+  510: any;
+} ? T[510] : T extends {
+  511: any;
+} ? T[511] : T extends {
+  "5XX": any;
+} ? T["5XX"] : T extends {
+  400: any;
+} ? T[400] : T extends {
+  401: any;
+} ? T[401] : T extends {
+  402: any;
+} ? T[402] : T extends {
+  403: any;
+} ? T[403] : T extends {
+  404: any;
+} ? T[404] : T extends {
+  405: any;
+} ? T[405] : T extends {
+  406: any;
+} ? T[406] : T extends {
+  407: any;
+} ? T[407] : T extends {
+  408: any;
+} ? T[408] : T extends {
+  409: any;
+} ? T[409] : T extends {
+  410: any;
+} ? T[410] : T extends {
+  411: any;
+} ? T[411] : T extends {
+  412: any;
+} ? T[412] : T extends {
+  413: any;
+} ? T[413] : T extends {
+  414: any;
+} ? T[414] : T extends {
+  415: any;
+} ? T[415] : T extends {
+  416: any;
+} ? T[416] : T extends {
+  417: any;
+} ? T[417] : T extends {
+  418: any;
+} ? T[418] : T extends {
+  420: any;
+} ? T[420] : T extends {
+  421: any;
+} ? T[421] : T extends {
+  422: any;
+} ? T[422] : T extends {
+  423: any;
+} ? T[423] : T extends {
+  424: any;
+} ? T[424] : T extends {
+  425: any;
+} ? T[425] : T extends {
+  426: any;
+} ? T[426] : T extends {
+  427: any;
+} ? T[427] : T extends {
+  428: any;
+} ? T[428] : T extends {
+  429: any;
+} ? T[429] : T extends {
+  430: any;
+} ? T[430] : T extends {
+  431: any;
+} ? T[431] : T extends {
+  444: any;
+} ? T[444] : T extends {
+  450: any;
+} ? T[450] : T extends {
+  451: any;
+} ? T[451] : T extends {
+  497: any;
+} ? T[497] : T extends {
+  498: any;
+} ? T[498] : T extends {
+  499: any;
+} ? T[499] : T extends {
+  "4XX": any;
+} ? T["4XX"] : T extends {
+  default: any;
+} ? T["default"] : never;
+/** Given an OpenAPI **Paths Object**, find all paths that have the given method */
+type PathsWithMethod<Paths extends {}, PathnameMethod extends HttpMethod> = { [Pathname in keyof Paths]: Paths[Pathname] extends { [K in PathnameMethod]: any; } ? Pathname : never; }[keyof Paths];
+/**
+ * DO NOT USE!
+ * Only used only for OperationObject type inference
+ */
+interface OperationObject {
+  parameters: any;
+  requestBody: any;
+  responses: any;
+}
+/** Internal helper used in PathsWithMethod */
+type PathItemObject = { [M in HttpMethod]: OperationObject; } & {
+  parameters?: any;
+};
+/** Return `responses` for an Operation Object */
+type ResponseObjectMap<T> = T extends {
+  responses: any;
+} ? T["responses"] : unknown;
+/** `ResponseObjectMap` narrowed to the Response Object shape. TypeScript 5.0 requires the narrowing. */
+type ResponseMap<T> = Extract<ResponseObjectMap<T>, Record<string | number, any>>;
+/** Return `content` for a Response Object */
+type ResponseContent<T> = T extends {
+  content: any;
+} ? T["content"] : unknown;
+/** Return type of `requestBody` for an Operation Object */
+type OperationRequestBody<T> = "requestBody" extends keyof T ? T["requestBody"] : never;
+/** Internal helper to get object type with only the `requestBody` property */
+type PickRequestBody<T> = "requestBody" extends keyof T ? Pick<T, "requestBody"> : never;
+/** Resolve to `true` if request body is optional, else `false` */
+type IsOperationRequestBodyOptional<T> = RequiredKeysOf<PickRequestBody<T>> extends never ? true : false;
+/** Internal helper used in OperationRequestBodyContent */
+type OperationRequestBodyMediaContent<T> = IsOperationRequestBodyOptional<T> extends true ? ResponseContent<NonNullable<OperationRequestBody<T>>> | undefined : ResponseContent<OperationRequestBody<T>>;
+/** Return first `content` from a Request Object Mapping, allowing any media type */
+type OperationRequestBodyContent<T> = FilterKeys<OperationRequestBodyMediaContent<T>, MediaType> extends never ? FilterKeys<NonNullable<OperationRequestBodyMediaContent<T>>, MediaType> | undefined : FilterKeys<OperationRequestBodyMediaContent<T>, MediaType>;
+/** Return all 2XX responses from a Response Object Map */
+type SuccessResponse<T extends Record<string | number, any>, Media extends MediaType = MediaType> = GetResponseContent<T, Media, OkStatus>;
+type GetResponseContent<T extends Record<string | number, any>, Media extends MediaType = MediaType, ResponseCode extends keyof T = keyof T> = ResponseCode extends keyof T ? { [K in ResponseCode]: T[K]["content"] extends Record<string, any> ? FilterKeys<T[K]["content"], Media> extends never ? T[K]["content"] : FilterKeys<T[K]["content"], Media> : K extends keyof T ? T[K]["content"] : never; }[ResponseCode] : never;
+/**
+ * Return all 5XX and 4XX responses (in that order) from a Response Object Map
+ */
+type ErrorResponse<T extends Record<string | number, any>, Media extends MediaType = MediaType> = GetResponseContent<T, Media, ErrorStatus>;
+/** Return first JSON-like 2XX response from a path + HTTP method */
+type SuccessResponseJSON<PathMethod extends Record<string | number, any>> = SuccessResponse<ResponseMap<PathMethod>, `${string}/json`>;
+/** Return first JSON-like 5XX or 4XX response from a path + HTTP method */
+type ErrorResponseJSON<PathMethod extends Record<string | number, any>> = ErrorResponse<ResponseMap<PathMethod>, `${string}/json`>;
+/** Return JSON-like request body from a path + HTTP method */
+type RequestBodyJSON<PathMethod> = JSONLike<FilterKeys<OperationRequestBody<PathMethod>, "content">>;
+/** Find first match of multiple keys */
+type FilterKeys<Obj, Matchers> = Obj[keyof Obj & Matchers];
+/** Return any `[string]/[string]` media type (important because openapi-fetch allows any content response, not just JSON-like) */
+type MediaType = `${string}/${string}`;
+/** Return any media type containing "json" (works for "application/json", "application/vnd.api+json", "application/vnd.oai.openapi+json") */
+type JSONLike<T> = FilterKeys<T, `${string}/json`>;
+/** Helper to get the required keys of an object. If no keys are required, will be `undefined` with strictNullChecks enabled, else `never` */
+type RequiredKeysOfHelper<T> = { [K in keyof T]: {} extends Pick<T, K> ? never : K; }[keyof T];
+/** Get the required keys of an object, or `never` if no keys are required */
+type RequiredKeysOf<T> = RequiredKeysOfHelper<T> extends undefined ? never : RequiredKeysOfHelper<T>;
+/** Marker type for readOnly properties (excluded from request bodies) */
+type $Read<T> = {
+  readonly $read: T;
+};
+/** Marker type for writeOnly properties (excluded from response bodies) */
+type $Write<T> = {
+  readonly $write: T;
+};
+/**
+ * Resolve type for reading (responses): strips $Write properties, unwraps $Read
+ * - $Read<T> → T (readable), continues recursion
+ * - $Write<T> → never (excluded from response)
+ * - object → recursively resolve
+ */
+type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? { [K in keyof T as NonNullable<T[K]> extends $Write<any> ? never : K]: Readable<T[K]>; } : T;
+/**
+ * Resolve type for writing (requests): strips $Read properties, unwraps $Write
+ * - $Write<T> → T (writable), continues recursion
+ * - $Read<T> → never (excluded from request)
+ * - object → recursively resolve
+ */
+type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends object ? { [K in keyof T as NonNullable<T[K]> extends $Read<any> ? never : K]: Writable<T[K]>; } & { [K in keyof T as NonNullable<T[K]> extends $Read<any> ? K : never]?: never; } : T;
+//#endregion
+//#region src/types.d.ts
+/** 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>;
+}
+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>, headers?: Headers) => 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;
+type RequestBodyOption<T> = 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">;
+type FetchResponse<T extends Record<string | number, any>, Options, Media extends MediaType> = {
+  data: ParseAsResponse<Readable<SuccessResponse<ResponseMap<T>, Media>>, Options>;
+  error?: never;
+  response: Response;
+} | {
+  data?: never;
+  error: Readable<ErrorResponse<ResponseMap<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-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;
+};
+/** 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>>;
+type InitParam<Init> = RequiredKeysOf<Init> extends never ? [(Init & {
+  [key: string]: unknown;
+})?] : [Init & {
+  [key: string]: unknown;
+}];
+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>>(url: Path, ...init: InitParam<Init>) => Promise<FetchResponse<Paths[Path][Method], Init, Media>>;
+type ClientRequestMethod<Paths extends Record<string, Record<HttpMethod, {}>>, 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<Paths[Path][Method], Init, Media>>;
+type ClientForPath<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>) => 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>;
+  /** 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;
+type PathBasedClient<Paths extends Record<string | number, any>, Media extends MediaType = MediaType> = { [Path in keyof Paths]: ClientForPath<Paths[Path], Media>; };
+//#endregion
+//#region src/client.d.ts
+/**
+ * Create an openapi-fetch client.
+ */
+export default function createClient<Paths extends {}, Media extends MediaType = MediaType>(clientOptions?: ClientOptions): Client<Paths, Media>;
+//#endregion
+//#region src/path-client.d.ts
+/**
+ * Wrap openapi-fetch client to support a path based API.
+ */
+export declare function wrapAsPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(coreClient: Client<Paths, Media>): PathBasedClient<Paths, Media>;
+/**
+ * Convenience method to an openapi-fetch path based client.
+ * Strictly equivalent to `wrapAsPathBasedClient(createClient(...))`.
+ */
+export declare function createPathBasedClient<Paths extends {}, Media extends MediaType = MediaType>(clientOptions?: ClientOptions): PathBasedClient<Paths, Media>;
+//#endregion
+//#region src/headers.d.ts
+/** Merge headers a and b, with b taking priority */
+export declare function mergeHeaders(...allHeaders: (HeadersOptions | undefined)[]): Headers;
+//#endregion
+//#region src/serializers/param.d.ts
+type SerializePrimitiveOptions = {
+  allowReserved?: boolean;
+};
+/** Serialize primitive params to string */
+export declare function serializePrimitiveParam(name: string, value: string | number | boolean | null | undefined, options?: SerializePrimitiveOptions): string;
+type SerializeObjectOptions = {
+  style: "simple" | "label" | "matrix" | "form" | "deepObject";
+  explode: boolean;
+  allowReserved?: boolean;
+};
+/** Serialize object param to string */
+export declare function serializeObjectParam(name: string, value: Record<string, unknown>, options: SerializeObjectOptions): string;
+type SerializeArrayOptions = {
+  style: "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited";
+  explode: boolean;
+  allowReserved?: boolean;
+};
+/** Serialize array param (shallow only) */
+export declare function serializeArrayParam(name: string, value: unknown[], options: SerializeArrayOptions): string;
+//#endregion
+//#region src/serializers/query.d.ts
+/** Serialize query params to string */
+export declare function createQuerySerializer<T = unknown>(options?: QuerySerializerOptions): (queryParams: T) => string;
+//#endregion
+//#region src/serializers/path.d.ts
+/**
+ * Handle different OpenAPI 3.x serialization styles
+ * @see https://swagger.io/docs/specification/serialization/#path
+ */
+export declare function defaultPathSerializer(pathname: string, pathParams: Record<string, unknown>): string;
+//#endregion
+//#region src/serializers/body.d.ts
+/** Serialize body object to string */
+export declare function defaultBodySerializer<T>(body: T, headers?: Headers | Record<string, unknown>): string | FormData;
+//#endregion
+//#region src/serializers/url.d.ts
+/** Construct URL string from baseUrl and handle path and query params */
+export declare function createFinalURL<O>(pathname: string, options: {
+  baseUrl: string;
+  params: {
+    query?: Record<string, unknown>;
+    path?: Record<string, unknown>;
+  };
+  querySerializer: QuerySerializer<O>;
+  pathSerializer: PathSerializer;
+}): string;
+/** Remove trailing slash from url */
+export declare function removeTrailingSlash(url: string): string;
+//#endregion
+export { type $Read, type $Write, type BodySerializer, type Client, type ClientForPath, type ClientMethod, type ClientOptions, type ClientPathsWithMethod, type ClientRequestMethod, type DefaultParamsOption, type ErrorResponse, type ErrorResponseJSON, type ErrorStatus, type FetchOptions, type FetchResponse, type FilterKeys, type FirstErrorStatus, type GetResponseContent, type HeadersOptions, type HttpMethod, type IsOperationRequestBodyOptional, type JSONLike, type MaybeOptionalInit, type MediaType, type MergedOptions, type MethodResponse, type Middleware, type MiddlewareCallbackParams, type MiddlewareRequestParams, type OKStatusUnion, type OkStatus, type OperationObject, type OperationRequestBody, type OperationRequestBodyContent, type OperationRequestBodyMediaContent, type ParamsOption, type ParseAs, type ParseAsResponse, type PathBasedClient, type PathItemObject, type PathSerializer, type PathsWithMethod, type QuerySerializer, type QuerySerializerOptions, type Readable, type RequestBodyJSON, type RequestBodyOption, type RequestOptions, type RequiredKeysOf, type ResponseContent, type ResponseObjectMap, type SuccessResponse, type SuccessResponseJSON, type Writable, createClient };