jsonlines

Vovk.ts JSON Lines streaming

JSON Lines is Vovk's streaming model: server yields one JSON object per line, client consumes as async iterable. Works for chat completions, progress updates, long-running jobs, anything where data arrives over time.

Two authoring styles:

• Generator handlers — function* / async function* with yield. Common case.
• JSONLinesResponder — low-level manual send / close / throw. For orchestration, fan-in, or when stream shape doesn't fit a generator.

Scope

Covers:

• Generator handler syntax (function*, async function*, yield*).
• procedure({ iteration, validateEachIteration }) for per-item schema validation.
• JSONLinesResponder class — send, close, throw, properties.
• Client consumption — for await, using, asPromise, onIterate, abortController, abortSilently.
• progressive() for multi-shape progressive responses.
• VovkIteration + VovkYieldType type helpers.
• Accept: application/jsonl behavior.
• Real-world patterns (OpenAI chat streaming, polling, multi-promise fan-in).

Out of scope:

• Non-streaming procedures → procedure skill.
• Client generation / vovk-client setup → rpc skill.
• Generator basics (JS language) — assume reader knows them.

Generator handler

Simplest streaming handler: async function* yielding objects. Each yield → one JSON line on wire.

import { post, procedure, operation } from 'vovk';
import { z } from 'zod';

export default class StreamController {
  @operation({ summary: 'Stream messages' })
  @post('completions')
  static getJSONLines = procedure({
    iteration: z.object({ message: z.string() }),
  }).handle(async function* () {
    yield { message: 'Hello,' };
    yield { message: ' World' };
  });
}

iteration: validation schema for each yielded object. Same role output plays for non-streaming procedures.

Delegating to a service with yield*

Keep controller thin, let service do work:

static getJSONLines = procedure({
  iteration: z.object({ message: z.string() }),
}).handle(function* () {
  yield* StreamService.getJSONLines();
});