YAMLParser

Defined in: packages/core/src/parser/yaml-parser.ts:416

YAML parser with schema validation and reference resolution

Remarks

This class provides static methods for parsing YAML configuration files, validating them against schemas, and resolving references between configuration sections. All methods are static as the parser maintains no internal state.

Examples

Parse and validate YAML (throws on error)

const config = YAMLParser.parse(yamlString);

Safe parse (returns result object)

const result = YAMLParser.safeParse(yamlString);
if (!result.success) {
  console.error('Validation errors:', result.errors);
}

Constructors

Constructor

new YAMLParser(): YAMLParser

Returns

YAMLParser

Methods

parse()

static parse(yaml): any

Defined in: packages/core/src/parser/yaml-parser.ts:440

Parse YAML string and validate against schema

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse

Returns

any

Validated configuration object

Throws

If YAML syntax is invalid

Throws

If validation fails

Remarks

This method parses the YAML, validates it against the RootSchema, resolves all references, and returns the validated config. If any step fails, it throws an error.

Example

try {
  const config = YAMLParser.parse(yamlString);
  console.log('Valid config:', config);
} catch (error) {
  console.error('Parse error:', error.message);
}

---

parseMapBlock()

static parseMapBlock(yaml): object

Defined in: packages/core/src/parser/yaml-parser.ts:800

Parse YAML string for a single map block and validate against MapBlockSchema

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse (should be a map block, not a full document)

Returns

object

Validated map block object

Throws

If YAML syntax is invalid

Throws

If validation fails

Remarks

This method is specifically for parsing individual map blocks (e.g., in documentation or component usage). Unlike parse, it validates against MapBlockSchema rather than RootSchema, so it expects a single map configuration without the pages array wrapper.

Example

const yaml = `
type: map
id: example
config:
  center: [0, 0]
  zoom: 2
  mapStyle: "https://example.com/style.json"
layers:
  - id: points
    type: circle
    source:
      type: geojson
      data: { type: "FeatureCollection", features: [] }
`;

const mapBlock = YAMLParser.parseMapBlock(yaml);

---

parseScrollytellingBlock()

static parseScrollytellingBlock(yaml): object

Defined in: packages/core/src/parser/yaml-parser.ts:994

Parse YAML string for a scrollytelling block and validate against ScrollytellingBlockSchema

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse (should be a scrollytelling block, not a full document)

Returns

object

Validated scrollytelling block object

Throws

If YAML syntax is invalid

Throws

If validation fails

Remarks

This method is specifically for parsing individual scrollytelling blocks (e.g., in documentation or component usage). Unlike parse, it validates against ScrollytellingBlockSchema rather than RootSchema, so it expects a single scrollytelling configuration without the pages array wrapper.

Example

const yaml = `
type: scrollytelling
id: story
config:
  center: [0, 0]
  zoom: 2
  mapStyle: "https://example.com/style.json"
chapters:
  - id: intro
    title: "Introduction"
    center: [0, 0]
    zoom: 3
    description: "Welcome to our story."
  - id: chapter2
    title: "Chapter 2"
    center: [10, 10]
    zoom: 5
    description: "The story continues."
`;

const scrollyBlock = YAMLParser.parseScrollytellingBlock(yaml);

---

resolveReferences()

static resolveReferences(config): any

Defined in: packages/core/src/parser/yaml-parser.ts:1193

Resolve $ref references to global layers and sources

Parameters

Parameter	Type	Description
config	any	Configuration object with potential references

Returns

any

Configuration with all references resolved

Throws

If a reference cannot be resolved

Remarks

References use JSON Pointer-like syntax: #/layers/layerName or #/sources/sourceName. This method walks the configuration tree, finds all objects with a $ref property, looks up the referenced item in config.layers or config.sources, and replaces the reference object with the actual item.

Reference Syntax

• #/layers/myLayer - Reference to a layer in the global layers section
• #/sources/mySource - Reference to a source in the global sources section

Example

const config = {
  layers: {
    myLayer: { id: 'layer1', type: 'circle', ... }
  },
  pages: [{
    blocks: [{
      type: 'map',
      layers: [{ $ref: '#/layers/myLayer' }]
    }]
  }]
};

const resolved = YAMLParser.resolveReferences(config);
// resolved.pages[0].blocks[0].layers[0] now contains the full layer object

---

safeParse()

static safeParse(yaml): ParseResult

Defined in: packages/core/src/parser/yaml-parser.ts:491

Parse YAML string and validate, returning a result object

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse

Returns

ParseResult

Result object with success flag and either data or errors

Remarks

This is the non-throwing version of parse. Instead of throwing errors, it returns a result object that indicates success or failure. Use this when you want to handle errors gracefully without try/catch.

Example

const result = YAMLParser.safeParse(yamlString);
if (result.success) {
  console.log('Config:', result.data);
} else {
  result.errors.forEach(err => {
    console.error(`Error at ${err.path}: ${err.message}`);
  });
}

---

safeParseAny()

static safeParseAny(yaml): SafeParseAnyResult

Defined in: packages/core/src/parser/yaml-parser.ts:1072

Detect the document type of a YAML string and validate it against the matching schema

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse (a map block, a scrollytelling block, or a root document)

Returns

SafeParseAnyResult

Discriminated result with the detected block type and the corresponding safeParse result

Remarks

Dispatches on the document’s top-level type: field:

• type: map → safeParseMapBlock
• type: scrollytelling → safeParseScrollytellingBlock
• no type: but a pages: key → safeParse (root document)

Any other type: value produces a failure result listing the valid values, as does a document that has neither type: nor pages:. This method never throws.

Example

const { blockType, result } = YAMLParser.safeParseAny(yamlString);
if (!result.success) {
  result.errors.forEach(err => console.error(`${err.path}: ${err.message}`));
} else if (blockType === 'map') {
  renderMap(result.data);
}

---

safeParseMapBlock()

static safeParseMapBlock(yaml): ParseResult<{[key: string]: any; }>

Defined in: packages/core/src/parser/yaml-parser.ts:847

Parse YAML string for a single map block, returning a result object

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse (should be a map block, not a full document)

Returns

ParseResult<{[key: string]: any; }>

Result object with success flag and either data or errors

Remarks

This is the non-throwing version of parseMapBlock. Instead of throwing errors, it returns a result object that indicates success or failure. Use this when you want to handle errors gracefully without try/catch.

Example

const result = YAMLParser.safeParseMapBlock(yamlString);
if (result.success) {
  console.log('Map config:', result.data);
} else {
  result.errors.forEach(err => {
    console.error(`Error at ${err.path}: ${err.message}`);
  });
}

---

safeParseMapBlockValue()

static safeParseMapBlockValue(value): ParseResult<{[key: string]: any; }>

Defined in: packages/core/src/parser/yaml-parser.ts:920

Validate an already-parsed map block — a JSON attribute, or a config object set programmatically.

Parameters

Parameter	Type
value	unknown

Returns

ParseResult<{[key: string]: any; }>

Remarks

The YAML entry points validate; these did not, so a well-formed object that failed the schema went straight to the renderer and produced a broken map with no diagnostic. Reuses the YAML pipeline by round-tripping through YAML, so errors, unknown-key suggestions and deprecation warnings are identical across every entry path.

Positions are stripped: they would refer to the serialized YAML, not to anything the caller wrote, and a line number pointing at text the author never saw is worse than none.

---

safeParseScrollytellingBlock()

static safeParseScrollytellingBlock(yaml): ParseResult<{[key: string]: any; }>

Defined in: packages/core/src/parser/yaml-parser.ts:1034

Parse YAML string for a scrollytelling block, returning a result object

Parameters

Parameter	Type	Description
yaml	string	YAML string to parse (should be a scrollytelling block, not a full document)

Returns

ParseResult<{[key: string]: any; }>

Result object with success flag and either data or errors

Remarks

This is the non-throwing version of parseScrollytellingBlock. Instead of throwing errors, it returns a result object that indicates success or failure. Use this when you want to handle errors gracefully without try/catch.

Example

const result = YAMLParser.safeParseScrollytellingBlock(yamlString);
if (result.success) {
  console.log('Scrollytelling config:', result.data);
} else {
  result.errors.forEach(err => {
    console.error(`Error at ${err.path}: ${err.message}`);
  });
}

---

validate()

static validate(config): any

Defined in: packages/core/src/parser/yaml-parser.ts:752

Validate a JavaScript object against the schema

Parameters

Parameter	Type	Description
config	unknown	JavaScript object to validate

Returns

any

Validated configuration object

Throws

If validation fails

Remarks

This method bypasses YAML parsing and directly validates a JavaScript object. Useful when you already have a parsed object (e.g., from JSON.parse) and just want to validate and resolve references.

Example

const jsConfig = JSON.parse(jsonString);
const validated = YAMLParser.validate(jsConfig);