{"_id":"@bakes/dastardly-yaml","name":"@bakes/dastardly-yaml","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@bakes/dastardly-yaml","version":"1.0.0","description":"YAML parser and serializer for dASTardly","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"keywords":["yaml","parser","serializer","ast","tree-sitter"],"author":{"name":"The Software Bakery"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/thesoftwarebakery/dastardly.git","directory":"packages/yaml"},"homepage":"https://github.com/thesoftwarebakery/dastardly#readme","bugs":{"url":"https://github.com/thesoftwarebakery/dastardly/issues"},"publishConfig":{"access":"public"},"dependencies":{"@tree-sitter-grammars/tree-sitter-yaml":"^0.7.1","tree-sitter":"^0.22.4","@bakes/dastardly-core":"^1.0.0","@bakes/dastardly-tree-sitter-runtime":"^1.0.0"},"devDependencies":{"@types/benchmark":"^2.1.5","@types/node":"^24.10.0","@vitest/ui":"^1.6.1","benchmark":"^2.1.4","js-yaml":"^4.1.0","typescript":"^5.3.0","vitest":"^1.6.1"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","benchmark":"pnpm build && npx tsx benchmarks/run.ts"},"_id":"@bakes/dastardly-yaml@1.0.0","_integrity":"sha512-tZowqOWH8hBO0uLPrw9bfkDyiiCFMg5R5oDIL9uTmt8eRKFbDpK7aceZlhG0C6r/mGAxdE9rByeHiDqeN5npvg==","_resolved":"/tmp/bb539fb2ebedfa8e849fee2dcd6b773c/bakes-dastardly-yaml-1.0.0.tgz","_from":"file:bakes-dastardly-yaml-1.0.0.tgz","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tZowqOWH8hBO0uLPrw9bfkDyiiCFMg5R5oDIL9uTmt8eRKFbDpK7aceZlhG0C6r/mGAxdE9rByeHiDqeN5npvg==","shasum":"c3a8625094c16188296126e6e1f855391be0e4a4","tarball":"https://registry.npmjs.org/@bakes/dastardly-yaml/-/dastardly-yaml-1.0.0.tgz","fileCount":19,"unpackedSize":94665,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bakes%2fdastardly-yaml@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCfg36dUlvAAR7QTaFT318iHT+m8JdIbfiW/cyTTx4QgwIgLlFZb/HWLtv7NJB7y8mtfdRCa0Q7z8V2vM/i5kHloSU="}]},"_npmUser":{"name":"georgewaters","email":"george@bakes.software"},"directories":{},"maintainers":[{"name":"georgewaters","email":"george@bakes.software"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dastardly-yaml_1.0.0_1763161275422_0.2799151094279835"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-14T23:01:15.304Z","1.0.0":"2025-11-14T23:01:15.618Z","modified":"2025-11-14T23:01:16.219Z"},"maintainers":[{"name":"georgewaters","email":"george@bakes.software"}],"description":"YAML parser and serializer for dASTardly","homepage":"https://github.com/thesoftwarebakery/dastardly#readme","keywords":["yaml","parser","serializer","ast","tree-sitter"],"repository":{"type":"git","url":"git+https://github.com/thesoftwarebakery/dastardly.git","directory":"packages/yaml"},"author":{"name":"The Software Bakery"},"bugs":{"url":"https://github.com/thesoftwarebakery/dastardly/issues"},"license":"MIT","readme":"# @bakes/dastardly-yaml\n\nHigh-performance YAML parser and serializer for dASTardly, built with Tree-sitter.\n\n## Installation\n\n```bash\nnpm install @bakes/dastardly-yaml @bakes/dastardly-core\n```\n\n```bash\npnpm add @bakes/dastardly-yaml @bakes/dastardly-core\n```\n\n## Overview\n\n`@bakes/dastardly-yaml` provides a blazing-fast YAML 1.2 parser and serializer that converts YAML to dASTardly's format-agnostic AST. Built on tree-sitter for real-time editor performance with full position tracking for precise error reporting.\n\n**Key Features:**\n- **High performance** - Tree-sitter-based parsing (36-52x faster than traditional parsers)\n- **Position tracking** - Every node tracks source location (line, column, offset)\n- **Full YAML 1.2 support** - Anchors, aliases, tags, merge keys, block scalars\n- **Type-safe** - Full TypeScript support with strict mode\n- **Comprehensive** - Handles all YAML types and advanced features\n- **Format-agnostic AST** - Convert to/from other formats (JSON, CSV, etc.)\n\n## Quick Start\n\n### Parsing\n\n```typescript\nimport { parse } from '@bakes/dastardly-yaml';\n\n// Parse to DocumentNode (includes document wrapper)\nconst doc = parse('name: Alice\\nage: 30');\nconsole.log(doc.type); // 'Document'\nconsole.log(doc.body.type); // 'Object'\n\n// Access the data directly\nconst obj = doc.body;\nconsole.log(obj.properties[0].key.value); // 'name'\n```\n\n### Serializing\n\n```typescript\nimport { serialize } from '@bakes/dastardly-yaml';\nimport { parse } from '@bakes/dastardly-yaml';\n\nconst doc = parse('name: Alice');\n\n// Block style (default)\nconst block = serialize(doc);\n// name: Alice\n\n// Flow style (compact JSON-like)\nconst flow = serialize(doc, { style: 'flow' });\n// {name: Alice}\n\n// Custom indentation\nconst indented = serialize(doc, { indent: 4 });\n```\n\n### Roundtrip\n\n```typescript\nimport { parse, serialize } from '@bakes/dastardly-yaml';\n\nconst source = 'name: Alice\\nage: 30';\nconst doc = parse(source);\nconst output = serialize(doc);\n// Preserves data structure, reformats with specified style\n```\n\n## API Reference\n\n### Package Object\n\nThe package exports a `yaml` object implementing the `FormatPackage` interface:\n\n```typescript\nimport { yaml } from '@bakes/dastardly-yaml';\n\nconst doc = yaml.parse('name: Alice');\nconst output = yaml.serialize(doc);\n```\n\n### Convenience Functions\n\nFor convenience, `parse` and `serialize` are also exported as standalone functions (destructured from the `yaml` object):\n\n#### `parse(source)`\n\nParse YAML string into a DocumentNode:\n\n```typescript\nfunction parse(source: string): DocumentNode;\n```\n\n**Parameters:**\n- `source` - YAML string to parse\n\n**Returns:** `DocumentNode` with YAML parsed into AST\n\n**Throws:** `ParseError` if source is invalid YAML\n\n**Example:**\n\n```typescript\nimport { parse } from '@bakes/dastardly-yaml';\n\n// Simple object\nconst doc1 = parse('name: Alice\\nage: 30');\n\n// Array\nconst doc2 = parse('- apple\\n- banana\\n- cherry');\n\n// Nested structure\nconst doc3 = parse(`\nperson:\n  name: Alice\n  address:\n    city: Portland\n    state: OR\n`);\n```\n\n#### `serialize(node, options?)`\n\nSerialize AST to YAML string:\n\n```typescript\nfunction serialize(\n  node: DocumentNode | DataNode,\n  options?: YAMLSerializeOptions\n): string;\n```\n\n**Parameters:**\n- `node` - DocumentNode or DataNode to serialize\n- `options` - Optional serialization options:\n  - `style?: 'block' | 'flow'` - Output style. Default: `'block'`\n  - `indent?: number` - Indentation spaces. Default: `2`\n  - `lineWidth?: number` - Max line width for flow style. Default: `80`\n\n**Returns:** YAML string\n\n**Example:**\n\n```typescript\nimport { serialize } from '@bakes/dastardly-yaml';\n\n// Block style (default, human-readable)\nserialize(doc);\n// name: Alice\n// age: 30\n\n// Flow style (compact, JSON-like)\nserialize(doc, { style: 'flow' });\n// {name: Alice, age: 30}\n\n// Custom indentation\nserialize(doc, { indent: 4 });\n// name: Alice\n// age:\n//     nested: value\n```\n\n## YAML-Specific Features\n\n### Anchors and Aliases\n\nYAML anchors (`&`) and aliases (`*`) allow you to reuse node values:\n\n```typescript\nimport { parse, serialize } from '@bakes/dastardly-yaml';\n\nconst source = `\ndefaults: &defaults\n  timeout: 30\n  retry: 3\n\nproduction:\n  <<: *defaults\n  host: prod.example.com\n\ndevelopment:\n  <<: *defaults\n  host: dev.example.com\n`;\n\nconst doc = parse(source);\n// Anchors are resolved during parsing\n// Both production and development will have timeout and retry fields\n```\n\n**Note:** Anchors are resolved during parsing and stored in node metadata. The serializer does not currently re-create anchors (they are expanded inline).\n\n### Explicit Type Tags\n\nYAML supports explicit type tags:\n\n```typescript\nconst source = `\nbinary: !!binary SGVsbG8=\ntimestamp: !!timestamp 2024-01-15T10:30:00Z\nnull_value: !!null\nstring: !!str 123\n`;\n\nconst doc = parse(source);\n// Tags are stored in node metadata and affect parsing\n```\n\n### Merge Keys\n\nYAML merge keys (`<<`) allow merging map values:\n\n```typescript\nconst source = `\ndefaults: &defaults\n  x: 1\n  y: 2\n\npoint:\n  <<: *defaults\n  z: 3\n`;\n\nconst doc = parse(source);\n// point will have x, y, and z properties\n```\n\n### Block Scalars\n\nYAML supports multi-line strings with literal (`|`) and folded (`>`) styles:\n\n```typescript\n// Literal block scalar (preserves newlines)\nconst literal = parse(`\ndescription: |\n  This is line 1\n  This is line 2\n  This is line 3\n`);\n\n// Folded block scalar (folds newlines to spaces)\nconst folded = parse(`\ndescription: >\n  This is a long paragraph\n  that spans multiple lines\n  but will be folded into one.\n`);\n```\n\n### Multi-Document Support\n\nYAML files can contain multiple documents separated by `---`:\n\n```typescript\nconst source = `\n---\nname: Document 1\n---\nname: Document 2\n`;\n\n// Currently parses as single document with first document content\n// Multi-document support planned for future release\n```\n\n## Types\n\n### YAMLSerializeOptions\n\n```typescript\ninterface YAMLSerializeOptions extends BaseSerializeOptions {\n  style?: 'block' | 'flow';\n  indent?: number;\n  lineWidth?: number;\n}\n```\n\n- **`style`** - Output style:\n  - `'block'` (default) - Human-readable block style with newlines\n  - `'flow'` - Compact JSON-like flow style\n- **`indent`** - Number of spaces for indentation (default: `2`)\n- **`lineWidth`** - Maximum line width for flow style (default: `80`)\n\n## Cross-Format Conversion\n\nConvert between YAML and other formats using dASTardly's common AST:\n\n```typescript\nimport { parse as parseYAML, serialize as serializeYAML } from '@bakes/dastardly-yaml';\nimport { serialize as serializeJSON } from '@bakes/dastardly-json';\n\n// YAML to JSON\nconst yamlSource = 'name: Alice\\nage: 30';\nconst doc = parseYAML(yamlSource);\nconst jsonOutput = serializeJSON(doc, { indent: 2 });\n// {\n//   \"name\": \"Alice\",\n//   \"age\": 30\n// }\n\n// JSON to YAML\nimport { parse as parseJSON } from '@bakes/dastardly-json';\nconst jsonSource = '{\"name\": \"Alice\", \"age\": 30}';\nconst doc2 = parseJSON(jsonSource);\nconst yamlOutput = serializeYAML(doc2);\n// name: Alice\n// age: 30\n```\n\n## Performance\n\nSee [benchmarks/README.md](./benchmarks/README.md) for detailed performance comparisons against popular YAML libraries like js-yaml.\n\n**Summary:**\n- **Parsing**: Competitive with js-yaml, optimized for editor use cases\n- **Serialization**: Fast block and flow style output\n- **Position tracking**: Native support with no performance penalty\n\n## Related Packages\n\n- [`@bakes/dastardly-core`](https://npmjs.com/package/@bakes/dastardly-core) - Core AST types\n- [`@bakes/dastardly-json`](https://npmjs.com/package/@bakes/dastardly-json) - JSON parser/serializer\n- [`@bakes/dastardly-csv`](https://npmjs.com/package/@bakes/dastardly-csv) - CSV parser/serializer\n- [`@bakes/dastardly-validation`](https://npmjs.com/package/@bakes/dastardly-validation) - JSON Schema validator\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-38b6ee3d4dfc68a906a754d2d6e3414f"}