sfn-diagram 0.6.0 → 1.0.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), both JSONPath and JSONata query languages
+- **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
@@ -44,6 +95,10 @@ browser (`node-html-to-image`) and Node's filesystem respectively. Because `node
 is an **optional peer dependency**, install it alongside `sfn-diagram` when you need PNG output;
 `exportPng` throws an actionable error if it is missing.
 
+**Node versions:** the package requires **Node >= 20**. PNG export additionally requires
+**Node >= 22.12.0**, the floor set by `node-html-to-image` v6 — SVG, Mermaid, and HTML
+output are unaffected and keep working on Node 20.
+
 ```ts
 // Works in Node, browser, and edge:
 import { generateSvg } from 'sfn-diagram';
@@ -62,7 +117,11 @@ npx sfn-diagram state.asl.json --format mermaid > diagram.mmd
 cat state.asl.json | npx sfn-diagram - --format svg
 ```
 
-Flags: `--format <svg|mermaid|png>`, `-o/--output <path>`, `--theme <light|dark>`, `--layout <TB|LR|RL|BT>`, `-h/--help`, `-v/--version`.
+Flags: `--format <svg|mermaid|png|html>`, `-o/--output <path>`, `--theme <light|dark>`, `--layout <TB|LR|RL|BT>`, `--hide-catch`, `--resolve-cfn`, `--resource <logicalId>`, `-h/--help`, `-v/--version`.
+
+CloudFormation/SAM/CDK templates work as input too — see [Extracting ASL from a CDK/CloudFormation template](#extracting-asl-from-a-cdkcloudformation-template).
+
+> **`--format png` needs the optional `node-html-to-image` peer.** It is not installed by default. With `npx`, run `npx --package sfn-diagram --package node-html-to-image sfn-diagram …`; in a project, `npm install node-html-to-image`. Without it the CLI exits with an actionable error. Or skip the install entirely with the [Docker image](#docker), which bundles Chromium.
 
 ## Docker
 
@@ -222,6 +281,154 @@ const { svg } = generateFromAwsResponse({
 });
 ```
 
+### Extracting ASL from a CDK/CloudFormation template
+
+`cdk synth` emits a state machine whose `DefinitionString` is an `Fn::Join` full
+of intrinsics, not plain ASL. The `sfn-diagram/cfn` subpath flattens it:
+
+```typescript
+import { extractAslFromTemplate } from 'sfn-diagram/cfn';
+import { generateMermaid } from 'sfn-diagram';
+
+const { aslDefinition, warnings } = extractAslFromTemplate({ template: cdkSynthJson });
+const { code } = generateMermaid({ aslDefinition });
+```
+
+Both JSON and YAML templates are supported (CloudFormation short-form tags like
+`!Sub` / `!GetAtt` included), and `DefinitionSubstitutions` are applied. When a
+template contains more than one state machine, pass `resourceId` to pick one.
+
+CLI (JSON templates auto-detect; use `--resolve-cfn` for YAML):
+
+```bash
+cdk synth > template.json
+npx sfn-diagram template.json --format mermaid
+npx sfn-diagram template.yaml --resolve-cfn --resource MyMachine --format svg -o out.svg
+```
+
+Intrinsics that don't affect the flow become readable placeholders
+(`${AWS::Partition}`, `<Ref:LogicalId>`). External `DefinitionUri` definitions
+are not supported — pass a template with an inline definition.
+
+### 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.
@@ -259,23 +466,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 });
@@ -294,6 +512,29 @@ generateSvg({ aslDefinition: asl, theme: customTheme });
 - `'straight'` - Direct straight lines
 - `'orthogonal'` - Right-angled paths
 
+### Large diagrams
+
+Big, branchy state machines are hard to read as a static image. A few options help:
+
+- **`--format html`** (or `generateHtml()`) — a self-contained interactive viewer
+  (drag to pan, wheel to zoom, fit/reset toolbar). No external dependencies, opens
+  offline straight from `file://`.
+  ```bash
+  npx sfn-diagram state.asl.json --format html -o diagram.html
+  ```
+  > **Known limitation:** if you also pass `showIcons: true`, the embedded SVG
+  > references AWS service icons hosted on a jsDelivr CDN (see
+  > [AWS Service Icons](#aws-service-icons) below), so the HTML is no longer fully
+  > offline — icons won't load without network access.
+- **`--hide-catch`** (or `catchHandling: 'hide'`) — drop per-state error-handler
+  (`Catch`) branches so the happy path stands out. A handler that's also reachable
+  via the happy path is kept.
+  ```bash
+  npx sfn-diagram state.asl.json --hide-catch --format svg -o diagram.svg
+  ```
+- **`--layout LR`** (or `layout: 'LR'`) — the default `TB` layout makes catch-heavy
+  or deeply branching machines extremely tall; `LR` reads better for wide graphs.
+
 ### AWS Service Icons
 
 Display AWS service icons on Task state nodes to improve diagram readability and quickly identify which AWS services are being used.
@@ -531,7 +772,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
 
@@ -547,28 +788,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,52 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _aws_sdk_client_sfn = require("@aws-sdk/client-sfn");
+//#region src/aws.ts
+/**
+* @module
+*
+* Node-only AWS convenience helpers for `sfn-diagram` (the `sfn-diagram/aws` subpath).
+*
+* 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,51 @@
+import { GetExecutionHistoryCommand } from "@aws-sdk/client-sfn";
+//#region src/aws.ts
+/**
+* @module
+*
+* Node-only AWS convenience helpers for `sfn-diagram` (the `sfn-diagram/aws` subpath).
+*
+* 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 };