decodeFromLines

Decodes TOON format from pre-split lines into a JavaScript value

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

lines · Iterable<string> · required

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

options · DecodeOptions

Optional decoding configuration.

indent · number · default: "2"

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

strict · boolean · default: "true"

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

expandPaths · '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

result · 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

From array of

import { decodeFromLines } from 'toon';

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

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

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.

Related Functions

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