Public API reference

class SchemaStream<TSchema extends ZodObjectSchema>

constructor(schema: TSchema, options?: SchemaStreamOptions<TSchema>)

getSchemaStub<TStubSchema extends ZodObjectSchema>(schema: TStubSchema, defaultData?: SchemaStreamDefaultData<TStubSchema>): SchemaStreamChunk<TStubSchema>

parse(options?: SchemaStreamParseOptions): TransformStream<Uint8Array, Uint8Array>

iterate<TChunk extends SchemaStreamInputChunk>(source: SchemaStreamSource<TChunk>, options?: SchemaStreamParseOptions): AsyncGenerator<SchemaStreamChunk<TSchema>, void, void>

export type OnKeyCompleteCallback = (data: OnKeyCompleteCallbackParams) => void

export type OnKeyCompleteCallbackParams = {
  /** The value currently receiving streamed content, or an empty path after parsing finishes. */
  activePath: SchemaPath
  /** Unique value paths that have completed at least once, in completion order. */
  completedPaths: SchemaPath[]
}

export type OnValueCompleteCallback = (event: OnValueCompleteCallbackParams) => void

export type OnValueCompleteCallbackParams = {
  /**
   * Path of the value that just completed. Children complete before their containers, and an empty
   * path identifies the completed root document.
   */
  path: SchemaStreamValuePath
  /**
   * The syntactically complete JSON value at `path`. The parser does not clone container values for
   * this callback; consumers should treat objects and arrays as read-only because mutations can be
   * visible in later ancestor and root completion events.
   */
  value: unknown
}

export type SchemaInput<TSchema extends ZodSchema> = TSchema extends {
  _zod: z4.$ZodType["_zod"]
}
  ? z4.input<TSchema & z4.$ZodType>
  : TSchema extends Zod3Schema
    ? TSchema["_input"]
    : never

export type SchemaPath = (string | number | undefined)[]

export type SchemaStreamChunk<TSchema extends ZodObjectSchema> = SchemaStreamValue<
  SchemaInput<TSchema>
>

export type SchemaStreamDefaultData<TSchema extends ZodObjectSchema> = Partial<
  SchemaStreamChunk<TSchema>
>

export type SchemaStreamInputChunk = string | Uint8Array

export type SchemaStreamOptions<TSchema extends ZodObjectSchema> = {
  /** Field-level placeholders that take precedence over schema and primitive defaults. */
  defaultData?: SchemaStreamDefaultData<TSchema>
  /** Fallback placeholders for primitive schema nodes. Defaults to `null`. */
  typeDefaults?: TypeDefaults
  /** Called as values progress and once more with an empty active path after completion. */
  onKeyComplete?: OnKeyCompleteCallback
  /**
   * Called once for each completed JSON value, including containers and the root document. Unlike
   * `onKeyComplete`, this callback emits a path delta and does not copy cumulative history.
   */
  onValueComplete?: OnValueCompleteCallback
}

export type SchemaStreamParseOptions = {
  /** Buffers string bytes in fixed-size blocks instead of emitting every incremental string. */
  stringBufferSize?: number
  /** Converts unescaped newlines inside strings to `\n`; enabled by default. */
  handleUnescapedNewLines?: boolean
  /** Selects when cumulative schema-shaped snapshots are emitted. */
  snapshotPolicy?: SnapshotPolicy
}

export type SchemaStreamSource<TChunk extends SchemaStreamInputChunk = SchemaStreamInputChunk> =
  | ReadableStream<TChunk>
  | AsyncIterable<TChunk>

export type SchemaStreamValue<TValue> = unknown extends TValue
  ? unknown
  : TValue extends readonly (infer TItem)[]
    ? SchemaStreamValue<TItem>[]
    : TValue extends Record<PropertyKey, unknown>
      ? { [TKey in keyof TValue]?: SchemaStreamValue<TValue[TKey]> }
      : TValue | null

export type SchemaStreamValuePath = readonly (string | number)[]

export type SnapshotPolicy =
  | {
      /** Emits after every input chunk. */
      mode: "chunk"
    }
  | {
      /** Emits when an input chunk completes one or more primitive values. */
      mode: "value"
    }
  | {
      /** Emits after this many or more source bytes have arrived. */
      bytes: number
      mode: "bytes"
    }
  | {
      /** Emits one snapshot after the complete JSON document is parsed. */
      mode: "final"
    }

export type TypeDefaults = {
  string?: string | null | undefined
  number?: number | null | undefined
  boolean?: boolean | null | undefined
}

export type Zod3ObjectSchema = Zod3Schema & {
  readonly shape: Readonly<Record<string, Zod3Schema>>
}

export type Zod3Schema = {
  readonly _def: unknown
  readonly _input: unknown
  readonly _output: unknown
}

export type ZodObjectSchema = Zod3ObjectSchema | z4.$ZodObject

export type ZodSchema = Zod3Schema | z4.$ZodType