@origints/yaml 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,173 @@
+# @origints/yaml
+
+> YAML parsing for Origins with anchor/alias/tag preservation and full lineage tracking.
+
+---
+
+## Why
+
+YAML parsers typically discard structural information like anchors, aliases, and tags during parsing. When you need to trace where a value came from in a complex YAML document with references, you're out of luck.
+
+This package preserves YAML's structural features while integrating with Origins' provenance system. Every value can be traced back to its source location, even through anchor references.
+
+---
+
+## Features
+
+- Parse single or multi-document YAML streams
+- Preserve anchors, aliases, and custom tags
+- Full source location tracking for every node
+- Navigation API with type-safe extraction
+- JSON conversion with customizable options
+- Integrates with Origins transform registry
+
+---
+
+## Quick Start
+
+```bash
+npm install @origints/yaml @origints/core
+```
+
+```ts
+import { parseYaml } from "@origints/yaml";
+
+const yaml = `
+name: Alice
+age: 30
+`;
+
+const result = parseYaml(yaml);
+
+if (result.ok) {
+  console.log(result.value.get("name").asString());
+}
+```
+
+Expected output:
+
+```
+Alice
+```
+
+---
+
+## Installation
+
+- Supported platforms:
+  - macOS / Linux / Windows
+- Runtime requirements:
+  - Node.js >= 18
+- Package managers:
+  - npm, pnpm, yarn
+- Peer dependencies:
+  - @origints/core ^0.1.0
+
+```bash
+npm install @origints/yaml @origints/core
+# or
+pnpm add @origints/yaml @origints/core
+```
+
+---
+
+## Usage
+
+### Basic parsing
+
+```ts
+import { parseYaml } from "@origints/yaml";
+
+const result = parseYaml(`
+database:
+  host: localhost
+  port: 5432
+`);
+
+if (result.ok) {
+  const node = result.value;
+  const host = node.get("database").get("host").asString();
+  const port = node.get("database").get("port").asNumber();
+}
+```
+
+### Multi-document streams
+
+```ts
+import { parseYamlAll } from "@origints/yaml";
+
+const result = parseYamlAll(`
+---
+name: doc1
+---
+name: doc2
+`);
+
+if (result.ok) {
+  for (const doc of result.value) {
+    console.log(doc.get("name").asString());
+  }
+}
+```
+
+### Using with Origins plans
+
+```ts
+import { Planner, loadFile, globalRegistry } from "@origints/core";
+import { parseYaml, registerYamlTransforms } from "@origints/yaml";
+
+registerYamlTransforms(globalRegistry);
+
+const plan = Planner.in(loadFile("config.yaml"))
+  .mapIn(parseYaml())
+  .emit((out, $) => {
+    out.add("host", $.get("database").get("host").asString());
+  })
+  .compile();
+```
+
+### Converting to JSON
+
+```ts
+import { parseYaml, toJson } from "@origints/yaml";
+
+const result = parseYaml(yamlString);
+if (result.ok) {
+  const json = toJson(result.value);
+}
+```
+
+---
+
+## Project Status
+
+- **Experimental** - APIs may change
+
+---
+
+## Non-Goals
+
+- Not a YAML serializer (output/writing)
+- Not a schema validator for YAML
+- Not a replacement for js-yaml or yaml packages
+
+---
+
+## Documentation
+
+- See `@origints/core` for Origins concepts
+- See [yaml](https://www.npmjs.com/package/yaml) for underlying parser
+
+---
+
+## Contributing
+
+- Open an issue before large changes
+- Keep PRs focused
+- Tests required for new features
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/yaml",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "YAML parsing for Origins with anchor/alias/tag preservation.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "yaml": "^2.7.1"
   },
@@ -27,20 +34,13 @@
     "@origints/core": "^0.1.0"
   },
   "devDependencies": {
+    "@origints/core": "workspace:*",
     "@types/node": "25.0.6",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "9.39.2",
     "typescript": "5.9.3",
     "vite": "7.3.1",
     "vite-plugin-dts": "4.5.4",
-    "vitest": "4.0.16",
-    "@origints/core": "0.1.0"
-  },
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint \"{src,tests}/**/*.{ts,tsx}\" --max-warnings 0",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "vitest": "4.0.16"
   }
-}
+}