decodeFromLines

Function Signature

function decodeFromLines(lines: Iterable<string>, options?: DecodeOptions): JsonValue

Decodes TOON format from pre-split lines into a JavaScript value. This is a convenience wrapper around the streaming decoder that builds the full value in memory. Useful when you already have lines as an array or iterable and want the standard decode behavior with path expansion support.

Parameters

Iterable<string>

required

Iterable of TOON lines (without newlines). Can be an array, generator, or any iterable of strings.

DecodeOptions

Optional decoding configuration.

number

default:"2"

Number of spaces per indentation level. Must match the indentation used when encoding.

boolean

default:"true"

When true, enforce strict validation of array lengths and tabular row counts.

'off' | 'safe'

default:"'off'"

Enable path expansion to reconstruct dotted keys into nested objects. When set to 'safe', keys containing dots are expanded into nested structures if all segments are valid identifiers (e.g., data.metadata.items becomes nested objects). Pairs with keyFolding='safe' for lossless round-trips.

Returns

JsonValue

Parsed JavaScript value (object, array, or primitive).

type JsonValue = JsonPrimitive | JsonObject | JsonArray
type JsonPrimitive = string | number | boolean | null
type JsonObject = { [Key in string]: JsonValue }
type JsonArray = JsonValue[]

Examples

import { decodeFromLines } from 'toon';

const lines = ['name: Alice', 'age: 30'];
const result = decodeFromLines(lines);

console.log(result);
// Output: { name: 'Alice', age: 30 }

import { decodeFromLines } from 'toon';
import { createReadStream } from 'fs';
import { createInterface } from 'readline';

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

const result = decodeFromLines(rl);
console.log(result);

import { decodeFromLines } from 'toon';

function* generateLines() {
  yield 'user:';
  yield '  name: Alice';
  yield '  age: 30';
}

const result = decodeFromLines(generateLines());
console.log(result);
// Output: { user: { name: 'Alice', age: 30 } }

import { decodeFromLines } from 'toon';

const lines = [
  'data.metadata.version: 1.0',
  'data.metadata.author: Alice'
];

const result = decodeFromLines(lines, { expandPaths: 'safe' });
console.log(result);
// Output:
// {
//   data: {
//     metadata: {
//       version: '1.0',
//       author: 'Alice'
//     }
//   }
// }

import { decodeFromLines } from 'toon';

const lines = [
  'items[2]:',
  '  - value: 1'
];

const result = decodeFromLines(lines, { strict: false });
console.log(result);
// Output: { items: [{ value: 1 }] }

Use Cases

Pre-split Input

When you already have lines from another source (file streams, network, etc.), decodeFromLines is more efficient than joining and splitting:

import { decodeFromLines } from 'toon';

// Already have lines from somewhere
const lines = fetchLinesFromSource();

// More efficient than:
// const toonString = lines.join('\n');
// const result = decode(toonString);

const result = decodeFromLines(lines);

Streaming Decode with Full Value

When you want to stream input but need the complete value (with path expansion):

import { decodeFromLines } from 'toon';
import { createReadStream } from 'fs';
import { createInterface } from 'readline';

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

// Builds complete value from streamed lines
const result = decodeFromLines(rl, { 
  expandPaths: 'safe' 
});

Processing Line Arrays

import { decodeFromLines } from 'toon';

const rawData = `
name: Alice
age: 30
role: developer
`.trim();

const lines = rawData.split('\n');
const result = decodeFromLines(lines);

console.log(result);
// Output: { name: 'Alice', age: 30, role: 'developer' }

Comparison with decode()

decodeFromLines is essentially equivalent to:

import { decode } from 'toon';

function decodeFromLinesEquivalent(
  lines: Iterable<string>, 
  options?: DecodeOptions
): JsonValue {
  const toonString = Array.from(lines).join('\n');
  return decode(toonString, options);
}

However, decodeFromLines is more efficient when you already have lines, as it avoids the join and re-split operations.

decode - Decode from a complete TOON string
encodeLines - Encode to lines for streaming

Core Functions

Streaming

Configuration

decodeFromLines

Function Signature

Parameters

Returns

Examples

Use Cases

Pre-split Input

Streaming Decode with Full Value

Processing Line Arrays

Comparison with decode()

​Function Signature

​Parameters

​Returns

​Examples

​Use Cases

​Pre-split Input

​Streaming Decode with Full Value

​Processing Line Arrays

​Comparison with decode()

​Related Functions

Function Signature

Parameters

Returns

Examples

Use Cases

Pre-split Input

Streaming Decode with Full Value

Processing Line Arrays

Comparison with decode()

Related Functions