@kubb/plugin-client 5.12.0 → 6.0.0

package/templates/mediaTypes/formData.ts

@@ -0,0 +1,59 @@
+import { isEncodedBody } from '../mediaTypes.ts'
+import type { MediaType } from '../mediaTypes.ts'
+import { isJsonMediaType, jsonReplacer, notNullish, toValue } from '../serializers.ts'
+import type { BodyEncoding } from '../serializers.ts'
+
+function appendFormDataValue({
+  formData,
+  key,
+  value,
+  contentType,
+}: {
+  formData: FormData
+  key: string
+  value: unknown
+  contentType?: string | undefined
+}): void {
+  if (value === undefined || value === null) return
+  if (value instanceof Blob) {
+    formData.append(key, value)
+    return
+  }
+  // A JSON part sends a scalar as JSON too, so a string arrives quoted.
+  if ((typeof value === 'object' && !(value instanceof Date)) || isJsonMediaType(contentType)) {
+    const encoded = JSON.stringify(value, jsonReplacer)
+    // A part's media type can only be set by wrapping the value in a typed Blob.
+    formData.append(key, contentType ? new Blob([encoded], { type: contentType }) : encoded)
+    return
+  }
+  formData.append(key, toValue(value))
+}
+
+const formDelimiters: Partial<Record<string, string>> = { spaceDelimited: ' ', pipeDelimited: '|' }
+
+function toFormData(body: Record<string, unknown>, encoding: Record<string, BodyEncoding> | undefined): FormData {
+  const formData = new FormData()
+  for (const [key, value] of Object.entries(body)) {
+    const { contentType, style, explode } = encoding?.[key] ?? {}
+    // `explode: false`, the default for the delimited styles, sends an array of scalars as one part, its items joined by the style's delimiter.
+    if (
+      Array.isArray(value) &&
+      !(explode ?? (style !== 'spaceDelimited' && style !== 'pipeDelimited')) &&
+      value.every((item) => typeof item !== 'object' || item === null || item instanceof Date)
+    ) {
+      const delimiter = formDelimiters[style ?? 'form'] ?? ','
+      formData.append(key, value.filter(notNullish).map(toValue).join(delimiter))
+      continue
+    }
+    for (const item of Array.isArray(value) ? value : [value]) appendFormDataValue({ formData, key, value: item, contentType })
+  }
+  return formData
+}
+
+/**
+ * The `multipart/form-data` handler, which follows `config.styles.body`.
+ */
+export const multipartFormData: MediaType = {
+  encode: (body, { config }) => (isEncodedBody(body) ? body : toFormData(body as Record<string, unknown>, config.styles?.body)),
+  decode: (response) => response.formData(),
+}

package/templates/mediaTypes/urlencoded.ts

@@ -0,0 +1,33 @@
+import { isEncodedBody } from '../mediaTypes.ts'
+import type { MediaType } from '../mediaTypes.ts'
+import { isJsonMediaType, jsonReplacer, serializeDefaultQueryParam } from '../serializers.ts'
+import type { BodyEncoding } from '../serializers.ts'
+import { serializeStyledQueryParam } from '../serializers/queryStyles.ts'
+
+function serializeUrlencodedBody(body: Record<string, unknown>, encoding: Record<string, BodyEncoding>): string {
+  const parts: Array<string> = []
+  for (const [key, value] of Object.entries(body)) {
+    const propertyEncoding = encoding[key]
+    // OpenAPI ignores `contentType` once a style field is set.
+    const styled = propertyEncoding?.style !== undefined || propertyEncoding?.explode !== undefined || propertyEncoding?.allowReserved !== undefined
+    if (value !== undefined && value !== null && !styled && isJsonMediaType(propertyEncoding?.contentType)) {
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(JSON.stringify(value, jsonReplacer))}`)
+      continue
+    }
+    parts.push(...(propertyEncoding ? serializeStyledQueryParam({ key, value, options: propertyEncoding }) : serializeDefaultQueryParam(key, value)))
+  }
+  return parts.join('&')
+}
+
+/**
+ * The `application/x-www-form-urlencoded` handler, which follows `config.styles.body`.
+ */
+export const urlencoded: MediaType = {
+  encode: (body, { config }) => {
+    if (isEncodedBody(body)) return body
+    const encoding = config.styles?.body
+    const encoded = serializeUrlencodedBody(body as Record<string, unknown>, encoding ?? {})
+    return encoding ? encoded : new URLSearchParams(encoded)
+  },
+  decode: (response) => response.formData(),
+}

package/templates/mediaTypes.ts

@@ -0,0 +1,147 @@
+import type { EventStreamOptions, RequestConfig } from './core.ts'
+import { baseContentType, jsonReplacer } from './serializers.ts'
+import type { RequestBody } from './serializers.ts'
+import { ParseError } from './standardSchema.ts'
+
+/**
+ * What a media type handler gets next to the body.
+ */
+export type MediaTypeContext = {
+  contentType: string
+  /**
+   * The response status, or `undefined` while a request body is encoded.
+   */
+  status?: number | undefined
+  signal?: AbortSignal | undefined
+  config: Omit<RequestConfig, 'client' | 'transport'> & EventStreamOptions
+  /**
+   * Where a stream records the last event ID it read, for `StreamResult.lastEventId`.
+   */
+  cursor?: { lastEventId: string } | undefined
+}
+
+/**
+ * Encodes and decodes bodies of one media type. Every method is optional.
+ */
+export type MediaType = {
+  encode?: (body: unknown, context: MediaTypeContext) => RequestBody | undefined
+  decode?: (response: Response, context: MediaTypeContext) => unknown
+  /**
+   * Reads a 2xx body item by item. Each item is validated with `validator.response`.
+   */
+  stream?: (body: ReadableStream<Uint8Array>, context: MediaTypeContext) => AsyncIterable<unknown>
+}
+
+/**
+ * Handlers keyed by media type. A key may be a pattern such as `application/*+json` or `text/*`.
+ */
+export type MediaTypes = Record<string, MediaType>
+
+/**
+ * Picks the handler for a `Content-Type`: the exact type, then its `+suffix`, then `type/*`, then the catch-all. With `use`, a
+ * handler without that method is skipped.
+ */
+export function resolveMediaType({
+  mediaTypes,
+  contentType,
+  use,
+}: {
+  mediaTypes: MediaTypes
+  contentType: string | null | undefined
+  use?: keyof MediaType
+}): MediaType | undefined {
+  const base = baseContentType(contentType)
+  const [type, subtype = ''] = base?.split('/') ?? []
+  const suffix = subtype.includes('+') ? subtype.slice(subtype.lastIndexOf('+')) : undefined
+  const keys = base ? [base, suffix ? `${type}/*${suffix}` : undefined, `${type}/*`, '*/*'] : ['*/*']
+  for (const key of keys) {
+    const mediaType = key ? mediaTypes[key] : undefined
+    if (mediaType && (!use || mediaType[use])) return mediaType
+  }
+  return undefined
+}
+
+/**
+ * Whether a body is already encoded, so every built-in media type sends it as is.
+ */
+export function isEncodedBody(body: unknown): body is RequestBody {
+  return (
+    typeof body === 'string' ||
+    body instanceof Blob ||
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof ReadableStream
+  )
+}
+
+function encodeOrJson(body: unknown, { contentType }: MediaTypeContext): RequestBody {
+  if (isEncodedBody(body)) return body
+  // XML, YAML, and CSV are never JSON, so a value for one must not go out as JSON under its label.
+  const mediaType = baseContentType(contentType)
+  if (mediaType && /[/+](xml|yaml|x-yaml|csv)$/.test(mediaType)) {
+    throw new TypeError(`Cannot encode the body as ${mediaType}, register mediaTypes['${mediaType}'].encode or pass the encoded body as a string.`)
+  }
+  return JSON.stringify(body, jsonReplacer)
+}
+
+/**
+ * Parses JSON text, throwing a `ParseError` that names the content type when it is not valid JSON.
+ */
+export function parseJson(text: string, contentType: string | undefined): unknown {
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new ParseError({ message: `Invalid JSON in a ${baseContentType(contentType)} body`, issues: [{ message: String(error) }], cause: error })
+  }
+}
+
+const json: MediaType = {
+  // A string is JSON-encoded too, so it arrives as a JSON string.
+  encode: (body) => (isEncodedBody(body) && typeof body !== 'string' ? body : JSON.stringify(body, jsonReplacer)),
+  decode: async (response, { contentType }) => {
+    const text = await response.text()
+    return text ? parseJson(text, contentType) : undefined
+  },
+}
+
+const text: MediaType = {
+  encode: encodeOrJson,
+  decode: async (response) => (await response.text()) || undefined,
+}
+
+const binary: MediaType = {
+  encode: encodeOrJson,
+  decode: (response) => response.blob(),
+}
+
+const catchAll: MediaType = {
+  encode: encodeOrJson,
+  // A server may label a plain message such as `Pet deleted` with any type, so non-JSON stays text.
+  decode: async (response) => {
+    const body = await response.text()
+    if (!body) return undefined
+    try {
+      return JSON.parse(body)
+    } catch {
+      return body
+    }
+  },
+}
+
+/**
+ * The media types every client knows: JSON, text, binary, and a catch-all that sends JSON and reads JSON or text.
+ */
+export const defaultMediaTypes: MediaTypes = {
+  'application/json': json,
+  'application/*+json': json,
+  'text/json': json,
+  'text/*': text,
+  'application/octet-stream': binary,
+  'application/pdf': binary,
+  'image/*': binary,
+  'audio/*': binary,
+  'video/*': binary,
+  '*/*': catchAll,
+}

package/templates/serializers/cookies.ts

@@ -0,0 +1,58 @@
+import { isJsonMediaType, isRecord, jsonReplacer, notNullish, toValue } from '../serializers.ts'
+import type { CookieSerializer } from '../serializers.ts'
+
+// RFC 6265 cookie-octets, which the `cookie` style sends unescaped.
+const cookieOctets = /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*$/
+// RFC 6265 cookie-name, an RFC 7230 token: an `=` would move the name/value split.
+const cookieToken = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+function rawCookieValue(name: string, item: unknown): string {
+  const value = toValue(item)
+  // The message leaves the value out, since cookies often carry session tokens.
+  if (!cookieOctets.test(value)) throw new TypeError(`Cookie ${name} has characters the cookie style cannot send, escape it first.`)
+  return value
+}
+
+function rawCookieName(name: string, key: string): string {
+  if (!cookieToken.test(key)) throw new TypeError(`Cookie ${name} has a key the cookie style cannot send as a cookie name, escape it first.`)
+  return key
+}
+
+function serializeCookie({ name, value, explode, raw }: { name: string; value: unknown; explode: boolean; raw: boolean }): string {
+  const encode = (item: unknown) => (raw ? rawCookieValue(name, item) : encodeURIComponent(toValue(item)))
+  if (Array.isArray(value)) {
+    const items = value.filter(notNullish).map(encode)
+    return explode ? items.map((item) => `${name}=${item}`).join('; ') : `${name}=${items.join(',')}`
+  }
+  if (isRecord(value)) {
+    const entries = Object.entries(value).filter(([, item]) => notNullish(item))
+    // An exploded key becomes a cookie name, so the cookie style checks it as a token.
+    if (explode) return entries.map(([key, item]) => `${raw ? rawCookieName(name, key) : encodeURIComponent(key)}=${encode(item)}`).join('; ')
+    return `${name}=${entries
+      .flatMap(([key, item]) => [key, item])
+      .map(encode)
+      .join(',')}`
+  }
+  return `${name}=${encode(value)}`
+}
+
+/**
+ * Joins cookie parameters into a `Cookie` header value with the OpenAPI `form` style, or the `cookie` style when a parameter sets it.
+ */
+export const serializeCookies: CookieSerializer = (cookies, styles) => {
+  const parts: Array<string> = []
+  for (const [name, value] of Object.entries(cookies)) {
+    if (value === undefined || value === null) continue
+    const style = styles?.[name]
+    if (isJsonMediaType(style?.contentType)) {
+      parts.push(`${name}=${encodeURIComponent(JSON.stringify(value, jsonReplacer))}`)
+      continue
+    }
+    // OpenAPI 3.2 defaults `explode` to true for the `cookie` style.
+    const raw = style?.style === 'cookie'
+    const cookie = serializeCookie({ name, value, explode: style?.explode ?? raw, raw })
+    // An empty exploded array or object has no pairs, so it adds no `; ` segment.
+    if (cookie) parts.push(cookie)
+  }
+  return parts.join('; ')
+}

package/templates/serializers/headers.ts

@@ -0,0 +1,35 @@
+import { isJsonMediaType, isRecord, jsonReplacer, notNullish, toValue } from '../serializers.ts'
+import type { HeaderSerializer, HeaderValue } from '../serializers.ts'
+
+function serializeHeaderValue(value: unknown, explode: boolean): string {
+  if (Array.isArray(value)) return value.filter(notNullish).map(toValue).join(',')
+  if (!isRecord(value)) return toValue(value)
+  const entries = Object.entries(value).filter(([, item]) => notNullish(item))
+  if (explode) return entries.map(([key, item]) => `${key}=${toValue(item)}`).join(',')
+  return entries
+    .flatMap(([key, item]) => [key, item])
+    .map(toValue)
+    .join(',')
+}
+
+// Header values must be Latin-1, so non-ASCII characters become JSON escapes.
+function toAsciiJson(value: unknown): string {
+  return JSON.stringify(value, jsonReplacer).replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
+}
+
+/**
+ * Serializes array and object headers with the OpenAPI `simple` style.
+ */
+export const serializeHeaders: HeaderSerializer = (headers, styles) => {
+  // A `Headers` instance only holds strings, so there is nothing to style.
+  if (!headers || headers instanceof Headers) return headers
+  const entries = Array.isArray(headers) ? headers : Object.entries(headers)
+  return entries.map(([key, value]) => {
+    // Without an entry the parameter uses the OpenAPI default: `simple`, no explode.
+    const style = styles?.[key] ?? {}
+    if (value === undefined || value === null) return [key, value] as [string, HeaderValue]
+    if (isJsonMediaType(style.contentType)) return [key, toAsciiJson(value)] as [string, HeaderValue]
+    if (typeof value !== 'object') return [key, value] as [string, HeaderValue]
+    return [key, serializeHeaderValue(value, style.explode ?? false)] as [string, HeaderValue]
+  })
+}

package/templates/serializers/path.ts

@@ -0,0 +1,19 @@
+import { encodeComponent, isRecord } from '../serializers.ts'
+import type { PathSerializer } from '../serializers.ts'
+
+/**
+ * The path serializer for the `simple` style, which `serializeStyledPath` also uses.
+ */
+export const serializePath: PathSerializer = ({ name, value, options }) => {
+  if (value === undefined || value === null) return ''
+  if (options?.style && options.style !== 'simple') {
+    throw new TypeError(`Cannot send path parameter ${name} with the ${options.style} style, register serializer.path on the client.`)
+  }
+  if (Array.isArray(value)) return value.map(encodeComponent).join(',')
+  if (isRecord(value)) {
+    return Object.entries(value)
+      .map(([key, item]) => `${encodeComponent(key)}${options?.explode ? '=' : ','}${encodeComponent(item)}`)
+      .join(',')
+  }
+  return encodeComponent(value)
+}

package/templates/serializers/pathStyles.ts

@@ -0,0 +1,27 @@
+import { encodeComponent as encode, isRecord } from '../serializers.ts'
+import type { PathSerializer } from '../serializers.ts'
+import { serializePath } from './path.ts'
+
+/**
+ * The path serializer for the OpenAPI `label` and `matrix` styles. A `simple` parameter uses `serializePath`.
+ */
+export const serializeStyledPath: PathSerializer = ({ name, value, options }) => {
+  const style = options?.style ?? 'simple'
+  if (style === 'simple' || value === undefined || value === null) return serializePath({ name, value, options })
+  const explode = options?.explode ?? false
+  const label = style === 'label'
+  if (Array.isArray(value)) {
+    const items = value.map(encode)
+    if (label) return `.${items.join(explode ? '.' : ',')}`
+    return explode ? items.map((item) => `;${name}=${item}`).join('') : `;${name}=${items.join(',')}`
+  }
+  if (isRecord(value)) {
+    const members = Object.entries(value).map(([key, item]) => `${encode(key)}${explode ? '=' : ','}${encode(item)}`)
+    if (label) return `.${members.join(explode ? '.' : ',')}`
+    return explode ? members.map((member) => `;${member}`).join('') : `;${name}=${members.join(',')}`
+  }
+  const encoded = encode(value)
+  // RFC 6570 drops the `=` of an empty matrix value: `;color`.
+  if (label) return `.${encoded}`
+  return encoded ? `;${name}=${encoded}` : `;${name}`
+}

package/templates/serializers/query.ts

@@ -0,0 +1,21 @@
+import { encodeComponent, isRecord, notNullish, serializeDefaultQueryParam } from '../serializers.ts'
+import type { QuerySerializer } from '../serializers.ts'
+
+/**
+ * The query serializer for a spec without styled query parameters: arrays repeat their key, objects use `form` with explode.
+ */
+export const serializeQuery: QuerySerializer = (params, options) => {
+  const parts: Array<string> = []
+  for (const [key, value] of Object.entries(params)) {
+    if (options?.[key]) throw new TypeError(`Cannot send query parameter ${key} with a style, register serializer.query on the client.`)
+    // `URLSearchParams` writes a space as `+`, form encoding for bodies. A query follows RFC 6570: `%20`.
+    parts.push(
+      ...(isRecord(value)
+        ? Object.entries(value)
+            .filter(([, item]) => notNullish(item))
+            .map(([prop, item]) => `${encodeComponent(prop)}=${encodeComponent(item)}`)
+        : serializeDefaultQueryParam(key, value).map((part) => part.replaceAll('+', '%20'))),
+    )
+  }
+  return parts.join('&')
+}

package/templates/serializers/queryStyles.ts

@@ -0,0 +1,107 @@
+import { baseContentType, encodeComponent, isJsonMediaType, isRecord, jsonReplacer, notNullish, serializeDefaultQueryParam, toValue } from '../serializers.ts'
+import type { QueryParamStyle, QuerySerializer, QueryStyle } from '../serializers.ts'
+
+const queryDelimiters: Record<QueryStyle, string> = { form: ',', spaceDelimited: '%20', pipeDelimited: '%7C', deepObject: ',' }
+
+// `allowReserved` keeps reserved characters and percent-encoded triples, but `#`, `&`, and `+` would end the query or change a form value.
+function encodeReserved(value: unknown): string {
+  return encodeURI(toValue(value))
+    .replace(/%25([0-9A-Fa-f]{2})/g, '%$1')
+    .replace(/[#&+]/g, encodeURIComponent)
+}
+
+// OpenAPI defaults `explode` to false for the delimited styles. A deepObject array of scalars, which OpenAPI leaves undefined, keeps repeating its key.
+function defaultExplode(options: QueryParamStyle): boolean {
+  return options.style !== 'spaceDelimited' && options.style !== 'pipeDelimited'
+}
+
+function serializeDeepObject({ key, value, encode }: { key: string; value: unknown; encode: (value: unknown) => string }): Array<string> {
+  if (value === undefined || value === null) return []
+  if (Array.isArray(value)) return value.flatMap((item, index) => serializeDeepObject({ key: `${key}[${index}]`, value: item, encode }))
+  if (isRecord(value)) {
+    return Object.entries(value)
+      .filter(([, item]) => notNullish(item))
+      .flatMap(([prop, item]) => serializeDeepObject({ key: `${key}[${prop}]`, value: item, encode }))
+  }
+  return [`${encode(key)}=${encode(value)}`]
+}
+
+function serializeStyledQueryArray({
+  key,
+  value,
+  options,
+  encode,
+}: {
+  key: string
+  value: Array<unknown>
+  options: QueryParamStyle
+  encode: (value: unknown) => string
+}): Array<string> {
+  const items = value.filter(notNullish)
+  if (options.explode ?? defaultExplode(options)) return items.map((item) => `${encode(key)}=${encode(item)}`)
+  return [`${encode(key)}=${items.map(encode).join(queryDelimiters[options.style ?? 'form'])}`]
+}
+
+function serializeStyledQueryObject({
+  key,
+  value,
+  options,
+  encode,
+}: {
+  key: string
+  value: Record<string, unknown>
+  options: QueryParamStyle
+  encode: (value: unknown) => string
+}): Array<string> {
+  if ((options.style ?? 'form') === 'deepObject') return serializeDeepObject({ key, value, encode })
+  const entries = Object.entries(value).filter(([, item]) => notNullish(item))
+  if (options.explode ?? defaultExplode(options)) return entries.map(([prop, item]) => `${encode(prop)}=${encode(item)}`)
+  return [
+    `${encode(key)}=${entries
+      .flatMap(([prop, item]) => [prop, item])
+      .map(encode)
+      .join(queryDelimiters[options.style ?? 'form'])}`,
+  ]
+}
+
+/**
+ * One query parameter or form field with its OpenAPI style, as encoded pairs.
+ */
+export function serializeStyledQueryParam({ key, value, options }: { key: string; value: unknown; options: QueryParamStyle }): Array<string> {
+  if (value === undefined || value === null) return []
+  const encode = options.allowReserved ? encodeReserved : encodeComponent
+  // OpenAPI leaves arrays under deepObject undefined. Objects in one are indexed, `items[0][price]=p`, as nested arrays are.
+  if (Array.isArray(value) && options.style === 'deepObject' && value.some(isRecord)) return serializeDeepObject({ key, value, encode })
+  if (Array.isArray(value)) return serializeStyledQueryArray({ key, value, options, encode })
+  if (isRecord(value)) return serializeStyledQueryObject({ key, value, options, encode })
+  return [`${encode(key)}=${encode(value)}`]
+}
+
+/**
+ * The query serializer for a spec with styled query parameters: an OpenAPI style, `allowReserved` or a JSON content
+ * type. Without a style entry, arrays repeat their key and objects use `form` with explode.
+ */
+export const serializeStyledQuery: QuerySerializer = (params, options) => {
+  const parts: Array<string> = []
+  for (const [key, value] of Object.entries(params)) {
+    const paramOptions = options?.[key]
+    if (notNullish(value) && isJsonMediaType(paramOptions?.contentType)) {
+      const json = encodeComponent(JSON.stringify(value, jsonReplacer))
+      parts.push(paramOptions?.querystring ? json : `${encodeComponent(key)}=${json}`)
+      continue
+    }
+    // A string querystring is already in its media type, so it only needs percent-encoding, which form-urlencoded has.
+    if (paramOptions?.querystring && typeof value === 'string') {
+      parts.push(baseContentType(paramOptions.contentType) === 'application/x-www-form-urlencoded' ? value : encodeComponent(value))
+      continue
+    }
+    const styled = paramOptions ?? (isRecord(value) ? {} : undefined)
+    // `URLSearchParams` writes a space as `+`, form encoding for bodies. A query follows RFC 6570, as a styled one does: `%20`.
+    parts.push(
+      ...(styled
+        ? serializeStyledQueryParam({ key, value, options: styled })
+        : serializeDefaultQueryParam(key, value).map((part) => part.replaceAll('+', '%20'))),
+    )
+  }
+  return parts.join('&')
+}