gorango Compiler Workflows (Alpha)
Flowcraft's compiler transforms imperative TypeScript into declarative blueprints at build time. Write familiar async functions with control flow — the compiler generates the graph.
[!WARNING] The compiler is in alpha. Contributions are welcome.
Quick start
Installation
npm install --save-dev @flowcraft/compiler
Write a workflow
/** @flow */
export async function myWorkflow(input: string) {
const data = await fetchData(input)
const result = await processData(data)
return result
}
/** @step */
async function fetchData(input: string) {
// Implementation — this becomes a durable node
return fetch(`/api/data?q=${input}`).then((r) => r.json())
}
/** @step */
async function processData(data: unknown) {
// Implementation — this becomes a durable node
return { processed: true, data }
}
Execute
import { FlowRuntime } from 'flowcraft'
import manifest from './generated/manifest'
const runtime = new FlowRuntime()
const result = await runtime.run(manifest['myWorkflow'], { input: 'hello' })
The Golden Rules
- **Mark orchestrators with
/** @flow \*/** — Functions that define workflow orchestration - **Mark durable operations with
/** @step \*/** — Async operations that should be retried/tracked - Never await plain async functions — The compiler errors if you await a non-
@stepfunction
Supported Control Flow
| Pattern | Syntax | Compiles to |
|---|---|---|
| Sequential | await stepA(); await stepB() |
Linear nodes with edges |
| Conditional | if/else with @step calls |
Conditional edges with actions |
| Switch | switch(val) { case ... } with @step calls |
Conditional multi-branch |
| Loops | for/while/do-while with @step calls |
Loop controller node |
| Fallbacks | try/catch/finally with @step calls |
Fallback/finally node routing |
| Parallelism | Promise.all([...]), Promise.allSettled([...]), Promise.race([...]) |
Fan-out/fan-in with join |
| Subflows | await otherFlow(input) |
Subflow node |
Configuration
Create flowcraft.config.ts:
import { defineConfig } from '@flowcraft/compiler'
export default defineConfig({
entryPoints: ['./src/workflows/**/*.ts'],
manifestPath: './src/generated/manifest.ts',
tsConfigPath: './tsconfig.json',
})
Build Tool Integration
Compilation happens automatically with plugins:
// vite.config.ts
import flowcraft from '@flowcraft/plugin-vite'
export default {
plugins: [flowcraft()],
}
Available plugins: Vite, Next.js, Nuxt, Astro, esbuild, tsup.
Unsupported Syntax
- Complex variable re-assignments within loops
- Dynamic function calls or
eval - Generator functions or async generators
- Class methods as steps (use standalone functions)
Runtime compilation (compileCode)
For testing, REPL environments, or low-frequency runtime configuration, use compileCode() to compile raw TypeScript strings into blueprints:
import { compileCode } from '@flowcraft/compiler'
const { blueprint, diagnostics } = compileCode(
`
/** @flow */
export async function myFlow() {
const data = await fetchData()
return await processData(data)
}
/** @step */
async function fetchData() { return { value: 42 } }
/** @step */
async function processData(d: any) { return { result: d.value * 2 } }
`,
{ id: 'myFlow' },
)
Note:
compileCode()writes temporary files and spins up a full compiler instance per call. For production, always use pre-compiled builds viacompileProject()or framework plugins.
Advanced topics
- Authoring detailed patterns: See authoring-guide.md
- Configuration options: See configuration.md