sfn-diagram 1.6.1 → 1.8.0

package/README.md

@@ -21,10 +21,10 @@ Generate diagrams from AWS Step Functions ASL (Amazon States Language) definitio
 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`:
+The core package pulls in **no browser engine or native rasterizer** — SVG and Mermaid generation stay lightweight. PNG export uses `@resvg/resvg-js`, a native, browser-free renderer, provided by an optional peer dependency. Install it only if you use `sfn-diagram/png`:
 
 ```bash
-npm install sfn-diagram node-html-to-image
+npm install sfn-diagram @resvg/resvg-js
 ```
 
 Not a Node project? The CLI also ships as standalone binaries for Linux, macOS, and Windows on every [release](https://github.com/yusufaf/sfn-diagram/releases), or via Homebrew (`brew install yusufaf/tap/sfn-diagram`), and as a [Docker image](https://sfn.yusufaf.dev/guides/cli/#docker). See [using sfn-diagram from other languages](https://sfn.yusufaf.dev/guides/other-languages/).
@@ -55,6 +55,26 @@ Prefer the command line:
 npx sfn-diagram my-workflow.asl.json --format svg -o diagram.svg
 ```
 
+Or render what is actually deployed, with `--from-aws`:
+
+```bash
+pnpm add @aws-sdk/client-sfn   # optional peer, only needed for --from-aws
+sfn-diagram --from-aws arn:aws:states:us-east-1:111122223333:stateMachine:Orders -o live.svg
+```
+
+The region comes from the ARN and credentials from the AWS SDK's default chain, so
+`AWS_PROFILE`, SSO and instance roles work as they do for the AWS CLI. The flag takes a
+state machine, version or alias ARN — not a bare name — is repeatable with `--out-dir`,
+and combines with `--diff` (whose baseline may itself be an ARN, for live-against-live
+drift), `--execution` and `--check`. It needs the optional peer above, so it is
+unavailable in the [standalone binary](https://sfn.yusufaf.dev/guides/cli/#standalone-binary).
+See [Rendering a live state machine](https://sfn.yusufaf.dev/guides/cli/#rendering-a-live-state-machine).
+
+It exits `0` on success, `1` when something goes wrong while running — including a failed
+AWS call — and `2` when the invocation itself was wrong, so a CI job can tell a bad flag
+from a bad definition. See
+[Exit codes](https://sfn.yusufaf.dev/guides/cli/#exit-codes).
+
 ## 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:
@@ -77,11 +97,12 @@ In short: reach for the AWS Console visualizer to eyeball a state machine you al
 - **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
+- **Linting**: `lintAsl()` returns every structural and semantic finding at once (unreachable states, dangling transitions, `End` with `Next`, JSONPath/JSONata field mixing, …); `sfn-diagram --check` fails CI on errors
+- **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. From a saved history file or live from an execution ARN, and `--follow` keeps re-rendering until the run finishes
 - **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
+- **AWS SDK Integration**: Direct integration with AWS Step Functions API, from the API (`generateFromAwsResponse`) or the CLI (`--from-aws <arn>`)
 - **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
 - **Collapse Large Diagrams**: Replace Parallel/Map containers with placeholder nodes before layout so huge diagrams stay readable, with a live toggle in the interactive HTML viewer. See the [configuration guide](https://sfn.yusufaf.dev/guides/configuration/) for `collapse` and every other option.
@@ -109,7 +130,7 @@ Full documentation lives at **[sfn.yusufaf.dev](https://sfn.yusufaf.dev)**.
 
 - [Introduction](https://sfn.yusufaf.dev/introduction/) — what it does and how it compares
 - [Quick start](https://sfn.yusufaf.dev/quick-start/) — your first diagram
-- [Command line](https://sfn.yusufaf.dev/guides/cli/) — the `sfn-diagram` CLI, diffs, and execution overlays
+- [Command line](https://sfn.yusufaf.dev/guides/cli/) — the `sfn-diagram` CLI, flags, exit codes, diffs, and execution overlays
 - [Configuration](https://sfn.yusufaf.dev/guides/configuration/) — themes, layouts, edge styles, service icons
 - [Examples](https://sfn.yusufaf.dev/guides/examples/) — complete worked examples
 - [Use with your framework](https://sfn.yusufaf.dev/guides/frameworks/) — Next.js, Remix, SvelteKit, Astro

package/dist/aws.cjs

@@ -1,4 +1,3 @@
-require("./ci.cjs");
 let _aws_sdk_client_sfn = require("@aws-sdk/client-sfn");
 //#region src/aws.ts
 /**

package/dist/aws.d.cts

@@ -1,7 +1,6 @@
 import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
-
 //#region src/aws.d.ts
-interface FetchExecutionHistoryParams {
+export interface FetchExecutionHistoryParams {
   /** A caller-constructed SFN client (with the caller's credentials/region). */
   client: SFNClient;
   /** ARN of the execution whose history should be fetched. */
@@ -10,27 +9,26 @@ interface FetchExecutionHistoryParams {
   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 };
+ * 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 });
+ * ```
+ */
+export declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion

package/dist/aws.d.ts

@@ -1,7 +1,6 @@
 import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
-
 //#region src/aws.d.ts
-interface FetchExecutionHistoryParams {
+export interface FetchExecutionHistoryParams {
   /** A caller-constructed SFN client (with the caller's credentials/region). */
   client: SFNClient;
   /** ARN of the execution whose history should be fetched. */
@@ -10,27 +9,26 @@ interface FetchExecutionHistoryParams {
   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 };
+ * 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 });
+ * ```
+ */
+export declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion