Flowcraft

https://flowcraft.js.org/
Admin
Flowcraft is a workflow engine that orchestrates processes from in-memory scripts to distributed AI...
Tokens:87,530
Snippets:844
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Usage Examples

Source: https://flowcraft.js.org/api/container

Examples demonstrating how to use the DI container.

```APIDOC
### Usage Examples 
#### Basic Usage with Defaults 
```typescript
import { createDefaultContainer, FlowRuntime } from 'flowcraft'

const container = createDefaultContainer()
const runtime = new FlowRuntime(container)
// Container has NullLogger, JsonSerializer, PropertyEvaluator, etc.
```

#### Custom Logger and Registry 
```typescript
import { createDefaultContainer, FlowRuntime, ConsoleLogger } from 'flowcraft'

const container = createDefaultContainer({
	registry: {
		fetchData: async ({ context }) => {
			const data = await apiCall()
			return { output: data }
		},
		processData: async ({ input }) => {
			return { output: input.toUpperCase() }
		},
	},
	logger: new ConsoleLogger(),
})

const runtime = new FlowRuntime(container)
```

#### With Middleware and Dependencies 
```typescript
import { createDefaultContainer, FlowRuntime } from 'flowcraft'

const container = createDefaultContainer({
	middleware: [
		{
			beforeNode: async (ctx, nodeId) => {
				console.log(`Starting ${nodeId}`)
			},
		},
	],
	dependencies: {
		database: new DatabaseClient(),
		cache: new RedisClient(),
	},
})

const runtime = new FlowRuntime(container)
// Nodes can access database and cache via context.dependencies
```

#### Advanced: Custom Services 
```typescript
import { createDefaultContainer, FlowRuntime, ServiceTokens } from 'flowcraft'
import { CustomEvaluator } from './custom-evaluator'

const container = createDefaultContainer({
	evaluator: new CustomEvaluator(),
	eventBus: {
		emit: async (event) => {
			await monitoringService.track(event)
		},
	},
})

// You can also manually register additional services
container.register('customService', new CustomService())

const runtime = new FlowRuntime(container)
```
```

--------------------------------

### Install dependencies

Source: https://flowcraft.js.org/guide/adapters/rabbitmq

Install the required Flowcraft adapter and necessary database clients.

```bash
npm install flowcraft @flowcraft/rabbitmq-adapter amqplib pg ioredis
```

--------------------------------

### Install Azure Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/azure

Install the required Flowcraft adapter and necessary Azure and Redis SDKs.

```bash
npm install flowcraft @flowcraft/azure-adapter @azure/storage-queue @azure/cosmos ioredis
```

--------------------------------

### Install PostgreSQL History Adapter

Source: https://flowcraft.js.org/guide/observability

Install the PostgreSQL history adapter package for enterprise-scale event storage.

```bash
npm install @flowcraft/postgres-history
```

--------------------------------

### Install SQLite History Adapter

Source: https://flowcraft.js.org/guide/observability

Install the SQLite history adapter package for persistent event storage.

```bash
npm install @flowcraft/sqlite-history
```

--------------------------------

### Configure and Start a Worker

Source: https://flowcraft.js.org/guide/adapters/kafka

Initialize the Kafka adapter with required clients and start the worker process.

```typescript
import { KafkaAdapter, RedisCoordinationStore } from '@flowcraft/kafka-adapter'
import { Client as CassandraClient } from 'cassandra-driver'
import { FlowRuntime } from 'flowcraft'
import Redis from 'ioredis'
import { Kafka } from 'kafkajs'

// 1. Define your blueprints and registry
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize service clients
const kafka = new Kafka({ brokers: [process.env.KAFKA_BROKER] })
const cassandraClient = new CassandraClient({
	contactPoints: [process.env.CASSANDRA_HOST],
	localDataCenter: 'datacenter1',
	keyspace: 'flowcraft_ks',
})
const redisClient = new Redis(process.env.REDIS_URL)

// 3. Create a runtime instance
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store
const coordinationStore = new RedisCoordinationStore(redisClient)

// 5. Initialize the adapter
const adapter = new KafkaAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	kafka,
	cassandraClient,
	keyspace: 'flowcraft_ks',
	contextTableName: 'contexts',
	statusTableName: 'statuses',
	topicName: 'flowcraft-jobs',
	groupId: 'flowcraft-workers',
})

// 6. Start the worker
await adapter.start()

console.log('Flowcraft worker with Kafka adapter is running...')
```

--------------------------------

### Install Flowcraft Cloudflare Adapter

Source: https://flowcraft.js.org/guide/adapters/cloudflare

Install the necessary packages to enable Cloudflare support.

```bash
npm install flowcraft @flowcraft/cloudflare-adapter
```

--------------------------------

### Install Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/kafka

Install the core flowcraft package along with the required Kafka, Cassandra, and Redis client drivers.

```bash
npm install flowcraft @flowcraft/kafka-adapter kafkajs cassandra-driver ioredis
```

--------------------------------

### Create a Simple Workflow with Flowcraft

Source: https://flowcraft.js.org/guide/getting-started

Define and run a basic workflow with start, sleep, and double nodes. This example showcases Flowcraft's durable timers and strongly-typed context system.

```typescript
import { createFlow, FlowRuntime, NodeContext } from 'flowcraft'

// 1. Define your functions for the nodes
async function startNode({ context }: NodeContext) {
	const output = await context.get('value')
	return { output }
}
async function doubleNode({ input }: NodeContext) {
	return { output: input * 2 }
}

// 2. Define the workflow structure
const flow = createFlow('simple-workflow')
	.node('start', startNode)
	.sleep('pause', { duration: 1000 }) // Sleep for 1 second
	.node('double', doubleNode)
	.edge('start', 'pause')
	.edge('pause', 'double')

// 3. Initialize the runtime
const runtime = new FlowRuntime()

// 4. Run the workflow
async function run() {
	const pause = await flow.run(runtime, { value: 42 })
	// Resume the workflow after the sleep node
	const result = await flow.resume(runtime, pause.serializedContext, {})

	console.log('Workflow Result:', result)
	// Expected Output:
	// {
	//   "context": {
	//     "value": 42,
	//     "_outputs.start": 42,
	//     "_inputs.double": 42,
	//     "_outputs.double": 84
	//   },
	//   "serializedContext": "{\"value\":42,\"_outputs.start\":42,\"_inputs.double\":42,\"_outputs.double\":84}",
	//   "status": "completed"
	// }
}

run()
```

--------------------------------

### Install Flowcraft Compiler

Source: https://flowcraft.js.org/guide/compiler/configuration

Install the compiler as a development dependency using npm.

```bash
npm install --save-dev @flowcraft/compiler
```

--------------------------------

### Install BullMQ Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/bullmq

Install the required packages for the BullMQ adapter and its Redis dependencies.

```bash
npm install flowcraft @flowcraft/bullmq-adapter bullmq ioredis
```

--------------------------------

### Setup In-Memory Event Store

Source: https://flowcraft.js.org/guide/time-travel

Configure an in-memory event store for development purposes. This is the simplest setup for testing.

```typescript
import { InMemoryEventStore, PersistentEventBusAdapter } from 'flowcraft'

const eventStore = new InMemoryEventStore()
const eventBus = new PersistentEventBusAdapter(eventStore)
const runtime = new FlowRuntime({ eventBus })
```

--------------------------------

### Start Redis for Local Development

Source: https://flowcraft.js.org/guide/adapters/bullmq

Use Docker to quickly spin up a Redis instance for local development.

```bash
docker run -d -p 6379:6379 --name flowcraft-redis redis:7-alpine
```

--------------------------------

### Start Workflow from Client

Source: https://flowcraft.js.org/guide/adapters/azure

Initializes a workflow by creating state in Cosmos DB and enqueuing start jobs to the Azure Queue. Requires the blueprint definition and initial context data.

```typescript
import { analyzeBlueprint } from 'flowcraft'
import { CosmosClient } from '@azure/cosmos'
import { QueueClient } from '@azure/storage-queue'

async function startWorkflow(blueprint, initialContext) {
	const runId = crypto.randomUUID()
	const cosmosClient = new CosmosClient(process.env.COSMOS_DB_CONNECTION_STRING)
	const queueClient = new QueueClient(
		process.env.AZURE_STORAGE_CONNECTION_STRING,
		'your-queue-name',
	)

	// 1. Set initial context and status in Cosmos DB
	const db = cosmosClient.database('your-cosmos-db-name')
	await db.container('workflow-contexts').items.create({ id: runId, ...initialContext })
	await db
		.container('workflow-statuses')
		.items.create({ id: runId, status: 'running', lastUpdated: new Date().toISOString() })

	// 2. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)
	const startJobs = analysis.startNodeIds.map((nodeId) =>
		queueClient.sendMessage(JSON.stringify({ runId, blueprintId: blueprint.id, nodeId })),
	)

	// 3. Enqueue start jobs
	await Promise.all(startJobs)

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Install Flowcraft with npm

Source: https://flowcraft.js.org/guide/getting-started

Install Flowcraft into your project using npm.

```bash
npm install flowcraft
```

--------------------------------

### Install Flowcraft CLI

Source: https://flowcraft.js.org/guide/cli

Install the Flowcraft CLI globally using npm or run it directly with npx.

```bash
npm install -g @flowcraft/cli
# or run with `npx @flowcraft/cli`
```

--------------------------------

### Start a Workflow

Source: https://flowcraft.js.org/guide/adapters/rabbitmq

Initializes a workflow by persisting state to PostgreSQL and publishing start jobs to a RabbitMQ queue.

```typescript
import { analyzeBlueprint } from 'flowcraft'
import amqplib from 'amqplib'
import { Client as PgClient } from 'pg'

async function startWorkflow(blueprint, initialContext) {
	const runId = crypto.randomUUID()
	const pg = new PgClient({ connectionString: process.env.POSTGRES_URL })
	await pg.connect()
	const amqp = await amqplib.connect(process.env.RABBITMQ_URL)

	// 1. Set initial context and status in PostgreSQL
	await pg.query('INSERT INTO flowcraft_contexts (run_id, context_data) VALUES ($1, $2)', [
		runId,
		initialContext,
	])
	await pg.query('INSERT INTO flowcraft_statuses (run_id, status) VALUES ($1, $2)', [
		runId,
		'running',
	])

	// 2. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)

	// 3. Publish start jobs to RabbitMQ
	const channel = await amqp.createChannel()
	const queue = 'flowcraft-jobs'
	await channel.assertQueue(queue, { durable: true })

	analysis.startNodeIds.forEach((nodeId) => {
		const job = Buffer.from(JSON.stringify({ runId, blueprintId: blueprint.id, nodeId }))
		channel.sendToQueue(queue, job, { persistent: true })
	})

	await channel.close()
	await amqp.close()
	await pg.end()

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Example: Parallel Processing with .batch()

Source: https://flowcraft.js.org/guide/batches

This example demonstrates creating a workflow that takes an array of numbers, doubles each one in parallel using `.batch()`, and then sums the results.

```typescript
import { createFlow } from 'flowcraft'

const flow = createFlow('batch-workflow')
	// 1. Start node provides the initial array.
	.node('start', async () => ({ output: [10, 20, 30] }))

	// 2. Define the batch operation.
	.batch(
		'double-items',
		// This worker function will run for each item (10, 20, and 30).
		async ({ input }) => ({ output: input * 2 }),
		{
			inputKey: 'start', // Read the array from the output of the 'start' node.
			outputKey: 'doubled', // Save the results array to `context.doubled`.
		},
	)

	// 3. A final node runs after the batch is complete.
	.node(
		'sum-results',
		// Its input is the array of results from the batch operation.
		async ({ input }) => {
			const sum = input.reduce((acc, val) => acc + val, 0) // 20 + 40 + 60 = 120
			return { output: sum }
		},
		{ inputs: 'doubled' }, // Map the batch output to this node's input.
	)

	// 4. Wire the dependencies.
	// The output of 'start' goes to the scatter part of the batch.
	.edge('start', 'double-items')
	// The output of the gather part of the batch goes to 'sum-results'.
	.edge('double-items', 'sum-results')
	.toBlueprint()
```

--------------------------------

### Configure and Start a Flowcraft Worker

Source: https://flowcraft.js.org/guide/adapters/gcp

Initialize the GCP adapter with the required clients and start the worker process.

```typescript
import { PubSubAdapter, RedisCoordinationStore } from '@flowcraft/gcp-adapter'
import { Firestore } from '@google-cloud/firestore'
import { PubSub } from '@google-cloud/pubsub'
import { FlowRuntime } from 'flowcraft'
import Redis from 'ioredis'

// 1. Define your blueprints and registry
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize service clients
const pubsubClient = new PubSub({ projectId: process.env.GCP_PROJECT_ID })
const firestoreClient = new Firestore({ projectId: process.env.GCP_PROJECT_ID })
const redisClient = new Redis(process.env.REDIS_URL)

// 3. Create a runtime instance
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store
const coordinationStore = new RedisCoordinationStore(redisClient)

// 5. Initialize the adapter
const adapter = new PubSubAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	pubsubClient,
	firestoreClient,
	topicName: 'flowcraft-jobs',
	subscriptionName: 'flowcraft-workers',
	contextCollectionName: 'workflow-contexts',
	statusCollectionName: 'workflow-statuses',
})

// 6. Start the worker
adapter.start()

console.log('Flowcraft worker with GCP adapter is running...')
```

--------------------------------

### Install Flowcraft GCP Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/gcp

Install the necessary packages for the adapter, GCP clients, and Redis connectivity.

```bash
npm install flowcraft @flowcraft/gcp-adapter @google-cloud/pubsub @google-cloud/firestore ioredis
```

--------------------------------

### Start a Workflow (Client-Side)

Source: https://flowcraft.js.org/guide/adapters/cloudflare

Initializes a workflow by setting the status in KV and enqueuing start jobs to a Cloudflare Queue.

```typescript
import { analyzeBlueprint } from 'flowcraft'

interface Env {
	STATUS: KVNamespace
	JOBS: Queue
}

async function startWorkflow(env: Env, blueprint, initialContext) {
	const runId = crypto.randomUUID()

	// 1. Set initial status in KV
	await env.STATUS.put(
		runId,
		JSON.stringify({
			status: 'running',
			lastUpdated: Math.floor(Date.now() / 1000),
		}),
	)

	// 2. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)

	// 3. Enqueue start jobs to Cloudflare Queue
	for (const nodeId of analysis.startNodeIds) {
		await env.JOBS.send({
			runId,
			blueprintId: blueprint.id,
			nodeId,
		})
	}

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Start a Workflow with Kafka and Cassandra

Source: https://flowcraft.js.org/guide/adapters/kafka

Initializes a workflow by persisting state to Cassandra and dispatching start jobs to Kafka.

```typescript
import { analyzeBlueprint } from 'flowcraft'
import { Client as CassandraClient } from 'cassandra-driver'
import { Kafka } from 'kafkajs'

async function startWorkflow(blueprint, initialContext) {
	const runId = crypto.randomUUID()
	const kafka = new Kafka({ brokers: [process.env.KAFKA_BROKER] })
	const cassandra = new CassandraClient({
		contactPoints: [process.env.CASSANDRA_HOST],
		localDataCenter: 'datacenter1',
		keyspace: 'flowcraft_ks',
	})

	// 1. Set initial context and status in Cassandra
	await cassandra.execute('INSERT INTO contexts (run_id, context_data) VALUES (?, ?)', [
		runId,
		JSON.stringify(initialContext),
	])
	await cassandra.execute('INSERT INTO statuses (run_id, status, updated_at) VALUES (?, ?, ?)', [
		runId,
		'running',
		new Date(),
	])

	// 2. Analyze blueprint for start nodes and prepare Kafka messages
	const analysis = analyzeBlueprint(blueprint)
	const messages = analysis.startNodeIds.map((nodeId) => ({
		key: runId, // Using runId as key ensures messages for the same workflow go to the same partition
		value: JSON.stringify({ runId, blueprintId: blueprint.id, nodeId }),
	}))

	// 3. Produce start jobs to Kafka
	const producer = kafka.producer()
	await producer.connect()
	await producer.send({ topic: 'flowcraft-jobs', messages })
	await producer.disconnect()

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Install Astro Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the Astro plugin using npm. This prepares your Astro project for Flowcraft integration.

```bash
npm install --save-dev @flowcraft/plugin-astro
```

--------------------------------

### Example BaseNode Implementation

Source: https://flowcraft.js.org/api/nodes-and-edges

Demonstrates how to extend the `BaseNode` abstract class to create a custom node. This example shows overriding `prep`, `exec`, and `post` methods for specific node logic.

```typescript
class MyNode extends BaseNode {
	async prep(context) {
		return await context.context.get('userId')
	}

	async exec(userId, context) {
		const user = await fetchUser(userId)
		return { output: user, action: 'success' }
	}

	async post(execResult, context) {
		await context.context.set('processedUser', execResult.output)
		return execResult
	}
}
```

--------------------------------

### Install esbuild Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the esbuild plugin using npm. This is necessary for integrating Flowcraft with esbuild.

```bash
npm install --save-dev @flowcraft/plugin-esbuild
```

--------------------------------

### Install tsup Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the tsup plugin using npm. This is required to integrate Flowcraft with tsup.

```bash
npm install --save-dev @flowcraft/plugin-tsup
```

--------------------------------

### Comprehensive Order Processing Workflow Example

Source: https://flowcraft.js.org/guide/durable-primitives

A complete example demonstrating the integration of sleep, waitForEvent, and createWebhook primitives for a resilient order processing workflow. Strongly typed payloads are used for clarity and safety.

```typescript
import { sleep, waitForEvent, createWebhook } from 'flowcraft/sdk'

interface PaymentEvent {
	orderId: string
	amount: number
	status: 'success' | 'failed'
}

interface WebhookNotification {
	type: 'payment' | 'refund'
	orderId: string
	details: any
}

/** @flow */
export async function orderProcessingWorkflow(orderId: string) {
	console.log(`Processing order ${orderId}`)

	// Step 1: Wait for payment event
	const payment = await waitForEvent<PaymentEvent>('payment_completed')
	if (payment.status === 'failed') {
		return { status: 'failed', reason: 'payment failed' }
	}

	// Step 2: Create webhook for external notifications
	const webhook = await createWebhook<WebhookNotification>()

	// Send webhook URL to external system
	await notifyExternalSystem(webhook.url, orderId)

	// Step 3: Sleep briefly to allow external processing
	await sleep('30s')

	// Step 4: Wait for webhook confirmation
	const { request } = await webhook.request
	const notification = await request.json()

	if (notification.type === 'refund') {
		return { status: 'refunded', notification }
	}

	return {
		status: 'completed',
		orderId,
		payment,
		notification,
	}
}
```

--------------------------------

### Install superjson

Source: https://flowcraft.js.org/guide/serializers

Install the superjson library using npm. This library extends JSON to support more data types.

```bash
npm install superjson
```

--------------------------------

### Install Vite Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the Vite plugin using npm. This is the first step to integrate Flowcraft with Vite.

```bash
npm install --save-dev @flowcraft/plugin-vite
```

--------------------------------

### Install Vercel Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/vercel

Install the required packages for Flowcraft, the Vercel adapter, Vercel Queues SDK, and ioredis.

```bash
npm install flowcraft @flowcraft/vercel-adapter @vercel/queue ioredis
```

--------------------------------

### Install Nuxt Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the Nuxt plugin using npm. This is required to use Flowcraft with Nuxt.js.

```bash
npm install --save-dev @flowcraft/plugin-nuxt
```

--------------------------------

### Install Next.js Plugin

Source: https://flowcraft.js.org/guide/compiler/build-tools

Install the Next.js plugin using npm. This enables Flowcraft integration with Next.js projects.

```bash
npm install --save-dev @flowcraft/plugin-next
```

--------------------------------

### Start a Workflow with Firestore and Pub/Sub

Source: https://flowcraft.js.org/guide/adapters/gcp

Initializes a workflow by creating state in Firestore and publishing start jobs to a Pub/Sub topic.

```typescript
import { analyzeBlueprint } from 'flowcraft'
import { Firestore } from '@google-cloud/firestore'
import { PubSub } from '@google-cloud/pubsub'

async function startWorkflow(blueprint, initialContext) {
	const runId = crypto.randomUUID()
	const projectId = process.env.GCP_PROJECT_ID
	const firestore = new Firestore({ projectId })
	const pubsub = new PubSub({ projectId })

	// 1. Set initial context and status in Firestore
	await firestore.collection('workflow-contexts').doc(runId).set(initialContext)
	await firestore
		.collection('workflow-statuses')
		.doc(runId)
		.set({ status: 'running', lastUpdated: new Date() })

	// 2. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)
	const topic = pubsub.topic('flowcraft-jobs')
	const publishPromises = analysis.startNodeIds.map((nodeId) => {
		const data = Buffer.from(JSON.stringify({ runId, blueprintId: blueprint.id, nodeId }))
		return topic.publishMessage({ data })
	})

	// 3. Publish start jobs
	await Promise.all(publishPromises)

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Setup PostgreSQL Event Store

Source: https://flowcraft.js.org/guide/time-travel

Configure a PostgreSQL event store for persistent logging. Specify connection details and the table name for events.

```typescript
import { PostgresHistoryAdapter } from '@flowcraft/postgres-history'

const eventStore = new PostgresHistoryAdapter({
	host: 'localhost',
	port: 5432,
	database: 'flowcraft',
	user: 'flowcraft',
	password: 'password',
	tableName: 'workflow_events',
})
const eventBus = new PersistentEventBusAdapter(eventStore)
const runtime = new FlowRuntime({ eventBus })
```

--------------------------------

### Create Kafka Topic

Source: https://flowcraft.js.org/guide/adapters/kafka

Initialize the required Kafka topic for job processing after starting the containers.

```bash
# 1. Create the Kafka topic
docker exec kafka kafka-topics --create --topic flowcraft-jobs --bootstrap-server localhost:9092
```

--------------------------------

### Install Flowcraft AWS Adapter Dependencies

Source: https://flowcraft.js.org/guide/adapters/sqs

Install the necessary packages for the adapter and the required AWS SDK v3 modules.

```bash
npm install flowcraft @flowcraft/sqs-adapter @aws-sdk/client-sqs @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb
```

--------------------------------

### Setup SQLite Event Store

Source: https://flowcraft.js.org/guide/time-travel

Configure a SQLite event store for persistent logging. Ensure WAL mode is enabled for concurrent access.

```typescript
import { SqliteHistoryAdapter } from '@flowcraft/sqlite-history'

const eventStore = new SqliteHistoryAdapter({
	databasePath: './workflow-events.db',
	walMode: true, // Enable WAL for concurrent access
})
const eventBus = new PersistentEventBusAdapter(eventStore)
const runtime = new FlowRuntime({ eventBus })
```

--------------------------------

### Example Usage

Source: https://flowcraft.js.org/api/context

Demonstrates how to define a workflow context shape and use it with type safety in node functions.

```APIDOC
### Example Usage

```typescript
// Define your workflow's context shape
interface SearchWorkflowContext {
	query: string
	results: SearchResult[]
	final_answer?: string
}

// Create a strongly-typed flow
const flow = createFlow<SearchWorkflowContext>('search-flow')

// In your node functions, get full type safety
flow.node('search', async (ctx) => {
	// ✅ Autocomplete suggests: 'query', 'results', 'final_answer'
	const query = await ctx.context.get('query')

	// ✅ Type inference: query is 'string | undefined'
	if (!query) return { action: 'fail' }

	const results = await searchWeb(query)

	// ✅ Type checking: results must match SearchResult[]
	await ctx.context.set('results', results)

	// ❌ Compile-time error: 'invalid_key' not in SearchWorkflowContext
	await ctx.context.get('invalid_key')
})
```
```

--------------------------------

### Start Workflow Producer

Source: https://flowcraft.js.org/guide/adapters/vercel

Initialize workflow state in Redis and enqueue the starting jobs for a new workflow run.

```typescript
// app/api/workflows/start/route.ts
import { analyzeBlueprint } from 'flowcraft'
import { send } from '@vercel/queue'
import Redis from 'ioredis'

export async function POST(req: Request) {
	const { blueprint, initialContext } = await req.json()
	const runId = crypto.randomUUID()

	const redis = new Redis(process.env.UPSTASH_REDIS_URL!)

	// 1. Set initial context in Redis
	const contextPrefix = 'flowcraft:context:'
	await redis.set(`${contextPrefix}${runId}:blueprintId`, blueprint.id, 'EX', 86400)
	await redis.set(
		`${contextPrefix}${runId}:blueprintVersion`,
		blueprint.metadata?.version || 'null',
		'EX',
		86400,
	)

	// 2. Set initial status
	await redis.set(
		`flowcraft:status:${runId}`,
		JSON.stringify({
			status: 'running',
			lastUpdated: Math.floor(Date.now() / 1000),
		}),
		'EX',
		86400,
	)

	// 3. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)

	// 4. Enqueue start jobs
	for (const nodeId of analysis.startNodeIds) {
		await send('flowcraft-jobs', { runId, blueprintId: blueprint.id, nodeId })
	}

	return Response.json({ runId })
}
```

--------------------------------

### Initialize and Start Flowcraft Worker

Source: https://flowcraft.js.org/guide/adapters/sqs

Configure the SQS adapter and DynamoDB coordination store, then start the worker to process jobs.

```typescript
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
import { SQSClient } from '@aws-sdk/client-sqs'
import { DynamoDbCoordinationStore, SqsAdapter } from '@flowcraft/sqs-adapter'
import { FlowRuntime } from 'flowcraft'

// 1. Define your workflow blueprints and node implementations
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize AWS service clients
const awsConfig = { region: process.env.AWS_REGION || 'us-east-1' }
const sqsClient = new SQSClient(awsConfig)
const dynamoDbClient = new DynamoDBClient(awsConfig)

// 3. Create a runtime instance
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store using DynamoDB
const coordinationStore = new DynamoDbCoordinationStore({
	client: dynamoDbClient,
	tableName: 'flowcraft-coordination',
})

// 5. Initialize the adapter
const adapter = new SqsAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	sqsClient,
	dynamoDbClient,
	queueUrl: process.env.SQS_QUEUE_URL,
	contextTableName: 'flowcraft-contexts',
	statusTableName: 'flowcraft-statuses',
})

// 6. Start the worker to begin polling the SQS queue
adapter.start()

console.log('Flowcraft worker with SQS adapter is running...')
```

--------------------------------

### Start a Workflow (Client-Side)

Source: https://flowcraft.js.org/guide/adapters/sqs

Initializes a workflow by persisting state to DynamoDB and enqueuing the first jobs to SQS.

```typescript
import { analyzeBlueprint } from 'flowcraft'
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
import { SQSClient, SendMessageBatchCommand } from '@aws-sdk/client-sqs'
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb'

async function startWorkflow(blueprint, initialContext) {
	const runId = crypto.randomUUID()
	const awsConfig = { region: process.env.AWS_REGION }
	const sqsClient = new SQSClient(awsConfig)
	const docClient = DynamoDBDocumentClient.from(new DynamoDBClient(awsConfig))

	// 1. Set initial context and status in DynamoDB
	await docClient.send(
		new PutCommand({
			TableName: 'flowcraft-contexts',
			Item: { runId, context: initialContext },
		}),
	)
	await docClient.send(
		new PutCommand({
			TableName: 'flowcraft-statuses',
			Item: { runId, status: 'running', lastUpdated: new Date().toISOString() },
		}),
	)

	// 2. Analyze blueprint for start nodes
	const analysis = analyzeBlueprint(blueprint)
	const startJobs = analysis.startNodeIds.map((nodeId) => ({
		Id: `${runId}-${nodeId}`,
		MessageBody: JSON.stringify({ runId, blueprintId: blueprint.id, nodeId }),
	}))

	// 3. Enqueue start jobs to SQS
	await sqsClient.send(
		new SendMessageBatchCommand({
			QueueUrl: process.env.SQS_QUEUE_URL,
			Entries: startJobs,
		}),
	)

	console.log(`Workflow ${runId} started.`)
	return runId
}
```

--------------------------------

### Mermaid diagram output example

Source: https://flowcraft.js.org/guide/visualizing-workflows

The resulting Mermaid syntax string generated by the library.

```text
flowchart TD
	fetch["fetch"]
	check["check<br/>params: {"threshold":5}"]
	process-big["process-big"]
	process-small["process-small"]
	fetch --> check
	check -- "big | result.output > 0" --> process-big
	check -- "small" --> process-small
```

--------------------------------

### Initialize and Start a BullMQ Worker

Source: https://flowcraft.js.org/guide/adapters/bullmq

Configure the BullMQ adapter with a Redis connection and start the worker to process workflow jobs.

```typescript
import { BullMQAdapter, RedisCoordinationStore } from '@flowcraft/bullmq-adapter'
import { FlowRuntime } from 'flowcraft'
import Redis from 'ioredis'

// 1. Define your workflow blueprints and node implementations
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize the Redis client. This will be shared across components.
const redisConnection = new Redis(process.env.REDIS_URL, {
	maxRetriesPerRequest: null, // Recommended for long-running workers
})

// 3. Create a runtime instance with your blueprints and registry
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store
const coordinationStore = new RedisCoordinationStore(redisConnection)

// 5. Initialize the adapter
const adapter = new BullMQAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	connection: redisConnection,
	queueName: 'my-workflow-queue', // Optional: defaults to 'flowcraft-queue'

	retryMode: 'queue', // Optional: delegates retries to BullMQ natively (defaults to 'in-process')
})

// 6. Start the worker to begin processing jobs
adapter.start()

console.log('Flowcraft worker with BullMQ adapter is running...')
```

--------------------------------

### Implement RabbitMQ worker

Source: https://flowcraft.js.org/guide/adapters/rabbitmq

Initialize the runtime, coordination store, and adapter to start the worker process.

```typescript
import { RabbitMqAdapter, RedisCoordinationStore } from '@flowcraft/rabbitmq-adapter'
import amqplib from 'amqplib'
import { FlowRuntime } from 'flowcraft'
import Redis from 'ioredis'
import { Client as PgClient } from 'pg'

// 1. Define your blueprints and registry
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize service clients
const amqpConnection = await amqplib.connect(process.env.RABBITMQ_URL)
const pgClient = new PgClient({ connectionString: process.env.POSTGRES_URL })
await pgClient.connect()
const redisClient = new Redis(process.env.REDIS_URL)

// 3. Create a runtime instance
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store
const coordinationStore = new RedisCoordinationStore(redisClient)

// 5. Initialize the adapter
const adapter = new RabbitMqAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	amqpConnection,
	pgClient,
	contextTableName: 'flowcraft_contexts',
	statusTableName: 'flowcraft_statuses',
	queueName: 'flowcraft-jobs',
})

// 6. Start the worker
adapter.start()

console.log('Flowcraft worker with RabbitMQ adapter is running...')
```

--------------------------------

### Start a Workflow with BullMQ

Source: https://flowcraft.js.org/guide/distributed-execution

Enqueue a job to start a Flowcraft workflow using BullMQ. Requires a Redis connection and the queue name 'flowcraft-queue'.

```typescript
// client.ts
import { Queue } from 'bullmq'
import IORedis from 'ioredis'

async function startWorkflow() {
	const redis = new IORedis()
	const queue = new Queue('flowcraft-queue', { connection: redis })
	const runId = crypto.randomUUID()

	// Analyze the blueprint to find the start node(s).
	const startNodeId = 'my-start-node'

	// Enqueue a job for the first node.
	await queue.add('executeNode', {
		runId,
		blueprintId: 'my-workflow',
		nodeId: startNodeId,
	})

	console.log(`Workflow ${runId} started.`) 
	// ... logic to wait for the final result ...
}

```

--------------------------------

### Programmatic Project Compilation

Source: https://flowcraft.js.org/guide/compiler/configuration

Run the compiler programmatically in build scripts. This example shows how to compile the project, handle compilation errors, and write the generated manifest.

```javascript
// scripts/compile-flows.js
import { compileProject } from '@flowcraft/compiler'

const result = await compileProject({
	entryPoints: ['./src/workflows/**/*.ts'],
	tsConfigPath: './tsconfig.json',
})

if (result.diagnostics.length > 0) {
	console.error('Compilation errors:', result.diagnostics)
	process.exit(1)
}

// Write the manifest
await fs.writeFile('./src/generated/manifest.ts', result.manifestSource)

// The result also includes:
// - result.blueprints: Array of compiled blueprint objects
// - result.registry: Registry of all discovered flows and steps
```

--------------------------------

### Implement Webhook Endpoint Registration

Source: https://flowcraft.js.org/guide/adapters/bullmq

Example implementation of registering a webhook endpoint within the BullMQAdapter class.

```typescript
// In BullMQAdapter
public async registerWebhookEndpoint(runId: string, nodeId: string): Promise<{ url: string; event: string }> {
  const eventName = `webhook:${runId}:${nodeId}`
  const url = `https://your-app.com/webhooks/${runId}/${nodeId}`

  // Store webhook mapping in Redis for later retrieval
  await this.redis.set(`webhook:${runId}:${nodeId}`, eventName)

  return { url, event: eventName }
}
```

--------------------------------

### Set up a BullMQ Worker

Source: https://flowcraft.js.org/guide/distributed-execution

Instantiate and start a Flowcraft worker using the BullMQ adapter. Requires Redis for queueing and state management. Ensure agentNodeRegistry and blueprints are loaded.

```typescript
// worker.ts
import { BullMQAdapter, RedisCoordinationStore } from '@flowcraft/bullmq-adapter'
import IORedis from 'ioredis'
// Assume agentNodeRegistry and blueprints are loaded here
import { agentNodeRegistry, blueprints } from './shared'

async function main() {
	const redisConnection = new IORedis()

	// 1. Create the coordination store using Redis.
	const coordinationStore = new RedisCoordinationStore(redisConnection)

	// 2. Instantiate the adapter.
	const adapter = new BullMQAdapter({
		connection: redisConnection,
		coordinationStore,
		runtimeOptions: {
			registry: agentNodeRegistry,
			blueprints,
		},
	})

	// 3. Start the worker. It will begin listening for jobs.
	adapter.start()
	console.log('Worker is running...')
}

main()

```

--------------------------------

### Transaction Middleware Example

Source: https://flowcraft.js.org/guide/middleware

Manages database transactions by starting a transaction before a node, committing on success, and rolling back on failure. Ensure to re-throw errors after rollback.

```typescript
import { Middleware, NodeResult } from 'flowcraft'
// Assume 'db' is your database client instance
import { db } from './database'

const transactionMiddleware: Middleware = {
	aroundNode: async (context, nodeId, next: () => Promise<NodeResult>) => {
		// This code runs BEFORE the node's logic.
		console.log(`[TX] Starting transaction for node: ${nodeId}`)
		await db.query('BEGIN')

		try {
			// `next()` executes the next middleware or the node itself.
			const result = await next()

			// This code runs ONLY if `next()` succeeds.
			console.log(`[TX] Committing transaction for node: ${nodeId}`)
			await db.query('COMMIT')
			return result
		} catch (e) {
			// This code runs ONLY if `next()` throws an error.
			console.log(`[TX] Rolling back transaction for node: ${nodeId}`)
			await db.query('ROLLBACK')

			// It's crucial to re-throw the error so the runtime can handle it.
			throw e
		}
	},
}

// Use it in the runtime:
const runtime = new FlowRuntime({
	middleware: [transactionMiddleware],
})
```

--------------------------------

### Node Usage with Configuration

Source: https://flowcraft.js.org/api/nodes-and-edges

Example of defining a node with retry, delay, timeout, fallback, and join strategy configurations. Suitable for potentially flaky operations.

```typescript
.node('flaky-api', async ({ input }) => {
  // Some API call that might fail
  return { output: await callExternalAPI(input) }
}, {
  config: {
    maxRetries: 3,
    retryDelay: 2000,
    timeout: 5000,
    fallback: 'fallback-node',
    joinStrategy: 'any'
  }
})
```

--------------------------------

### Analyze Workflow Blueprint with analyzeBlueprint

Source: https://flowcraft.js.org/guide/static-analysis

Use `analyzeBlueprint` to get a comprehensive analysis of a workflow blueprint. This includes detecting cycles, identifying start and terminal nodes, and counting nodes and edges.

```typescript
import { analyzeBlueprint, createFlow } from 'flowcraft'

const flow = createFlow('analysis-example')
	.node('A', async () => ({}))
	.node('B', async () => ({}))
	.node('C', async () => ({}))
	.edge('A', 'B')
	.edge('B', 'C')
	.toBlueprint()

const analysis = analyzeBlueprint(flow)
console.log(analysis)
```

```json
{
	"cycles": [],
	"startNodeIds": ["A"],
	"terminalNodeIds": ["C"],
	"nodeCount": 3,
	"edgeCount": 2,
	"isDag": true
}
```

--------------------------------

### Initialize PostgreSQL tables

Source: https://flowcraft.js.org/guide/adapters/rabbitmq

Create the required tables for context data and status tracking in PostgreSQL.

```sql
-- For context data
CREATE TABLE flowcraft_contexts (
    run_id TEXT PRIMARY KEY,
    context_data JSONB NOT NULL
);

-- For final status
CREATE TABLE flowcraft_statuses (
    run_id TEXT PRIMARY KEY,
    status TEXT NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    result JSONB
);
```

--------------------------------

### Provision Azure Infrastructure via CLI

Source: https://flowcraft.js.org/guide/adapters/azure

Create the necessary Storage Account, Queue, Cosmos DB database/containers, and Redis cache using Azure CLI commands.

```bash
# 1. Create Storage Account and Queue
az storage account create --name flowcraftstorage --resource-group my-rg
az storage queue create --name flowcraft-jobs --account-name flowcraftstorage

# 2. Create Cosmos DB Account, Database, and Containers
az cosmosdb create --name flowcraft-cosmos --resource-group my-rg
az cosmosdb sql database create --account-name flowcraft-cosmos --name flowcraft-db --resource-group my-rg
az cosmosdb sql container create --account-name flowcraft-cosmos --database-name flowcraft-db --name contexts --partition-key-path "/runId" --resource-group my-rg
az cosmosdb sql container create --account-name flowcraft-cosmos --database-name flowcraft-db --name statuses --partition-key-path "/runId" --resource-group my-rg

# 3. Create Redis Cache
az redis create --name flowcraft-redis --resource-group my-rg --location eastus --sku Basic --vm-size c0
```

--------------------------------

### Set Up FlowRuntime with Subflows

Source: https://flowcraft.js.org/guide/subflows

This code demonstrates how to set up the FlowRuntime by providing all necessary blueprints, including subflow blueprints, to the constructor. It then runs the parent workflow and logs the final context.

```typescript
// main.ts
import { FlowRuntime } from 'flowcraft'
import { parentFlow } from './parent-flow'
import { mathSubflowBlueprint } from './subflow'

const runtime = new FlowRuntime({
	// The runtime needs access to all blueprints it might be asked to run.
	blueprints: {
		'math-subflow': mathSubflowBlueprint,
	},
	// The registry only needs the implementations from the parent flow.
	registry: parentFlow.getFunctionRegistry(),
})

const result = await runtime.run(parentFlow.toBlueprint(), {})
console.log(result.context)
// {
//   val1: 10,
//   val2: 20,
//   prepare_data: 'Data ready',
//   run_math: { a: 10, b: 20, add: 30 }, // Subflow's final context
//   addition_result: 30 // Mapped output
// }
```

--------------------------------

### Initialize and Start Flowcraft Worker

Source: https://flowcraft.js.org/guide/adapters/azure

Configure the AzureQueueAdapter with service clients and start the worker process.

```typescript
import { CosmosClient } from '@azure/cosmos'
import { QueueClient } from '@azure/storage-queue'
import { AzureQueueAdapter, RedisCoordinationStore } from '@flowcraft/azure-adapter'
import { FlowRuntime } from 'flowcraft'
import Redis from 'ioredis'

// 1. Define your blueprints and registry
const blueprints = {
	/* your workflow blueprints */
}
const registry = {
	/* your node implementations */
}

// 2. Initialize service clients
const queueClient = new QueueClient(process.env.AZURE_STORAGE_CONNECTION_STRING, 'your-queue-name')
const cosmosClient = new CosmosClient(process.env.COSMOS_DB_CONNECTION_STRING)
const redisClient = new Redis(process.env.REDIS_CONNECTION_STRING)

// 3. Create a runtime instance
const runtime = new FlowRuntime({ blueprints, registry })

// 4. Set up the coordination store
const coordinationStore = new RedisCoordinationStore(redisClient)

// 5. Initialize the adapter
const adapter = new AzureQueueAdapter({
	runtimeOptions: runtime.options,
	coordinationStore,
	queueClient,
	cosmosClient,
	cosmosDatabaseName: 'your-cosmos-db-name',
	contextContainerName: 'workflow-contexts',
	statusContainerName: 'workflow-statuses',
})

// 6. Start the worker
adapter.start()

console.log('Flowcraft worker with Azure adapter is running...')
```

--------------------------------

### Initialize Cassandra Schema

Source: https://flowcraft.js.org/guide/adapters/kafka

Execute this command to create the necessary keyspace and tables for Flowcraft storage in Cassandra.

```bash
docker exec -it cassandra cqlsh -e "
CREATE KEYSPACE IF NOT EXISTS flowcraft_ks WITH REPLICATION = {'class': 'SimpleStrategy', 'replication_factor': 1};
USE flowcraft_ks;
CREATE TABLE contexts (run_id text PRIMARY KEY, context_data text);
CREATE TABLE statuses (run_id text PRIMARY KEY, status text, updated_at timestamp);
"
```

--------------------------------

### Provision GCP Infrastructure via gcloud CLI

Source: https://flowcraft.js.org/guide/adapters/gcp

Use the gcloud CLI to set up the required Pub/Sub, Firestore, and Redis resources.

```bash
# 1. Create Pub/Sub topic and subscription
gcloud pubsub topics create flowcraft-jobs
gcloud pubsub subscriptions create flowcraft-workers --topic flowcraft-jobs

# 2. Enable Firestore API
gcloud services enable firestore.googleapis.com

# 3. Create a Redis instance in Memorystore
gcloud redis instances create flowcraft-redis --size=1 --region=us-central1
```

--------------------------------

### Run Workflow (Before)

Source: https://flowcraft.js.org/api/flow

Illustrates the manual way to run a workflow using the runtime, explicitly passing the blueprint and function registry.

```typescript
const blueprint = flow.toBlueprint()
const result = await runtime.run(
	blueprint,
	{},
	{
		functionRegistry: flow.getFunctionRegistry(),
	},
)
```

--------------------------------

### .run(runtime, initialState?, options?)

Source: https://flowcraft.js.org/api/flow

Runs this flow on the given runtime, automatically passing the function registry. This is a convenience wrapper around `runtime.run(blueprint, initialState, { functionRegistry })`.

```APIDOC
## .run(runtime, initialState?, options?)

### Description
Runs this flow on the given runtime, automatically passing the function registry. This is a convenience wrapper around `runtime.run(blueprint, initialState, { functionRegistry })`.

### Parameters
* **`runtime`** (`FlowRuntime`): The runtime to execute on.
* **`initialState?`** (`Partial<TContext> | string`): The initial state for the workflow's context.
* **`options?`** (`{ strict?: boolean, signal?: AbortSignal, concurrency?: number }`): Runtime options (excluding `functionRegistry`, which is provided automatically).

### Returns
* `Promise<WorkflowResult<TContext>>`

### Example
**Before:**
```typescript
const blueprint = flow.toBlueprint()
const result = await runtime.run(
	blueprint,
	{},
	{
		functionRegistry: flow.getFunctionRegistry(),
	},
)
```

**After:**
```typescript
const result = await flow.run(runtime)
```
```

--------------------------------

### FlowRuntime Initialization with Middleware

Source: https://flowcraft.js.org/api/middleware

Demonstrates how to integrate custom middleware into the `FlowRuntime` by passing an array of middleware instances to the constructor.

```APIDOC
## Usage with FlowRuntime 

Middleware is provided to the `FlowRuntime` constructor:

typescript
```typescript
const runtime = new FlowRuntime({
	middleware: [myMiddleware1, myMiddleware2],
})
```

Middleware executes in LIFO order (last in, first out).
```
Tokens:
Raw