sfn-diagram 1.1.1 → 1.3.0

package/README.md

@@ -1,6 +1,8 @@
 # sfn-diagram
 
 [![npm version](https://img.shields.io/npm/v/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
+[![npm downloads](https://img.shields.io/npm/dm/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
+[![Unit Test](https://github.com/yusufaf/sfn-diagram/actions/workflows/unit-test.yml/badge.svg)](https://github.com/yusufaf/sfn-diagram/actions/workflows/unit-test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Live Playground](https://img.shields.io/badge/playground-live-brightgreen)](https://yusufaf.github.io/sfn-diagram/)
 
@@ -8,6 +10,30 @@ 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.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/parallel-dark.svg">
+  <img src="docs/images/parallel-light.svg" alt="Example diagram of a Parallel state Step Functions workflow generated by sfn-diagram" width="410">
+</picture>
+
+## Table of Contents
+
+- [What it looks like](#what-it-looks-like)
+- [Why sfn-diagram](#why-sfn-diagram)
+- [Features](#features)
+- [Installation](#installation)
+- [Runtime Support](#runtime-support)
+- [Command-line Usage](#command-line-usage)
+- [Docker](#docker)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Configuration Options](#configuration-options)
+- [Supported State Types](#supported-state-types)
+- [Examples](#examples)
+- [TypeScript Support](#typescript-support)
+- [Use with your framework](#use-with-your-framework)
+- [Ecosystem](#ecosystem)
+- [Contributing](#contributing)
+
 ## What it looks like
 
 Give it an ASL definition like this order-processing workflow ([`examples/order-processing.asl.json`](examples/order-processing.asl.json)):
@@ -57,11 +83,27 @@ stateDiagram-v2
     class OrderComplete successState
 ```
 
+## Why sfn-diagram
+
+There's no shortage of ways to look at a state machine — this is where sfn-diagram fits versus the other two most common options:
+
+| | **sfn-diagram** | AWS Console visualizer | Mermaid Live Editor |
+|---|---|---|---|
+| Input | ASL, CloudFormation/SAM/CDK templates, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
+| Output | SVG, Mermaid, PNG, interactive HTML | Static graph in-browser | Mermaid diagram only |
+| CI / PR integration | [GitHub Action](#github-action) posts a diff overlay on every PR that touches ASL | None | None |
+| Execution overlays | Paints a real run's path/status/duration onto the diagram | Basic per-execution highlighting, console-only | Not applicable |
+| Runs where | CLI, Node, browser, edge runtimes | AWS Console only | Web app only |
+| Automation | Full programmatic API (`generateSvg`, `generateMermaid`, etc.) | None — UI only | None — UI only |
+
+In short: reach for the AWS Console visualizer to eyeball a state machine you already deployed, reach for Mermaid Live if you're hand-drawing a diagram from scratch — reach for sfn-diagram when you want diagrams generated automatically from your actual definition, checked into CI, and diffed on every pull request.
+
 ## 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, plus `Catch`/`Retry` rendering
+- **Modern ASL**: Variables (`Assign`) shown per state, and Distributed Map rendered distinctly from an inline Map — including its `MaxConcurrency`, `ItemReader` source, and `ResultWriter` sink
 - **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
@@ -117,7 +159,51 @@ npx sfn-diagram state.asl.json --format mermaid > diagram.mmd
 cat state.asl.json | npx sfn-diagram - --format svg
 ```
 
-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`.
+| Flag | Description |
+|---|---|
+| `--format <svg\|mermaid\|png\|html>` | Output format (default: `svg`) |
+| `-o`, `--output <path>` | Output file (required for `png`; stdout otherwise) |
+| `--theme <light\|dark>` | Color theme for SVG/PNG/HTML (default: `light`) |
+| `--layout <TB\|LR\|RL\|BT>` | Graph direction (default: `TB`) |
+| `--hide-catch` | Drop error-handler (`Catch`) branches |
+| `--hide-variables` | Drop the `$var` annotations for ASL `Assign` blocks |
+| `--show-icons` | Draw [AWS service icons](#aws-service-icons) on Task states |
+| `--icon-position <left\|top\|right>` | Icon placement relative to the label (default: `left`) |
+| `--icon-size <pixels>` | Icon size in pixels (default: `24`) |
+| `--diff <baseline>` | Compare the input (head) against a baseline definition |
+| `--execution <history.json>` | Overlay a `GetExecutionHistory` result on the diagram |
+| `--resolve-cfn` | Treat the input as a CloudFormation/SAM/CDK template |
+| `--resource <logicalId>` | State machine to extract when the template has several |
+| `-h`, `--help` / `-v`, `--version` | Show help / version and exit |
+
+### Diff and execution overlays from the CLI
+
+```bash
+# Highlight what changed between two revisions of a definition
+npx sfn-diagram head.asl.json --diff base.asl.json -o diff.svg
+npx sfn-diagram head.asl.json --diff base.asl.json --format mermaid > diff.mmd
+
+# Colour a diagram by what actually happened in a run
+aws stepfunctions get-execution-history --execution-arn "$ARN" > history.json
+npx sfn-diagram state.asl.json --execution history.json -o run.svg
+```
+
+Both flags support `--format svg` and `--format mermaid` only, and cannot be combined
+with each other. The change/status summary is written to **stderr**, so the diagram on
+stdout still pipes cleanly:
+
+```
+Diff summary:
+  Added:     NewStep
+  Modified:  StepB
+  Removed:   StepC
+  Unchanged: 1
+```
+
+`--execution` accepts either a full `GetExecutionHistory` response (`{"events": [...]}`)
+or a bare events array. See [generateDiff](#generatemermaiddiffparams--generatediffparams)
+and [generateExecution](#generateexecutionparams--generatemermaidexecutionparams) for the
+programmatic equivalents.
 
 CloudFormation/SAM/CDK templates work as input too — see [Extracting ASL from a CDK/CloudFormation template](#extracting-asl-from-a-cdkcloudformation-template).
 
@@ -202,6 +288,7 @@ const result = generateSvg({
   padding: 20,                     // Diagram padding
   edgeStyle: 'curved',             // 'curved', 'straight', 'orthogonal'
   showStateTypes: false,           // Display state types on nodes
+  showVariables: true,             // Annotate nodes with the variables they Assign
   includeComments: true,           // Use state comments as labels
   customColors: {}                 // Override colors for specific states
 });
@@ -535,6 +622,36 @@ Big, branchy state machines are hard to read as a static image. A few options he
 - **`--layout LR`** (or `layout: 'LR'`) — the default `TB` layout makes catch-heavy
   or deeply branching machines extremely tall; `LR` reads better for wide graphs.
 
+### Variables and Distributed Map
+
+Two pieces of modern ASL are rendered explicitly, because both are otherwise
+invisible in a diagram.
+
+**Variables (`Assign`).** A state that assigns variables is annotated with their
+names beneath its label — `$orderId, $total`. The list caps at three names, then
+collapses to `+N more`, so a state assigning many variables cannot blow out the
+node width. Disable with `showVariables: false`.
+
+```typescript
+const { svg } = generateSvg({ aslDefinition: asl, showVariables: false });
+```
+
+**Distributed Map.** A Map whose `ItemProcessor` declares
+`ProcessorConfig.Mode: 'DISTRIBUTED'` runs a child execution per batch rather than
+iterating inline, so it is labelled `Distributed` in the container header instead
+of rendering identically to an inline Map. `MaxConcurrency` is shown alongside it
+when set.
+
+Its `ItemReader` (dataset source — S3 or Athena) and `ResultWriter` (result sink)
+each become a satellite node beside the container, wired in and out of the Map.
+With `showIcons: true` they pick up the appropriate AWS service icon, resolved
+from the ARN the same way Task states are.
+
+```
+ItemReader (s3) ──▶ ProcessItems ──▶ ResultWriter (s3)
+                  Distributed · max 100
+```
+
 ### AWS Service Icons
 
 Display AWS service icons on Task state nodes to improve diagram readability and quickly identify which AWS services are being used.
@@ -760,6 +877,120 @@ import type {
 import type { PngOutput, ExportPngParams } from 'sfn-diagram/png';
 ```
 
+## Use with your framework
+
+`generateSvg()` returns an SVG **string** and the core has no DOM dependency, so any
+framework can render a diagram by injecting that string. There is nothing React-specific
+in the core — [`sfn-diagram-react`](packages/sfn-diagram-react/) exists for convenience,
+not necessity.
+
+Each snippet below is the whole integration. See [API Reference](#api-reference) for the
+full option set (`theme`, `layout`, `showIcons`, …) and [`generateMermaid`](#generatemermaidparams)
+if you would rather emit Mermaid than SVG.
+
+**Svelte 5**
+
+```svelte
+<script lang="ts">
+  import { generateSvg } from 'sfn-diagram';
+
+  let { definition } = $props();
+  const svg = $derived(generateSvg({ aslDefinition: definition }).svg);
+</script>
+
+{@html svg}
+```
+
+**Vue 3**
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+const props = defineProps<{ definition: AslDefinition | string }>();
+const svg = computed(() => generateSvg({ aslDefinition: props.definition }).svg);
+</script>
+
+<template>
+  <div v-html="svg" />
+</template>
+```
+
+**Solid**
+
+```tsx
+import { createMemo } from 'solid-js';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+export function SfnDiagram(props: { definition: AslDefinition | string }) {
+  const svg = createMemo(() => generateSvg({ aslDefinition: props.definition }).svg);
+  return <div innerHTML={svg()} />;
+}
+```
+
+**Angular**
+
+`[innerHTML]` strips SVG unless the value is marked trusted, so the sanitizer bypass is required.
+
+```ts
+import { Component, computed, inject, input } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+import { generateSvg } from 'sfn-diagram';
+import type { AslDefinition } from 'sfn-diagram';
+
+@Component({
+  selector: 'sfn-diagram',
+  template: `<div [innerHTML]="svg()"></div>`,
+})
+export class SfnDiagramComponent {
+  readonly definition = input.required<AslDefinition | string>();
+  private readonly sanitizer = inject(DomSanitizer);
+
+  readonly svg = computed(() =>
+    this.sanitizer.bypassSecurityTrustHtml(
+      generateSvg({ aslDefinition: this.definition() }).svg
+    )
+  );
+}
+```
+
+**Astro**
+
+Astro runs the frontmatter at build time, so the diagram ships as static markup with
+**zero client-side JavaScript** — the DOM-free core at its best. (Astro also hosts React
+islands, so `sfn-diagram-react` works there too if you need interactivity.)
+
+```astro
+---
+import { generateSvg } from 'sfn-diagram';
+// `?raw` gives the file as a string, which `aslDefinition` accepts directly
+import definition from '../workflows/order-processing.asl.json?raw';
+
+const { svg } = generateSvg({ aslDefinition: definition, theme: 'light' });
+---
+
+<Fragment set:html={svg} />
+```
+
+**Vanilla JS / htmx / anything else**
+
+```js
+import { generateSvg } from 'sfn-diagram';
+
+const response = await fetch('/workflows/order-processing.asl.json');
+const { svg } = generateSvg({ aslDefinition: await response.text() });
+document.querySelector('#diagram').innerHTML = svg;
+```
+
+> **On the "unsafe HTML" APIs.** Every snippet above uses its framework's raw-HTML escape
+> hatch (`{@html}`, `v-html`, `innerHTML`, `dangerouslySetInnerHTML`). The SVG builder
+> HTML-escapes every attribute and text value it emits, following the HTML serialization
+> algorithm, so state names, comments, and choice conditions taken from your ASL are
+> escaped before they reach the string.
+
 ## Ecosystem
 
 ### Playground
@@ -790,7 +1021,11 @@ code --install-extension vscode-sfn-diagram-*.vsix
 
 ### 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.
+Render diagrams in a React app with the [`sfn-diagram-react`](https://www.npmjs.com/package/sfn-diagram-react) package ([source](packages/sfn-diagram-react/)). It wraps `generateSvg`/`generateMermaid` in a component with the same platform-agnostic core, so it works in any React renderer. React 18 and 19 are both supported.
+
+```bash
+npm install sfn-diagram-react sfn-diagram react
+```
 
 ```tsx
 import { SfnDiagram } from 'sfn-diagram-react';

package/dist/cfn.d.cts

@@ -23,8 +23,33 @@ interface ChoiceRule {
   Variable?: string;
   [key: string]: any;
 }
+/**
+* A Map state's `ProcessorConfig`, which selects between the inline and
+* distributed execution modes. `Mode: 'DISTRIBUTED'` marks a Distributed Map —
+* a separate child execution per batch, with its own concurrency and failure
+* tolerance semantics.
+*/
+interface ProcessorConfig {
+  ExecutionType?: "EXPRESS" | "STANDARD";
+  Mode?: "DISTRIBUTED" | "INLINE";
+}
+/**
+* A Distributed Map `ItemReader` (dataset source) or `ResultWriter` (result sink).
+* Both point at an AWS resource — typically S3, or Athena for `ItemReader` — via
+* the same `Resource` ARN shape used by Task states.
+*/
+interface ItemIo {
+  Parameters?: Record<string, any>;
+  ReaderConfig?: {
+    InputType?: string;
+    MaxItems?: number;
+  };
+  Resource?: string;
+  WriterConfig?: Record<string, any>;
+}
 /** A single state within an ASL definition, covering fields for every state type. */
 interface AslState {
+  Arguments?: Record<string, any>;
   Assign?: Record<string, any>;
   Branches?: AslDefinition[];
   Catch?: CatchBlock[];
@@ -34,8 +59,13 @@ interface AslState {
   Default?: string;
   End?: boolean;
   Error?: string;
+  ItemBatcher?: Record<string, any>;
   ItemProcessor?: AslDefinition;
+  ItemReader?: ItemIo;
+  ItemSelector?: Record<string, any>;
   Iterator?: AslDefinition;
+  Label?: string;
+  MaxConcurrency?: number | string;
   Next?: string;
   Output?: any;
   Parameters?: Record<string, any>;
@@ -43,16 +73,25 @@ interface AslState {
   Resource?: string;
   Result?: any;
   ResultPath?: string;
+  ResultWriter?: ItemIo;
   Retry?: RetryBlock[];
   Seconds?: number | string;
   SecondsPath?: string;
   Timestamp?: string;
   TimestampPath?: string;
+  ToleratedFailureCount?: number;
+  ToleratedFailurePercentage?: number;
   Type: StateType;
 }
 /** A complete Amazon States Language state machine definition. */
 interface AslDefinition {
   Comment?: string;
+  /**
+  * Map-specific, and only valid on an `ItemProcessor` sub-definition rather
+  * than on the Map state itself — this is where the ASL spec places it.
+  * Selects inline vs distributed execution.
+  */
+  ProcessorConfig?: ProcessorConfig;
   QueryLanguage?: "JSONata" | "JSONPath";
   StartAt: string;
   States: Record<string, AslState>;

package/dist/cfn.d.ts

@@ -23,8 +23,33 @@ interface ChoiceRule {
   Variable?: string;
   [key: string]: any;
 }
+/**
+* A Map state's `ProcessorConfig`, which selects between the inline and
+* distributed execution modes. `Mode: 'DISTRIBUTED'` marks a Distributed Map —
+* a separate child execution per batch, with its own concurrency and failure
+* tolerance semantics.
+*/
+interface ProcessorConfig {
+  ExecutionType?: "EXPRESS" | "STANDARD";
+  Mode?: "DISTRIBUTED" | "INLINE";
+}
+/**
+* A Distributed Map `ItemReader` (dataset source) or `ResultWriter` (result sink).
+* Both point at an AWS resource — typically S3, or Athena for `ItemReader` — via
+* the same `Resource` ARN shape used by Task states.
+*/
+interface ItemIo {
+  Parameters?: Record<string, any>;
+  ReaderConfig?: {
+    InputType?: string;
+    MaxItems?: number;
+  };
+  Resource?: string;
+  WriterConfig?: Record<string, any>;
+}
 /** A single state within an ASL definition, covering fields for every state type. */
 interface AslState {
+  Arguments?: Record<string, any>;
   Assign?: Record<string, any>;
   Branches?: AslDefinition[];
   Catch?: CatchBlock[];
@@ -34,8 +59,13 @@ interface AslState {
   Default?: string;
   End?: boolean;
   Error?: string;
+  ItemBatcher?: Record<string, any>;
   ItemProcessor?: AslDefinition;
+  ItemReader?: ItemIo;
+  ItemSelector?: Record<string, any>;
   Iterator?: AslDefinition;
+  Label?: string;
+  MaxConcurrency?: number | string;
   Next?: string;
   Output?: any;
   Parameters?: Record<string, any>;
@@ -43,16 +73,25 @@ interface AslState {
   Resource?: string;
   Result?: any;
   ResultPath?: string;
+  ResultWriter?: ItemIo;
   Retry?: RetryBlock[];
   Seconds?: number | string;
   SecondsPath?: string;
   Timestamp?: string;
   TimestampPath?: string;
+  ToleratedFailureCount?: number;
+  ToleratedFailurePercentage?: number;
   Type: StateType;
 }
 /** A complete Amazon States Language state machine definition. */
 interface AslDefinition {
   Comment?: string;
+  /**
+  * Map-specific, and only valid on an `ItemProcessor` sub-definition rather
+  * than on the Map state itself — this is where the ASL spec places it.
+  * Selects inline vs distributed execution.
+  */
+  ProcessorConfig?: ProcessorConfig;
   QueryLanguage?: "JSONata" | "JSONPath";
   StartAt: string;
   States: Record<string, AslState>;