awaitly-visualizer 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,242 @@
+import { WorkflowEvent } from 'awaitly/workflow';
+export { ScopeType } from 'awaitly/workflow';
+import { D as DiagramSource, E as ExportFormat, a as ExportOptions, b as DecisionStartEvent, c as DecisionBranchEvent, d as DecisionEndEvent, S as ScopeStartEvent, e as ScopeEndEvent, W as WorkflowIR, O as OutputFormat, V as VisualizerOptions } from './url-PkfQz4V5.cjs';
+export { A as ActiveStepSnapshot, B as BaseNode, C as ColorScheme, f as DecisionBranch, g as DecisionEvent, h as DecisionNode, i as EnhancedRenderOptions, F as FlowNode, j as FlowchartRenderOptions, H as HTMLRenderOptions, k as HTMLTheme, l as HeatLevel, m as HeatmapData, n as HookExecution, o as HookState, I as IRSnapshot, K as KrokiExportOptions, p as KrokiFormat, L as LayoutDirection, q as LiveVisualizerOptions, M as MermaidInkExportOptions, r as MermaidRenderOptions, N as NodePerformance, P as ParallelNode, R as RaceNode, s as RenderOptions, t as Renderer, u as ScopeEvent, v as SequenceNode, w as ServerMessage, x as StepNode, y as StepSkippedEvent, z as StepState, G as StreamNode, T as TimeTravelState, U as UrlGeneratorOptions, J as VisualizingWorkflowOptions, Q as WebVisualizerMessage, X as WorkflowHooks, Y as WorkflowNode, Z as createUrlGenerator, _ as hasChildren, $ as isDecisionNode, a0 as isParallelNode, a1 as isRaceNode, a2 as isSequenceNode, a3 as isStepNode, a4 as isStreamNode, a5 as toKrokiPngUrl, a6 as toKrokiSvgUrl, a7 as toKrokiUrl } from './url-PkfQz4V5.cjs';
+export { D as DecisionTracker, H as HookLog, I as IRBuilderOptions, a as IfTracker, L as LiveVisualizer, b as LoggerOutput, c as LoggerRenderOptions, P as ParallelDetectorOptions, d as PerformanceAnalyzer, S as StepLog, e as SwitchTracker, T as TimeTravelController, f as TimeTravelOptions, W as WorkflowRun, g as WorkflowSummary, h as asciiRenderer, i as createIRBuilder, j as createLiveVisualizer, k as createParallelDetector, l as createPerformanceAnalyzer, m as createTimeTravelController, n as defaultColorScheme, o as detectParallelGroups, p as flowchartRenderer, q as getHeatLevel, r as htmlRenderer, s as loggerRenderer, t as mermaidRenderer, u as renderToHTML, v as trackDecision, w as trackIf, x as trackSwitch } from './performance-analyzer-BNwE4AiO.cjs';
+export { D as DiagramProvider, K as KrokiProviderOptions, M as MermaidInkFormat, a as MermaidInkGenerator, b as MermaidInkImageType, c as MermaidInkOptions, d as MermaidInkPaperSize, e as MermaidInkProviderOptions, f as MermaidInkTheme, P as ProviderOptions, g as buildMermaidInkUrl, h as createMermaidInkGenerator, i as encodeForMermaidInk, t as toMermaidInkJpegUrl, j as toMermaidInkPdfUrl, k as toMermaidInkPngUrl, l as toMermaidInkSvgUrl, m as toMermaidInkUrl, n as toMermaidInkWebpUrl } from './types-BnWc9Wlr.cjs';
+import { Result } from 'awaitly';
+import 'awaitly/core';
+
+/**
+ * Unified Export URL Generation
+ *
+ * Generates export URLs from diagram sources using configured providers.
+ * Decoupled from IR - takes already-rendered diagram text.
+ */
+
+/**
+ * Error types for export URL generation.
+ */
+type ExportUrlError = "UNSUPPORTED_DIAGRAM_KIND" | "UNSUPPORTED_FORMAT" | "UNKNOWN_PROVIDER";
+/**
+ * Internal context for export operations.
+ * Used to provide caller context in error messages.
+ */
+interface ExportContext {
+    /** The calling method name (e.g., "toSvgUrl") */
+    caller?: string;
+}
+/**
+ * Generate export URL from diagram source.
+ * Decoupled from IR - takes already-rendered diagram text.
+ *
+ * @param diagram - The diagram source (kind + text)
+ * @param format - Export format (svg, png, pdf)
+ * @param options - Provider-specific options
+ * @param ctx - Optional context for error messages
+ * @returns Result with export URL or ExportUrlError
+ *
+ * @example
+ * ```typescript
+ * const result = toExportUrl(
+ *   { kind: "mermaid", source: "flowchart TD\n  A-->B" },
+ *   "svg",
+ *   { provider: "kroki" }
+ * );
+ * if (result.ok) {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+declare function toExportUrl(diagram: DiagramSource, format: ExportFormat, options: ExportOptions, ctx?: ExportContext): Result<string, ExportUrlError>;
+
+/**
+ * Workflow Visualization Module
+ *
+ * Provides tools for visualizing workflow execution with color-coded
+ * step states and support for parallel/race operations.
+ *
+ * @example
+ * ```typescript
+ * import { createVisualizer } from 'awaitly-visualizer';
+ *
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * const workflow = createWorkflow(deps, { onEvent: viz.handleEvent });
+ *
+ * await workflow(async (step) => {
+ *   await step(() => validateCart(cart), 'Validate cart');
+ *   await step(() => processPayment(payment), 'Process payment');
+ * });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+
+/**
+ * Workflow visualizer that processes events and renders output.
+ */
+interface WorkflowVisualizer {
+    /** Process a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Process a scope event (parallel/race) */
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    /** Process a decision event (conditional branches) */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get current IR state */
+    getIR: () => WorkflowIR;
+    /** Render current state using the default renderer */
+    render: () => string;
+    /** Render to a specific format */
+    renderAs: (format: OutputFormat) => string;
+    /** Reset state for a new workflow */
+    reset: () => void;
+    /** Subscribe to IR updates (for live visualization) */
+    onUpdate: (callback: (ir: WorkflowIR) => void) => () => void;
+    /**
+     * Generate export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param format - Export format (svg, png, pdf)
+     * @param options - Provider options (required unless default configured)
+     * @returns The export URL
+     * @throws If no provider configured and none passed
+     * @throws If format not supported by provider
+     */
+    toUrl: (format: ExportFormat, options?: ExportOptions) => string;
+    /**
+     * Generate SVG export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The SVG export URL
+     * @throws If no provider configured and none passed
+     */
+    toSvgUrl: (options?: ExportOptions) => string;
+    /**
+     * Generate PNG export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The PNG export URL
+     * @throws If no provider configured and none passed
+     */
+    toPngUrl: (options?: ExportOptions) => string;
+    /**
+     * Generate PDF export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     * Note: Kroki does not support PDF for mermaid diagrams.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The PDF export URL
+     * @throws If no provider configured and none passed
+     * @throws If provider doesn't support PDF (e.g., Kroki for mermaid)
+     */
+    toPdfUrl: (options?: ExportOptions) => string;
+}
+/**
+ * Create a workflow visualizer.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'my-workflow' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: viz.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => { ... });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+declare function createVisualizer(options?: VisualizerOptions): WorkflowVisualizer;
+/**
+ * Combine multiple event handlers into one.
+ * Use when you need visualization + logging + custom handlers.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: combineEventHandlers(
+ *     viz.handleEvent,
+ *     (e) => console.log(e.type),
+ *     (e) => metrics.track(e),
+ *   ),
+ * });
+ * ```
+ */
+declare function combineEventHandlers<E = unknown, C = void>(...handlers: Array<(event: WorkflowEvent<E, C>, ctx?: C) => void>): (event: WorkflowEvent<E, C>, ctx: C) => void;
+/**
+ * Union type for all collectable/visualizable events (workflow + decision).
+ */
+type CollectableEvent = WorkflowEvent<unknown> | DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent;
+/**
+ * Visualize collected events (post-execution).
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const events: CollectableEvent[] = [];
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: (e) => events.push(e),
+ * });
+ *
+ * await workflow(async (step) => {
+ *   const decision = trackIf('check', condition, {
+ *     emit: (e) => events.push(e),
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(visualizeEvents(events));
+ * ```
+ */
+declare function visualizeEvents(events: CollectableEvent[], options?: VisualizerOptions): string;
+/**
+ * Create an event collector for later visualization.
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const collector = createEventCollector();
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: collector.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => {
+ *   // Decision events can also be collected
+ *   const decision = trackIf('check', condition, {
+ *     emit: collector.handleDecisionEvent,
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(collector.visualize());
+ * ```
+ */
+declare function createEventCollector(options?: VisualizerOptions): {
+    /** Handle a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Handle a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get all collected events */
+    getEvents: () => CollectableEvent[];
+    /** Get workflow events only */
+    getWorkflowEvents: () => WorkflowEvent<unknown>[];
+    /** Get decision events only */
+    getDecisionEvents: () => (DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent)[];
+    /** Clear collected events */
+    clear: () => void;
+    /** Visualize collected events */
+    visualize: () => string;
+    /** Visualize in a specific format */
+    visualizeAs: (format: OutputFormat) => string;
+};
+
+export { type CollectableEvent, DecisionBranchEvent, DecisionEndEvent, DecisionStartEvent, DiagramSource, ExportFormat, ExportOptions, OutputFormat, ScopeEndEvent, ScopeStartEvent, VisualizerOptions, WorkflowIR, type WorkflowVisualizer, combineEventHandlers, createEventCollector, createVisualizer, toExportUrl, visualizeEvents };

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+import { WorkflowEvent } from 'awaitly/workflow';
+export { ScopeType } from 'awaitly/workflow';
+import { D as DiagramSource, E as ExportFormat, a as ExportOptions, b as DecisionStartEvent, c as DecisionBranchEvent, d as DecisionEndEvent, S as ScopeStartEvent, e as ScopeEndEvent, W as WorkflowIR, O as OutputFormat, V as VisualizerOptions } from './url-PkfQz4V5.js';
+export { A as ActiveStepSnapshot, B as BaseNode, C as ColorScheme, f as DecisionBranch, g as DecisionEvent, h as DecisionNode, i as EnhancedRenderOptions, F as FlowNode, j as FlowchartRenderOptions, H as HTMLRenderOptions, k as HTMLTheme, l as HeatLevel, m as HeatmapData, n as HookExecution, o as HookState, I as IRSnapshot, K as KrokiExportOptions, p as KrokiFormat, L as LayoutDirection, q as LiveVisualizerOptions, M as MermaidInkExportOptions, r as MermaidRenderOptions, N as NodePerformance, P as ParallelNode, R as RaceNode, s as RenderOptions, t as Renderer, u as ScopeEvent, v as SequenceNode, w as ServerMessage, x as StepNode, y as StepSkippedEvent, z as StepState, G as StreamNode, T as TimeTravelState, U as UrlGeneratorOptions, J as VisualizingWorkflowOptions, Q as WebVisualizerMessage, X as WorkflowHooks, Y as WorkflowNode, Z as createUrlGenerator, _ as hasChildren, $ as isDecisionNode, a0 as isParallelNode, a1 as isRaceNode, a2 as isSequenceNode, a3 as isStepNode, a4 as isStreamNode, a5 as toKrokiPngUrl, a6 as toKrokiSvgUrl, a7 as toKrokiUrl } from './url-PkfQz4V5.js';
+export { D as DecisionTracker, H as HookLog, I as IRBuilderOptions, a as IfTracker, L as LiveVisualizer, b as LoggerOutput, c as LoggerRenderOptions, P as ParallelDetectorOptions, d as PerformanceAnalyzer, S as StepLog, e as SwitchTracker, T as TimeTravelController, f as TimeTravelOptions, W as WorkflowRun, g as WorkflowSummary, h as asciiRenderer, i as createIRBuilder, j as createLiveVisualizer, k as createParallelDetector, l as createPerformanceAnalyzer, m as createTimeTravelController, n as defaultColorScheme, o as detectParallelGroups, p as flowchartRenderer, q as getHeatLevel, r as htmlRenderer, s as loggerRenderer, t as mermaidRenderer, u as renderToHTML, v as trackDecision, w as trackIf, x as trackSwitch } from './performance-analyzer-B5VF5b1F.js';
+export { D as DiagramProvider, K as KrokiProviderOptions, M as MermaidInkFormat, a as MermaidInkGenerator, b as MermaidInkImageType, c as MermaidInkOptions, d as MermaidInkPaperSize, e as MermaidInkProviderOptions, f as MermaidInkTheme, P as ProviderOptions, g as buildMermaidInkUrl, h as createMermaidInkGenerator, i as encodeForMermaidInk, t as toMermaidInkJpegUrl, j as toMermaidInkPdfUrl, k as toMermaidInkPngUrl, l as toMermaidInkSvgUrl, m as toMermaidInkUrl, n as toMermaidInkWebpUrl } from './types-BIZSmXif.js';
+import { Result } from 'awaitly';
+import 'awaitly/core';
+
+/**
+ * Unified Export URL Generation
+ *
+ * Generates export URLs from diagram sources using configured providers.
+ * Decoupled from IR - takes already-rendered diagram text.
+ */
+
+/**
+ * Error types for export URL generation.
+ */
+type ExportUrlError = "UNSUPPORTED_DIAGRAM_KIND" | "UNSUPPORTED_FORMAT" | "UNKNOWN_PROVIDER";
+/**
+ * Internal context for export operations.
+ * Used to provide caller context in error messages.
+ */
+interface ExportContext {
+    /** The calling method name (e.g., "toSvgUrl") */
+    caller?: string;
+}
+/**
+ * Generate export URL from diagram source.
+ * Decoupled from IR - takes already-rendered diagram text.
+ *
+ * @param diagram - The diagram source (kind + text)
+ * @param format - Export format (svg, png, pdf)
+ * @param options - Provider-specific options
+ * @param ctx - Optional context for error messages
+ * @returns Result with export URL or ExportUrlError
+ *
+ * @example
+ * ```typescript
+ * const result = toExportUrl(
+ *   { kind: "mermaid", source: "flowchart TD\n  A-->B" },
+ *   "svg",
+ *   { provider: "kroki" }
+ * );
+ * if (result.ok) {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+declare function toExportUrl(diagram: DiagramSource, format: ExportFormat, options: ExportOptions, ctx?: ExportContext): Result<string, ExportUrlError>;
+
+/**
+ * Workflow Visualization Module
+ *
+ * Provides tools for visualizing workflow execution with color-coded
+ * step states and support for parallel/race operations.
+ *
+ * @example
+ * ```typescript
+ * import { createVisualizer } from 'awaitly-visualizer';
+ *
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * const workflow = createWorkflow(deps, { onEvent: viz.handleEvent });
+ *
+ * await workflow(async (step) => {
+ *   await step(() => validateCart(cart), 'Validate cart');
+ *   await step(() => processPayment(payment), 'Process payment');
+ * });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+
+/**
+ * Workflow visualizer that processes events and renders output.
+ */
+interface WorkflowVisualizer {
+    /** Process a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Process a scope event (parallel/race) */
+    handleScopeEvent: (event: ScopeStartEvent | ScopeEndEvent) => void;
+    /** Process a decision event (conditional branches) */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get current IR state */
+    getIR: () => WorkflowIR;
+    /** Render current state using the default renderer */
+    render: () => string;
+    /** Render to a specific format */
+    renderAs: (format: OutputFormat) => string;
+    /** Reset state for a new workflow */
+    reset: () => void;
+    /** Subscribe to IR updates (for live visualization) */
+    onUpdate: (callback: (ir: WorkflowIR) => void) => () => void;
+    /**
+     * Generate export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param format - Export format (svg, png, pdf)
+     * @param options - Provider options (required unless default configured)
+     * @returns The export URL
+     * @throws If no provider configured and none passed
+     * @throws If format not supported by provider
+     */
+    toUrl: (format: ExportFormat, options?: ExportOptions) => string;
+    /**
+     * Generate SVG export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The SVG export URL
+     * @throws If no provider configured and none passed
+     */
+    toSvgUrl: (options?: ExportOptions) => string;
+    /**
+     * Generate PNG export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The PNG export URL
+     * @throws If no provider configured and none passed
+     */
+    toPngUrl: (options?: ExportOptions) => string;
+    /**
+     * Generate PDF export URL for the current workflow diagram.
+     * Requires explicit provider unless export.default is configured.
+     * Note: Kroki does not support PDF for mermaid diagrams.
+     *
+     * @param options - Provider options (required unless default configured)
+     * @returns The PDF export URL
+     * @throws If no provider configured and none passed
+     * @throws If provider doesn't support PDF (e.g., Kroki for mermaid)
+     */
+    toPdfUrl: (options?: ExportOptions) => string;
+}
+/**
+ * Create a workflow visualizer.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'my-workflow' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: viz.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => { ... });
+ *
+ * console.log(viz.render());
+ * ```
+ */
+declare function createVisualizer(options?: VisualizerOptions): WorkflowVisualizer;
+/**
+ * Combine multiple event handlers into one.
+ * Use when you need visualization + logging + custom handlers.
+ *
+ * @example
+ * ```typescript
+ * const viz = createVisualizer({ workflowName: 'checkout' });
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: combineEventHandlers(
+ *     viz.handleEvent,
+ *     (e) => console.log(e.type),
+ *     (e) => metrics.track(e),
+ *   ),
+ * });
+ * ```
+ */
+declare function combineEventHandlers<E = unknown, C = void>(...handlers: Array<(event: WorkflowEvent<E, C>, ctx?: C) => void>): (event: WorkflowEvent<E, C>, ctx: C) => void;
+/**
+ * Union type for all collectable/visualizable events (workflow + decision).
+ */
+type CollectableEvent = WorkflowEvent<unknown> | DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent;
+/**
+ * Visualize collected events (post-execution).
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const events: CollectableEvent[] = [];
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: (e) => events.push(e),
+ * });
+ *
+ * await workflow(async (step) => {
+ *   const decision = trackIf('check', condition, {
+ *     emit: (e) => events.push(e),
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(visualizeEvents(events));
+ * ```
+ */
+declare function visualizeEvents(events: CollectableEvent[], options?: VisualizerOptions): string;
+/**
+ * Create an event collector for later visualization.
+ *
+ * Supports both workflow events (from onEvent) and decision events
+ * (from trackDecision/trackIf/trackSwitch).
+ *
+ * @example
+ * ```typescript
+ * const collector = createEventCollector();
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: collector.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => {
+ *   // Decision events can also be collected
+ *   const decision = trackIf('check', condition, {
+ *     emit: collector.handleDecisionEvent,
+ *   });
+ *   // ...
+ * });
+ *
+ * console.log(collector.visualize());
+ * ```
+ */
+declare function createEventCollector(options?: VisualizerOptions): {
+    /** Handle a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Handle a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get all collected events */
+    getEvents: () => CollectableEvent[];
+    /** Get workflow events only */
+    getWorkflowEvents: () => WorkflowEvent<unknown>[];
+    /** Get decision events only */
+    getDecisionEvents: () => (DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent)[];
+    /** Clear collected events */
+    clear: () => void;
+    /** Visualize collected events */
+    visualize: () => string;
+    /** Visualize in a specific format */
+    visualizeAs: (format: OutputFormat) => string;
+};
+
+export { type CollectableEvent, DecisionBranchEvent, DecisionEndEvent, DecisionStartEvent, DiagramSource, ExportFormat, ExportOptions, OutputFormat, ScopeEndEvent, ScopeStartEvent, VisualizerOptions, WorkflowIR, type WorkflowVisualizer, combineEventHandlers, createEventCollector, createVisualizer, toExportUrl, visualizeEvents };