AST Nodes

class Scalar<T = unknown> {
  /** Scalar value */
  value: T;
  
  /** Node type identifier */
  type?: 'BLOCK_FOLDED' | 'BLOCK_LITERAL' | 'PLAIN' | 'QUOTE_DOUBLE' | 'QUOTE_SINGLE';
  
  /** Comment after the scalar */
  comment?: string | null;
  
  /** Comment before the scalar */
  commentBefore?: string | null;
  
  /** Spacing before the node */
  spaceBefore?: boolean;
  
  /** Source range information */
  range?: Range;
  
  /** Anchor name if present */
  anchor?: string | null;
  
  /** Tag information */
  tag?: string | null;
  
  /** Format settings */
  format?: 'BIN' | 'HEX' | 'OCT' | 'TIME' | string;
  
  /** Minimum number of fractional digits for numbers */
  minFractionDigits?: number;
  
  /**
   * Create scalar node
   * @param value - Scalar value
   */
  constructor(value: T);
  
  /** Convert to JSON representation */
  toJSON(): any;
  
  /** Convert to YAML string */
  toString(): string;
  
  // Static formatting constants
  static readonly BLOCK_FOLDED: 'BLOCK_FOLDED';
  static readonly BLOCK_LITERAL: 'BLOCK_LITERAL';
  static readonly PLAIN: 'PLAIN';
  static readonly QUOTE_DOUBLE: 'QUOTE_DOUBLE';
  static readonly QUOTE_SINGLE: 'QUOTE_SINGLE';
}

import { Scalar } from "yaml";

// Basic scalar creation
const stringScalar = new Scalar("Hello World");
const numberScalar = new Scalar(42);
const booleanScalar = new Scalar(true);

// Formatted scalars
const multilineScalar = new Scalar("Line 1\nLine 2\nLine 3");
multilineScalar.type = Scalar.BLOCK_LITERAL;

const quotedScalar = new Scalar("Text with spaces");
quotedScalar.type = Scalar.QUOTE_DOUBLE;

// With comments
const commentedScalar = new Scalar(100);
commentedScalar.comment = " Maximum value";
commentedScalar.commentBefore = " Configuration setting";

// With anchors and tags
const anchoredScalar = new Scalar("shared-value");
anchoredScalar.anchor = "shared";
anchoredScalar.tag = "!!str";

console.log(commentedScalar.toString());
// # Configuration setting
// 100 # Maximum value

class YAMLMap<K = unknown, V = unknown> extends Collection {
  /** Map items as array of pairs */
  items: Pair<K, V>[];
  
  /** Collection flow style */
  flow?: boolean;
  
  /** Comment after the collection */
  comment?: string | null;
  
  /** Comment before the collection */
  commentBefore?: string | null;
  
  /** Spacing before the node */
  spaceBefore?: boolean;
  
  /** Tag name for this collection type */
  static readonly tagName: '!!map';
  
  /**
   * Create YAMLMap from object
   * @param schema - Schema to use
   * @param obj - Object to convert
   * @param ctx - Creation context
   * @returns YAMLMap instance
   */
  static from(schema: Schema, obj: unknown, ctx: CreateNodeContext): YAMLMap;
  
  /**
   * Create empty map
   * @param schema - Schema to use
   */
  constructor(schema?: Schema);
  
  /**
   * Add key-value pair to map
   * @param pair - Pair to add or plain object
   * @param overwrite - Whether to overwrite existing keys
   */
  add(pair: Pair | { key: any; value: any }, overwrite?: boolean): void;
  
  /**
   * Delete key from map
   * @param key - Key to delete
   * @returns True if key was deleted
   */
  delete(key: unknown): boolean;
  
  /**
   * Get value for key
   * @param key - Key to retrieve
   * @param keepScalar - Keep scalar nodes instead of values
   * @returns Value for key
   */
  get(key: unknown, keepScalar?: boolean): unknown;
  
  /**
   * Check if map has key
   * @param key - Key to check
   * @returns True if key exists
   */
  has(key: unknown): boolean;
  
  /**
   * Set value for key
   * @param key - Key to set
   * @param value - Value to set
   */
  set(key: any, value: any): void;
  
  /** Convert to JSON object */
  toJSON(): any;
  
  /** Convert to YAML string */
  toString(): string;
}

import { YAMLMap, Scalar, Pair } from "yaml";

// Create empty map
const map = new YAMLMap();

// Add key-value pairs
map.add({ key: 'name', value: 'John Doe' });
map.add({ key: 'age', value: 30 });
map.add({ key: 'active', value: true });

// Using Pair objects
const emailPair = new Pair('email', 'john@example.com');
emailPair.comment = ' Contact information';
map.add(emailPair);

// Set values directly
map.set('location', 'New York');
map.set('skills', ['JavaScript', 'TypeScript', 'Node.js']);

// Access values
console.log(map.get('name')); // 'John Doe'
console.log(map.has('email')); // true

// Flow style
map.flow = true; // Use flow notation: {key: value, ...}

console.log(map.toString());

class YAMLSeq<T = unknown> extends Collection {
  /** Sequence items */
  items: T[];
  
  /** Collection flow style */
  flow?: boolean;
  
  /** Comment after the collection */
  comment?: string | null;
  
  /** Comment before the collection */
  commentBefore?: string | null;
  
  /** Spacing before the node */
  spaceBefore?: boolean;
  
  /** Tag name for this collection type */
  static readonly tagName: '!!seq';
  
  /**
   * Create YAMLSeq from array
   * @param schema - Schema to use
   * @param obj - Array to convert
   * @param ctx - Creation context
   * @returns YAMLSeq instance
   */
  static from(schema: Schema, obj: unknown, ctx: CreateNodeContext): YAMLSeq;
  
  /**
   * Create empty sequence
   * @param schema - Schema to use
   */
  constructor(schema?: Schema);
  
  /**
   * Add value to sequence
   * @param value - Value to add
   * @returns Index of added item
   */
  add(value: T): number;
  
  /**
   * Delete item at index
   * @param index - Index to delete
   * @returns True if item was deleted
   */
  delete(index: number): boolean;
  
  /**
   * Get item at index
   * @param index - Index to retrieve
   * @param keepScalar - Keep scalar nodes instead of values
   * @returns Item at index
   */
  get(index: number, keepScalar?: boolean): unknown;
  
  /**
   * Check if sequence has item at index
   * @param index - Index to check
   * @returns True if index exists
   */
  has(index: number): boolean;
  
  /**
   * Set item at index
   * @param index - Index to set
   * @param value - Value to set
   */
  set(index: number, value: T): void;
  
  /** Convert to JSON array */
  toJSON(): any;
  
  /** Convert to YAML string */
  toString(): string;
}

import { YAMLSeq, Scalar } from "yaml";

// Create sequence
const seq = new YAMLSeq();

// Add items
seq.add('item1');
seq.add('item2');
seq.add(42);
seq.add(true);

// Add complex items
const nestedMap = new YAMLMap();
nestedMap.set('nested', 'value');
seq.add(nestedMap);

// Access items
console.log(seq.get(0)); // 'item1'
console.log(seq.has(2)); // true

// Modify items
seq.set(1, 'modified-item2');
seq.delete(3); // Remove boolean

// Flow style
seq.flow = true; // Use flow notation: [item1, item2, ...]

console.log(seq.toString());

class Pair<K = unknown, V = unknown> {
  /** Pair key */
  key: K;
  
  /** Pair value */
  value: V;
  
  /** Comment after the pair */
  comment?: string | null;
  
  /** Comment before the pair */
  commentBefore?: string | null;
  
  /** Spacing before the pair */
  spaceBefore?: boolean;
  
  /** Source range information */
  range?: Range;
  
  /**
   * Create key-value pair
   * @param key - Key for the pair
   * @param value - Value for the pair
   */
  constructor(key: K, value?: V);
  
  /** Create deep clone of pair */
  clone(): Pair<K, V>;
  
  /** Convert to JSON representation */
  toJSON(): { key: any; value: any };
  
  /** Convert to YAML string */
  toString(): string;
}

class Alias {
  /** Source node being referenced */
  source: Node;
  
  /** Comment after the alias */
  comment?: string | null;
  
  /** Comment before the alias */
  commentBefore?: string | null;
  
  /** Spacing before the alias */
  spaceBefore?: boolean;
  
  /** Source range information */
  range?: Range;
  
  /**
   * Create alias node
   * @param source - Node to reference
   */
  constructor(source: Node);
  
  /**
   * Resolve alias to its target value
   * @param doc - Document context
   * @returns Resolved value
   */
  resolve(doc: Document): unknown;
  
  /** Convert to JSON (resolves to source value) */
  toJSON(_arg?: unknown, ctx?: ToJSContext): unknown;
  
  /** Convert to YAML string */
  toString(): string;
}

import { parseDocument, Alias } from "yaml";

// Create document with anchored node
const doc = parseDocument(`
defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com
`);

// Create new alias programmatically
const defaultsNode = doc.get(['defaults'], true);
if (defaultsNode) {
  const alias = new Alias(defaultsNode);
  doc.set(['development'], alias);
}

console.log(doc.toString());

abstract class Collection {
  /** Collection items */
  items: unknown[];
  
  /** Collection schema */
  schema?: Schema;
  
  /** Collection flow style */
  flow?: boolean;
  
  /** Comment after the collection */
  comment?: string | null;
  
  /** Comment before the collection */
  commentBefore?: string | null;
  
  /** Spacing before the collection */
  spaceBefore?: boolean;
  
  /** Source range information */
  range?: Range;
  
  /** Anchor name if present */
  anchor?: string | null;
  
  /** Tag information */
  tag?: string | null;
  
  /** Convert to JSON representation */
  abstract toJSON(): any;
  
  /** Convert to YAML string */
  abstract toString(): string;
}

type Node = Alias | Scalar | YAMLMap | YAMLSeq;
type ParsedNode = Alias | Scalar<any> | YAMLMap<any, any> | YAMLSeq<any>;
type Collection = YAMLMap | YAMLSeq;

type Range = [start: number, valueEnd: number, nodeEnd: number];

interface CreateNodeContext {
  /** Node creation options */
  options: CreateNodeOptions;
  /** Document schema */
  schema: Schema;
}