API Reference

TypeScript/JavaScript API documentation for the @toon-format/toon package. For format rules, see the Format Overview or the Specification. For other languages, see Implementations.

Installation

npm

npm install @toon-format/toon

pnpm

pnpm add @toon-format/toon

yarn

yarn add @toon-format/toon

Encoding Functions

encode(input, options?)

Converts any JSON-serializable value to TOON format.

import { encode } from '@toon-format/toon'

const toon = encode(data, {
  indentSize: 2,
  delimiter: ','
})

Parameters

Parameter	Type	Description
input	unknown	Any JSON-serializable value (object, array, primitive, or nested structure)
options	EncodeOptions?	Optional encoding options (see Configuration Reference)

Return Value

Returns a TOON-formatted string with no trailing newline or spaces.

Type Normalization

Non-JSON-serializable values are normalized before encoding:

Input	Output
Object with toJSON() method	Result of calling toJSON(), recursively normalized
Finite number in [1e-6, 1e21) (or zero)	Canonical decimal (e.g., 1e6 → 1000000, -0 → 0)
Finite number outside that range	Exponent form permitted (e.g., 1e-7, 1e+21)
NaN, Infinity, -Infinity	null
BigInt (within safe range)	Number
BigInt (out of range)	Quoted decimal string (e.g., "9007199254740993")
Date	ISO string in quotes (e.g., "2025-01-01T00:00:00.000Z")
Empty slot in a sparse array	null
Set	Array of normalized values
Map	Object with String(key) keys
undefined, function, symbol	null

INFO

TOON itself doesn't specify how Date should be encoded – the spec leaves this to implementations. This library emits an ISO 8601 string in quotes; other implementations may choose differently.

Example

import { encode } from '@toon-format/toon'

const items = [
  { sku: 'A1', qty: 2, price: 9.99 },
  { sku: 'B2', qty: 1, price: 14.5 }
]

console.log(encode({ items }))

Output:

items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5

encodeLines(input, options?)

Preferred method for streaming TOON output. Converts any JSON-serializable value to TOON format as a sequence of lines, without building the full string in memory. Suitable for streaming large outputs to files, HTTP responses, or process stdout.

import { encodeLines } from '@toon-format/toon'

// Stream to stdout (Node.js)
for (const line of encodeLines(data)) {
  process.stdout.write(`${line}\n`)
}

// Write to file line-by-line
const lines = encodeLines(data, { indentSize: 2, delimiter: '\t' })
for (const line of lines) {
  await writeToStream(`${line}\n`)
}

// Collect to array
const lineArray = Array.from(encodeLines(data))

Parameters

Parameter	Type	Description
input	unknown	Any JSON-serializable value (object, array, primitive, or nested structure)
options	EncodeOptions?	Optional encoding options (see Configuration Reference)

Return Value

Returns an Iterable<string> that yields TOON lines one at a time. Each yielded string is a single line without a trailing newline character – you must add \n when writing to streams or stdout.

Relationship to encode()

encode(value, options) is equivalent to:

Array.from(encodeLines(value, options)).join('\n')

Example

import { createWriteStream } from 'node:fs'
import { encodeLines } from '@toon-format/toon'

const data = {
  items: Array.from({ length: 100000 }, (_, i) => ({
    id: i,
    name: `Item ${i}`,
    value: Math.random()
  }))
}

// Stream large dataset to file
const stream = createWriteStream('output.toon')
for (const line of encodeLines(data, { delimiter: '\t' })) {
  stream.write(`${line}\n`)
}
stream.end()

Replacer Function

The replacer option allows you to transform or filter values during encoding. It works similarly to JSON.stringify's replacer parameter, but with path tracking for more precise control.

Type Signature

type EncodeReplacer = (
  key: string,
  value: JsonValue,
  path: readonly (string | number)[]
) => unknown

Parameters

Parameter	Type	Description
key	string	Property name, array index (as string), or empty string for root
value	JsonValue	The normalized value at this location
path	readonly (string | number)[]	Path from root to current value

Return Value

• Return the value unchanged to keep it
• Return a different value to replace it (will be normalized)
• Return undefined to omit properties/array elements
• For root value, undefined means "no change" (root cannot be omitted)

Examples

Filtering sensitive data:

import { encode } from '@toon-format/toon'

const data = {
  user: { name: 'Ada', password: 'secret123', email: 'ada@example.com' }
}

function replacer(key, value) {
  if (key === 'password')
    return undefined
  return value
}

console.log(encode(data, { replacer }))

Output:

user:
  name: Ada
  email: ada@example.com

Transforming values:

const data = { user: 'alice', role: 'admin' }

function replacer(key, value) {
  if (typeof value === 'string')
    return value.toUpperCase()
  return value
}

console.log(encode(data, { replacer }))

Output:

user: ALICE
role: ADMIN

Path-based transformations:

const data = {
  metadata: { created: '2025-01-01' },
  user: { created: '2025-01-02' }
}

function replacer(key, value, path) {
  // Add timezone info only to top-level metadata
  if (path.length === 1 && path[0] === 'metadata' && key === 'created') {
    return `${value}T00:00:00Z`
  }
  return value
}

console.log(encode(data, { replacer }))

Output:

metadata:
  created: "2025-01-01T00:00:00Z"
user:
  created: 2025-01-02

Replacer Execution Order

The replacer is called in a depth-first manner:

1. Root value first (key = '', path = [])
2. Then each property/element (with proper key and path)
3. Values are re-normalized after replacement
4. Children are processed after parent transformation

Array Indices as Strings

Following JSON.stringify behavior, array indices are passed as strings ('0', '1', '2', etc.) to the replacer, not as numbers.

Raw String Output

Return rawString(...) from a replacer to emit a string verbatim at the value position, bypassing TOON's quoting, escaping, and number/keyword detection. Compose it with escapeString to control quoting yourself without reimplementing escape handling.

import { encode, escapeString, rawString } from '@toon-format/toon'

const data = { name: 'Ada', age: 30 }

// Always-quote mode: wrap every leaf in quotes
console.log(encode(data, {
  replacer: (key, value) => rawString(`"${escapeString(String(value))}"`)
}))

Output:

name: "Ada"
age: "30"

Semantics

• A rawString is only honored where a primitive would go. Returned for an object or array value, it is ignored and the container is encoded normally – this lets "wrap every value" replacers recurse into containers instead of collapsing them.
• A value containing a line whose first non-space character is # throws at rawString(...) time – regardless of where the value would be emitted – since decoders silently strip such comment lines and the data would vanish without an error.

escapeString(value)

Escapes backslashes, quotes, and control characters for use inside a quoted TOON string. The decision whether a value needs quoting at all stays with the caller.

escapeString('a "quoted" value') // a \"quoted\" value
escapeString('line1\nline2') // line1\nline2 (escaped)

One-Way Escape Hatch

Raw emission bypasses the encoder's correctness guarantees: the output is not guaranteed to be valid TOON or to round-trip losslessly. In the example above, age decodes back as the string "30", not the number 30.

Decoding Functions

decode(input, options?)

Converts a TOON-formatted string back to JavaScript values.

import { decode } from '@toon-format/toon'

const data = decode(toon, {
  indentSize: 2,
  strict: true
})

Parameters

Parameter	Type	Description
input	string	A TOON-formatted string to parse
options	DecodeOptions?	Optional decoding options (see Configuration Reference)

Return Value

Returns a JavaScript value (object, array, or primitive) representing the parsed TOON data.

Numeric tokens decode to number and follow IEEE 754 double precision: values beyond it round silently (including integers outside the safe integer range), and tokens that overflow the finite range decode as strings – this is the decoder's documented out-of-range policy per spec §4. Values that must stay exact belong in quoted strings; encode() writes out-of-range BigInt values that way automatically.

Example

import { decode } from '@toon-format/toon'

const toon = `
items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5
`

const data = decode(toon)
console.log(data)

Output:

{
  "items": [
    { "sku": "A1", "qty": 2, "price": 9.99 },
    { "sku": "B2", "qty": 1, "price": 14.5 }
  ]
}

decodeFromLines(lines, options?)

Decodes TOON format from pre-split lines into a JavaScript value. This is a streaming-friendly wrapper around the event-based decoder that builds the full value in memory.

Useful when you already have lines as an array or iterable (e.g., from file streams, readline interfaces, or network responses) and want the standard decode behavior.

Parameters

Parameter	Type	Description
lines	Iterable<string>	Iterable of TOON lines (without trailing newlines)
options	DecodeOptions?	Optional decoding configuration (see Configuration Reference)

Return Value

Returns a JsonValue (the parsed JavaScript value: object, array, or primitive).

Example

Basic usage with arrays:

import { decodeFromLines } from '@toon-format/toon'

const lines = ['name: Ada', 'age: 30']
const value = decodeFromLines(lines)
// { name: 'Ada', age: 30 }

Streaming from Node.js readline:

import { createReadStream } from 'node:fs'
import { createInterface } from 'node:readline'
import { decodeFromLines } from '@toon-format/toon'

const rl = createInterface({
  input: createReadStream('data.toon'),
  crlfDelay: Infinity,
})

const value = decodeFromLines(rl)
console.log(value)

Choosing the Right Decoder

Function	Input	Output	Async	Use When
decode()	String	Value	No	You have a complete TOON string
decodeFromLines()	Lines	Value	No	You have lines and want the full value
decodeStreamSync()	Lines	Events	No	You need event-by-event processing (sync)
decodeStream()	Lines	Events	Yes	You need event-by-event processing (async)

Key Differences

• Value vs. Events: Functions ending in Stream yield events without building the full value in memory.
• Async support: Only decodeStream() accepts async iterables (useful for file/network streams).

Streaming Decoders

decodeStreamSync(lines, options?)

Synchronously decodes TOON lines into a stream of JSON events. This function yields structured events that represent the JSON data model without building the full value tree.

Useful for streaming processing, custom transformations, or memory-efficient parsing of large datasets where you don't need the full value in memory.

Event Streaming

This is a low-level API that returns individual parse events. For most use cases, decodeFromLines() or decode() are more convenient.

Parameters

Parameter	Type	Description
lines	Iterable<string>	Iterable of TOON lines (without trailing newlines)
options	DecodeStreamOptions?	Optional streaming decoding configuration (see Configuration Reference)

Return Value

Returns an Iterable<JsonStreamEvent> that yields structured events (see TypeScript Types for event structure).

Example

Basic event streaming:

import { decodeStreamSync } from '@toon-format/toon'

const lines = ['name: Ada', 'age: 30']

for (const event of decodeStreamSync(lines)) {
  console.log(event)
}

// Output:
// { type: 'startObject' }
// { type: 'key', key: 'name' }
// { type: 'primitive', value: 'Ada' }
// { type: 'key', key: 'age' }
// { type: 'primitive', value: 30 }
// { type: 'endObject' }

Custom processing:

import { decodeStreamSync } from '@toon-format/toon'

const lines = ['users[2]{id,name}:', '  1,Ada', '  2,Bob']
let userCount = 0

for (const event of decodeStreamSync(lines)) {
  if (event.type === 'endObject' && userCount < 2) {
    userCount++
    console.log(`Processed user ${userCount}`)
  }
}

decodeStream(source, options?)

Asynchronously decodes TOON lines into a stream of JSON events. This is the async version of decodeStreamSync(), supporting both synchronous and asynchronous iterables.

Useful for processing file streams, network responses, or other async sources where you want to handle data incrementally as it arrives.

Parameters

Parameter	Type	Description
source	AsyncIterable<string> | Iterable<string>	Async or sync iterable of TOON lines (without trailing newlines)
options	DecodeStreamOptions?	Optional streaming decoding configuration (see Configuration Reference)

Return Value

Returns an AsyncIterable<JsonStreamEvent> that yields structured events asynchronously (see TypeScript Types for event structure).

Example

Streaming from file:

import { createReadStream } from 'node:fs'
import { createInterface } from 'node:readline'
import { decodeStream } from '@toon-format/toon'

const fileStream = createReadStream('data.toon', 'utf-8')
const rl = createInterface({ input: fileStream, crlfDelay: Infinity })

for await (const event of decodeStream(rl)) {
  console.log(event)
  // Process events as they arrive
}

Error Handling

Decoding throws a ToonDecodeError when input cannot be parsed. The class extends SyntaxError, so existing error instanceof SyntaxError checks keep working without code changes.

ToonDecodeError

import { ToonDecodeError } from '@toon-format/toon'

Fields

Field	Type	Description
name	'ToonDecodeError'	Discriminator – error.name === 'ToonDecodeError'
message	string	Human-readable message; prefixed with Line N: when a line is known
line	number?	1-based line number where the error was detected
source	string?	Raw source line (including its leading whitespace)
cause	unknown?	The original error when the decoder enriched a lower-level parser failure

The line and source fields are populated for every error that has line context – essentially every parse error during normal decoding. The cause chain points back to the underlying SyntaxError or TypeError thrown by the token-level parser, so debuggers and verbose loggers can show the original frame.

Example

import { decode, ToonDecodeError } from '@toon-format/toon'

try {
  decode('a:\n\tb: 1')
}
catch (error) {
  if (error instanceof ToonDecodeError) {
    console.error(`Line ${error.line}:`, error.source)
    console.error(error.message)
    // Line 2: 	b: 1
    // Line 2: Tabs are not allowed in indentation in strict mode
  }
  else {
    throw error
  }
}

Backwards Compatibility

ToonDecodeError extends SyntaxError. Code written against earlier versions that catches SyntaxError continues to match these errors. The class adds structured fields without removing anything.

Configuration Reference

EncodeOptions

Configuration for encode() and encodeLines():

Option	Type	Default	Description
indentSize	number	2	Number of spaces per indentation level
delimiter	',' | '\t' | '|'	','	Delimiter for array values and tabular rows
replacer	EncodeReplacer	undefined	Optional hook to transform or omit values before encoding (see Replacer Function)

Delimiter options:

Comma (default)

encode(data, { delimiter: ',' })

Tab

encode(data, { delimiter: '\t' })

Pipe

encode(data, { delimiter: '|' })

See Delimiter Options for guidance on choosing delimiters.

DecodeOptions

Configuration for decode() and decodeFromLines():

Option	Type	Default	Description
indentSize	number	2	Expected number of spaces per indentation level
strict	boolean	true	Throw where false applies the five §14.4 recoveries listed below

By default, the decoder validates input:

• Invalid escape sequences: Throws on \x, unterminated strings, lone-surrogate \uXXXX
• Syntax errors: Throws on missing colons, malformed headers
• Array length mismatches: Throws when declared length doesn't match actual count
• Keyed tabular mismatches: Throws when the entry-row count doesn't match the declared count or a row's cell count doesn't match the header's leaf fields (§9.5)
• Header delimiter mismatch: Throws when the bracket-declared delimiter differs from the field-list delimiter (§14.2)
• Indentation errors: Throws when leading spaces aren't exact multiples of indentSize, on depth jumps of more than one level into a nested scope, and on over-indented lines that belong to no scope (§14.2) – decoding never silently discards input, including trailing content after a completed root array or keyed tabular root (§5)
• Header structure: Throws on leading-zero or non-integer array lengths, malformed keyed markers, and intervening content between bracket/fields/colon
• Duplicate sibling keys: Throws when an object has two children with the same key, including duplicate entry keys (§14.3)

All decode errors are thrown as ToonDecodeError instances with structured line and source fields.

Set strict: false to apply the five recoveries of §14.4 instead: a declared [N] never truncates a scope, so every value, list item, row, and entry row it contains is decoded; duplicate keys resolve with last-write-wins in document order; indentation may be a non-multiple of indentSize or use tabs, one level each; blank lines inside an array or keyed object are ignored; and a scope's first line may sit deeper than expected and set the scope's depth. Every other check is an error in both modes.

Documented decoder policies. The specification requires each implementation to state the choices it leaves open (§4, §15):

• Numbers out of range: a token matching §4's number grammar whose magnitude exceeds the IEEE 754 double range decodes as a string; one that underflows decodes as numeric 0; one that fits but cannot be represented exactly decodes as the nearest double. Use a replacer or post-process the decoded value when exact decimals matter.
• Object representation: decoded objects are plain JavaScript objects. __proto__, constructor, and prototype are materialized as ordinary own entries and never mutate the prototype chain (§15). JavaScript reorders integer-like keys ahead of string keys, so a document whose keys include integer-like tokens does not preserve document key order (§2).

DecodeStreamOptions

Configuration for decodeStreamSync() and decodeStream():

Option	Type	Default	Description
indentSize	number	2	Expected number of spaces per indentation level
strict	boolean	true	Same as in DecodeOptions

TypeScript Types

JsonStreamEvent

Events emitted by decodeStreamSync() and decodeStream():

type JsonStreamEvent
  = | { type: 'startObject' }
    | { type: 'endObject' }
    | { type: 'startArray', length: number }
    | { type: 'endArray' }
    | { type: 'key', key: string }
    | { type: 'primitive', value: JsonPrimitive }

Delimiters

import { DEFAULT_DELIMITER, DELIMITERS } from '@toon-format/toon'

DEFAULT_DELIMITER // ','
DELIMITERS // { comma: ',', tab: '\t', pipe: '|' }

Export	Description
DEFAULT_DELIMITER	The default delimiter character (,) used when none is specified
DELIMITERS	Frozen record mapping delimiter names to their characters
Delimiter	Type union of valid delimiter characters: ',' | '\t' | '|'
DelimiterKey	Type union of delimiter names: 'comma' | 'tab' | 'pipe'

Option Types

Export	Description
EncodeOptions	Options accepted by encode() and encodeLines()
DecodeOptions	Options accepted by decode() and decodeFromLines()
DecodeStreamOptions	Options accepted by decodeStreamSync() and decodeStream()
EncodeReplacer	Signature of the replacer function
ResolvedEncodeOptions	EncodeOptions after defaults are applied (advanced)
ResolvedDecodeOptions	DecodeOptions after defaults are applied (advanced)