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

package/src/index.js

@@ -1,10 +1,18 @@
 // settings & const
 const PATH_PARAM_RE = /\{[^{}]+\}/g;
-/** A `.` or `..` path segment; URLs resolve it, so a parameter value could leave its path (#2483). */
+/**
+ * A `.` or `..` path segment; URLs resolve it, so a parameter value could leave its path (#2483).
+ */
 const DOT_SEGMENT_RE = /(^|\/)\.\.?(\/|$)/;
-/** Any JSON media type: `application/json`, `application/problem+json`, with or without parameters. */
+/** Where the path of a URL ends: its query or fragment, which have no segments. */
+const QUERY_OR_FRAGMENT_RE = /[?#]/;
+/**
+ * Any JSON media type: `application/json`, `application/problem+json`, with or without
+ * parameters.
+ */
 const JSON_MEDIA_TYPE_RE = /json/i;
-const FORM_MEDIA_TYPE = "application/x-www-form-urlencoded";
+/** `application/x-www-form-urlencoded`, with or without parameters such as `charset`. */
+const FORM_MEDIA_TYPE_RE = /^application\/x-www-form-urlencoded(;|$)/i;
 /** `multipart/form-data`, with or without parameters. */
 const MULTIPART_MEDIA_TYPE_RE = /^multipart\/form-data(;|$)/i;
 const NESTED_FORM_VALUE_MESSAGE = "Nested form values need your own `bodySerializer()`.";
@@ -39,6 +47,7 @@ export function randomID() {
  * Create an openapi-typesafe-fetch client.
  * @type {import("./index.js").default}
  */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
 export default function createClient(clientOptions) {
   let {
     baseUrl = "",
@@ -60,6 +69,7 @@ export default function createClient(clientOptions) {
    * @param {T} url
    * @param {import('./index.js').FetchOptions<T>} fetchOptions
    */
+  // biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
   async function coreFetch(schemaPath, fetchOptions) {
     const {
       baseUrl: localBaseUrl,
@@ -101,11 +111,12 @@ export default function createClient(clientOptions) {
         ? undefined
         : 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.
+            // 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 because null intentionally un-sets headers.
             mergeHeaders(baseHeaders, headers, params.header),
           );
     const finalHeaders = mergeHeaders(
@@ -124,7 +135,10 @@ export default function createClient(clientOptions) {
     // `fetch` sends a FormData as multipart with a boundary only it knows. A `Content-Type` without
     // that boundary, set by hand, replaced the platform's, and the server could not split the parts
     // (upstream #1214), so it goes and the platform sets its own (ADR-013, decision 10).
-    if (serializedBody instanceof FormData && !BOUNDARY_PARAMETER_RE.test(finalHeaders.get("Content-Type"))) {
+    if (
+      serializedBody instanceof FormData &&
+      !BOUNDARY_PARAMETER_RE.test(finalHeaders.get("Content-Type"))
+    ) {
       finalHeaders.delete("Content-Type");
     }
 
@@ -142,7 +156,12 @@ export default function createClient(clientOptions) {
     let id;
     let options;
     let request = new Request(
-      createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer, pathSerializer }),
+      createFinalURL(schemaPath, {
+        baseUrl: finalBaseUrl,
+        params,
+        querySerializer,
+        pathSerializer,
+      }),
       requestInit,
     );
     let response;
@@ -176,13 +195,15 @@ export default function createClient(clientOptions) {
             id,
           });
           if (result) {
-            if (result instanceof Request) {
+            if (isRequest(result)) {
               request = result;
-            } else if (result instanceof Response) {
+            } else if (isResponse(result)) {
               response = result;
               break;
             } else {
-              throw new Error("onRequest: must return new Request() or Response() when modifying the request");
+              throw new Error(
+                "onRequest: must return new Request() or Response() when modifying the request",
+              );
             }
           }
         }
@@ -211,7 +232,7 @@ export default function createClient(clientOptions) {
               });
               if (result) {
                 // if error is handled by returning a response, skip remaining middleware
-                if (result instanceof Response) {
+                if (isResponse(result)) {
                   errorAfterMiddleware = undefined;
                   response = result;
                   break;
@@ -249,8 +270,10 @@ export default function createClient(clientOptions) {
               id,
             });
             if (result) {
-              if (!(result instanceof Response)) {
-                throw new Error("onResponse: must return new Response() when modifying the response");
+              if (!isResponse(result)) {
+                throw new Error(
+                  "onResponse: must return new Response() when modifying the response",
+                );
               }
               response = result;
             }
@@ -278,7 +301,8 @@ export default function createClient(clientOptions) {
         }
 
         if (parseAs === "json" && !contentLength) {
-          // use text() when no content-length is provided to avoid errors parsing empty bodies (200 with no content)
+          // use text() when no content-length is provided to avoid errors parsing empty bodies
+          // (200 with no content)
           const raw = await response.text();
           return raw ? JSON.parse(raw) : undefined;
         }
@@ -350,7 +374,9 @@ export default function createClient(clientOptions) {
           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()`");
+          throw new Error(
+            "Middleware must be an object with one of `onRequest()`, `onResponse()` or `onError()`",
+          );
         }
         globalMiddlewares.push(m);
       }
@@ -451,6 +477,25 @@ export function createPathBasedClient(clientOptions) {
 
 // utils
 
+// Fetch API objects are recognized by the members the client uses, not by `instanceof`: that is
+// bound to one realm's class, and a Request from the `undici` package, another realm (an iframe,
+// an Electron host) or a custom `Request` option is not an instance of it (upstream #1847). The
+// same rule as for headers in `defaultBodySerializer` (upstream #2637).
+
+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);
+}
+
 // Parameter names and object keys can be data (an `additionalProperties` object). They are encoded
 // like values, except for characters common in names that do not split a URL (ADR-013, decision 9).
 const KEPT_NAME_ESCAPES = /%(?:5B|5D|24|3A|40|2C)/g;
@@ -479,6 +524,7 @@ export function serializePrimitiveParam(name, value, options) {
  * Serialize object param (shallow only)
  * @type {import("./index.js").serializeObjectParam}
  */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
 export function serializeObjectParam(name, value, options) {
   if (!value || typeof value !== "object") {
     return "";
@@ -494,9 +540,13 @@ export function serializeObjectParam(name, value, options) {
   // explode: false
   if (options.style !== "deepObject" && options.explode === false) {
     for (const k in value) {
-      values.push(encodeName(k), options.allowReserved === true ? value[k] : encodeURIComponent(value[k]));
+      values.push(
+        encodeName(k),
+        options.allowReserved === true ? value[k] : encodeURIComponent(value[k]),
+      );
     }
-    const final = values.join(","); // note: values are always joined by comma in explode: false (but joiner can prefix)
+    // note: values are always joined by comma in explode: false (but joiner can prefix)
+    const final = values.join(",");
     switch (options.style) {
       case "form": {
         return `${name}=${final}`;
@@ -526,6 +576,7 @@ export function serializeObjectParam(name, value, options) {
  * Serialize array param (shallow only)
  * @type {import("./index.js").serializeArrayParam}
  */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
 export function serializeArrayParam(name, value, options) {
   if (!Array.isArray(value)) {
     return "";
@@ -533,8 +584,11 @@ export function serializeArrayParam(name, value, options) {
 
   // explode: false
   if (options.explode === false) {
-    const joiner = { form: ",", spaceDelimited: "%20", pipeDelimited: "|" }[options.style] || ","; // note: for arrays, joiners vary wildly based on style + explode behavior
-    const final = (options.allowReserved === true ? value : value.map((v) => encodeURIComponent(v))).join(joiner);
+    // note: for arrays, joiners vary wildly based on style + explode behavior
+    const joiner = { form: ",", spaceDelimited: "%20", pipeDelimited: "|" }[options.style] || ",";
+    const final = (
+      options.allowReserved === true ? value : value.map((v) => encodeURIComponent(v))
+    ).join(joiner);
     switch (options.style) {
       case "simple": {
         return final;
@@ -619,6 +673,7 @@ export function createQuerySerializer(options) {
  * @type {import("./index.js").defaultPathSerializer}
  * @see https://swagger.io/docs/specification/serialization/#path
  */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
 export function defaultPathSerializer(pathname, pathParams) {
   let nextURL = pathname;
   for (const match of pathname.match(PATH_PARAM_RE) ?? []) {
@@ -640,24 +695,31 @@ export function defaultPathSerializer(pathname, pathParams) {
       continue;
     }
     const value = pathParams[name];
+    let serialized;
     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;
+      serialized = serializeArrayParam(name, value, { style, explode });
+    } else if (typeof value === "object") {
+      serialized = serializeObjectParam(name, value, { style, explode });
+    } else if (style === "matrix") {
+      serialized = `;${serializePrimitiveParam(name, value)}`;
+    } else {
+      serialized = style === "label" ? `.${encodeURIComponent(value)}` : encodeURIComponent(value);
     }
-    nextURL = nextURL.replace(match, style === "label" ? `.${encodeURIComponent(value)}` : encodeURIComponent(value));
+    // A function: a string replacement reads `$'`, `$&` and the like, which object keys keep.
+    nextURL = nextURL.replace(match, () => serialized);
   }
-  // `encodeURIComponent` keeps dots, so a value `..` would move the request up a path level (ADR-013).
-  if (DOT_SEGMENT_RE.test(nextURL)) {
+  const path = nextURL.split(QUERY_OR_FRAGMENT_RE, 1)[0];
+  // `encodeURIComponent` keeps dots, so a value `..` would move the request up a path level
+  // (ADR-013).
+  // Only the path is checked: before a query (`/a/{id}?v=2`), `$` did not match after `..`.
+  if (DOT_SEGMENT_RE.test(path)) {
     throw new Error(`Dot path segment in ${nextURL}`);
   }
+  // `//host/…` is a protocol-relative URL: with a relative baseUrl a browser sends it to that
+  // host.
+  if (path.startsWith("//")) {
+    throw new Error(`Empty first path segment in ${nextURL}`);
+  }
   return nextURL;
 }
 
@@ -677,15 +739,24 @@ function isRawBody(body) {
 
 /**
  * A form body. A nested object has no standard form encoding (servers read `a[b]`, `a.b` or JSON),
- * and `URLSearchParams` wrote it as `[object Object]` (ADR-013, decision 7).
+ * and `URLSearchParams` wrote it as `[object Object]` (ADR-013, decision 7). `null` and `undefined`
+ * fields are left out, as in a multipart body; `URLSearchParams` sent them as the text "null" and
+ * "undefined" (ADR-030). A string or a list of pairs is form data already.
  */
 function formBody(body) {
-  for (const value of Object.values(body)) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return new URLSearchParams(body).toString();
+  }
+  const form = new URLSearchParams();
+  for (const [name, value] of Object.entries(body)) {
     if (value && typeof value === "object" && !Array.isArray(value)) {
       throw new Error(NESTED_FORM_VALUE_MESSAGE);
     }
+    if (value != null) {
+      form.append(name, value);
+    }
   }
-  return new URLSearchParams(body).toString();
+  return form.toString();
 }
 
 /**
@@ -718,14 +789,12 @@ export 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"])
-    : undefined;
-  if (contentType === FORM_MEDIA_TYPE) {
+  // Headers with a `get` are read directly: headers from another realm (iframe, `node:vm`) may have
+  // nothing else (upstream #2637). A record or a list of pairs is read through `Headers`, which
+  // matches the name in any letter case.
+  const contentType =
+    headers && (isHeaders(headers) ? headers : mergeHeaders(headers)).get("Content-Type");
+  if (FORM_MEDIA_TYPE_RE.test(contentType)) {
     return formBody(body);
   }
   if (body && typeof body === "object" && MULTIPART_MEDIA_TYPE_RE.test(contentType)) {
@@ -769,7 +838,12 @@ export function mergeHeaders(...allHeaders) {
     if (!h || typeof h !== "object") {
       continue;
     }
-    const iterator = h instanceof Headers ? h.entries() : Object.entries(h);
+    // A list of pairs (`[["x-t", "1"]]`) is a `HeadersInit` too; `Headers` joins a repeated name.
+    const iterator = isHeaders(h)
+      ? h.entries()
+      : Symbol.iterator in h
+        ? new Headers(h).entries()
+        : Object.entries(h);
     for (const [k, v] of iterator) {
       if (v === null) {
         finalHeaders.delete(k);