sfn-diagram 0.4.1 → 0.6.0

package/README.md

@@ -2,19 +2,23 @@
 
 [![npm version](https://img.shields.io/npm/v/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
 [![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/)
 
 Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon States Language) definitions. Supports dual output formats: D3.js-based SVG and Mermaid.js diagram code, plus PNG export.
 
+**▶ [Try it in the live playground](https://yusufaf.github.io/sfn-diagram/)** — paste any ASL definition and preview the diagram instantly, no install required.
+
 ## 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
 - **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
 - **AWS SDK Integration**: Direct integration with AWS Step Functions API
 - **Dual APIs**: Function-based and class-based interfaces
+- **Runs Anywhere**: SVG and Mermaid generation has zero platform dependencies — works in Node, the browser, and edge runtimes
 
 ## Installation
 
@@ -22,6 +26,32 @@ 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
+`generateSvg`, `generateMermaid`, `generateDiagram`, and `generateFromAwsResponse`
+run in **Node, browsers, and edge runtimes** (Cloudflare Workers, Vercel Edge, Deno, Bun)
+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. 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:
+import { generateSvg } from 'sfn-diagram';
+
+// Node-only:
+import { exportPng } from 'sfn-diagram/png';
+```
+
 ## Command-line Usage
 
 The package ships a CLI for use without writing any JavaScript:
@@ -82,15 +112,15 @@ console.log(`Generated ${width}x${height} diagram`);
 ```typescript
 import { SfnDiagramGenerator } from 'sfn-diagram';
 
-const generator = new SfnDiagramGenerator()
-  .setAsl(asl)
-  .setTheme('dark')
-  .setLayout('TB')
-  .setNodeDimensions({ width: 150, height: 80 });
+const generator = new SfnDiagramGenerator({
+  theme: 'dark',
+  layout: 'TB',
+  nodeWidth: 150,
+  nodeHeight: 80,
+});
 
-const { svg } = generator.generateSvg();
-const { mermaid } = generator.generateMermaid();
-const { png } = await generator.exportPng();
+const { svg } = generator.generateSvg({ aslDefinition: asl });
+const { code } = generator.generateMermaid({ aslDefinition: asl });
 ```
 
 ## API Reference
@@ -117,7 +147,7 @@ const result = generateSvg({
   customColors: {}                 // Override colors for specific states
 });
 
-// Returns: { svg: string, width: number, height: number, nodeCount: number }
+// Returns SvgOutput: { svg: string, width: number, height: number, metadata: { edgeCount: number, nodeCount: number } }
 ```
 
 ### generateMermaid(params)
@@ -132,40 +162,43 @@ const result = generateMermaid({
   includeComments: true
 });
 
-// Returns: { mermaid: string, nodeCount: number, edgeCount: number }
+// Returns MermaidOutput: { code: string, metadata: { edgeCount: number, stateCount: number } }
 ```
 
 ### generateDiagram(params)
 
-Generate both SVG and Mermaid output simultaneously.
+Generate a diagram, choosing the output format via the `format` option (defaults to `'svg'`).
 
 ```typescript
 import { generateDiagram } from 'sfn-diagram';
 
-const result = generateDiagram({
+const svgResult = generateDiagram({
   aslDefinition: asl,
   theme: 'dark'
-});
+});                                // Returns SvgOutput
 
-// Returns: { svg: SvgOutput, mermaid: MermaidOutput }
+const mermaidResult = generateDiagram({
+  aslDefinition: asl,
+  format: 'mermaid'
+});                                // Returns MermaidOutput
 ```
 
 ### exportPng(params)
 
-Export diagram as PNG image.
+Export diagram as PNG image. Node-only — imported from the `sfn-diagram/png` subpath.
 
 ```typescript
-import { exportPng } from 'sfn-diagram';
+import { exportPng } from 'sfn-diagram/png';
 
 const result = await exportPng({
   aslDefinition: asl,
   theme: 'light',
-  quality: 1.0,
-  transparent: false
+  pngQuality: 90,               // 1–100 (default 90)
+  backgroundColor: 'transparent'
 });
 
-// Returns: { png: Buffer, width: number, height: number }
-writeFileSync('diagram.png', result.png);
+// Returns PngOutput: { buffer: Buffer, width: number, height: number, metadata: { format: 'png' } }
+writeFileSync('diagram.png', result.buffer);
 ```
 
 ### generateFromAwsResponse(params)
@@ -184,33 +217,39 @@ const response = await client.send(
 );
 
 const { svg } = generateFromAwsResponse({
-  awsResponse: response,
+  response,
   theme: 'dark'
 });
 ```
 
 ### SfnDiagramGenerator Class
 
-Fluent interface for generating diagrams.
+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.
 
 ```typescript
 import { SfnDiagramGenerator } from 'sfn-diagram';
 
-const generator = new SfnDiagramGenerator()
-  .setAsl(asl)
-  .setTheme('dark')
-  .setLayout('LR')
-  .setNodeDimensions({ width: 150, height: 80 })
-  .setSpacing({ rankSeparation: 60, nodeSeparation: 60 })
-  .setEdgeStyle('curved')
-  .setPadding(30);
-
-// Generate outputs
-const svgResult = generator.generateSvg();
-const mermaidResult = generator.generateMermaid();
-const pngResult = await generator.exportPng({ quality: 1.0 });
+const generator = new SfnDiagramGenerator({
+  theme: 'dark',
+  layout: 'LR',
+  nodeWidth: 150,
+  nodeHeight: 80,
+  rankSeparation: 60,
+  nodeSeparation: 60,
+  edgeStyle: 'curved',
+  padding: 30,
+});
+
+// Update options later (chainable)
+generator.setOptions({ theme: 'light' });
+
+// Generate outputs (aslDefinition passed per call)
+const svgResult = generator.generateSvg({ aslDefinition: asl });
+const mermaidResult = generator.generateMermaid({ aslDefinition: asl });
 ```
 
+> PNG export is a standalone function from `sfn-diagram/png` (`exportPng`), not a method on this class.
+
 ## Configuration Options
 
 ### Themes
@@ -332,7 +371,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
 
@@ -434,21 +482,23 @@ const { svg } = generateSvg({ aslDefinition: parallelAsl });
 ### Export Multiple Formats
 
 ```typescript
-import { generateDiagram, exportPng } from 'sfn-diagram';
+import { generateSvg, generateMermaid } from 'sfn-diagram';
+import { exportPng } from 'sfn-diagram/png';
 import { writeFileSync } from 'fs';
 
 // Generate SVG and Mermaid
-const { svg, mermaid } = generateDiagram({ aslDefinition: asl });
-writeFileSync('diagram.svg', svg.svg);
-writeFileSync('diagram.mmd', mermaid.mermaid);
+const { svg } = generateSvg({ aslDefinition: asl });
+const { code } = generateMermaid({ aslDefinition: asl });
+writeFileSync('diagram.svg', svg);
+writeFileSync('diagram.mmd', code);
 
-// Generate PNG
-const { png } = await exportPng({
+// Generate PNG (Node-only)
+const { buffer } = await exportPng({
   aslDefinition: asl,
-  quality: 1.0,
-  transparent: false
+  pngQuality: 90,
+  backgroundColor: 'transparent'
 });
-writeFileSync('diagram.png', png);
+writeFileSync('diagram.png', buffer);
 ```
 
 ## TypeScript Support
@@ -461,10 +511,62 @@ import type {
   DiagramOptions,
   SvgOutput,
   MermaidOutput,
-  PngOutput,
   CustomTheme,
   StateType
 } from 'sfn-diagram';
+
+// PNG types live on the Node-only subpath
+import type { PngOutput, ExportPngParams } from 'sfn-diagram/png';
+```
+
+## Ecosystem
+
+### Playground
+
+An interactive browser-based editor for exploring ASL definitions and previewing diagrams in real time. **[Open the live playground →](https://yusufaf.github.io/sfn-diagram/)** or run it locally from the [`playground/`](playground/) directory.
+
+```bash
+cd playground
+pnpm install
+pnpm dev
+```
+
+Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server.
+
+### VS Code Extension
+
+Preview Step Functions diagrams directly inside VS Code. Located in [`packages/vscode-sfn-diagram/`](packages/vscode-sfn-diagram/).
+
+**Install from source:**
+```bash
+cd packages/vscode-sfn-diagram
+pnpm install
+pnpm package          # produces vscode-sfn-diagram-*.vsix
+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.
+
+### 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/).
+
+```yaml
+# .github/workflows/sfn-preview.yml
+name: Step Functions Preview
+on:
+  pull_request:
+    paths: ['**/*.asl.json']
+
+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 }}
 ```
 
 ## Contributing