sfn-diagram 0.5.1 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 
 - **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
@@ -26,6 +26,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 +40,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:
@@ -363,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
 

package/dist/cli.js

@@ -4,7 +4,6 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import dagre from "@dagrejs/dagre";
 import { curveBasis, line } from "d3-shape";
-import nodeHtmlToImage from "node-html-to-image";
 //#region src/config/themes.ts
 /**
 * AWS Light Theme - matches the AWS Step Functions console light mode
@@ -49,7 +48,8 @@ const AWS_LIGHT_THEME = {
 		choice: "#7b1fa2",
 		default: "#9c27b0",
 		error: "#f44336",
-		normal: "#546e7a"
+		normal: "#546e7a",
+		retry: "#f9a825"
 	},
 	textColor: "#212121",
 	fontSize: 14,
@@ -98,7 +98,8 @@ const AWS_DARK_THEME = {
 		choice: "#ce93d8",
 		default: "#ba68c8",
 		error: "#ef5350",
-		normal: "#90a4ae"
+		normal: "#90a4ae",
+		retry: "#ffca28"
 	},
 	textColor: "#e0e0e0",
 	fontSize: 14,
@@ -181,8 +182,21 @@ const EDGE_LABELS = {
 	CONDITION_FALLBACK: "Condition",
 	DEFAULT: "Default",
 	ERROR_PREFIX: "Error:",
-	ITERATOR: "Iterator"
+	ITERATOR: "Iterator",
+	RETRY_SYMBOL: "↻"
 };
+/** Default MaxAttempts when a Retry block omits it (per the ASL spec). */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/**
+* Summarize a state's Retry blocks into a compact self-loop label,
+* e.g. "↻ States.TaskFailed (3x)" or "↻ States.ALL (2x); Timeout (5x)".
+*/
+function getRetryLabel(retryBlocks) {
+	const parts = retryBlocks.map((retry) => {
+		return `${retry.ErrorEquals?.join(", ") || "All"} (${retry.MaxAttempts ?? DEFAULT_MAX_ATTEMPTS}x)`;
+	});
+	return `${EDGE_LABELS.RETRY_SYMBOL} ${parts.join("; ")}`;
+}
 /**
 * Generates an error label with error types
 */
@@ -506,7 +520,7 @@ function createStateNode(params) {
 	const baseNode = {
 		id: name,
 		isContainer,
-		label: state.Comment || name,
+		label: options?.includeComments !== false ? state.Comment || name : name,
 		style: getNodeStyle({
 			stateType: state.Type,
 			stylePreset
@@ -560,6 +574,13 @@ function extractEdgesFromState(params) {
 			});
 			break;
 	}
+	if (state.Retry && state.Retry.length > 0) edges.push({
+		from: stateName,
+		label: getRetryLabel(state.Retry),
+		to: stateName,
+		type: "retry",
+		visualOnly: true
+	});
 	if (state.Catch) state.Catch.forEach((catchBlock, index) => {
 		if (catchBlock.Next) edges.push({
 			from: stateName,
@@ -574,13 +595,87 @@ function extractEdgesFromState(params) {
 	});
 	return edges;
 }
+/** ASL data-type prefixes for typed comparison operators */
+const COMPARISON_TYPE_PREFIXES = [
+	"String",
+	"Numeric",
+	"Boolean",
+	"Timestamp"
+];
+/** Operator suffixes mapped to display symbols (longest suffixes first for matching) */
+const COMPARISON_OPERATORS = [
+	["LessThanEquals", "<="],
+	["GreaterThanEquals", ">="],
+	["LessThan", "<"],
+	["GreaterThan", ">"],
+	["Equals", "=="],
+	["Matches", "matches"]
+];
+/** Unary presence/type checks mapped to display phrases */
+const IS_CHECKS = {
+	IsBoolean: "is boolean",
+	IsNull: "is null",
+	IsNumeric: "is numeric",
+	IsPresent: "is present",
+	IsString: "is string",
+	IsTimestamp: "is timestamp"
+};
+/** Strip JSONata delimiters (`{% ... %}`) from a condition expression. */
+function cleanJsonataExpression(expression) {
+	return expression.replace(/^\{%\s*/, "").replace(/\s*%\}$/, "").trim();
+}
+/**
+* Format a single comparison operator on a Choice rule into a readable label,
+* or return null if the key is not a recognized comparison operator.
+*/
+function formatComparison(variable, operatorKey, value) {
+	const isCheckPhrase = IS_CHECKS[operatorKey];
+	if (isCheckPhrase) return value === false ? `${variable} ${isCheckPhrase.replace("is ", "is not ")}` : `${variable} ${isCheckPhrase}`;
+	const isPath = operatorKey.endsWith("Path");
+	const baseKey = isPath ? operatorKey.slice(0, -4) : operatorKey;
+	const prefix = COMPARISON_TYPE_PREFIXES.find((typePrefix) => baseKey.startsWith(typePrefix));
+	if (!prefix) return null;
+	const suffix = baseKey.slice(prefix.length);
+	const operator = COMPARISON_OPERATORS.find(([name]) => name === suffix);
+	if (!operator) return null;
+	const formattedValue = !isPath && (prefix === "String" || prefix === "Timestamp") ? JSON.stringify(value) : String(value);
+	return `${variable} ${operator[1]} ${formattedValue}`;
+}
+/**
+* Recursively describe a Choice rule, handling And/Or/Not combinators,
+* the full set of typed comparison operators, presence checks, and JSONata conditions.
+*/
+function describeChoiceRule(rule) {
+	if (rule.Condition !== void 0) return typeof rule.Condition === "string" ? cleanJsonataExpression(rule.Condition) : String(rule.Condition);
+	if (Array.isArray(rule.And)) {
+		const parts = rule.And.map(describeChoiceRule).filter(Boolean);
+		return parts.length > 0 ? parts.join(" AND ") : "";
+	}
+	if (Array.isArray(rule.Or)) {
+		const parts = rule.Or.map(describeChoiceRule).filter(Boolean);
+		return parts.length > 0 ? parts.join(" OR ") : "";
+	}
+	if (rule.Not && typeof rule.Not === "object") {
+		const inner = describeChoiceRule(rule.Not);
+		return inner ? `NOT (${inner})` : "";
+	}
+	const variable = rule.Variable || "";
+	for (const [operatorKey, value] of Object.entries(rule)) {
+		const formatted = formatComparison(variable, operatorKey, value);
+		if (formatted) return formatted;
+	}
+	return "";
+}
 function extractConditionLabel(choice) {
-	const conditions = [];
-	const variable = choice.Variable || "";
-	if (choice.StringEquals !== void 0) conditions.push(`${variable} == "${choice.StringEquals}"`);
-	if (choice.NumericEquals !== void 0) conditions.push(`${variable} == ${choice.NumericEquals}`);
-	if (choice.BooleanEquals !== void 0) conditions.push(`${variable} == ${choice.BooleanEquals}`);
-	return conditions.join(" AND ") || EDGE_LABELS.CONDITION_FALLBACK;
+	return describeChoiceRule(choice) || EDGE_LABELS.CONDITION_FALLBACK;
+}
+/**
+* Resolve a Map state's inline processor definition.
+* Prefers the modern `ItemProcessor` field (used by inline and Distributed Map)
+* and falls back to the legacy `Iterator` field for pre-2022 definitions.
+*/
+function getMapProcessor(state) {
+	return state.ItemProcessor ?? state.Iterator;
 }
 /**
 * Recursively extract all states including those nested in Parallel branches and Map iterators
@@ -626,8 +721,9 @@ function extractStatesRecursively(params) {
 				nodeIndex
 			});
 		});
-		if (state.Type === "Map" && state.Iterator) {
-			const iterator = state.Iterator;
+		const mapProcessor = state.Type === "Map" ? getMapProcessor(state) : void 0;
+		if (state.Type === "Map" && mapProcessor) {
+			const iterator = mapProcessor;
 			extractStatesRecursively({
 				definition: iterator,
 				nodeIndex,
@@ -716,15 +812,16 @@ function extractNestedEdges(params) {
 				options
 			});
 		});
-		if (state.Type === "Map" && state.Iterator) {
+		const mapProcessor = state.Type === "Map" ? getMapProcessor(state) : void 0;
+		if (state.Type === "Map" && mapProcessor) {
 			const endNodeId = `${stateName}__iterator__end`;
 			edges.push({
 				from: stateName,
-				to: state.Iterator.StartAt,
+				to: mapProcessor.StartAt,
 				type: "normal",
 				visualOnly: true
 			});
-			for (const [iteratorStateName, iteratorState] of Object.entries(state.Iterator.States)) {
+			for (const [iteratorStateName, iteratorState] of Object.entries(mapProcessor.States)) {
 				const iteratorEdges = extractEdgesFromState({
 					catchLabelStyle: options?.catchLabelStyle,
 					state: iteratorState,
@@ -751,7 +848,7 @@ function extractNestedEdges(params) {
 				});
 			}
 			extractNestedEdges({
-				definition: state.Iterator,
+				definition: mapProcessor,
 				edges,
 				options
 			});
@@ -781,6 +878,14 @@ var DagreLayout = class {
 			ranksep: this.options.rankSeparation || 50
 		});
 		graph.setDefaultEdgeLabel(() => ({}));
+		const containerIds = new Set(nodes.filter((node) => node.isContainer).map((node) => node.id));
+		const containerChildren = new Map(nodes.filter((node) => node.isContainer).map((node) => [node.id, new Set(node.children || [])]));
+		const entryChildrenByContainer = /* @__PURE__ */ new Map();
+		for (const edge of edges) if (edge.visualOnly && containerChildren.get(edge.from)?.has(edge.to)) {
+			const entries = entryChildrenByContainer.get(edge.from) ?? [];
+			entries.push(edge.to);
+			entryChildrenByContainer.set(edge.from, entries);
+		}
 		const layoutNodes = nodes.filter((node) => !node.isContainer);
 		layoutNodes.forEach((node) => {
 			const dimensions = this.getNodeDimensions(node);
@@ -792,6 +897,16 @@ var DagreLayout = class {
 			});
 		});
 		edges.filter((edge) => !edge.visualOnly).forEach((edge) => {
+			const toIsContainer = containerIds.has(edge.to);
+			const fromIsContainer = containerIds.has(edge.from);
+			if (toIsContainer && !fromIsContainer) {
+				for (const child of entryChildrenByContainer.get(edge.to) ?? []) graph.setEdge(edge.from, child, {
+					label: edge.label,
+					type: edge.type
+				});
+				return;
+			}
+			if (fromIsContainer || toIsContainer) return;
 			graph.setEdge(edge.from, edge.to, {
 				label: edge.label,
 				type: edge.type
@@ -816,7 +931,10 @@ var DagreLayout = class {
 		const allPositionedNodes = [...positionedNodes, ...containerNodes];
 		const positionedNodesById = new Map(allPositionedNodes.map((node) => [node.id, node]));
 		const routedEdges = edges.map((edge) => {
-			if (edge.visualOnly) return {
+			const fromNode = positionedNodesById.get(edge.from);
+			const toNode = positionedNodesById.get(edge.to);
+			const touchesContainer = Boolean(fromNode?.isContainer || toNode?.isContainer);
+			if (edge.visualOnly || touchesContainer) return {
 				...edge,
 				points: this.calculateVisualEdgePoints({
 					edge,
@@ -826,7 +944,7 @@ var DagreLayout = class {
 			const dagEdge = graph.edge(edge.from, edge.to);
 			return {
 				...edge,
-				points: dagEdge.points
+				points: dagEdge?.points ?? []
 			};
 		});
 		const graphDims = graph.graph();
@@ -894,6 +1012,26 @@ var DagreLayout = class {
 		const fromNode = positionedNodesById.get(edge.from);
 		const toNode = positionedNodesById.get(edge.to);
 		if (!fromNode || !toNode) return [];
+		if (edge.from === edge.to) {
+			const rightX = (fromNode.x || 0) + (fromNode.width || 0) / 2;
+			const centerY = fromNode.y || 0;
+			const loopReach = 40;
+			const loopSpread = 12;
+			return [
+				{
+					x: rightX,
+					y: centerY - loopSpread
+				},
+				{
+					x: rightX + loopReach,
+					y: centerY
+				},
+				{
+					x: rightX,
+					y: centerY + loopSpread
+				}
+			];
+		}
 		if (fromNode.isContainer && fromNode.children?.includes(edge.to)) {
 			const headerHeight = 50;
 			const fromX = fromNode.x || 0;
@@ -1036,6 +1174,7 @@ var SvgRenderer = class {
 		defs.append("marker").attr("id", "arrowhead-error").attr("markerWidth", 10).attr("markerHeight", 10).attr("refX", 9).attr("refY", 3).attr("orient", "auto").append("polygon").attr("points", "0 0, 10 3, 0 6").attr("fill", this.theme.edgeColors.error);
 		defs.append("marker").attr("id", "arrowhead-choice").attr("markerWidth", 10).attr("markerHeight", 10).attr("refX", 9).attr("refY", 3).attr("orient", "auto").append("polygon").attr("points", "0 0, 10 3, 0 6").attr("fill", this.theme.edgeColors.choice);
 		defs.append("marker").attr("id", "arrowhead-default").attr("markerWidth", 10).attr("markerHeight", 10).attr("refX", 9).attr("refY", 3).attr("orient", "auto").append("polygon").attr("points", "0 0, 10 3, 0 6").attr("fill", this.theme.edgeColors.default);
+		defs.append("marker").attr("id", "arrowhead-retry").attr("markerWidth", 10).attr("markerHeight", 10).attr("refX", 9).attr("refY", 3).attr("orient", "auto").append("polygon").attr("points", "0 0, 10 3, 0 6").attr("fill", this.resolveEdgeColor("retry"));
 		const edgesGroup = svg.append("g").attr("class", "edges");
 		const containersGroup = svg.append("g").attr("class", "containers");
 		const nodesGroup = svg.append("g").attr("class", "nodes");
@@ -1090,13 +1229,14 @@ var SvgRenderer = class {
 		});
 		layout.edges.forEach((edge) => {
 			if (edge.points) edge.points.forEach((point) => {
+				if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return;
 				minX = Math.min(minX, point.x);
 				minY = Math.min(minY, point.y);
 				maxX = Math.max(maxX, point.x);
 				maxY = Math.max(maxY, point.y);
 			});
 			if (edge.label && edge.points && edge.points.length > 0) {
-				const midpoint = this.getPathMidpoint(edge.points);
+				const midpoint = this.edgeLabelCenter(edge);
 				const labelDimensions = this.calculateLabelDimensions(edge.label);
 				const labelMinX = midpoint.x - labelDimensions.width / 2;
 				const labelMaxX = midpoint.x + labelDimensions.width / 2;
@@ -1271,19 +1411,55 @@ var SvgRenderer = class {
 	renderEdge(params) {
 		const { edge, group } = params;
 		if (!edge.points || edge.points.length < 2) return;
-		const edgeColor = this.theme.edgeColors[edge.type || "normal"];
+		const edgeColor = this.resolveEdgeColor(edge.type);
 		const markerType = edge.type || "normal";
-		const pathElement = group.append("path").attr("d", this.pathGenerator(edge.points) ?? "").attr("fill", "none").attr("stroke", edgeColor).attr("stroke-width", edge.type === "error" ? 2 : 1.5).attr("marker-end", `url(#arrowhead-${markerType})`);
+		const pathData = edge.from === edge.to ? this.buildSelfLoopPath(edge.points) : this.pathGenerator(edge.points) ?? "";
+		const pathElement = group.append("path").attr("d", pathData).attr("fill", "none").attr("stroke", edgeColor).attr("stroke-width", edge.type === "error" ? 2 : 1.5).attr("marker-end", `url(#arrowhead-${markerType})`);
 		if (edge.type === "error") pathElement.attr("stroke-dasharray", "5,5");
 		else if (edge.type === "default") pathElement.attr("stroke-dasharray", "8,4");
+		else if (edge.type === "retry") pathElement.attr("stroke-dasharray", "4,3");
 		if (edge.label) {
-			const midpoint = this.getPathMidpoint(edge.points);
+			const midpoint = this.edgeLabelCenter(edge);
 			const labelDimensions = this.calculateLabelDimensions(edge.label);
 			group.append("rect").attr("x", midpoint.x - labelDimensions.width / 2).attr("y", midpoint.y - labelDimensions.height / 2).attr("width", labelDimensions.width).attr("height", labelDimensions.height).attr("fill", this.theme.background || "#ffffff").attr("stroke", edgeColor).attr("stroke-width", .5).attr("rx", 3);
 			group.append("text").attr("x", midpoint.x).attr("y", midpoint.y).attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("fill", edgeColor).attr("font-size", this.theme.fontSize - 2).text(edge.label);
 		}
 	}
 	/**
+	* Resolve the stroke colour for an edge type, falling back to the error colour
+	* (then normal) so themes that predate a given edge type still render.
+	*/
+	resolveEdgeColor(type) {
+		const colors = this.theme.edgeColors;
+		return colors[type || "normal"] ?? colors.error ?? colors.normal;
+	}
+	/**
+	* Build an SVG path for a self-loop edge from its [entry, apex, exit] points,
+	* curving out to the apex and back so the arrow re-enters the node.
+	*/
+	buildSelfLoopPath(points) {
+		const [entry, apex, exit] = points;
+		return `M ${entry.x},${entry.y} C ${apex.x},${apex.y} ${apex.x},${apex.y} ${exit.x},${exit.y}`;
+	}
+	/**
+	* Compute where an edge's label should be centered. Normal edges center on the
+	* path midpoint; self-loops (Retry) shift the label to the right of the loop apex
+	* so a long policy label never overlaps the node it belongs to.
+	*/
+	edgeLabelCenter(edge) {
+		const points = edge.points ?? [];
+		const midpoint = this.getPathMidpoint(points);
+		if (edge.from === edge.to && edge.label) {
+			const gap = 8;
+			const labelWidth = this.calculateLabelDimensions(edge.label).width;
+			return {
+				x: midpoint.x + gap + labelWidth / 2,
+				y: midpoint.y
+			};
+		}
+		return midpoint;
+	}
+	/**
 	* Get the midpoint of a path for label placement
 	*/
 	getPathMidpoint(points) {
@@ -1578,6 +1754,20 @@ function generateMermaid(params) {
 //#endregion
 //#region src/exporters/PngExporter.ts
 /**
+* Lazily load node-html-to-image, which is an optional peer dependency.
+* Keeping it out of the static import graph means SVG/Mermaid-only consumers
+* never pull Puppeteer/Chromium, and the runtime error is actionable when it is
+* genuinely missing.
+*/
+async function loadRenderer() {
+	try {
+		const mod = await import("node-html-to-image");
+		return typeof mod === "function" ? mod : mod.default;
+	} catch {
+		throw new Error("PNG export requires the optional peer dependency 'node-html-to-image'. Install it with: npm install node-html-to-image");
+	}
+}
+/**
 * PngExporter - Converts SVG to PNG using headless rendering
 */
 var PngExporter = class {
@@ -1594,13 +1784,14 @@ var PngExporter = class {
 	*/
 	async convert(params) {
 		const { svg, width, height } = params;
+		const html = this.wrapSvgInHtml({
+			svg,
+			width,
+			height
+		});
 		return {
-			buffer: await nodeHtmlToImage({
-				html: this.wrapSvgInHtml({
-					svg,
-					width,
-					height
-				}),
+			buffer: await (await loadRenderer())({
+				html,
 				puppeteerArgs: { args: ["--no-sandbox", "--disable-setuid-sandbox"] },
 				quality: this.options.pngQuality || 90,
 				transparent: this.options.backgroundColor === "transparent",