Skip to content
Ky logo

Ky

OfficialBetav0.1.0

@kubb/plugin-ky

kubb add plugin-ky

Server-sent events

Consume typed server-sent events and JSON Lines with the generated Ky client. Stop, resume, and handle streaming errors.

Kubb types the items from the OpenAPI document, and .kubb/sse.ts parses events as the WHATWG event stream specification does.

How Kubb detects a stream

Kubb generates a stream call when the success response declares only a stream content type:

The success response declaresEach item
text/event-stream, and the item schema declares event or dataTypedEvent<Item>, narrowed by event.event
text/event-stream, with any other item schemaServerSentEvent<Item>, with Item in data
application/jsonl, application/x-ndjson, application/json-seq, or a +json-seq typeItem, one per line

With text/event-stream next to another content type, Kubb generates a normal call instead. See JSON or an event stream.

The item schema is itemSchema in OpenAPI 3.2. In OpenAPI 3.0 and 3.1, schema describes one event or one line:

/chat:
  post:
    operationId: streamChat
    responses:
      '200':
        description: One event per oneOf member
        content:
          text/event-stream:
            itemSchema:
              type: object
              required: [event]
              properties:
                event: { type: string }
                id: { type: string }
                retry: { type: integer, minimum: 0 }
              oneOf:
                - type: object
                  required: [event, data]
                  properties:
                    event: { type: string, const: message_delta }
                    data: { $ref: '#/components/schemas/MessageDelta' }
                - type: object
                  required: [event]
                  properties:
                    event: { type: string, const: ping }
                    data: { type: string }

In OpenAPI 3.0 and 3.1, put the item schema on schema instead: the PetEvent reference for a payload, or the same oneOf with a discriminator on event for typed events.

The generated function

export function streamChat<ThrowOnError extends boolean = true>(
  options: StreamOptions<StreamChatOptions, ThrowOnError> = {},
): Unwrappable<StreamResult<StreamChatResponses, ThrowOnError, TypedEvent<SuccessOf<StreamChatResponses>>>>

A StreamResult has the fields of a RequestResult for the first connection, plus stream and lastEventId. The result iterates its items, which are also in stream and data. With returnType: 'data', the call resolves to the items.

Pass these stream options next to the request params:

OptionWhat it does
terminatorEnds the stream when an event's data, or a JSON line, equals this value, such as [DONE].
transformMaps each Server-Sent Event before validation, for example to camelCase its keys.
maxEventSizeThe most characters in one event or line. Default 16 * 1024 * 1024. Infinity turns it off.
signalAn AbortSignal that ends the request and the loop.

Consume items

import { streamChat } from './gen/clients/streamChat'

for await (const event of await streamChat({ body: { prompt: 'Hi' }, terminator: '[DONE]' })) {
  switch (event.event) {
    case 'message_delta':
      render(event.data.text) // MessageDelta
      break
    case 'ping':
      break
  }
}

An event the document does not declare reaches the default of your switch, so declare heartbeat and error events too. For event names, IDs, and JSON Lines limits, see Event names, IDs, and JSON Lines.

With validator: 'zod', the validator checks each item: the whole event for typed events, data for a payload, and each line for JSON Lines. To keep going past a failing item, return { value } from onValidationError:

const { stream } = await streamChat({ body, onValidationError: (error, { value }) => ({ value }) })

Stop, abort, and resume

  • break out of the loop to stop. The runtime cancels the reader and releases the connection.
  • Pass signal to stop from outside. The call or the loop rejects with the signal's reason.
  • A dropped connection ends the loop with the transport's error. The runtime does not reconnect, so the retry policy is up to your app.

To resume, send a new call with a Last-Event-ID header. lastEventId is the id of the last event the server completed. Declare Last-Event-ID as a header parameter, so the call accepts it in headers:

import { ResponseError } from './gen/.kubb/client'
import { ParseError } from './gen/.kubb/standardSchema'

async function* resumeChat(attempts = 3) {
  let lastEventId = ''

  for (let attempt = 1; ; attempt++) {
    try {
      const result = await streamChat({ body, headers: lastEventId ? { 'Last-Event-ID': lastEventId } : {} })
      for await (const event of result) {
        lastEventId = result.lastEventId
        yield event
      }
      return
    } catch (error) {
      if (attempt === attempts || ResponseError.is(error) || error instanceof ParseError) throw error
    }
  }
}

for await (const event of resumeChat()) render(event)

The loop retries a failed connect and a dropped connection. It rethrows the last failure, so a cut stream never looks complete. It also rethrows a ResponseError and a ParseError at once, because a retry cannot fix them and would skip the failing event. Rethrow your abort reason the same way when you pass signal. An error from render is thrown outside the generator, so it is never retried.

For cleared IDs and resuming with returnType: 'data', see Event IDs when you resume.

Handle errors

What happensWhere it fails
Non-2xx responseThe call throws a ResponseError.
Non-2xx response with throwOnError: falseThe call resolves with status and error. data is undefined, and the stream yields nothing.
2xx response whose body is not a stream, such as JSONThe call throws a TypeError with the body as its cause.
2xx response with an empty bodyNo error. The stream is empty.
Dropped connection or abortThe loop throws.
An item fails its schemaThe loop throws a ParseError, unless onValidationError returns { value }.
An event is larger than maxEventSizeThe loop throws a RangeError.
A JSON line is not valid JSONThe loop throws a SyntaxError.
const result = await streamChat({ body, throwOnError: false })

if (!result.data) console.error('stream rejected', result.status, result.error)
else for await (const event of result.data) render(event)

An error thrown from the loop skips client.interceptors.error. .unwrap() resolves to the items, as on a regular call.

JSON or an event stream

When the success response declares text/event-stream next to another type, such as application/json, Kubb generates a normal call that sends Accept: text/event-stream. Pass contentType: { response: 'application/json' } to ask for JSON. When the server streams, data is the raw ReadableStream<Uint8Array>, so read it with parseEventStream, or parseJsonLines({ stream }) for JSON Lines:

import { parseEventStream } from './gen/.kubb/client'

const result = await getRecentChanges({ signal })

if (result.contentType === 'text/event-stream') {
  for await (const { data } of parseEventStream(result.data)) render(data)
} else {
  render(result.data) // the JSON body
}

Stream with the client

client.stream(config) sends a stream request by hand. It runs the same interceptors and transport as client(config), and validates each item with validator.response. Type it with the responses record, ThrowOnError, and the item type:

import { client, type SuccessOf } from './gen/.kubb/client'
import type { StreamLogsResponses } from './gen/types/StreamLogs'

const result = await client.stream<StreamLogsResponses, true, SuccessOf<StreamLogsResponses>>({
  method: 'GET',
  url: '/logs',
  contentType: { response: 'application/jsonl' },
})

Without contentType.response or an Accept header, client.stream sends Accept: text/event-stream.

The item type defaults to ServerSentEvent around the success body. To stream another format, register a stream handler, as Add a media type shows.

Import the stream helpers and types from .kubb/client, and do not edit the .kubb/ files: Kubb rewrites them on each run.

Less common cases

JSON in a data string

When an event's data is a string with contentMediaType: application/json and a contentSchema, Kubb types and parses it as that schema. See How Kubb detects a stream for the item schemas.

Stream result types

When you type a variable that holds a stream result, the type depends on the response and on returnType:

SettingThe call returns
DefaultUnwrappable<StreamResult<…>>
The response declares headersUnwrappable<StreamResultWithHeaders<…>>, so headers.get suggests their names
returnType: 'data'Promise<UnwrappedStreamResult<…>>: the items, or the full result with throwOnError: false
returnType: 'data', and the response declares headersPromise<UnwrappedStreamResultWithHeaders<…>>

The generated function shows the default signature.

Stream options Kubb sets

When you call client.stream yourself, pass the options a generated stream call gets from the document:

OptionWhat it does
eventShapeWhether the validator checks the whole event ('event') or its data ('data').
rawDataKeeps data as text, for every event or for a list of event names. Kubb sets it when the document types data as a string. Otherwise data is parsed as JSON when it parses.

Event names, IDs, and JSON Lines

When the server leaves a field out of an event, or sends JSON Lines:

  • An event takes message as its name when the server sends none.
  • The id carries over to later events, and retry holds the server's reconnect hint.
  • A JSON Lines stream has no event IDs, and transform does not apply to it.
  • An application/json-seq record must fit on one line.

Event IDs when you resume

When you resume a stream:

  • The runtime does not reconnect, because many streams end on purpose and the retry policy belongs to your app.
  • lastEventId is empty until the server sends an id, and an empty id: clears it.
  • The resume loop copies lastEventId after each event, so after a clear it sends no Last-Event-ID. A connection that drops before its first event keeps the ID from the connection before.
  • With returnType: 'data', the items alone carry no lastEventId, so pass throwOnError: false to get the full result.

Interceptors on a stream call

When a response interceptor runs on a stream call, data in its DecodedResponse is the raw body stream. See Add interceptors.

Stream runtime files

When you look for a stream helper or type, import it from .kubb/client:

  • .kubb/sse.ts holds parseEventStream, parseJsonLines, and the stream media types, and .kubb/client.ts re-exports it.
  • The stream types, such as ServerSentEvent, TypedEvent, StreamOptions, and StreamResult, live in .kubb/core.ts.