temporalio-graphs

Generate workflow graphs for Temporal by running workflows in mocked-execution mode.

TypeScript port of Temporalio.Graphs by Oleg Shilo

The original .NET library provides an elegant approach to visualizing Temporal workflows by executing them in a mocked environment and capturing the execution graph. This TypeScript implementation brings the same capabilities to the Node.js ecosystem.

Features

• Generate complete workflow DAGs without running actual activities
• Capture all decision branches via automatic permutation
• Output Mermaid flowchart syntax
• Interactive HTML viewer with pan/zoom and step-by-step animation
• Support for child workflow visualization

Installation

npm install temporalio-graphs

Quick Start

1. Define Your Activities with Decision Points

Use the @Decision decorator to mark activities that represent branching decisions:

import { Decision } from 'temporalio-graphs';

export class MyActivities {
  @Decision({ positiveLabel: 'high', negativeLabel: 'low' })
  async isHighValue(amount: number): Promise<boolean> {
    return amount > 10000;
  }

  async processPayment(amount: number): Promise<void> {
    // Process payment logic
  }
}

2. Build the Graph

Create a build script that uses createMockActivities to mock your activities during graph generation:

import { buildGraph, generateViewerHtml, createMockActivities } from 'temporalio-graphs';
import { MyActivities } from './activities';
import * as fs from 'fs';

// Create mock activities for graph building
const activitiesInstance = new MyActivities();
const activities = createMockActivities<MyActivities>({
  activitiesClass: activitiesInstance,
});

// Define workflow using mock activities
async function myWorkflow(input: { amount: number }): Promise<void> {
  if (await activities.isHighValue(input.amount)) {
    // High value path
  }
  await activities.processPayment(input.amount);
}

// Build the graph
const result = await buildGraph(myWorkflow, {
  workflowArgs: [{ amount: 5000 }],
  splitNamesByWords: true,
});

// Output Mermaid syntax
console.log(result.mermaid);

// Generate interactive HTML viewer
const html = generateViewerHtml(result.mermaid, 'My Workflow');
fs.writeFileSync('workflow.html', html);

Output Example

flowchart LR
s((Start)) --> isHighValue{isHighValue}
isHighValue -- high --> processPayment --> e((End))
isHighValue -- low --> processPayment

Using with Temporal Runtime

For use within actual Temporal workers, export the interceptors from your workflows file:

import { createGraphBuildingInterceptors } from 'temporalio-graphs';

export const interceptors = createGraphBuildingInterceptors();

API Reference

buildGraph(workflow, options)

Builds a workflow graph by running the workflow in mocked-execution mode.

Options:

• workflowArgs: Arguments to pass to the workflow
• maxDecisions: Maximum decision points to explore (default: 10)
• splitNamesByWords: Split camelCase names for readability

Returns: GraphResult with paths, edges, mermaid, pathDescriptions

createMockActivities<T>(options?)

Creates mock activity proxies for graph building mode. This is the key function for generating graphs outside the Temporal runtime.

Options:

• activitiesClass: Instance of your activities class (used to detect @Decision decorators)

@Decision(options?)

Decorator to mark an activity as a decision point.

Options:

• positiveLabel: Label for true branch (default: 'yes')
• negativeLabel: Label for false branch (default: 'no')

toDecision(condition, label, options?)

Wrapper for inline boolean conditions in workflows.

generateViewerHtml(mermaid, title?)

Generates an interactive HTML viewer for the workflow graph.

createGraphBuildingInterceptors()

Creates workflow interceptors for graph building mode (for use with Temporal runtime).

Design Decisions

Decision Point Marking

We use @Decision decorator + toDecision() wrapper (matching the .NET implementation) because:

1. Parity with .NET - Familiar patterns for Temporalio.Graphs users
2. Explicit over implicit - Decision points are architectural choices
3. Covers both use cases - Activities and inline conditions
4. Type-safe - Full TypeScript support
5. No magic - Clear developer intent

Examples

See the examples/ directory:

• money-transfer/ - Port of the original .NET example
• fintech-pipeline/ - Simplified daily pipeline example

To run an example:

cd examples/money-transfer
npm install
npm run graph
open workflow.html

License

MIT - Based on Temporalio.Graphs by Oleg Shilo.