{"_id":"@577-industries/workflow-dag","name":"@577-industries/workflow-dag","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@577-industries/workflow-dag","version":"1.0.0","description":"YAML-to-DAG workflow compiler with Kahn's topological sort, cycle detection, and parallel group identification","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit"},"keywords":["workflow","dag","topological-sort","kahn","yaml","compiler","orchestration","parallel"],"author":{"name":"577 Industries"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/577-industries/workflow-dag.git"},"homepage":"https://www.577industries.com/forge","dependencies":{"yaml":"^2.7.0"},"devDependencies":{"tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@577-industries/workflow-dag@1.0.0","gitHead":"94819bcc2b9159837791c837ed3338fe1d2a1b8b","bugs":{"url":"https://github.com/577-industries/workflow-dag/issues"},"_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-SCSuAXV7pVkxjS6NGU0jATdjlLH8gp4TxjSilaQ6j5JzeYEgMFbmoI5OwHSnzy31kDCgXiqLmwJF+SEIMgFn4A==","shasum":"9041c8cb25f252b36fdfc4549e17baec8d1f0620","tarball":"https://registry.npmjs.org/@577-industries/workflow-dag/-/workflow-dag-1.0.0.tgz","fileCount":7,"unpackedSize":30535,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDg6/izNeur76eNQ7k2vOCQoV0fgjZzzrUJIyuwbD4VFAIhAMzZkSSsfKypcuM+qQhMSmmZo4C3ayuHrvl03H9Wzob8"}]},"_npmUser":{"name":"577industries","email":"t.waweru@577industries.com"},"directories":{},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/workflow-dag_1.0.0_1773252943188_0.6713276724575843"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T18:15:43.081Z","1.0.0":"2026-03-11T18:15:43.335Z","modified":"2026-03-11T18:15:43.633Z"},"maintainers":[{"name":"577industries","email":"t.waweru@577industries.com"}],"description":"YAML-to-DAG workflow compiler with Kahn's topological sort, cycle detection, and parallel group identification","homepage":"https://www.577industries.com/forge","keywords":["workflow","dag","topological-sort","kahn","yaml","compiler","orchestration","parallel"],"repository":{"type":"git","url":"git+https://github.com/577-industries/workflow-dag.git"},"author":{"name":"577 Industries"},"bugs":{"url":"https://github.com/577-industries/workflow-dag/issues"},"license":"Apache-2.0","readme":"# @577-industries/workflow-dag\r\n\r\n[![npm version](https://img.shields.io/npm/v/@577-industries/workflow-dag)](https://www.npmjs.com/package/@577-industries/workflow-dag)\r\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\r\n\r\nA YAML-to-DAG workflow compiler that uses Kahn's topological sort to determine execution order, detect cycles, and identify steps that can run in parallel.\r\n\r\nImplements the core algorithm described in the **\"Workflow DAG Compiler\"** patent (March 2026) by 577 Industries.\r\n\r\n## How It Works\r\n\r\n```\r\n                    ┌──────────┐\r\n  YAML Definition → │  Parser  │\r\n                    └────┬─────┘\r\n                         │\r\n                    ┌────▼─────┐\r\n                    │ Compiler │ ← Kahn's Algorithm\r\n                    └────┬─────┘\r\n                         │\r\n              ┌──────────┼──────────┐\r\n              │          │          │\r\n         ┌────▼───┐ ┌───▼────┐ ┌──▼───────┐\r\n         │ Order  │ │ Groups │ │ Mermaid  │\r\n         └────────┘ └────────┘ └──────────┘\r\n```\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install @577-industries/workflow-dag\r\n```\r\n\r\n```typescript\r\nimport { parseYaml, compileWorkflow, toMermaid } from \"@577-industries/workflow-dag\";\r\n\r\nconst yaml = `\r\nname: deploy-pipeline\r\nsteps:\r\n  - id: build\r\n    task: compile_code\r\n  - id: test_unit\r\n    task: run_unit_tests\r\n    depends_on: [build]\r\n  - id: test_e2e\r\n    task: run_e2e_tests\r\n    depends_on: [build]\r\n  - id: deploy\r\n    task: deploy_to_prod\r\n    depends_on: [test_unit, test_e2e]\r\n`;\r\n\r\nconst definition = parseYaml(yaml);\r\nconst dag = compileWorkflow(definition);\r\n\r\nconsole.log(dag.executionOrder);\r\n// → [\"build\", \"test_unit\", \"test_e2e\", \"deploy\"]\r\n\r\nconsole.log(dag.parallelGroups);\r\n// → [[\"build\"], [\"test_unit\", \"test_e2e\"], [\"deploy\"]]\r\n\r\nconsole.log(toMermaid(dag));\r\n// → graph TD\r\n//     build[\"compile_code\"]\r\n//     test_unit[\"run_unit_tests\"]\r\n//     ...\r\n```\r\n\r\n## API Reference\r\n\r\n### `parseYaml(yamlString: string): WorkflowDefinition`\r\n\r\nParses a YAML string into a validated workflow definition.\r\n\r\n### `compileWorkflow(definition: WorkflowDefinition): CompiledDag`\r\n\r\nCompiles a workflow definition into a DAG with execution order and parallel groups. Throws `CycleDetectedError` if a cycle exists, or `InvalidDependencyError` if a step references a nonexistent dependency.\r\n\r\n### `toMermaid(dag: CompiledDag): string`\r\n\r\nGenerates a Mermaid graph diagram from a compiled DAG.\r\n\r\n### `simulate(dag: CompiledDag): SimulationResult`\r\n\r\nDry-runs the DAG, estimating total execution time based on step timeouts and parallelism.\r\n\r\n### Types\r\n\r\n| Type | Description |\r\n|------|-------------|\r\n| `WorkflowDefinition` | Input workflow with name, steps, and metadata |\r\n| `WorkflowStep` | A single step: id, task, depends_on, condition, timeout |\r\n| `DagNode` | Compiled node with resolved dependencies |\r\n| `CompiledDag` | Full compilation result: nodes, order, parallel groups |\r\n| `SimulationResult` | Dry-run result with group timing estimates |\r\n\r\n### Error Types\r\n\r\n| Error | When |\r\n|-------|------|\r\n| `CycleDetectedError` | Workflow contains circular dependencies |\r\n| `InvalidDependencyError` | Step references a nonexistent dependency |\r\n\r\n## Architecture\r\n\r\nThis library implements Kahn's algorithm for topological sorting:\r\n\r\n1. **Parse** — YAML → validated WorkflowDefinition\r\n2. **Build adjacency** — compute in-degree for each node\r\n3. **Process zero-degree nodes** — in batches (each batch = parallel group)\r\n4. **Detect cycles** — if unprocessed nodes remain after sort, a cycle exists\r\n\r\nBased on the [\"Workflow DAG Compiler\" patent](https://www.577industries.com/forge) by 577 Industries.\r\n\r\n---\r\n\r\nExtracted from [FORGE OS](https://www.577industries.com) by **577 Industries**.\r\n","readmeFilename":"README.md","_rev":"1-c690941986f7a951813768b311d00a45"}