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

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Drew Powers
+Copyright (c) 2026 Fedor Chishchin and openapi-typesafe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
 # openapi-typesafe-fetch
 
-This name is reserved for openapi-typesafe. This version contains no code.
+A type-safe `fetch` client for types generated by [`openapi-typesafe`](../openapi-typesafe). About 8 kB minified,
+one tiny dependency, works in browsers, Node.js, Bun and Deno, and with React, Vue, Svelte or plain JavaScript.
+
+A maintained, drop-in successor to `openapi-fetch` (see the [repository README](../../README.md)).
+
+> **Status: in development; not published to npm yet.**
+
+## Setup
+
+```sh
+npm i openapi-typesafe-fetch
+npm i -D openapi-typesafe typescript
+npx openapi-typesafe ./openapi.yaml -o ./src/api/schema.d.ts
+```
+
+## Usage
+
+```ts
+import createClient from "openapi-typesafe-fetch";
+import type { paths } from "./api/schema";
+
+const client = createClient<paths>({ baseUrl: "https://api.example.com/v1/" });
+
+const {
+  data, // present on a 2xx response
+  error, // present on a 4xx or 5xx response
+} = await client.GET("/posts/{post_id}", {
+  params: { path: { post_id: "123" } },
+});
+
+await client.PUT("/posts", {
+  body: { title: "My new post" },
+});
+```
+
+URLs, parameters, request bodies and responses are all checked against the schema, with no generics or type
+assertions in your code. `GET()`, `PUT()`, `POST()` and the other methods are thin wrappers around the native
+[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API); you can pass your own `fetch`.
+
+Also included: middleware (`client.use()` / `client.eject()`), custom query, path and body serializers, `parseAs`
+for non-JSON responses, and a path-based client (`createPathBasedClient`).
+
+## Migrating from openapi-fetch
+
+```diff
+- import createClient from "openapi-fetch";
++ import createClient from "openapi-typesafe-fetch";
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,620 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const PATH_PARAM_RE = /\{[^{}]+\}/g;
+const DOT_SEGMENT_RE = /(^|\/)\.\.?(\/|$)/;
+const JSON_MEDIA_TYPE_RE = /json/i;
+const FORM_MEDIA_TYPE = "application/x-www-form-urlencoded";
+const MULTIPART_MEDIA_TYPE_RE = /^multipart\/form-data(;|$)/i;
+const NESTED_FORM_VALUE_MESSAGE = "Nested form values need your own `bodySerializer()`.";
+const BOUNDARY_PARAMETER_RE = /;\s*boundary=/i;
+const supportsRequestInitExt = () => {
+  return typeof process === "object" && process.versions?.undici;
+};
+let requestIdCount = 0;
+function randomID() {
+  requestIdCount += 1;
+  return requestIdCount.toString(36);
+}
+function createClient(clientOptions) {
+  let {
+    baseUrl = "",
+    Request: CustomRequest = globalThis.Request,
+    fetch: baseFetch = globalThis.fetch,
+    querySerializer: globalQuerySerializer,
+    bodySerializer: globalBodySerializer,
+    pathSerializer: globalPathSerializer,
+    headers: baseHeaders,
+    requestInitExt = void 0,
+    ...baseOptions
+  } = { ...clientOptions };
+  requestInitExt = supportsRequestInitExt() ? requestInitExt : void 0;
+  baseUrl = removeTrailingSlash(baseUrl);
+  const globalMiddlewares = [];
+  async function coreFetch(schemaPath, fetchOptions) {
+    const {
+      baseUrl: localBaseUrl,
+      fetch = baseFetch,
+      Request = CustomRequest,
+      headers,
+      params = {},
+      parseAs = "json",
+      querySerializer: requestQuerySerializer,
+      bodySerializer = globalBodySerializer ?? defaultBodySerializer,
+      pathSerializer: requestPathSerializer,
+      body,
+      middleware: requestMiddlewares = [],
+      ...init
+    } = fetchOptions || {};
+    let finalBaseUrl = baseUrl;
+    if (localBaseUrl) {
+      finalBaseUrl = removeTrailingSlash(localBaseUrl) ?? baseUrl;
+    }
+    let querySerializer = typeof globalQuerySerializer === "function" ? globalQuerySerializer : createQuerySerializer(globalQuerySerializer);
+    if (requestQuerySerializer) {
+      querySerializer = typeof requestQuerySerializer === "function" ? requestQuerySerializer : createQuerySerializer({
+        ...typeof globalQuerySerializer === "object" ? globalQuerySerializer : {},
+        ...requestQuerySerializer
+      });
+    }
+    const pathSerializer = requestPathSerializer || globalPathSerializer || defaultPathSerializer;
+    const serializedBody = body === void 0 ? void 0 : bodySerializer(
+      body,
+      // Note: we declare mergeHeaders() both here and below because it’s a bit of a chicken-or-egg situation:
+      // bodySerializer() needs all headers so we aren’t dropping ones set by the user, however,
+      // the result of this ALSO sets the lowest-priority content-type header. So we re-merge below,
+      // setting the content-type at the very beginning to be overwritten.
+      // Lastly, based on the way headers work, it’s not a simple “present-or-not” check becauase null intentionally un-sets headers.
+      mergeHeaders(baseHeaders, headers, params.header)
+    );
+    const finalHeaders = mergeHeaders(
+      // with no body, we should not to set Content-Type
+      serializedBody === void 0 || // a raw body (FormData, Blob, ...) gets its Content-Type from the platform, or none
+      isRawBody(serializedBody) ? {} : {
+        "Content-Type": "application/json"
+      },
+      baseHeaders,
+      headers,
+      params.header
+    );
+    if (serializedBody instanceof FormData && !BOUNDARY_PARAMETER_RE.test(finalHeaders.get("Content-Type"))) {
+      finalHeaders.delete("Content-Type");
+    }
+    const finalMiddlewares = [...globalMiddlewares, ...requestMiddlewares];
+    const requestInit = {
+      redirect: "follow",
+      ...baseOptions,
+      ...init,
+      body: serializedBody,
+      headers: finalHeaders
+    };
+    let id;
+    let options;
+    let request = new Request(
+      createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer, pathSerializer }),
+      requestInit
+    );
+    let response;
+    for (const key in init) {
+      if (!(key in request)) {
+        request[key] = init[key];
+      }
+    }
+    if (finalMiddlewares.length) {
+      id = randomID();
+      options = Object.freeze({
+        baseUrl: finalBaseUrl,
+        fetch,
+        parseAs,
+        querySerializer,
+        bodySerializer,
+        pathSerializer
+      });
+      for (const m of finalMiddlewares) {
+        if (m && typeof m === "object" && typeof m.onRequest === "function") {
+          const result = await m.onRequest({
+            request,
+            schemaPath,
+            params,
+            options,
+            id
+          });
+          if (result) {
+            if (isRequest(result)) {
+              request = result;
+            } else if (isResponse(result)) {
+              response = result;
+              break;
+            } else {
+              throw new Error("onRequest: must return new Request() or Response() when modifying the request");
+            }
+          }
+        }
+      }
+    }
+    if (!response) {
+      try {
+        response = await fetch(request, requestInitExt);
+      } catch (error2) {
+        let errorAfterMiddleware = error2;
+        if (finalMiddlewares.length) {
+          for (let i = finalMiddlewares.length - 1; i >= 0; i--) {
+            const m = finalMiddlewares[i];
+            if (m && typeof m === "object" && typeof m.onError === "function") {
+              const result = await m.onError({
+                request,
+                error: errorAfterMiddleware,
+                schemaPath,
+                params,
+                options,
+                id
+              });
+              if (result) {
+                if (isResponse(result)) {
+                  errorAfterMiddleware = void 0;
+                  response = result;
+                  break;
+                }
+                if (result instanceof Error) {
+                  errorAfterMiddleware = result;
+                  continue;
+                }
+                throw new Error("onError: must return new Response() or instance of Error");
+              }
+            }
+          }
+        }
+        if (errorAfterMiddleware) {
+          throw errorAfterMiddleware;
+        }
+      }
+      if (finalMiddlewares.length) {
+        for (let i = finalMiddlewares.length - 1; i >= 0; i--) {
+          const m = finalMiddlewares[i];
+          if (m && typeof m === "object" && typeof m.onResponse === "function") {
+            const result = await m.onResponse({
+              request,
+              response,
+              schemaPath,
+              params,
+              options,
+              id
+            });
+            if (result) {
+              if (!isResponse(result)) {
+                throw new Error("onResponse: must return new Response() when modifying the response");
+              }
+              response = result;
+            }
+          }
+        }
+      }
+    }
+    const contentLength = response.headers.get("Content-Length");
+    if (response.status === 204 || request.method === "HEAD" || contentLength === "0" && !response.headers.get("Transfer-Encoding")?.includes("chunked")) {
+      return response.ok ? { data: void 0, response } : { error: void 0, response };
+    }
+    if (response.ok) {
+      const getResponseData = async () => {
+        if (parseAs === "stream") {
+          return response.body;
+        }
+        if (parseAs === "json" && !contentLength) {
+          const raw2 = await response.text();
+          return raw2 ? JSON.parse(raw2) : void 0;
+        }
+        return await response[parseAs]();
+      };
+      return { data: await getResponseData(), response };
+    }
+    const raw = await response.text();
+    if (!raw) {
+      return { error: void 0, response };
+    }
+    let error = raw;
+    try {
+      error = JSON.parse(raw);
+    } catch {
+    }
+    return { error, response };
+  }
+  return {
+    request(method, url, init) {
+      return coreFetch(url, { ...init, method: method.toUpperCase() });
+    },
+    /** Call a GET endpoint */
+    GET(url, init) {
+      return coreFetch(url, { ...init, method: "GET" });
+    },
+    /** Call a PUT endpoint */
+    PUT(url, init) {
+      return coreFetch(url, { ...init, method: "PUT" });
+    },
+    /** Call a POST endpoint */
+    POST(url, init) {
+      return coreFetch(url, { ...init, method: "POST" });
+    },
+    /** Call a DELETE endpoint */
+    DELETE(url, init) {
+      return coreFetch(url, { ...init, method: "DELETE" });
+    },
+    /** Call a OPTIONS endpoint */
+    OPTIONS(url, init) {
+      return coreFetch(url, { ...init, method: "OPTIONS" });
+    },
+    /** Call a HEAD endpoint */
+    HEAD(url, init) {
+      return coreFetch(url, { ...init, method: "HEAD" });
+    },
+    /** Call a PATCH endpoint */
+    PATCH(url, init) {
+      return coreFetch(url, { ...init, method: "PATCH" });
+    },
+    /** Call a TRACE endpoint */
+    TRACE(url, init) {
+      return coreFetch(url, { ...init, method: "TRACE" });
+    },
+    /** Call a QUERY endpoint (OpenAPI 3.2) */
+    QUERY(url, init) {
+      return coreFetch(url, { ...init, method: "QUERY" });
+    },
+    /** Register middleware */
+    use(...middleware) {
+      for (const m of middleware) {
+        if (!m) {
+          continue;
+        }
+        if (typeof m !== "object" || !("onRequest" in m || "onResponse" in m || "onError" in m)) {
+          throw new Error("Middleware must be an object with one of `onRequest()`, `onResponse()` or `onError()`");
+        }
+        globalMiddlewares.push(m);
+      }
+    },
+    /** Unregister middleware */
+    eject(...middleware) {
+      for (const m of middleware) {
+        const i = globalMiddlewares.indexOf(m);
+        if (i !== -1) {
+          globalMiddlewares.splice(i, 1);
+        }
+      }
+    }
+  };
+}
+class PathCallForwarder {
+  constructor(client, url) {
+    this.client = client;
+    this.url = url;
+  }
+  GET = (init) => {
+    return this.client.GET(this.url, init);
+  };
+  PUT = (init) => {
+    return this.client.PUT(this.url, init);
+  };
+  POST = (init) => {
+    return this.client.POST(this.url, init);
+  };
+  DELETE = (init) => {
+    return this.client.DELETE(this.url, init);
+  };
+  OPTIONS = (init) => {
+    return this.client.OPTIONS(this.url, init);
+  };
+  HEAD = (init) => {
+    return this.client.HEAD(this.url, init);
+  };
+  PATCH = (init) => {
+    return this.client.PATCH(this.url, init);
+  };
+  TRACE = (init) => {
+    return this.client.TRACE(this.url, init);
+  };
+  QUERY = (init) => {
+    return this.client.QUERY(this.url, init);
+  };
+}
+class PathClientProxyHandler {
+  constructor() {
+    this.client = null;
+  }
+  // Assume the property is an URL.
+  get(coreClient, url) {
+    const forwarder = new PathCallForwarder(coreClient, url);
+    this.client[url] = forwarder;
+    return forwarder;
+  }
+}
+function wrapAsPathBasedClient(coreClient) {
+  const handler = new PathClientProxyHandler();
+  const proxy = new Proxy(coreClient, handler);
+  function Client() {
+  }
+  Client.prototype = proxy;
+  const client = new Client();
+  handler.client = client;
+  return client;
+}
+function createPathBasedClient(clientOptions) {
+  return wrapAsPathBasedClient(createClient(clientOptions));
+}
+function isHeaders(value) {
+  return typeof value?.get === "function";
+}
+function isRequest(value) {
+  return typeof value?.method === "string" && typeof value.url === "string" && isHeaders(value.headers);
+}
+function isResponse(value) {
+  return typeof value?.status === "number" && isHeaders(value.headers);
+}
+const KEPT_NAME_ESCAPES = /%(?:5B|5D|24|3A|40|2C)/g;
+function encodeName(name) {
+  return encodeURIComponent(name).replace(KEPT_NAME_ESCAPES, decodeURIComponent);
+}
+function serializePrimitiveParam(name, value, options) {
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (typeof value === "object") {
+    throw new Error(
+      "Deeply-nested arrays/objects aren\u2019t supported. Provide your own `querySerializer()` to handle these."
+    );
+  }
+  return `${name}=${options?.allowReserved === true ? value : encodeURIComponent(value)}`;
+}
+function serializeObjectParam(name, value, options) {
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+  const values = [];
+  const joiner = {
+    simple: ",",
+    label: ".",
+    matrix: ";"
+  }[options.style] || "&";
+  if (options.style !== "deepObject" && options.explode === false) {
+    for (const k in value) {
+      values.push(encodeName(k), options.allowReserved === true ? value[k] : encodeURIComponent(value[k]));
+    }
+    const final2 = values.join(",");
+    switch (options.style) {
+      case "form": {
+        return `${name}=${final2}`;
+      }
+      case "label": {
+        return `.${final2}`;
+      }
+      case "matrix": {
+        return `;${name}=${final2}`;
+      }
+      default: {
+        return final2;
+      }
+    }
+  }
+  for (const k in value) {
+    const finalName = options.style === "deepObject" ? `${name}[${encodeName(k)}]` : encodeName(k);
+    values.push(serializePrimitiveParam(finalName, value[k], options));
+  }
+  const final = values.join(joiner);
+  return options.style === "label" || options.style === "matrix" ? `${joiner}${final}` : final;
+}
+function serializeArrayParam(name, value, options) {
+  if (!Array.isArray(value)) {
+    return "";
+  }
+  if (options.explode === false) {
+    const joiner2 = { form: ",", spaceDelimited: "%20", pipeDelimited: "|" }[options.style] || ",";
+    const final = (options.allowReserved === true ? value : value.map((v) => encodeURIComponent(v))).join(joiner2);
+    switch (options.style) {
+      case "simple": {
+        return final;
+      }
+      case "label": {
+        return `.${final}`;
+      }
+      case "matrix": {
+        return `;${name}=${final}`;
+      }
+      // case "spaceDelimited":
+      // case "pipeDelimited":
+      default: {
+        return `${name}=${final}`;
+      }
+    }
+  }
+  const joiner = { simple: ",", label: ".", matrix: ";" }[options.style] || "&";
+  const values = [];
+  for (const v of value) {
+    if (options.style === "simple" || options.style === "label") {
+      values.push(options.allowReserved === true ? v : encodeURIComponent(v));
+    } else {
+      values.push(serializePrimitiveParam(name, v, options));
+    }
+  }
+  return options.style === "label" || options.style === "matrix" ? `${joiner}${values.join(joiner)}` : values.join(joiner);
+}
+function createQuerySerializer(options) {
+  return function querySerializer(queryParams) {
+    const search = [];
+    if (queryParams && typeof queryParams === "object") {
+      for (const key in queryParams) {
+        const value = queryParams[key];
+        const name = encodeName(key);
+        if (value === void 0 || value === null) {
+          continue;
+        }
+        if (Array.isArray(value)) {
+          if (value.length === 0) {
+            continue;
+          }
+          search.push(
+            serializeArrayParam(name, value, {
+              style: "form",
+              explode: true,
+              ...options?.array,
+              allowReserved: options?.allowReserved || false
+            })
+          );
+          continue;
+        }
+        if (typeof value === "object") {
+          search.push(
+            serializeObjectParam(name, value, {
+              style: "deepObject",
+              explode: true,
+              ...options?.object,
+              allowReserved: options?.allowReserved || false
+            })
+          );
+          continue;
+        }
+        search.push(serializePrimitiveParam(name, value, options));
+      }
+    }
+    return search.join("&");
+  };
+}
+function defaultPathSerializer(pathname, pathParams) {
+  let nextURL = pathname;
+  for (const match of pathname.match(PATH_PARAM_RE) ?? []) {
+    let name = match.substring(1, match.length - 1);
+    let explode = false;
+    let style = "simple";
+    if (name.endsWith("*")) {
+      explode = true;
+      name = name.substring(0, name.length - 1);
+    }
+    if (name.startsWith(".")) {
+      style = "label";
+      name = name.substring(1);
+    } else if (name.startsWith(";")) {
+      style = "matrix";
+      name = name.substring(1);
+    }
+    if (!pathParams || pathParams[name] === void 0 || pathParams[name] === null) {
+      continue;
+    }
+    const value = pathParams[name];
+    if (Array.isArray(value)) {
+      nextURL = nextURL.replace(match, serializeArrayParam(name, value, { style, explode }));
+      continue;
+    }
+    if (typeof value === "object") {
+      nextURL = nextURL.replace(match, serializeObjectParam(name, value, { style, explode }));
+      continue;
+    }
+    if (style === "matrix") {
+      nextURL = nextURL.replace(match, `;${serializePrimitiveParam(name, value)}`);
+      continue;
+    }
+    nextURL = nextURL.replace(match, style === "label" ? `.${encodeURIComponent(value)}` : encodeURIComponent(value));
+  }
+  if (DOT_SEGMENT_RE.test(nextURL)) {
+    throw new Error(`Dot path segment in ${nextURL}`);
+  }
+  return nextURL;
+}
+function isRawBody(body) {
+  return body instanceof FormData || body instanceof Blob || body instanceof URLSearchParams || body instanceof ArrayBuffer || ArrayBuffer.isView(body);
+}
+function formBody(body) {
+  for (const value of Object.values(body)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      throw new Error(NESTED_FORM_VALUE_MESSAGE);
+    }
+  }
+  return new URLSearchParams(body).toString();
+}
+function multipartBody(body) {
+  const formData = new FormData();
+  for (const [name, value] of Object.entries(body)) {
+    for (const item of [value].flat()) {
+      if (item instanceof Blob) {
+        formData.append(name, item);
+      } else if (item && typeof item === "object") {
+        throw new Error(NESTED_FORM_VALUE_MESSAGE);
+      } else if (item != null) {
+        formData.append(name, String(item));
+      }
+    }
+  }
+  return formData;
+}
+function defaultBodySerializer(body, headers) {
+  if (isRawBody(body)) {
+    return body;
+  }
+  const contentType = headers ? (
+    // `typeof`, not `instanceof Function`: headers from another realm (iframe, `node:vm`) have a
+    // `get` that is not an instance of this realm's Function (upstream #2637).
+    typeof headers.get === "function" ? headers.get("Content-Type") ?? headers.get("content-type") : headers["Content-Type"] ?? headers["content-type"]
+  ) : void 0;
+  if (contentType === FORM_MEDIA_TYPE) {
+    return formBody(body);
+  }
+  if (body && typeof body === "object" && MULTIPART_MEDIA_TYPE_RE.test(contentType)) {
+    return multipartBody(body);
+  }
+  if (typeof body === "string" && contentType && !JSON_MEDIA_TYPE_RE.test(contentType)) {
+    return body;
+  }
+  return JSON.stringify(body);
+}
+function createFinalURL(pathname, options) {
+  let finalURL = `${options.baseUrl}${pathname}`;
+  if (options.params?.path) {
+    finalURL = options.pathSerializer(finalURL, options.params.path);
+  }
+  let search = options.querySerializer(options.params.query ?? {});
+  if (search.startsWith("?")) {
+    search = search.substring(1);
+  }
+  if (search) {
+    finalURL += `${finalURL.includes("?") ? "&" : "?"}${search}`;
+  }
+  return finalURL;
+}
+function mergeHeaders(...allHeaders) {
+  const finalHeaders = new Headers();
+  for (const h of allHeaders) {
+    if (!h || typeof h !== "object") {
+      continue;
+    }
+    const iterator = isHeaders(h) ? h.entries() : Object.entries(h);
+    for (const [k, v] of iterator) {
+      if (v === null) {
+        finalHeaders.delete(k);
+      } else if (Array.isArray(v)) {
+        for (const v2 of v) {
+          finalHeaders.append(k, v2);
+        }
+      } else if (v !== void 0) {
+        finalHeaders.set(k, v);
+      }
+    }
+  }
+  return finalHeaders;
+}
+function removeTrailingSlash(url) {
+  if (url.endsWith("/")) {
+    return url.substring(0, url.length - 1);
+  }
+  return url;
+}
+
+exports.createFinalURL = createFinalURL;
+exports.createPathBasedClient = createPathBasedClient;
+exports.createQuerySerializer = createQuerySerializer;
+exports.default = createClient;
+exports.defaultBodySerializer = defaultBodySerializer;
+exports.defaultPathSerializer = defaultPathSerializer;
+exports.mergeHeaders = mergeHeaders;
+exports.randomID = randomID;
+exports.removeTrailingSlash = removeTrailingSlash;
+exports.serializeArrayParam = serializeArrayParam;
+exports.serializeObjectParam = serializeObjectParam;
+exports.serializePrimitiveParam = serializePrimitiveParam;
+exports.wrapAsPathBasedClient = wrapAsPathBasedClient;
+//# sourceMappingURL=index.cjs.map