sfn-diagram 0.5.1 → 0.7.0

package/README.md

@@ -8,11 +8,62 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 
 **▶ [Try it in the live playground](https://yusufaf.github.io/sfn-diagram/)** — paste any ASL definition and preview the diagram instantly, no install required.
 
+## What it looks like
+
+Give it an ASL definition like this order-processing workflow ([`examples/order-processing.asl.json`](examples/order-processing.asl.json)):
+
+```jsonc
+{
+  "StartAt": "ValidateOrder",
+  "States": {
+    "ValidateOrder": { "Type": "Pass", "Next": "CheckStock" },
+    "CheckStock": {
+      "Type": "Choice",
+      "Choices": [{ "Variable": "$.inStock", "BooleanEquals": true, "Next": "ChargePayment" }],
+      "Default": "CancelOrder"
+    },
+    "ChargePayment": { "Type": "Task", "Resource": "arn:aws:lambda:...:charge-payment", "Next": "ShipOrder" },
+    "ShipOrder":     { "Type": "Task", "Resource": "arn:aws:lambda:...:ship-order", "Next": "OrderComplete" },
+    "CancelOrder":   { "Type": "Fail", "Error": "OutOfStock" },
+    "OrderComplete": { "Type": "Succeed" }
+  }
+}
+```
+
+…and `generateMermaid` turns it into a diagram GitHub renders inline (the same code also drives SVG and PNG output):
+
+```mermaid
+stateDiagram-v2
+
+    [*] --> ValidateOrder
+    ValidateOrder --> CheckStock
+    CheckStock --> ChargePayment: $.inStock == true
+    CheckStock --> CancelOrder: Default
+    ChargePayment --> ShipOrder
+    ShipOrder --> OrderComplete
+
+    CancelOrder --> [*]
+    OrderComplete --> [*]
+
+    classDef successState fill:#e8f5e8,stroke:#4caf50,stroke-width:3px
+    classDef failState fill:#ffebee,stroke:#f44336,stroke-width:3px
+    classDef choiceState fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef taskState fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
+
+    class CheckStock choiceState
+    class ChargePayment taskState
+    class ShipOrder taskState
+    class CancelOrder failState
+    class OrderComplete successState
+```
+
 ## Features
 
 - **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
 - **Automatic Layout**: Smart graph positioning using Dagre layout engine
-- **Full ASL Support**: All state types (Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map)
+- **Full ASL Support**: All state types (Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map), both JSONPath and JSONata query languages, plus `Catch`/`Retry` rendering
+- **Visual Diffing**: Compare two definitions and highlight added / modified / removed states — drives the PR-preview GitHub Action
+- **Execution Overlays**: Paint a real execution's history onto the diagram — succeeded/failed/caught/not-reached states, the taken path, and per-state duration & retry counts
 - **Customizable Themes**: AWS light/dark themes plus custom theme support
 - **Flexible Layouts**: Top-bottom, left-right, right-left, bottom-top
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
@@ -26,6 +77,12 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 npm install sfn-diagram
 ```
 
+The core package pulls in **no browser engine** — SVG and Mermaid generation stay lightweight. PNG export relies on a headless browser, provided by the optional peer dependency `node-html-to-image`. Install it only if you use `sfn-diagram/png`:
+
+```bash
+npm install sfn-diagram node-html-to-image
+```
+
 ## Runtime Support
 
 The core entry (`sfn-diagram`) builds SVG with a DOM-free string renderer, so
@@ -34,7 +91,9 @@ run in **Node, browsers, and edge runtimes** (Cloudflare Workers, Vercel Edge, D
 with no DOM polyfill.
 
 PNG export (`sfn-diagram/png`) and the CLI are **Node-only** — they rely on a headless
-browser (`node-html-to-image`) and Node's filesystem respectively.
+browser (`node-html-to-image`) and Node's filesystem respectively. Because `node-html-to-image`
+is an **optional peer dependency**, install it alongside `sfn-diagram` when you need PNG output;
+`exportPng` throws an actionable error if it is missing.
 
 ```ts
 // Works in Node, browser, and edge:
@@ -214,6 +273,125 @@ const { svg } = generateFromAwsResponse({
 });
 ```
 
+### generateMermaidDiff(params) / generateDiff(params)
+
+Compare two ASL definitions and highlight what changed. `generateMermaidDiff` returns Mermaid code (renders inline on GitHub); `generateDiff` returns the same comparison as an SVG. Added states are green, modified yellow, removed red — and both return a `metadata` change summary (`added`, `modified`, `removed`, `unchanged`). The comparison is order-insensitive, so reordering a state's properties is **not** flagged as a change.
+
+```typescript
+import { generateMermaidDiff } from 'sfn-diagram';
+
+const { code, metadata } = generateMermaidDiff({
+  before: baseAsl, // old (base) ASL definition, object or JSON string
+  after: headAsl,  // new (head) ASL definition, object or JSON string
+});
+
+metadata; // { added: [...], modified: [...], removed: [...], unchanged: [...], stateCount, edgeCount }
+```
+
+For the order-processing workflow above, adding a `FraudCheck` step, bumping `ChargePayment`'s resource, and dropping `CancelOrder` renders like this:
+
+```mermaid
+stateDiagram-v2
+
+    [*] --> ValidateOrder
+    ValidateOrder --> CheckStock
+    CheckStock --> ChargePayment: $.inStock == true
+    CheckStock --> OrderComplete: Default
+    ChargePayment --> FraudCheck
+    FraudCheck --> ShipOrder
+    ShipOrder --> OrderComplete
+
+    OrderComplete --> [*]
+    CancelOrder --> [*]
+
+    classDef diffAdded fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
+    classDef diffModified fill:#fff9c4,stroke:#f57f17,stroke-width:2px
+    classDef diffRemoved fill:#ffcdd2,stroke:#c62828,stroke-width:2px
+
+    class FraudCheck diffAdded
+    class CheckStock diffModified
+    class ChargePayment diffModified
+    class CancelOrder diffRemoved
+```
+
+> This is exactly what the [GitHub Action](#github-action) posts on pull requests that touch ASL files.
+
+### generateExecution(params) / generateMermaidExecution(params)
+
+Overlay a **real execution** onto the diagram. Where the diff shows how a definition
+_changed_, the execution overlay shows what one _run_ actually did: which path it took,
+which states succeeded (green), failed (red), were caught and recovered (orange), or were
+never reached (grey) — plus per-state duration and retry counts.
+
+Pass the ASL definition plus the execution's history. `history` accepts the events array
+from `GetExecutionHistory`, the raw command output, or a JSON string of either — so the
+core stays credential-free and runs in the browser.
+
+```typescript
+import { generateExecution, generateMermaidExecution } from 'sfn-diagram';
+
+// history: events from `aws stepfunctions get-execution-history`, or the SDK response
+const { svg, metadata } = generateExecution({ aslDefinition: asl, history });
+
+metadata;
+// { succeeded: [...], failed: [...], caught: [...], notReached: [...], running: [...],
+//   takenEdgeCount, executionStatus, nodeCount, edgeCount }
+
+// Mermaid variant (states coloured + duration/retry annotations in labels):
+const { code } = generateMermaidExecution({ aslDefinition: asl, history });
+```
+
+> **Note:** Mermaid `stateDiagram-v2` cannot style individual transitions, so taken-path
+> emphasis in Mermaid is expressed through node colours and label annotations. The SVG
+> overlay additionally dims the transitions the run did not take.
+
+Need just the data (no rendering)? `parseExecutionHistory({ events })` returns the pure
+`ExecutionOverlay` model — per-state status, attempts, duration, and the taken edges — for
+building your own UI.
+
+```typescript
+import { parseExecutionHistory } from 'sfn-diagram';
+
+const overlay = parseExecutionHistory({ events });
+overlay.states['ProcessOrder']; // { status: 'succeeded', attempts: 1, durationMs: 1250 }
+overlay.takenEdges;             // [{ from: 'ValidateOrder', to: 'ProcessOrder' }, ...]
+```
+
+Fetching history from AWS (Node) — use the `sfn-diagram/aws` helper, which paginates `GetExecutionHistory` for you:
+
+```typescript
+import { SFNClient } from '@aws-sdk/client-sfn';
+import { fetchExecutionHistory } from 'sfn-diagram/aws';
+
+const client = new SFNClient({ region: 'us-east-1' });
+const events = await fetchExecutionHistory({ client, executionArn });
+
+const { svg } = generateExecution({ aslDefinition: asl, history: events });
+```
+
+`sfn-diagram/aws` is a Node-only subpath. `@aws-sdk/client-sfn` is an **optional peer dependency** — install it yourself (`npm i @aws-sdk/client-sfn`); the core `sfn-diagram` package stays dependency-free and browser-safe.
+
+<details>
+<summary>Prefer to paginate yourself? The manual loop:</summary>
+
+```typescript
+import { SFNClient, GetExecutionHistoryCommand } from '@aws-sdk/client-sfn';
+
+const client = new SFNClient({ region: 'us-east-1' });
+const events = [];
+let nextToken;
+do {
+  const page = await client.send(
+    new GetExecutionHistoryCommand({ executionArn, nextToken, maxResults: 1000 }),
+  );
+  events.push(...(page.events ?? []));
+  nextToken = page.nextToken;
+} while (nextToken);
+
+const { svg } = generateExecution({ aslDefinition: asl, history: events });
+```
+</details>
+
 ### SfnDiagramGenerator Class
 
 Reusable generator that holds diagram options once and applies them to every call. Configure options via the constructor or the fluent `setOptions()` method; pass the `aslDefinition` per generation.
@@ -251,23 +429,34 @@ const mermaidResult = generator.generateMermaid({ aslDefinition: asl });
 - `'dark'` - AWS dark theme
 
 **Custom theme:**
+
+A `CustomTheme` sets the background, per-state-type fill/stroke colours, edge colours, and typography. Pass it anywhere a theme is accepted.
+
 ```typescript
-const customTheme = {
-  backgroundColor: '#ffffff',
-  nodeStroke: '#232f3e',
-  nodeStrokeWidth: 2,
-  fontSize: 14,
+import type { CustomTheme } from 'sfn-diagram';
+
+const customTheme: CustomTheme = {
+  background: '#ffffff',
+  edgeColors: {
+    choice: '#7b1fa2',
+    default: '#607d8b',
+    error: '#f44336',
+    normal: '#232f3e',
+    retry: '#f9a825', // optional; falls back to `error` when omitted
+  },
   fontFamily: 'Arial, sans-serif',
-  stateColors: {
-    Pass: '#4CAF50',
-    Task: '#2196F3',
-    Choice: '#FF9800',
-    Wait: '#9C27B0',
-    Succeed: '#4CAF50',
-    Fail: '#F44336',
-    Parallel: '#00BCD4',
-    Map: '#3F51B5'
-  }
+  fontSize: 14,
+  nodeColors: {
+    Pass:     { fill: '#e8f5e9', stroke: '#4caf50' },
+    Task:     { fill: '#e3f2fd', stroke: '#2196f3' },
+    Choice:   { fill: '#fff3e0', stroke: '#ff9800' },
+    Wait:     { fill: '#f3e5f5', stroke: '#9c27b0' },
+    Succeed:  { fill: '#e8f5e9', stroke: '#4caf50' },
+    Fail:     { fill: '#ffebee', stroke: '#f44336' },
+    Parallel: { fill: '#e0f7fa', stroke: '#00bcd4' },
+    Map:      { fill: '#e8eaf6', stroke: '#3f51b5' },
+  },
+  textColor: '#232f3e',
 };
 
 generateSvg({ aslDefinition: asl, theme: customTheme });
@@ -363,7 +552,16 @@ All AWS Step Functions state types are fully supported:
 | **Succeed** | Circle | Terminates successfully |
 | **Fail** | Circle | Terminates with failure |
 | **Parallel** | Rectangle | Executes branches in parallel |
-| **Map** | Rectangle | Iterates over array items |
+| **Map** | Rectangle | Iterates over array items (legacy `Iterator` and modern `ItemProcessor`/Distributed Map) |
+
+### Error handling & retries
+
+- **`Catch`** blocks render as dashed error edges to their handler states.
+- **`Retry`** policies render as a labelled self-loop on the state (e.g. `↻ States.Timeout (4x); States.ALL (2x)`) — a self-transition in Mermaid output.
+
+### Query languages
+
+Both JSONPath and JSONata (`QueryLanguage: "JSONata"`) definitions are supported. Choice branch labels are derived from JSONPath comparison operators (`$.score >= 90`, `And`/`Or`/`Not`, `Is*` checks) or from JSONata `Condition` expressions, whichever the state uses.
 
 ## Examples
 
@@ -514,7 +712,7 @@ pnpm install
 pnpm dev
 ```
 
-Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server.
+Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server. Switch **Mode** to _Execution overlay_ to paste an execution history alongside the definition and watch the run's path light up.
 
 ### VS Code Extension
 
@@ -530,28 +728,53 @@ code --install-extension vscode-sfn-diagram-*.vsix
 
 **Usage:** Open any `.json` or `.asl` file and run **Step Functions: Preview Step Functions Diagram** from the command palette, or click the diagram icon in the editor title bar.
 
+### React Component
+
+Render diagrams in a React app with the [`sfn-diagram-react`](packages/sfn-diagram-react/) package. It wraps `generateSvg`/`generateMermaid` in a component with the same platform-agnostic core, so it works in any React renderer.
+
+```tsx
+import { SfnDiagram } from 'sfn-diagram-react';
+
+<SfnDiagram
+  definition={asl}     // ASL object or JSON string
+  format="svg"         // 'svg' (default) | 'mermaid'
+  theme="dark"         // 'light' | 'dark' | CustomTheme
+  layout="LR"          // 'TB' | 'LR' | 'RL' | 'BT'
+  history={history}    // optional: renders an execution overlay
+  onError={(err) => console.error(err)}
+/>
+```
+
 ### GitHub Action
 
-Post SVG diff previews and Mermaid diagrams as PR comments whenever ASL files change. Located in [`packages/github-action-sfn-diagram/`](packages/github-action-sfn-diagram/).
+Comment a Step Functions diagram on every pull request that touches an ASL file. For **changed** files the comment highlights the diff — added states green, modified yellow, removed red — plus a summary table of what changed; **new** and **deleted** files get a plain diagram. Everything is Mermaid, so it renders inline in the PR with no image hosting. The comment is upserted (updated in place) on each push.
+
+Available on the [GitHub Marketplace](https://github.com/marketplace/actions/step-functions-diagram-preview) as [`yusufaf/sfn-diagram-action`](https://github.com/yusufaf/sfn-diagram-action) — pin the moving major tag `@v1`. (Source lives here in [`packages/github-action-sfn-diagram/`](packages/github-action-sfn-diagram/); the Marketplace repo is generated from it.)
 
 ```yaml
 # .github/workflows/sfn-preview.yml
 name: Step Functions Preview
 on:
   pull_request:
-    paths: ['**/*.asl.json']
+    paths: ['**/*.asl.json', '**/*.asl']
+
+permissions:
+  contents: read
+  pull-requests: write   # required to post the comment
 
 jobs:
   preview:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - uses: ./packages/github-action-sfn-diagram
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0 }   # needed to diff base vs head
+      - uses: yusufaf/sfn-diagram-action@v1
 ```
 
+Inputs: `github-token` (defaults to `${{ github.token }}`), `asl-glob` (comma-separated globs, default `**/*.asl.json,**/*.asl`), `comment-tag` (marker used to find/update the comment, default `sfn-diagram-preview`).
+
+Optionally overlay a real run: set `execution-mode` (`latest` or `latest-failed`) and `state-machine-arn` to append the most recent (or most recent failed) execution as a Mermaid overlay beneath the diff. This is opt-in (`off` by default), needs AWS credentials (`states:ListExecutions` + `states:GetExecutionHistory`), and applies when exactly one ASL file changed — see the [action README](packages/github-action-sfn-diagram/README.marketplace.md) for a full workflow.
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/dist/aws.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _aws_sdk_client_sfn = require("@aws-sdk/client-sfn");
+//#region src/aws.ts
+/**
+* Node-only AWS convenience helpers for `sfn-diagram`.
+*
+* This subpath (`sfn-diagram/aws`) is isolated from the core entry so that
+* importing `sfn-diagram` never pulls in `@aws-sdk/client-sfn`, keeping the core
+* dependency-free and browser-safe. `@aws-sdk/client-sfn` is an optional peer
+* dependency — install it yourself to use these helpers.
+*/
+/**
+* Fetches the complete history of a Step Functions execution, paginating through
+* every `GetExecutionHistory` page so callers don't have to hand-roll the
+* `nextToken` loop.
+*
+* The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+* `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+*
+* @param params - The SFN client, execution ARN, and optional page size.
+* @returns All history events for the execution, in chronological order.
+*
+* @example
+* ```ts
+* import { SFNClient } from '@aws-sdk/client-sfn';
+* import { fetchExecutionHistory } from 'sfn-diagram/aws';
+* import { generateExecution } from 'sfn-diagram';
+*
+* const client = new SFNClient({ region: 'us-east-1' });
+* const events = await fetchExecutionHistory({ client, executionArn });
+* const { svg } = generateExecution({ aslDefinition: asl, history: events });
+* ```
+*/
+async function fetchExecutionHistory(params) {
+	const { client, executionArn, maxResults = 1e3 } = params;
+	const events = [];
+	let nextToken;
+	do {
+		const page = await client.send(new _aws_sdk_client_sfn.GetExecutionHistoryCommand({
+			executionArn,
+			maxResults,
+			nextToken
+		}));
+		events.push(...page.events ?? []);
+		nextToken = page.nextToken;
+	} while (nextToken);
+	return events;
+}
+//#endregion
+exports.fetchExecutionHistory = fetchExecutionHistory;

package/dist/aws.d.cts

@@ -0,0 +1,36 @@
+import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
+
+//#region src/aws.d.ts
+interface FetchExecutionHistoryParams {
+  /** A caller-constructed SFN client (with the caller's credentials/region). */
+  client: SFNClient;
+  /** ARN of the execution whose history should be fetched. */
+  executionArn: string;
+  /** Page size passed to `GetExecutionHistory`. Defaults to 1000 (the AWS max). */
+  maxResults?: number;
+}
+/**
+ * Fetches the complete history of a Step Functions execution, paginating through
+ * every `GetExecutionHistory` page so callers don't have to hand-roll the
+ * `nextToken` loop.
+ *
+ * The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+ * `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+ *
+ * @param params - The SFN client, execution ARN, and optional page size.
+ * @returns All history events for the execution, in chronological order.
+ *
+ * @example
+ * ```ts
+ * import { SFNClient } from '@aws-sdk/client-sfn';
+ * import { fetchExecutionHistory } from 'sfn-diagram/aws';
+ * import { generateExecution } from 'sfn-diagram';
+ *
+ * const client = new SFNClient({ region: 'us-east-1' });
+ * const events = await fetchExecutionHistory({ client, executionArn });
+ * const { svg } = generateExecution({ aslDefinition: asl, history: events });
+ * ```
+ */
+declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion
+export { FetchExecutionHistoryParams, fetchExecutionHistory };

package/dist/aws.d.ts

@@ -0,0 +1,36 @@
+import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
+
+//#region src/aws.d.ts
+interface FetchExecutionHistoryParams {
+  /** A caller-constructed SFN client (with the caller's credentials/region). */
+  client: SFNClient;
+  /** ARN of the execution whose history should be fetched. */
+  executionArn: string;
+  /** Page size passed to `GetExecutionHistory`. Defaults to 1000 (the AWS max). */
+  maxResults?: number;
+}
+/**
+ * Fetches the complete history of a Step Functions execution, paginating through
+ * every `GetExecutionHistory` page so callers don't have to hand-roll the
+ * `nextToken` loop.
+ *
+ * The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+ * `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+ *
+ * @param params - The SFN client, execution ARN, and optional page size.
+ * @returns All history events for the execution, in chronological order.
+ *
+ * @example
+ * ```ts
+ * import { SFNClient } from '@aws-sdk/client-sfn';
+ * import { fetchExecutionHistory } from 'sfn-diagram/aws';
+ * import { generateExecution } from 'sfn-diagram';
+ *
+ * const client = new SFNClient({ region: 'us-east-1' });
+ * const events = await fetchExecutionHistory({ client, executionArn });
+ * const { svg } = generateExecution({ aslDefinition: asl, history: events });
+ * ```
+ */
+declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion
+export { FetchExecutionHistoryParams, fetchExecutionHistory };

package/dist/aws.js

@@ -0,0 +1,49 @@
+import { GetExecutionHistoryCommand } from "@aws-sdk/client-sfn";
+//#region src/aws.ts
+/**
+* Node-only AWS convenience helpers for `sfn-diagram`.
+*
+* This subpath (`sfn-diagram/aws`) is isolated from the core entry so that
+* importing `sfn-diagram` never pulls in `@aws-sdk/client-sfn`, keeping the core
+* dependency-free and browser-safe. `@aws-sdk/client-sfn` is an optional peer
+* dependency — install it yourself to use these helpers.
+*/
+/**
+* Fetches the complete history of a Step Functions execution, paginating through
+* every `GetExecutionHistory` page so callers don't have to hand-roll the
+* `nextToken` loop.
+*
+* The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+* `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+*
+* @param params - The SFN client, execution ARN, and optional page size.
+* @returns All history events for the execution, in chronological order.
+*
+* @example
+* ```ts
+* import { SFNClient } from '@aws-sdk/client-sfn';
+* import { fetchExecutionHistory } from 'sfn-diagram/aws';
+* import { generateExecution } from 'sfn-diagram';
+*
+* const client = new SFNClient({ region: 'us-east-1' });
+* const events = await fetchExecutionHistory({ client, executionArn });
+* const { svg } = generateExecution({ aslDefinition: asl, history: events });
+* ```
+*/
+async function fetchExecutionHistory(params) {
+	const { client, executionArn, maxResults = 1e3 } = params;
+	const events = [];
+	let nextToken;
+	do {
+		const page = await client.send(new GetExecutionHistoryCommand({
+			executionArn,
+			maxResults,
+			nextToken
+		}));
+		events.push(...page.events ?? []);
+		nextToken = page.nextToken;
+	} while (nextToken);
+	return events;
+}
+//#endregion
+export { fetchExecutionHistory };