BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

namespace

JSONL

namespace JSONL

JSONL (JSON Lines) related APIs.

Each line in the input is expected to be a valid JSON value separated by newlines.

  • interface ParseChunkResult

    The result of Bun.JSONL.parseChunk.

    • done: boolean

      true if all input was consumed successfully. false if the input ends with an incomplete value or a parse error occurred.

    • error: null | SyntaxError

      A SyntaxError if a parse error occurred, otherwise null. Values parsed before the error are still available in values.

    • read: number

      How far into the input was consumed. When the input is a string, this is a character offset. When the input is a TypedArray, this is a byte offset. Use input.slice(read) or input.subarray(read) to get the unconsumed remainder.

    • values: unknown[]

      The successfully parsed JSON values.

  • function parse(
    input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBuffer>
    ): unknown[];

    Parse a JSONL (JSON Lines) string into an array of JavaScript values.

    If a parse error occurs and no values were successfully parsed, throws a SyntaxError. If values were parsed before the error, returns the successfully parsed values without throwing.

    Incomplete trailing values (e.g. from a partial chunk) are silently ignored and not included in the result.

    When a TypedArray is passed, the bytes are parsed directly without copying if the content is ASCII.

    @param input

    The JSONL string or typed array to parse

    @returns

    An array of parsed values

    const items = Bun.JSONL.parse('{"a":1}\n{"b":2}\n');
// [{ a: 1 }, { b: 2 }]

// From a Uint8Array (zero-copy for ASCII):
const buf = new TextEncoder().encode('{"a":1}\n{"b":2}\n');
const items = Bun.JSONL.parse(buf);
// [{ a: 1 }, { b: 2 }]

// Partial results on error after valid values:
const partial = Bun.JSONL.parse('{"a":1}\n{bad}\n');
// [{ a: 1 }]

// Throws when no valid values precede the error:
Bun.JSONL.parse('{bad}\n'); // throws SyntaxError
  • function parseChunk(
    input: string

    Parse a JSONL chunk, designed for streaming use.

    Never throws on parse errors. Instead, returns whatever values were successfully parsed along with an error property containing the SyntaxError (or null on success). Use read to determine how much input was consumed and done to check if all input was parsed.

    When a TypedArray is passed, the bytes are parsed directly without copying if the content is ASCII. Optional start and end parameters allow slicing without copying, and read will be a byte offset into the original typed array.

    @param input

    The JSONL string or typed array to parse

    @returns

    An object with values, read, done, and error properties

    let buffer = new Uint8Array(0);
for await (const chunk of stream) {
  buffer = Buffer.concat([buffer, chunk]);
  const { values, read, error } = Bun.JSONL.parseChunk(buffer);
  if (error) throw error;
  for (const value of values) handle(value);
  buffer = buffer.subarray(read);
}
    function parseChunk(
    input: ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBuffer>,
    start?: number,
    end?: number

    Parse a JSONL chunk, designed for streaming use.

    Never throws on parse errors. Instead, returns whatever values were successfully parsed along with an error property containing the SyntaxError (or null on success). Use read to determine how much input was consumed and done to check if all input was parsed.

    When a TypedArray is passed, the bytes are parsed directly without copying if the content is ASCII. Optional start and end parameters allow slicing without copying, and read will be a byte offset into the original typed array.

    @param input

    The JSONL string or typed array to parse

    @param start

    Byte offset to start parsing from (typed array only, default: 0)

    @param end

    Byte offset to stop parsing at (typed array only, default: input.byteLength)

    @returns

    An object with values, read, done, and error properties

    let buffer = new Uint8Array(0);
for await (const chunk of stream) {
  buffer = Buffer.concat([buffer, chunk]);
  const { values, read, error } = Bun.JSONL.parseChunk(buffer);
  if (error) throw error;
  for (const value of values) handle(value);
  buffer = buffer.subarray(read);
}