Getting Started with VaakLoom

1. Installation

Install the core engine and optional platform packages in your Node.js project:

# Install with pnpm / npm / yarn
pnpm add @vaakloom/engine @vaakloom/platform

2. Your First Fluent Workflow

VaakLoom provides an expressive, type-safe DSL for building resilient orchestration DAGs:

import { Application, workflow, map, when, fanOut, branch, mockApi } from "@vaakloom/engine";

// Define the declarative workflow
export const orderWorkflow = workflow("orders-create")
  .route("POST", "/orders")
  .search("orderId", "tenantId")
  .tags("orders", "checkout")
  .steps(
    // 1. Enrich / Shape input attributes
    map("annotate", {
      mergeInput: true,
      set: {
        tenantId: "{{attrs.tenantId}}",
        processedAt: "{{now}}",
      },
    }),

    // 2. Conditional branching based on cart amount
    when("{{input.amount}} > 1000", [
      map("flagVip", { mergeInput: true, set: { tier: "VIP" } }),
    ]),

    // 3. Parallel asynchronous fan-out
    fanOut("verify", [
      branch("inventory", mockApi("stockCheck", { inStock: true, ms: 15 })),
      branch("pricing", mockApi("taxService", { taxRate: 0.08, ms: 20 })),
    ], {
      id: "joinCheck",
      kind: "map",
      config: { set: { verified: true, details: "{{input}}" } },
    })
  )
  .build();

// Register with the application server
const app = new Application({
  searchFields: ["tenantId"],
  inject: (req) => ({ tenantId: req.headers?.["x-tenant-id"] || "default" }),
});

app.register(orderWorkflow);
await app.listen({ port: 8787 });
console.log("VaakLoom engine running at http://localhost:8787");

3. Complete Platform (Engine + Hub UI + SQLite + RBAC)

When deploying in production or running locally with visual tracing and management, use @vaakloom/platform:

import { Platform } from "@vaakloom/platform";
import { orderWorkflow } from "./workflows";

const platform = new Platform({
  dbPath: "./data/vaakloom.db",
  protectInvoke: false, // Set to true to require x-api-key for workflow routes
});

platform.register(orderWorkflow);
await platform.listen(8787);

// Platform automatically exposes:
// - Workflow routes: POST /orders
// - Hub Control Plane API: /hub/*
// - Prometheus metrics: GET /metrics
// - Health check: GET /health

4. CLI Commands

VaakLoom includes a zero-config CLI for testing, validating, and serving workflow specs:

# Serve compiled workflow files
vaakloom serve --workflows ./dist/workflows.js --port 8787

# Validate workflow JSON spec without running
vaakloom validate ./orders.workflow.json

# Run Snapline regression comparisons
vaakloom test --workflows ./dist/workflows.js --mode compare

# Export deploy bundle for containerized deployment
vaakloom export --out ./bundle --workflows ./dist/workflows.js

5. Python Parity (Asyncio Engine)

VaakLoom also provides full engine parity in Python with native asyncio:

from vaakloom import Application, workflow, step

wf = (
    workflow("orders-create")
    .route("POST", "/orders")
    .step(step("shape", kind="map", config={"set": {"orderId": "{{input.orderId}}"}}))
    .build()
)

app = Application()
app.register(wf)
app.run(port=8787)

6. Next Steps

• Declarative Workflows — Learn about condition expressions, retries, timeouts, and template interpolation.
• Architecture & Execution — Deep dive into the reactive async model and memory spilling.
• Adapters & Compute — Integrate REST, GraphQL, gRPC, WebSockets, SQL, and background compute workers.
• Interactive Demo — Test sample workflows in the live browser simulator.