sfn-diagram 1.2.0 → 1.3.0

package/README.md

@@ -11,8 +11,8 @@ 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="examples/outputs/parallel-dark.svg">
-  <img src="examples/outputs/parallel-light.svg" alt="Example diagram of a Parallel state Step Functions workflow generated by sfn-diagram" width="410">
+  <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
@@ -103,6 +103,7 @@ In short: reach for the AWS Console visualizer to eyeball a state machine you al
 - **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
@@ -158,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).
 
@@ -243,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
 });
@@ -576,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.

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>;