⦿ DAG + FSM architecture framework for TypeScript: type-safe nodes, abortable execution, deterministic resume, and JSON-LD canonical wire format.
The full documentation is published at https://studnicky.github.io/Dagonizer/.
- Getting Started
- Architecture: DAG, Node, Placement kinds
- Concepts: state lifecycle, placement routing, fan-out
- DAGBuilder: fluent authoring API
- Lifecycle / FSM: DAGLifecycleMachine, state transitions
- Cancellation & Retry: abort signals, deadlines, backoff strategies
- Checkpoint / Resume: deterministic pause and resume
- Schema & JSON-LD: JSON Schema validation, canonical wire format
- The Archivist: in-browser demo running on Dagonizer
- The Cartographer: deterministic logistics pipeline demo
pnpm run cipasses with all package and example tests, docs checks, and lints.pnpm run docs:buildgenerates the GitHub Pages site successfully.- Example DAGs are lint-validated and stable; docs snippets are all type-checked.
examples/the-cartographerandexamples/the-archivistare part of the validated example test set.
Node.js >= 24 (matches engines.node in package.json).
Dagonizer ships as a workspace of independently versioned plugins:
| Tier | Packages |
|---|---|
| Adapters (LLM backends) | @studnicky/dagonizer-adapter-{anthropic,gemini-api,gemini-nano,ollama,web-llm} |
| Embedders (vector backends) | @studnicky/dagonizer-embedder-{gemini-api,mistral,ollama,tensorflow,transformers,web-llm} |
| Tools (concrete) | @studnicky/dagonizer-tool-{openlibrary,googlebooks,wikipedia} |
| Patterns (abstract bases consumers extend) | @studnicky/dagonizer-patterns-{rag,graph,flow} |
Install only what you use. The main @studnicky/dagonizer package exposes three stable contract subpaths every plugin builds on: ./adapter, ./patterns, ./tool. See the plugins guide for the full story.
npm install @studnicky/dagonizer
# plus any plugins you want, for example:
npm install @studnicky/dagonizer-adapter-anthropic @studnicky/dagonizer-patterns-ragThe package is also mirrored to GitHub Packages as @studnicky/dagonizer:
echo '@studnicky:registry=https://npm.pkg.github.com' >> .npmrc
npm install @studnicky/dagonizerMIT. See LICENSE.
See CHANGELOG.md and the GitHub releases.
The name compresses the three ideas the project is built on.
The structure — a DAG. The engine executes a Directed Acyclic Graph: steps joined by forward-only edges, with no cycles, so the steps always admit a well-defined execution order. Engineers compose DAGs constantly — build graphs, task schedulers, spreadsheet recalculation, linker symbol resolution, and now agent tool-call chains — often without naming the structure as such. Dagonizer makes the DAG the explicit, type-safe unit of composition.
The role — an orchestrator. In H. P. Lovecraft's fiction, Dagon is the primordial deity that presides over the submerged multitudes of the Deep Ones — first evoked in the 1919 short story of the same name. The image fits an engine whose job is to marshal many small autonomous workers — LLM agents, ETL stages — through one coordinated flow. The workers are the multitude; Dagonizer is what directs them.
The shape — ports and adapters. Backends plug into Dagonizer through adapter contracts — LlmAdapterInterface, StoreInterface, ClockProviderInterface, and the rest — never through callbacks or function-passing. That is the hexagonal "ports and adapters" architecture described by Alistair Cockburn: capabilities snap together at the boundary like interchangeable parts, and the core stays closed to modification.
Read together, Dagonizer is "the orchestrator of the DAGs." Spoken aloud it also resolves to dag-on-eyes-er — a deliberate nod to the Eye of Dagon, and to a logo that is meant to be just slightly unsettling.