TOON Specification

https://toonformat.dev/reference/
Admin
TOON is a human-friendly, line-oriented, indentation-based data format with a JSON data model,...
Tokens:16,659
Snippets:147
Trust Score:6.8
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install @toon-format/toon Package

Source: https://toonformat.dev/reference/api

Installs the @toon-format/toon package using various package managers like npm, pnpm, and yarn. This is the first step to using the library in your project.

```bash
npm install @toon-format/toon
```

```bash
pnpm add @toon-format/toon
```

```bash
yarn add @toon-format/toon
```

--------------------------------

### Round-Trip Compatibility Example

Source: https://toonformat.dev/reference/api

Demonstrates lossless round-trip compatibility of ToonFormat after normalization.

```APIDOC
## Round-Trip Compatibility

TOON provides lossless round-trips after normalization:

```ts
import { decode, encode } from '@toon-format/toon'

const original = {
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
}

const toon = encode(original)
const restored = decode(toon)

console.log(JSON.stringify(original) === JSON.stringify(restored)) // true
```

**With Key Folding:**

```ts
import { decode, encode } from '@toon-format/toon'

const original = { data: { metadata: { items: ['a', 'b'] } } }

// Encode with folding
const toon = encode(original, { keyFolding: 'safe' })
// → "data.metadata.items[2]: a,b"

// Decode with expansion
const restored = decode(toon, { expandPaths: 'safe' })
// → { data: { metadata: { items: ['a', 'b'] } } }

console.log(JSON.stringify(original) === JSON.stringify(restored)) // true
```
```

--------------------------------

### TOON Round-Trip Compatibility Example (TypeScript)

Source: https://toonformat.dev/reference/api

Demonstrates a basic round-trip serialization and deserialization of data using TOON's encode and decode functions. This example verifies that the data can be losslessly converted between JavaScript objects and TOON format.

```TypeScript
import { decode, encode } from '@toon-format/toon';

const original = {
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
};

const toon = encode(original);
const restored = decode(toon);

console.log(JSON.stringify(original) === JSON.stringify(restored));
// Output: true
```

--------------------------------

### Tab Delimiter Usage in Toon Format (YAML Example)

Source: https://toonformat.dev/reference/api

Shows an example of using tab characters (`\t`) as delimiters in Toon Format for more efficient tokenization, especially in tabular data. This reduces the need for quote-escaping compared to commas.

```yaml
items[2	]{sku	name	qty	price}:
  A1	Widget	2	9.99
  B2	Gadget	1	14.5
```

--------------------------------

### Decoding TOON String with decode() in TypeScript

Source: https://toonformat.dev/reference/api

Provides an example of decoding a TOON-formatted string back into JavaScript values using the 'decode' function. It shows basic usage and highlights optional parameters like 'indent', 'strict', and 'expandPaths'.

```typescript
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)
```

--------------------------------

### Path-Based Transformations with encode() in TypeScript

Source: https://toonformat.dev/reference/api

Shows how to perform transformations based on the data's path using a replacer function that accepts 'key', 'value', and 'path' arguments. This example adds timezone information to a 'created' field only if it's within the top-level 'metadata' object.

```typescript
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 }))
```

--------------------------------

### TOON Array with Pipe Delimiter

Source: https://toonformat.dev/reference/syntax-cheatsheet

Example of using a pipe character as a delimiter in TOON array headers for tabular data.

```yaml
items[2|]{id|name}:
  1|Alice
  2|Bob
```

--------------------------------

### Multi-field Object in TOON Array

Source: https://toonformat.dev/reference/syntax-cheatsheet

Example of a TOON array containing objects with multiple fields, including a nested tabular array.

```yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob
    status: active
```

--------------------------------

### TOON Array with Tab Delimiter

Source: https://toonformat.dev/reference/syntax-cheatsheet

Example of using a tab character as a delimiter in TOON array headers for tabular data.

```yaml
items[2	]{	id	name}:
  1	Alice
  2	Bob
```

--------------------------------

### Single-field Object in TOON Array

Source: https://toonformat.dev/reference/syntax-cheatsheet

Example of a TOON array containing objects with a single field, specifically a nested tabular array.

```yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob
```

--------------------------------

### Transforming Values with encode() in TypeScript

Source: https://toonformat.dev/reference/api

Illustrates how to transform data values during encoding using a custom replacer function. This example converts all string values to uppercase. The replacer function receives the key and value, and its return value replaces the original value.

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

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

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

--------------------------------

### Key Folding with Toon Format Encoding (TypeScript)

Source: https://toonformat.dev/reference/api

Demonstrates how to use key folding during data encoding with the Toon Format library. Key folding collapses single-key wrapper chains to reduce data verbosity. It takes data as input and an optional configuration object.

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

const data = { data: { metadata: { items: ['a', 'b'] } } }

// Without folding
console.log(encode(data))

// With folding
console.log(encode(data, { keyFolding: 'safe' }))
```

--------------------------------

### Encode Options

Source: https://toonformat.dev/reference/api

Configuration options for the `encode()` and `encodeLines()` functions in ToonFormat.

```APIDOC
## Encode Options

Configuration for [`encode()`](#encode-input-options) and [`encodeLines()`](#encodelines-input-options):

### Parameters

#### Request Body

- **indent** (number) - Optional - Number of spaces per indentation level. Default: `2`
- **delimiter** (string) - Optional - Delimiter for array values and tabular rows. Allowed values: `'|'`, `','`, `'\t'`. Default: `'\t'`
- **keyFolding** (string) - Optional - Enable key folding to collapse single-key wrapper chains into dotted paths. Allowed values: `'off'`, `'safe'`. Default: `'off'`
- **flattenDepth** (number) - Optional - Maximum number of segments to fold when `keyFolding` is enabled. Default: `Infinity`
- **replacer** (EncodeReplacer) - Optional - Hook to transform or omit values before encoding.

### Request Example

```json
{
  "indent": 4,
  "delimiter": ",",
  "keyFolding": "safe"
}
```

### Delimiter Examples

```ts
// Comma (default)
encode(data, { delimiter: ',' })

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

// Pipe
encode(data, { delimiter: '|' })
```
```

--------------------------------

### Decoding TOON Data

Source: https://toonformat.dev/reference/api

Explains how to use the `decode` function to convert a TOON-formatted string back into JavaScript values. Includes details on parameters and return values.

```APIDOC
## POST /decode

### Description
Decodes a TOON-formatted string into JavaScript values. Supports various options for controlling the decoding process.

### Method
POST

### Endpoint
/decode

### Parameters
#### Request Body
- **input** (string) - Required - The TOON-formatted string to parse.
- **options** (object) - Optional - Decoding options.
  - **indent** (number) - Specifies the indentation level for the output.
  - **strict** (boolean) - Enables strict parsing mode.
  - **expandPaths** (string) - Controls path expansion behavior ('on', 'off', 'safe').

### Request Example
```json
{
  "input": "items[2]{\n  sku,qty,price\n}:\n  A1,2,9.99\n  B2,1,14.5\n",
  "options": {
    "indent": 2,
    "strict": true,
    "expandPaths": "off"
  }
}
```

### Response
#### Success Response (200)
- **decoded_data** (object | array | primitive) - The parsed JavaScript value.

#### Response Example
```json
{
  "decoded_data": {
    "items": [
      { "sku": "A1", "qty": 2, "price": 9.99 },
      { "sku": "B2", "qty": 1, "price": 14.5 }
    ]
  }
}
```
```

--------------------------------

### TOON Encoding and Decoding with Key Folding and Path Expansion (TypeScript)

Source: https://toonformat.dev/reference/api

Illustrates a round-trip data serialization using TOON, showcasing the use of key folding during encoding and path expansion during decoding. This preserves nested object structures.

```TypeScript
import { decode, encode } from '@toon-format/toon';

const original = { data: { metadata: { items: ['a', 'b'] } } };

// Encode with key folding enabled
const toon = encode(original, { keyFolding: 'safe' });
// Expected TOON string: "data.metadata.items[2]: a,b"

// Decode with path expansion enabled
const restored = decode(toon, { expandPaths: 'safe' });

console.log(JSON.stringify(original) === JSON.stringify(restored));
// Output: true
```

--------------------------------

### Decode Options

Source: https://toonformat.dev/reference/api

Configuration options for the `decode()` and `decodeFromLines()` functions in ToonFormat.

```APIDOC
## Decode Options

Configuration for [`decode()`](#decode-input-options) and [`decodeFromLines()`](#decodefromlines-lines-options):

### Parameters

#### Request Body

- **indent** (number) - Optional - Expected number of spaces per indentation level. Default: `2`
- **strict** (boolean) - Optional - Enable strict validation (array counts, indentation, delimiter consistency). Default: `true`
- **expandPaths** (string) - Optional - Enable path expansion to reconstruct dotted keys into nested objects. Allowed values: `'off'`, `'safe'`. Default: `'off'`

### Description

By default (`strict: true`), the decoder validates input strictly for:

*   Invalid escape sequences
*   Syntax errors
*   Array length mismatches
*   Delimiter mismatches
*   Indentation errors

Set `strict: false` to skip validation for lenient parsing.

See [Key Folding & Path Expansion](#key-folding-path-expansion) for more details on path expansion behavior and conflict resolution.
```

--------------------------------

### Empirical Validation: Basic Array Structure (JSON vs. TOON)

Source: https://toonformat.dev/reference/efficiency-formalization

Compares the byte representation of a simple array of pairs in JSON and TOON. Demonstrates TOON's structural differences in representing array elements.

```json
{ "pairs": [[1, 2], [3, 4]] }
```

```yaml
pairs[2]:
  - [2]: 1,2
  - [2]: 3,4
```

--------------------------------

### Empirical Validation: String Literals (JSON vs. TOON)

Source: https://toonformat.dev/reference/efficiency-formalization

Illustrates how TOON and JSON handle string literals that resemble numbers or booleans. Both formats require quotes for these values, reducing TOON's typical advantage.

```json
{ "version": "123", "enabled": "true" }
```

```yaml
version: "123"
enabled: "true"
```

--------------------------------

### Encoding Data with ToonFormat

Source: https://toonformat.dev/reference/api

Demonstrates various use cases for the `encode` function, including filtering sensitive data, transforming values, and applying path-based transformations.

```APIDOC
## POST /encode

### Description
Encodes JavaScript data into TOON format. Supports custom replacer functions for filtering and transforming data during encoding.

### Method
POST

### Endpoint
/encode

### Parameters
#### Query Parameters
- **replacer** (function) - Optional - A function to transform or filter data during encoding. It receives `key`, `value`, and `path` as arguments.

#### Request Body
- **data** (object | array | primitive) - Required - The data to be encoded.
- **options** (object) - Optional - Encoding options, including the `replacer` function.
  - **replacer** (function) - Optional - A function to transform or filter data during encoding.

### Request Example
```json
{
  "data": {
    "user": {
      "name": "Alice",
      "password": "secret123",
      "email": "alice@example.com"
    }
  },
  "options": {
    "replacer": "function(key, value) { if (key === 'password') return undefined; return value; }"
  }
}
```

### Response
#### Success Response (200)
- **encoded_data** (string) - The TOON-formatted string.

#### Response Example
```json
{
  "encoded_data": "user:\n  name: Alice\n  email: alice@example.com"
}
```
```

--------------------------------

### Path Expansion with Toon Format Decoding (TypeScript)

Source: https://toonformat.dev/reference/api

Illustrates path expansion during data decoding using the Toon Format library. Path expansion reverses key folding, reconstructing the original nested data structure. It requires the encoded string and an optional configuration object.

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

const toon = 'data.metadata.items[2]: a,b'

const data = decode(toon, { expandPaths: 'safe' })
console.log(data)
```

--------------------------------

### Tabular Arrays: JSON vs TOON Comparison

Source: https://toonformat.dev/reference/efficiency-formalization

Highlights TOON's significant advantage in representing tabular data (uniform arrays of objects). TOON declares keys once and streams values, saving considerable space compared to JSON's repetition.

```json
{ "items": [{ "id": 1, "qty": 5 }, { "id": 2, "qty": 3 }] }
```

```yaml
items[2]{id,qty}:
  1,5
  2,3
```

--------------------------------

### Nested Objects: JSON vs TOON Comparison

Source: https://toonformat.dev/reference/efficiency-formalization

Demonstrates the byte difference between JSON and TOON for representing a nested object. TOON offers a slight advantage due to reduced braces and indentation.

```json
{ "user": { "id": 1, "name": "Ada" } }
```

```yaml
user:
  id: 1
  name: Ada
```

--------------------------------

### Empty Object Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Demonstrates the representation of an empty JSON object in TOON format, which results in no output.

```json
{}
```

```yaml
(empty output)
```

--------------------------------

### Primitive Array Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Shows the conversion of a simple JSON array of primitives to TOON format. Note the specific syntax for TOON arrays.

```json
{
  "tags": ["foo", "bar", "baz"]
}
```

```yaml
tags[3]: foo,bar,baz
```

--------------------------------

### Empty String Mapping to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Shows the TOON representation of an empty string in JSON, which requires quoting.

```json
{
  "name": ""
}
```

```yaml
name: ""
```

--------------------------------

### Decoding TOON Data from Lines

Source: https://toonformat.dev/reference/api

Details the `decodeFromLines` function, which decodes TOON format from an iterable of lines, suitable for streaming scenarios.

```APIDOC
## POST /decode/lines

### Description
Decodes TOON format from an iterable of lines. This is useful for processing TOON data from streams or pre-split string arrays.

### Method
POST

### Endpoint
/decode/lines

### Parameters
#### Request Body
- **lines** (Iterable<string>) - Required - An iterable of TOON lines (without trailing newlines).
- **options** (object) - Optional - Decoding configuration options (see [Configuration Reference](#configuration-reference)).
  - **expandPaths** (string) - Controls path expansion behavior ('on', 'off', 'safe').

### Request Example
```json
{
  "lines": [
    "name: Alice",
    "age: 30"
  ],
  "options": {
    "expandPaths": "safe"
  }
}
```

### Response
#### Success Response (200)
- **decoded_data** (object | array | primitive) - The parsed JavaScript value.

#### Response Example
```json
{
  "decoded_data": {
    "name": "Alice",
    "age": 30
  }
}
```
```

--------------------------------

### TOON Encoding Delimiter Options (TypeScript)

Source: https://toonformat.dev/reference/api

Demonstrates how to configure the delimiter for encoding data into TOON format. Different delimiters like comma, tab, and pipe can be used to separate array values and tabular rows.

```TypeScript
import { encode } from '@toon-format/toon';

const data = {}; // Your data here

// Using comma as delimiter
const toonComma = encode(data, { delimiter: ',' });

// Using tab as delimiter
const toonTab = encode(data, { delimiter: '\t' });

// Using pipe as delimiter
const toonPipe = encode(data, { delimiter: '|' });
```

--------------------------------

### Key Folding in TOON Format

Source: https://toonformat.dev/reference/syntax-cheatsheet

Illustrates the optional key folding feature in TOON format, where nested keys are represented using dot notation.

```yaml
data.metadata.items[2]: a,b
```

--------------------------------

### TypeScript Types

Source: https://toonformat.dev/reference/api

TypeScript type definitions for ToonFormat events and primitives.

```APIDOC
## TypeScript Types

### `JsonStreamEvent`

Events emitted by [`decodeStreamSync()`](#decodestreamsync-lines-options) and [`decodeStream()`](#decodestream-source-options):

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

type JsonPrimitive = string | number | boolean | null
```
```

--------------------------------

### Optimizing Toon Format Encoding with Tabs and Key Folding (TypeScript)

Source: https://toonformat.dev/reference/api

Combines tab delimiters and key folding in Toon Format encoding for maximum token savings on large datasets. This approach is ideal for efficiently representing tabular data for LLMs.

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

// Assuming 'data' is your large tabular dataset
const data = { ... }; 
encode(data, { delimiter: '\t', keyFolding: 'safe' })
```

--------------------------------

### Decode Stream Options

Source: https://toonformat.dev/reference/api

Configuration options for the `decodeStreamSync()` and `decodeStream()` functions in ToonFormat.

```APIDOC
## Decode Stream Options

Configuration for [`decodeStreamSync()`](#decodestreamsync-lines-options) and [`decodeStream()`](#decodestream-source-options):

### Parameters

#### Request Body

- **indent** (number) - Optional - Expected number of spaces per indentation level. Default: `2`
- **strict** (boolean) - Optional - Enable strict validation (array counts, indentation, delimiter consistency). Default: `true`

### Warning

Path expansion is not supported due to its incompatibility with event streaming. Use [`decodeFromLines()`](#decodefromlines-lines-options) if path expansion is needed.
```

--------------------------------

### Root Array Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Shows the TOON representation for a JSON array at the root level.

```json
["x", "y", "z"]
```

```yaml
[3]: x,y,z
```

--------------------------------

### Object Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Demonstrates the conversion of a simple JSON object to its equivalent TOON representation. This is a fundamental mapping for key-value pairs.

```json
{
  "id": 1,
  "name": "Ada"
}
```

```yaml
id: 1
name: Ada
```

--------------------------------

### Array of Arrays Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Illustrates how nested arrays (arrays of arrays) in JSON are converted to the TOON format.

```json
{
  "pairs": [[1, 2], [3, 4]]
}
```

```yaml
pairs[2]:
  - [2]: 1,2
  - [2]: 3,4
```

--------------------------------

### Primitive Arrays: JSON vs TOON Comparison

Source: https://toonformat.dev/reference/efficiency-formalization

Compares the byte representation of primitive arrays in JSON and TOON. TOON's efficiency comes from omitting most quotes and using a length marker.

```json
{ "tags": ["foo", "bar", "baz"] }
```

```yaml
tags[3]: foo,bar,baz
```

--------------------------------

### Empty Array Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Shows how an empty JSON array within an object is represented in TOON format.

```json
{
  "items": []
}
```

```yaml
items[0]:
```

--------------------------------

### Quoting Strings with Leading/Trailing Spaces in TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Demonstrates that strings with leading or trailing whitespace require quoting in TOON to maintain the spaces.

```json
{
  "message": " padded "
}
```

```yaml
message: " padded "
```

--------------------------------

### Mixed/Non-Uniform Array Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Demonstrates the TOON representation of JSON arrays containing mixed data types or non-uniform structures.

```json
{
  "items": [1, { "a": 1 }, "x"]
}
```

```yaml
items[3]:
  - 1
  - a: 1
  - x
```

--------------------------------

### Tabular Array Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Explains how JSON arrays of objects (tabular data) are mapped to TOON format, including column headers.

```json
{
  "items": [
    { "id": 1, "qty": 5 },
    { "id": 2, "qty": 3 }
  ]
}
```

```yaml
items[2]{id,qty}:
  1,5
  2,3
```

--------------------------------

### Decoding TOON Lines with decodeFromLines() in TypeScript

Source: https://toonformat.dev/reference/api

Demonstrates decoding TOON format from an iterable of lines using 'decodeFromLines'. This function is useful for streaming data or when lines are already pre-processed. It supports path expansion options.

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

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

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

const lines = ['user.name: Alice', 'user.age: 30']
const value = decodeFromLines(lines, { expandPaths: 'safe' })
// { user: { name: 'Alice', age: 30 } }
```

--------------------------------

### Streaming Decoders - decodeStream()

Source: https://toonformat.dev/reference/api

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

```APIDOC
## decodeStream(source, options?)

### Description
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.

### Method
Asynchronous Function Call

### Endpoint
N/A (Function within a library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **source** (`AsyncIterable<string>` or `Iterable<string>`) - Required - Async or sync iterable of TOON lines (without trailing newlines).
- **options** (`DecodeStreamOptions?`) - Optional - Optional streaming decoding configuration.

### Return Value
- `AsyncIterable<JsonStreamEvent>` - An async iterable that yields structured events asynchronously.

### Request Example
```ts
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
}
```

### Response
#### Success Response (AsyncIterable<JsonStreamEvent>)
- **type** (`string`) - The type of the JSON stream event (e.g., 'startObject', 'key', 'primitive', 'endObject').
- **value** (any) - The value associated with the event (for 'primitive' events).
- **key** (`string`) - The key associated with the event (for 'key' events).

#### Response Example
```json
{
  "type": "startObject"
}
{
  "type": "key",
  "key": "user"
}
{
  "type": "startObject"
}
// ... more events
{
  "type": "endObject"
}
```
```

--------------------------------

### Quoting Strings Resembling Literals in TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Illustrates when strings in JSON that look like numbers or booleans need to be quoted in TOON to preserve their string type.

```json
{
  "version": "123",
  "enabled": "true"
}
```

```yaml
version: "123"
enabled: "true"
```

--------------------------------

### Streaming Decoders - decodeStreamSync()

Source: https://toonformat.dev/reference/api

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.

```APIDOC
## decodeStreamSync(lines, options?)

### Description
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.

### Method
Synchronous Function Call

### Endpoint
N/A (Function within a library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **lines** (`Iterable<string>`) - Required - Iterable of TOON lines (without trailing newlines).
- **options** (`DecodeStreamOptions?`) - Optional - Optional streaming decoding configuration.

### Return Value
- `Iterable<JsonStreamEvent>` - An iterable that yields structured events.

### Request Example
```ts
import { decodeStreamSync } from '@toon-format/toon'

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

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

### Response
#### Success Response (Iterable<JsonStreamEvent>)
- **type** (`string`) - The type of the JSON stream event (e.g., 'startObject', 'key', 'primitive', 'endObject').
- **value** (any) - The value associated with the event (for 'primitive' events).
- **key** (`string`) - The key associated with the event (for 'key' events).

#### Response Example
```json
{
  "type": "startObject"
}
{
  "type": "key",
  "key": "name"
}
{
  "type": "primitive",
  "value": "Alice"
}
{
  "type": "key",
  "key": "age"
}
{
  "type": "primitive",
  "value": 30
}
{
  "type": "endObject"
}
```
```

--------------------------------

### Nested Object Mapping JSON to TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Illustrates how nested objects in JSON are represented in TOON format. This shows the hierarchical structure conversion.

```json
{
  "user": {
    "id": 1,
    "name": "Ada"
  }
}
```

```yaml
user:
  id: 1
  name: Ada
```

--------------------------------

### Filtering Sensitive Data with encode() in TypeScript

Source: https://toonformat.dev/reference/api

Demonstrates how to filter sensitive data like passwords during the encoding process using a custom replacer function with the 'encode' utility. This function is called for each key-value pair and can selectively exclude properties by returning 'undefined'.

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

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

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

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

--------------------------------

### Quoting Strings with Active Delimiters in TOON

Source: https://toonformat.dev/reference/syntax-cheatsheet

Shows that strings containing the active delimiter (e.g., comma) must be quoted in TOON format.

```json
{
  "note": "hello, world"
}
```

```yaml
note: "hello, world"
```

--------------------------------

### Encode Data to TOON Format (TypeScript)

Source: https://toonformat.dev/reference/api

Converts any JSON-serializable value into TOON format using the `encode` function. It accepts optional configuration options for indentation, delimiters, and key folding. The function returns a TOON-formatted string.

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

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

const toon = encode(data, {
  indent: 2,
  delimiter: ',',
  keyFolding: 'off',
  flattenDepth: Infinity
})

console.log(toon)
// Output:
// items[2]{"sku","qty","price"}:
//   A1,2,9.99
//   B2,1,14.5
```
Tokens:
Raw