Loop Engine™

Packages

@loop-engine/dsl

@loop-engine/dsl turns fluent TypeScript or YAML/JSON documents into validated LoopDefinition contracts.

Install

1npm install @loop-engine/dsl

LoopBuilder

1LoopBuilder.create(id: string, domain: string): LoopBuilder

Builder methods implemented in source:

  • .version(v: string): LoopBuilder
  • .description(d: string): LoopBuilder
  • .state(id: string, options?: { isTerminal?: boolean; isError?: boolean }): LoopBuilder
  • .initialState(id: string): LoopBuilder
  • .transition(spec: { id: string; from: string; to: string; actors: ActorType[]; guards?: Partial<GuardSpec>[] }): LoopBuilder
  • .outcome(spec: { id?: string; description?: string; valueUnit?: string; measurable?: boolean; businessMetrics?: ... }): LoopBuilder
  • .build(): LoopDefinition

Fluent example

1import { LoopBuilder } from "@loop-engine/dsl"
2 
3const approval = LoopBuilder
4  .create("expense.approval", "finance")
5  .version("1.0.0")
6  .description("Expense approval loop")
7  .state("SUBMITTED")
8  .state("UNDER_REVIEW")
9  .state("APPROVED", { isTerminal: true })
10  .state("REJECTED", { isTerminal: true })
11  .initialState("SUBMITTED")
12  .transition({
13    id: "start_review",
14    from: "SUBMITTED",
15    to: "UNDER_REVIEW",
16    actors: ["automation"]
17  })
18  .transition({
19    id: "approve",
20    from: "UNDER_REVIEW",
21    to: "APPROVED",
22    actors: ["human"],
23    guards: [
24      {
25        id: "approval_obtained" as never,
26        description: "Manager approval required",
27        failureMessage: "Approval missing",
28        severity: "hard",
29        evaluatedBy: "runtime"
30      }
31    ]
32  })
33  .outcome({
34    id: "expense_approved",
35    description: "Expense approved",
36    valueUnit: "expense_approved",
37    measurable: true
38  })
39  .build()

YAML parsing

1import { parseLoopYaml } from "@loop-engine/dsl"
2 
3const definition = parseLoopYaml(yamlString)

Equivalent YAML for the same loop:

1id: expense.approval
2version: 1.0.0
3description: Expense approval loop
4domain: finance
5states:
6  - id: SUBMITTED
7  - id: UNDER_REVIEW
8  - id: APPROVED
9    isTerminal: true
10  - id: REJECTED
11    isTerminal: true
12initialState: SUBMITTED
13transitions:
14  - id: start_review
15    from: SUBMITTED
16    to: UNDER_REVIEW
17    allowedActors: [automation]
18  - id: approve
19    from: UNDER_REVIEW
20    to: APPROVED
21    allowedActors: [human]
22    guards:
23      - id: approval_obtained
24        description: Manager approval required
25        failureMessage: Approval missing
26        severity: hard
27        evaluatedBy: runtime
28outcome:
29  id: expense_approved
30  description: Expense approved
31  valueUnit: expense_approved
32  measurable: true

See /docs/defining-loops/yaml-format for the full format reference.

Validation and serialization

1import {
2  parseLoopJson,
3  parseLoopFile,
4  serializeToJson,
5  serializeToYaml,
6  validateLoopDefinition
7} from "@loop-engine/dsl"

Validation signature:

1validateLoopDefinition(input: unknown): { valid: boolean; errors: string[]; definition?: LoopDefinition }

Validation failure example:

1{
2  valid: false,
3  errors: ["initialState: initialState must exist in states"]
4}