Validation

The validateDocument function checks an ElucimDocument for structural errors, missing fields, unknown references, timeline mistakes, and state-machine issues before rendering.

Usage

import { validateDocument } from '@elucim/dsl';

const result = validateDocument(myDocument);

if (result.valid) {
  console.log('Document is valid!');
} else {
  for (const error of result.errors) {
    console.error(`[${error.severity}] ${error.path}: ${error.message}`);
  }
}

Return Type

interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
}

interface ValidationError {
  path: string;       // JSON path to the issue, e.g. "elements.title.props.content"
  message: string;    // Human-readable description
  severity: 'error' | 'warning';
}

The valid field is true only when there are no errors (warnings are allowed).

What Gets Checked

Check	Severity	Example
`version` field present and `'2.0'`	error	Missing or wrong version
`scene` and `elements` are present	error	No scene, or missing element map
All node `type` values are recognized	error	`"type": "sparkle"`
Required fields per node type	error	`circle` missing `cx`
Numeric props are numbers	error	`"r": "big"`
`inputRange` / `outputRange` lengths match	error	Mismatched interpolate ranges
Math expression safety (no dangerous code)	error	`fn: "process.exit()"`
Unused or unknown props	warning	Typo like `"strokWidth"`

Example with Errors

import { validateDocument } from '@elucim/dsl';

const result = validateDocument({
  version: '2.0',
  scene: {
    type: 'player',
    width: 800,
    height: 600,
    fps: 30,
    children: ['sparkle'],
  },
  elements: {
    sparkle: { id: 'sparkle', type: '', props: {} },
  },
});

console.log(result.valid); // false
console.log(result.errors);
// [
//   { path: 'elements.sparkle.type', message: 'Element type is required', severity: 'error' },
// ]

Programmatic Use

Validation is useful for:

CI pipelines — validate JSON or YAML files before deployment
AI agents — check generated documents before rendering
Editors — show inline errors as the user types

import { validateDocument } from '@elucim/dsl';
import fs from 'fs';

const doc = JSON.parse(fs.readFileSync('animation.json', 'utf-8'));
const { valid, errors } = validateDocument(doc);

if (!valid) {
  console.error('Validation failed:');
  errors.forEach(e => console.error(`  ${e.path}: ${e.message}`));
  process.exit(1);
}

For YAML files, use fromYaml() which validates automatically:

import { fromYaml, ElucimYamlError } from '@elucim/dsl';
import fs from 'fs';

try {
  const doc = fromYaml(fs.readFileSync('animation.yaml', 'utf-8'));
  console.log('YAML document is valid!');
} catch (e) {
  if (e instanceof ElucimYamlError) {
    console.error('Validation failed:', e.message);
    e.validationErrors.forEach(err =>
      console.error(`  ${err.path}: ${err.message}`)
    );
    process.exit(1);
  }
  throw e;
}