@kubb/plugin-client 5.12.0 → 6.0.1

package/templates/sse.ts

@@ -1,86 +1,5 @@
-import type { DataShape, NativeRequest, NativeResponse, Options, RequestResult, SuccessOf } from './client.ts'
-import { isValidationEnabled, runValidator, type StandardSchemaValidator, type ValidateOption, type ValidationErrorHandler } from './standardSchema.ts'
+import type { EventStreamOptions, MediaType, MediaTypes, ServerSentEvent } from './client.ts'
 
-/**
- * One decoded Server-Sent Event. `data` is parsed as JSON when valid and kept as the raw string otherwise,
- * `event` is `message` when the server sent no `event` field, and `id` is the last event ID the stream has set.
- */
-export type ServerSentEvent<TData = unknown> = {
-  data: TData
-  event: string
-  id?: string
-  retry?: number
-}
-
-/** An event the document types by name: the member's own `event` and `data`, plus the `id` and `retry` any event may carry. */
-export type TypedEvent<TEvent> = TEvent & Pick<ServerSentEvent, 'id' | 'retry'>
-
-/** Per-call options of a streamed operation, passed next to its request params. */
-export type EventStreamOptions = {
-  /**
-   * The largest number of characters, line breaks included, one event may hold before the blank line that ends it.
-   * A larger event throws a `RangeError` and cancels the stream. Set `Infinity` to turn the limit off.
-   * @default 16777216
-   */
-  maxEventSize?: number
-  /**
-   * Ends the stream when an event's raw `data` equals this value, such as `[DONE]`.
-   */
-  terminator?: string
-  /**
-   * Maps each event before validation.
-   */
-  transform?: (event: ServerSentEvent) => ServerSentEvent
-}
-
-/** The options of a streamed operation: the call's `Options` with the per-call stream options, as `Options` is for a regular call. */
-export type StreamOptions<TData extends DataShape, ThrowOnError extends boolean = true> = Options<TData, ThrowOnError> & EventStreamOptions
-
-/**
- * The validation settings a call or its client may set.
- */
-type ValidationSettings = { validate?: ValidateOption; onValidationError?: ValidationErrorHandler }
-
-/**
- * What the client resolves a streamed call to: the body as a stream or a decoded value, its content type, and the native response.
- */
-export type EventStreamCall<TResponse> = { data: unknown; error?: unknown; status?: number; contentType?: string; request?: NativeRequest; response: TResponse }
-
-/** The payload wrapped in `ServerSentEvent`, or the item itself when the document types it as a whole event. */
-type StreamEvent<TData> = TData extends { event: string } ? TData : ServerSentEvent<TData>
-
-/** Parsed events with the fields a `RequestResult` carries. `TData` is the payload, or the typed event. Iterating the result reads `stream`. */
-export type EventStreamResult<TData = unknown, TResponse = NativeResponse> = AsyncIterable<StreamEvent<TData>> & {
-  stream: AsyncGenerator<StreamEvent<TData>>
-  /** The same events as `stream` on a 2xx response, so `.unwrap()` and `returnType: 'data'` return them. */
-  data: AsyncGenerator<StreamEvent<TData>> | undefined
-  status: number | undefined
-  /** The error body of a failed call with `throwOnError: false`, whose `stream` then yields nothing. */
-  error: unknown
-  contentType: string | undefined
-  request: NativeRequest | undefined
-  response: TResponse
-  /**
-   * The last event ID the server sent, to resume from with a `Last-Event-ID` header on a new call. Empty until the server sends `id`.
-   */
-  readonly lastEventId: string
-}
-
-type StreamParts<TData> = AsyncIterable<StreamEvent<TData>> & { stream: AsyncGenerator<StreamEvent<TData>>; readonly lastEventId: string }
-
-type WithEvents<TResult, TData> = TResult extends { error: undefined } ? Omit<TResult, 'data'> & { data: AsyncGenerator<StreamEvent<TData>> } : TResult
-
-/** A stream call's result, as `RequestResult` is a regular call's: `status` narrows `error`, and the events are its `data`. Branching on `ThrowOnError` lets a generated call cast to it. */
-export type StreamResult<TResponses, ThrowOnError extends boolean = true, TData = SuccessOf<TResponses>> = ThrowOnError extends true
-  ? WithEvents<RequestResult<TResponses, true>, TData> & StreamParts<TData>
-  : WithEvents<RequestResult<TResponses, false>, TData> & StreamParts<TData>
-
-/** What a stream operation returns with `returnType: 'data'`, as `UnwrappedResult` is for a regular call. */
-export type UnwrappedStreamResult<TResponses, ThrowOnError extends boolean = true, TData = SuccessOf<TResponses>> = ThrowOnError extends true
-  ? AsyncGenerator<StreamEvent<TData>>
-  : StreamResult<TResponses, false, TData>
-
-/** The last event ID, shared with the result so it can be read after the loop. */
 type Cursor = { lastEventId: string }
 
 async function* readBytes(stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array> {
@@ -101,7 +20,26 @@ async function* readBytes(stream: ReadableStream<Uint8Array> | AsyncIterable<Uin
   }
 }
 
-function parseData<TData>(raw: string): TData {
+async function* readLines(stream: EventStreamInput): AsyncGenerator<{ lines: Array<string>; rest: string }> {
+  const decoder = new TextDecoder()
+  let rest = ''
+  let endsWithCR = false
+  for await (const chunk of readBytes(stream)) {
+    const decoded = decoder.decode(chunk, { stream: true })
+    if (!decoded) continue
+    // A CRLF split across chunks already ended its line on the `\r`.
+    const text: string = endsWithCR && decoded.startsWith('\n') ? decoded.slice(1) : decoded
+    endsWithCR = text.endsWith('\r')
+
+    const lines = text.split(/\r\n|\r|\n/)
+    lines[0] = rest + lines[0]
+    rest = lines.pop() ?? ''
+    yield { lines, rest }
+  }
+}
+
+function parseData<TData>(raw: string, event: string, rawData?: boolean | Array<string>): TData {
+  if (rawData === true || (rawData && rawData.includes(event))) return raw as TData
   try {
     return JSON.parse(raw) as TData
   } catch {
@@ -109,27 +47,20 @@ function parseData<TData>(raw: string): TData {
   }
 }
 
-/**
- * Parses a `text/event-stream` body as the WHATWG event stream specification does: an event is dispatched at its blank line
- * when it holds `data`, `event` defaults to `message`, `id` carries across events until an empty `id` resets it, `retry` needs
- * all digits, and an unfinished event at the end is dropped. `data` is parsed as JSON when it is valid and kept as text
- * otherwise. Consume with `for await`, and break the loop to cancel the stream.
- */
 type EventStreamInput = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>
 
+/**
+ * Parses a `text/event-stream` body into events, as the WHATWG spec does. Break the loop to cancel the stream.
+ */
 export async function* parseEventStream<TData = unknown>(
-  input: EventStreamInput | (Pick<EventStreamOptions, 'maxEventSize' | 'terminator'> & { stream: EventStreamInput; cursor?: Cursor }),
+  input: EventStreamInput | (Pick<EventStreamOptions, 'maxEventSize' | 'terminator' | 'rawData'> & { stream: EventStreamInput; cursor?: Cursor | undefined }),
 ): AsyncGenerator<ServerSentEvent<TData>> {
-  // The stream alone is the form earlier releases took.
-  const { stream, maxEventSize = 16 * 1024 * 1024, terminator, cursor = { lastEventId: '' } } = isStreamBody(input) ? { stream: input } : input
-  const decoder = new TextDecoder()
+  const { stream, maxEventSize = 16 * 1024 * 1024, terminator, rawData, cursor = { lastEventId: '' } } = isStreamBody(input) ? { stream: input } : input
   const tooLarge = `Server-sent event exceeds maxEventSize of ${maxEventSize} characters`
   let type = ''
   let data: Array<string> = []
   let retry: number | undefined
   let size = 0
-  let line = ''
-  let endsWithCR = false
   let pendingId = cursor.lastEventId
 
   const readField = (part: string) => {
@@ -151,25 +82,16 @@ export async function* parseEventStream<TData = unknown>(
     }
   }
 
-  for await (const chunk of readBytes(stream)) {
-    const decoded = decoder.decode(chunk, { stream: true })
-    if (!decoded) continue
-    // A CRLF split across chunks already ended its line on the `\r`.
-    const text: string = endsWithCR && decoded.startsWith('\n') ? decoded.slice(1) : decoded
-    endsWithCR = text.endsWith('\r')
-
-    const parts = text.split(/\r\n|\r|\n/)
-    parts[0] = line + parts[0]
-    line = parts.pop() ?? ''
-    for (const part of parts) {
+  for await (const { lines, rest: line } of readLines(stream)) {
+    for (const part of lines) {
       if (!part) {
-        // The ID is committed at the blank line, so a drop inside an event does not report an ID past the last full event.
+        // Committed at the blank line, so a dropped stream never reports an ID past the last full event.
         cursor.lastEventId = pendingId
         if (data.length) {
           const raw = data.join('\n')
           if (raw === terminator) return
           yield {
-            data: parseData<TData>(raw),
+            data: parseData<TData>(raw, type || 'message', rawData),
             event: type || 'message',
             ...(cursor.lastEventId ? { id: cursor.lastEventId } : {}),
             ...(retry !== undefined ? { retry } : {}),
@@ -181,12 +103,10 @@ export async function* parseEventStream<TData = unknown>(
         size = 0
         continue
       }
-      // A comment line is dropped and does not count toward the event, but must fit the limit on its own.
       if (part.startsWith(':')) {
         if (part.length + 1 > maxEventSize) throw new RangeError(tooLarge)
         continue
       }
-      // A finished line counts one more character for its line break.
       if (size + part.length + 1 > maxEventSize) throw new RangeError(tooLarge)
       size += part.length + 1
       readField(part)
@@ -195,80 +115,69 @@ export async function* parseEventStream<TData = unknown>(
   }
 }
 
+/**
+ * Parses a JSON Lines body into one value per line. Break the loop to cancel the stream.
+ */
+export async function* parseJsonLines<TData = unknown>({
+  stream,
+  maxEventSize = 16 * 1024 * 1024,
+  terminator,
+}: Pick<EventStreamOptions, 'maxEventSize' | 'terminator'> & { stream: EventStreamInput }): AsyncGenerator<TData> {
+  const tooLarge = `JSON line exceeds maxEventSize of ${maxEventSize} characters`
+  async function* lines(): AsyncGenerator<string> {
+    let last = ''
+    for await (const chunk of readLines(stream)) {
+      yield* chunk.lines
+      last = chunk.rest
+      if (last.length > maxEventSize) throw new RangeError(tooLarge)
+    }
+    yield last
+  }
+
+  for await (const raw of lines()) {
+    if (raw.length + 1 > maxEventSize) throw new RangeError(tooLarge)
+    // shortcut: a json-seq record must fit on one line, so a pretty-printed record fails to parse; split on the separator to read one.
+    const line = raw.split('\u001e').join('').trim()
+    if (!line) continue
+    if (line === terminator) return
+    yield JSON.parse(line) as TData
+  }
+}
+
 function isStreamBody(data: unknown): data is ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> {
   return !!data && typeof data === 'object' && (Symbol.asyncIterator in data || 'getReader' in data)
 }
 
+async function* mapEvents(events: AsyncIterable<ServerSentEvent>, transform: (event: ServerSentEvent) => ServerSentEvent): AsyncGenerator<ServerSentEvent> {
+  for await (const event of events) yield transform(event)
+}
+
 /**
- * Reads a call as typed Server-Sent Events, transformed and validated one by one, until the terminator or the end of the
- * stream. A successful call whose body is not a stream, such as a decoded JSON answer, throws a `TypeError` with the body
- * as its `cause`. A dropped connection ends the loop with the transport's error; `lastEventId` on the result is the ID
- * to resume from.
+ * The `text/event-stream` handler. A whole body, such as an error, is read as text.
  */
-export async function toEventStream<TData = unknown, TResponse = NativeResponse>(
-  call: Promise<EventStreamCall<TResponse>>,
-  {
-    client,
-    config: options = {},
-    ...meta
-  }: {
-    /**
-     * The client the call went through, for the validation settings a call does not set itself.
-     */
-    client?: { getConfig: () => ValidationSettings }
-    config?: EventStreamOptions & ValidationSettings
-    /**
-     * `event` when the document types each event with its own `event` and `data`, or `data` when it types only the payload.
-     * @default 'data'
-     */
-    shape?: 'event' | 'data'
-    /**
-     * Validates each event (`shape: 'event'`) or its `data` (`shape: 'data'`), after `transform`.
-     */
-    validator?: StandardSchemaValidator
-  } = {},
-): Promise<EventStreamResult<TData, TResponse>> {
-  const defaults = client?.getConfig() ?? {}
-  const onValidationError = options.onValidationError ?? defaults.onValidationError
-  const validator = isValidationEnabled(options.validate ?? defaults.validate, 'response') ? meta.validator : undefined
-  const cursor: Cursor = { lastEventId: '' }
-  const { data: body, error, status, contentType, request, response } = await call
-  const ok = status === undefined || (status >= 200 && status < 300)
-  // A transport decodes a JSON answer, so a success that is not a stream would otherwise end as an empty stream.
-  // A 204 or empty answer has no body, `undefined` or `null`, and still ends as an empty stream.
-  if (ok && body != null && !isStreamBody(body)) {
-    // `cause` is assigned, since the constructor option needs the ES2022 library a generated client cannot assume.
-    throw Object.assign(new TypeError(`Expected a text/event-stream body, got ${contentType ?? 'a body without a content type'}`), { cause: body })
-  }
-
-  const validateEvent = async (event: ServerSentEvent): Promise<ServerSentEvent> => {
-    if (!validator) return event
-    const value = meta.shape === 'event' ? event : event.data
-    const validated = await runValidator({ validator, value, context: { direction: 'response', source: 'body' }, onValidationError })
-    // The schema may not declare `id` and `retry`, so the parsed value is merged over the event instead of replacing it.
-    return meta.shape === 'event' ? { ...event, ...(validated as object) } : { ...event, data: validated }
-  }
+export const eventStream: MediaType = {
+  decode: (response) => response.text(),
+  stream: (body, { config, cursor }) => {
+    const events = parseEventStream({ stream: body, maxEventSize: config.maxEventSize, terminator: config.terminator, rawData: config.rawData, cursor })
+    return config.transform ? mapEvents(events, config.transform) : events
+  },
+}
 
-  async function* events(): AsyncGenerator<StreamEvent<TData>> {
-    if (!isStreamBody(body)) return
-    // A consumer `break` or a failed event closes this loop, which cancels the reader.
-    for await (const event of parseEventStream({ stream: body, maxEventSize: options.maxEventSize, terminator: options.terminator, cursor })) {
-      yield (await validateEvent(options.transform ? options.transform(event) : event)) as StreamEvent<TData>
-    }
-  }
+/**
+ * The JSON Lines handler. A whole body, such as an error, is read as text.
+ */
+export const jsonLines: MediaType = {
+  decode: (response) => response.text(),
+  stream: (body, { config }) => parseJsonLines({ stream: body, maxEventSize: config.maxEventSize, terminator: config.terminator }),
+}
 
-  const stream = events()
-  return {
-    stream,
-    data: ok ? stream : undefined,
-    status,
-    error,
-    contentType,
-    request,
-    response,
-    get lastEventId() {
-      return cursor.lastEventId
-    },
-    [Symbol.asyncIterator]: () => stream,
-  }
+/**
+ * The Server-Sent Events and JSON Lines handlers, registered when the document streams.
+ */
+export const streamMediaTypes: MediaTypes = {
+  'text/event-stream': eventStream,
+  'application/jsonl': jsonLines,
+  'application/x-ndjson': jsonLines,
+  'application/json-seq': jsonLines,
+  'application/*+json-seq': jsonLines,
 }

package/templates/standardSchema.ts

@@ -1,6 +1,5 @@
 /**
- * A Standard Schema-compatible validator: a minimal duck-type covering Zod v3/v4, valibot, and
- * arktype schemas. Only the `~standard.validate` method is required at runtime.
+ * A Standard Schema validator, such as a Zod, Valibot, or ArkType schema.
  */
 export type StandardSchemaValidator<TOutput = unknown> = {
   readonly '~standard': {
@@ -8,42 +7,31 @@ export type StandardSchemaValidator<TOutput = unknown> = {
   }
 }
 
-/**
- * The two possible outcomes of a Standard Schema `validate` call. A successful result carries
- * `value`; a failed result carries `issues`.
- */
 export type StandardSchemaResult<TOutput> = { readonly value: TOutput; readonly issues?: undefined } | { readonly issues: ReadonlyArray<StandardSchemaIssue> }
 
-/**
- * One validation issue from a Standard Schema `validate` call.
- */
 export type StandardSchemaIssue = {
   readonly message?: string
-  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined
 }
 
 /**
- * Thrown by `validateStandardSchema` when validation fails. Carries the raw `issues` array from
- * the schema's `validate` result so callers receive a uniform error shape regardless of which
- * schema library is in use.
+ * Thrown when validation fails, with the schema's `issues`.
  */
 export class ParseError extends Error {
   readonly issues: ReadonlyArray<StandardSchemaIssue>
+  // Declared here and set below, since the `cause` constructor option needs the ES2022 library.
+  declare readonly cause?: unknown
 
-  constructor({ issues, message }: { issues: ReadonlyArray<StandardSchemaIssue>; message?: string }) {
+  constructor({ issues, message, cause }: { issues: ReadonlyArray<StandardSchemaIssue>; message?: string; cause?: unknown }) {
     super(message ?? 'Validation failed')
     this.name = 'ParseError'
     this.issues = issues
+    if (cause !== undefined) this.cause = cause
   }
 }
 
 /**
- * Validates `value` against a Standard Schema-compatible `schema`. Returns the parsed output on
- * success; throws `ParseError` with the schema's `issues` on failure. Handles both sync and async
- * `validate` implementations transparently.
- *
- * @example
- * const pet = await validateStandardSchema(PetSchema, rawData)
+ * Returns the parsed value, or throws a `ParseError` with the schema's `issues`.
  */
 export async function validateStandardSchema<TOutput>(schema: StandardSchemaValidator<TOutput>, value: unknown): Promise<TOutput> {
   const result = await schema['~standard'].validate(value)
@@ -54,13 +42,8 @@ export async function validateStandardSchema<TOutput>(schema: StandardSchemaVali
 }
 
 /**
- * Wraps an object schema so its keys match case-insensitively.
- * Keys the schema does not declare pass through untouched.
- * The declared keys are validated with `schema` under their declared names.
- * Every key, and every issue path, keeps the casing the caller used.
+ * Wraps an object schema so its keys match in any letter case. `entries` are the keys the schema declares.
  *
- * @param schema Standard Schema-compatible object schema.
- * @param entries The record of keys the passed object schema validates.
  * @example
  * ```ts
  * validator: { headers: toHeadersStandardSchema(putEventHeadersSchema, putEventHeadersSchema.shape) }
@@ -109,25 +92,24 @@ export function toHeadersStandardSchema(schema: StandardSchemaValidator, entries
 }
 
 /**
- * Identifies the value and request that failed validation in `onValidationError`.
+ * Which value and request failed validation.
  */
 export type ValidationErrorContext = {
   value: unknown
   direction: 'request' | 'response' | 'error'
-  source: 'body' | 'path' | 'query' | 'headers'
-  method?: string
-  url?: string
-  status?: number
+  source: 'body' | 'path' | 'query' | 'headers' | 'cookies'
+  method?: string | undefined
+  url?: string | undefined
+  status?: number | undefined
 }
 
 /**
- * Return `{ value }` to substitute a failed value, including `undefined`. Returning nothing rethrows the `ParseError`.
+ * Return `{ value }` to use instead of a failed value. Return nothing to rethrow the `ParseError`.
  */
 export type ValidationErrorHandler = (error: ParseError, context: ValidationErrorContext) => { value: unknown } | void | Promise<{ value: unknown } | void>
 
 /**
- * Turns generated validation on or off. `false` skips every validator, an object skips only the directions set to `false`:
- * `request` is the body, `params` are path, query, and header params, `response` and `error` are the response bodies.
+ * Turns generated validation on or off, for every direction or per direction.
  * @default true
  */
 export type ValidateOption = boolean | { request?: boolean; params?: boolean; response?: boolean; error?: boolean }
@@ -136,9 +118,6 @@ export function isValidationEnabled(validate: ValidateOption | undefined, direct
   return typeof validate === 'object' ? validate[direction] !== false : validate !== false
 }
 
-/**
- * Runs a validator when there is one, handing a `ParseError` to `onValidationError` first, which may substitute the value.
- */
 export async function runValidator<T>({
   validator,
   value,