yaml

class YamlParseError extends ParseError {

Error thrown when YAML input is malformed or violates configured limits.

The error extends ParseError and carries YAML format metadata plus line, column, and offset information where available. Duplicate keys, unsupported tags, undefined aliases, alias expansion limits, and syntax errors are reported through this type.

import { YamlParseError, parse } from 'fino:format/yaml';

try {
  parse('a: 1\na: 2\n');
} catch (error) {
  if (error instanceof YamlParseError) console.error(error.render());
}

Properties

type YamlValue = null | boolean | number | string | Uint8Array | Date | YamlValue[] | YamlMapping | Map<unknown, YamlValue>

Value types produced by the YAML core schema parser and accepted by stringify.

Core tags resolve to JavaScript primitives, Uint8Array for !!binary, Date for !!timestamp, arrays for sequences, plain objects for mappings with string keys, and Map for mappings with complex keys.

import { parse, stringify, type YamlValue } from 'fino:format/yaml';

const value: YamlValue = parse('enabled: true\ncount: 3\n');
stringify(value);

type YamlMapping = { [k: string]: YamlValue; }

Plain-object YAML mapping with string keys.

Mappings with non-string keys are returned as Map<unknown, YamlValue> instead, because JavaScript object keys cannot preserve arbitrary YAML key values.

import { parse, type YamlMapping } from 'fino:format/yaml';

const mapping = parse('server:\n  port: 8080\n') as YamlMapping;
(mapping.server as YamlMapping).port;

interface YamlParseOptions {

Options controlling YAML parsing limits and duplicate-key behavior.

Defaults reject duplicate keys and cap total alias expansion at 1,000,000 estimated characters.

import { parse, type YamlParseOptions } from 'fino:format/yaml';

const options: YamlParseOptions = { maxAliasExpansion: 10_000 };
parse('a: 1\n', options);

Properties

import { parse } from 'fino:format/yaml';

parse('a: 1\na: 2\n', { allowDuplicateKeys: true });

import { parse } from 'fino:format/yaml';

parse('a: &a hello\nb: *a\n', { maxAliasExpansion: 100 });

interface YamlStringifyOptions {

Options controlling YAML serialization style.

Stringification emits a readable block style for objects and arrays and does not preserve source comments, anchor names, or merge keys from parsed input.

import { stringify, type YamlStringifyOptions } from 'fino:format/yaml';

const options: YamlStringifyOptions = { indent: 4 };
stringify({ server: { port: 8080 } }, options);

Properties

import { stringify } from 'fino:format/yaml';

stringify({ a: { b: 1 } }, { indent: 4 });

function parse(input: string | Uint8Array, options: YamlParseOptions = {}): YamlValue

Parse one YAML document, returning the first document from a stream.

String input is parsed directly; byte input is decoded as UTF-8. If the input contains no document content, the function returns null. For multi-document streams, use parseAll() to keep every document.

Throws YamlParseError when the input is malformed, uses an unsupported feature (directives, custom or local tags), repeats a key without allowDuplicateKeys, or exceeds the alias expansion budget.

import { parse, type YamlMapping } from 'fino:format/yaml';

const config = parse(`
server:
  host: 0.0.0.0
  port: 8080
features:
  - metrics
  - tracing
`) as YamlMapping;

const server = config.server as YamlMapping;
server.port;    // 8080 (number, resolved by the core schema)
config.features; // ['metrics', 'tracing']

function parseAll(input: string | Uint8Array, options: YamlParseOptions = {}): YamlValue[]

Parse all YAML documents from a multi-document stream.

Document markers (--- and ...) are consumed between documents. Anchors are scoped per document and cleared before parsing the next document, so an alias in one document cannot reference an anchor from a previous one. Empty input returns an empty array.

Throws YamlParseError under the same conditions as parse(); a syntax error anywhere in the stream fails the whole call.

import { parseAll } from 'fino:format/yaml';

const docs = parseAll('---\na: 1\n---\nb: 2\n');
docs.length; // 2

function stringify(value: YamlValue, options: YamlStringifyOptions = {}): string

Serialize a YAML-compatible value.

Serialization emits YAML core-schema values from JavaScript primitives, arrays, plain mappings, Map, Uint8Array (as !!binary), and Date (as !!timestamp). It does not re-emit comments, merge keys, document markers, or anchor names from parsed input; however, an object referenced more than once in the value graph is emitted once with a generated anchor (&a1) and aliased (*a1) at later occurrences, so shared identity survives a round-trip. Strings that would otherwise resolve as another scalar type, or that start with an indicator character or contain newlines, are single-quoted.

import { stringify } from 'fino:format/yaml';

stringify({
  server: { host: '0.0.0.0', port: 8080 },
  hosts: ['a', 'b'],
});
// server:
//   host: 0.0.0.0
//   port: 8080
// hosts: [a, b]