nvent 0.4.4 → 0.5.0

package/dist/runtime/events/wiring/registry.d.ts

@@ -0,0 +1,19 @@
+export interface Wiring {
+    start(): void | Promise<void>;
+    stop(): void | Promise<void>;
+}
+export interface WiringRegistryOptions {
+    /**
+     * Stream wiring options
+     */
+    streamWiring?: {
+        enabled?: boolean;
+    };
+    /**
+     * State wiring options
+     */
+    stateWiring?: {
+        strategy?: 'never' | 'on-complete' | 'immediate' | 'ttl';
+    };
+}
+export declare function createWiringRegistry(opts?: WiringRegistryOptions): Wiring;

package/dist/runtime/events/wiring/registry.js

@@ -0,0 +1,35 @@
+import { createFlowWiring } from "./flowWiring.js";
+import { createStreamWiring } from "./streamWiring.js";
+import { createStateWiring } from "./stateWiring.js";
+import { createTriggerWiring } from "./triggerWiring.js";
+export function createWiringRegistry(opts) {
+  const wirings = [
+    // 1. Flow orchestration (persistence, completion tracking, step triggering)
+    createFlowWiring(),
+    // 2. Stream wiring (publish persisted events to UI clients)
+    createStreamWiring(opts?.streamWiring || {
+      enabled: true
+    }),
+    // 3. State wiring (automatic state cleanup)
+    createStateWiring(opts?.stateWiring),
+    // 4. Trigger wiring (v0.5: trigger.fired, await.registered, await.resolved)
+    createTriggerWiring()
+  ];
+  let started = false;
+  return {
+    async start() {
+      if (started) return;
+      started = true;
+      for (const w of wirings) await w.start();
+    },
+    async stop() {
+      for (const w of wirings) {
+        try {
+          await w.stop();
+        } catch {
+        }
+      }
+      started = false;
+    }
+  };
+}

package/dist/runtime/events/wiring/stateWiring.d.ts

@@ -0,0 +1,37 @@
+/**
+ * State Wiring - Automatic cleanup of flow state
+ *
+ * Subscribes to the local event bus (single source of truth) and handles
+ * automatic cleanup of flow state based on configuration strategy.
+ *
+ * Cleanup strategies:
+ * - 'never': State persists indefinitely (default)
+ * - 'on-complete': Cleanup when flow completes (recommended)
+ * - 'immediate': Cleanup after each step (not recommended)
+ * - 'ttl': State expires automatically via TTL (handled by storage provider)
+ *
+ * Benefits:
+ * - Single source of truth (event bus)
+ * - Configurable cleanup strategies
+ * - Clear separation of concerns
+ */
+export interface StateWiringOptions {
+    /**
+     * Cleanup strategy
+     * - 'never': State persists indefinitely
+     * - 'on-complete': Cleanup when flow completes (recommended)
+     * - 'immediate': Cleanup after each step
+     * - 'ttl': State expires automatically via TTL
+     * Default: 'never'
+     */
+    strategy?: 'never' | 'on-complete' | 'immediate' | 'ttl';
+}
+/**
+ * Create state wiring
+ *
+ * Subscribes to event bus and handles state cleanup based on configuration
+ */
+export declare function createStateWiring(opts?: StateWiringOptions): {
+    start: () => void;
+    stop: () => void;
+};

package/dist/runtime/events/wiring/stateWiring.js

@@ -0,0 +1,92 @@
+import { getEventBus } from "../eventBus.js";
+import { useNventLogger, useStateAdapter, useRuntimeConfig } from "#imports";
+export function createStateWiring(opts) {
+  let strategy = opts?.strategy;
+  if (!strategy) {
+    try {
+      const rc = useRuntimeConfig();
+      strategy = rc?.nvent?.store?.state?.cleanup?.strategy || "never";
+    } catch {
+      strategy = "never";
+    }
+  }
+  const bus = getEventBus();
+  const unsubs = [];
+  let wired = false;
+  function start() {
+    if (wired) return;
+    wired = true;
+    if (strategy === "never" || strategy === "ttl") {
+      return;
+    }
+    const logger = useNventLogger("state-wiring");
+    const stateAdapter = useStateAdapter();
+    logger.info("Starting state wiring", { strategy });
+    if (strategy === "on-complete") {
+      const cleanupFlowState = async (event, reason) => {
+        const flowId = event.runId;
+        if (!flowId) return;
+        try {
+          const pattern = `flow:${flowId}:*`;
+          const deletedCount = await stateAdapter.clear(pattern);
+          if (deletedCount > 0) {
+            logger.info(`Cleaned up state after ${reason}`, {
+              flowId,
+              deletedCount
+            });
+          }
+        } catch (error) {
+          logger.error(`Error cleaning up state after ${reason}`, {
+            flowId,
+            error: error?.message
+          });
+        }
+      };
+      const handleFlowCompleted = (event) => cleanupFlowState(event, "flow completion");
+      const handleFlowFailed = (event) => cleanupFlowState(event, "flow failure");
+      const handleFlowCanceled = (event) => cleanupFlowState(event, "flow cancellation");
+      const handleFlowStalled = (event) => cleanupFlowState(event, "flow stall");
+      unsubs.push(bus.onType("flow.completed", handleFlowCompleted));
+      unsubs.push(bus.onType("flow.failed", handleFlowFailed));
+      unsubs.push(bus.onType("flow.cancel", handleFlowCanceled));
+      unsubs.push(bus.onType("flow.stalled", handleFlowStalled));
+      logger.debug("State cleanup enabled: on-complete (includes stalled and canceled)");
+    } else if (strategy === "immediate") {
+      const handleStepCompleted = async (event) => {
+        const flowId = event.runId;
+        if (!flowId) return;
+        try {
+          const pattern = `flow:${flowId}:*`;
+          const deletedCount = await stateAdapter.clear(pattern);
+          if (deletedCount > 0) {
+            logger.info("Cleaned up state after step completion", {
+              flowId,
+              stepName: event.stepName,
+              deletedCount
+            });
+          }
+        } catch (error) {
+          logger.error("Error cleaning up state after step", {
+            flowId,
+            error: error?.message
+          });
+        }
+      };
+      unsubs.push(bus.onType("step.completed", handleStepCompleted));
+      logger.debug("State cleanup enabled: immediate");
+    }
+    logger.info("State wiring started");
+  }
+  function stop() {
+    const logger = useNventLogger("state-wiring");
+    for (const unsub of unsubs.splice(0)) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    wired = false;
+    logger.debug("State wiring stopped");
+  }
+  return { start, stop };
+}

package/dist/runtime/events/wiring/streamWiring.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Stream Wiring - Bridge event bus to StreamAdapter for real-time UI updates
+ *
+ * Architecture:
+ * 1. Event Bus - Single source of truth for all events (in-memory)
+ * 2. StreamWiring - Bridges persisted events to stream topics (this file)
+ * 3. StreamAdapter - Pub/sub for real-time distribution (Redis/Memory)
+ * 4. WebSocket handlers - Subscribe to topics and send to clients
+ *
+ * Flow:
+ * Event Bus → StreamWiring → StreamAdapter → WebSocket → UI
+ *
+ * Stream Topics (defined in useStreamTopics):
+ * - stream:flow:events:{runId} - Flow events for specific run
+ * - stream:flow:stats - Flow statistics updates
+ * - stream:trigger:events:{triggerName} - Trigger events
+ * - stream:trigger:stats - Trigger statistics updates
+ *
+ * Only publishes persisted events (with id/ts) to avoid duplicates
+ */
+export interface StreamWiringOptions {
+    /**
+     * Enable client messages (WebSocket/SSE)
+     * Default: true
+     */
+    enabled?: boolean;
+}
+/**
+ * Create stream wiring
+ *
+ * Subscribes to event bus and publishes persisted events to UI clients
+ */
+export declare function createStreamWiring(opts?: StreamWiringOptions): {
+    start: () => void;
+    stop: () => void;
+};

package/dist/runtime/events/wiring/streamWiring.js

@@ -0,0 +1,156 @@
+import { getEventBus } from "../eventBus.js";
+import { useNventLogger, useStreamAdapter, useStreamTopics } from "#imports";
+export function createStreamWiring(opts = {}) {
+  const {
+    enabled = true
+  } = opts;
+  const bus = getEventBus();
+  const unsubs = [];
+  let wired = false;
+  function start() {
+    if (wired) return;
+    wired = true;
+    if (!enabled) return;
+    const logger = useNventLogger("stream-wiring");
+    const stream = useStreamAdapter();
+    const { StreamTopics } = useStreamTopics();
+    logger.info("Starting stream wiring for UI clients");
+    const handleFlowEvent = async (e) => {
+      if (!e.id || !e.ts) return;
+      const runId = e.runId;
+      if (!runId) return;
+      try {
+        const topic = StreamTopics.flowEvents(runId);
+        await stream.publish(topic, {
+          type: "flow.event",
+          data: {
+            event: {
+              id: e.id,
+              ts: e.ts,
+              type: e.type,
+              runId: e.runId,
+              flowName: e.flowName,
+              // Include step-specific fields for UI
+              stepName: e.stepName,
+              stepId: e.stepId,
+              attempt: e.attempt,
+              data: e.data
+            }
+          },
+          timestamp: Date.now()
+        });
+        logger.debug("Published flow event to stream", { type: e.type, runId });
+      } catch (err) {
+        logger.error("Failed to publish flow event to stream", {
+          error: err?.message
+        });
+      }
+    };
+    const handleTriggerEvent = async (e) => {
+      if (!e.id || !e.ts) return;
+      const triggerName = e.triggerName;
+      if (!triggerName) return;
+      try {
+        const topic = StreamTopics.triggerEvents(triggerName);
+        await stream.publish(topic, {
+          type: "trigger.event",
+          data: {
+            event: {
+              id: e.id,
+              ts: e.ts,
+              type: e.type,
+              triggerName,
+              data: e.data
+            }
+          },
+          timestamp: Date.now()
+        });
+        logger.debug("Published trigger event to stream", {
+          triggerName,
+          type: e.type,
+          id: e.id
+        });
+      } catch (err) {
+        logger.error("Failed to publish trigger event to stream", {
+          triggerName,
+          type: e.type,
+          error: err?.message
+        });
+      }
+    };
+    const flowEventTypes = [
+      "flow.start",
+      "flow.completed",
+      "flow.failed",
+      "flow.cancel",
+      "step.started",
+      "step.completed",
+      "step.failed",
+      "step.retry",
+      "await.registered",
+      "await.resolved",
+      "await.timeout",
+      "log",
+      "emit"
+    ];
+    const triggerEventTypes = [
+      "trigger.registered",
+      "trigger.updated",
+      "trigger.deleted",
+      "trigger.fired",
+      "subscription.added",
+      "subscription.removed"
+    ];
+    const handleFlowStatsUpdate = async (e) => {
+      try {
+        const topic = StreamTopics.flowStats();
+        await stream.publish(topic, {
+          id: e.flowName,
+          metadata: e.metadata
+        });
+        logger.debug("Published flow stats to stream", { flowName: e.flowName });
+      } catch (err) {
+        logger.error("Failed to publish flow stats to stream", {
+          flowName: e.flowName,
+          error: err?.message
+        });
+      }
+    };
+    const handleTriggerStatsUpdate = async (e) => {
+      try {
+        const topic = StreamTopics.triggerStats();
+        await stream.publish(topic, {
+          id: e.triggerName,
+          metadata: e.metadata
+        });
+        logger.debug("Published trigger stats to stream", { triggerName: e.triggerName });
+      } catch (err) {
+        logger.error("Failed to publish trigger stats to stream", {
+          triggerName: e.triggerName,
+          error: err?.message
+        });
+      }
+    };
+    for (const type of flowEventTypes) {
+      unsubs.push(bus.onType(type, handleFlowEvent));
+    }
+    for (const type of triggerEventTypes) {
+      unsubs.push(bus.onType(type, handleTriggerEvent));
+    }
+    unsubs.push(bus.onType("flow.stats.updated", handleFlowStatsUpdate));
+    unsubs.push(bus.onType("trigger.stats.updated", handleTriggerStatsUpdate));
+    logger.info("Stream wiring started - listening for persisted flow and trigger events");
+  }
+  function stop() {
+    const logger = useNventLogger("stream-wiring");
+    for (const unsub of unsubs.splice(0)) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    wired = false;
+    logger.debug("Stream wiring stopped");
+  }
+  return { start, stop };
+}

package/dist/runtime/events/wiring/triggerWiring.d.ts

@@ -0,0 +1,21 @@
+import type { TriggerFiredEvent } from '../types.js';
+/**
+ * Create trigger event wiring
+ * Listens to trigger.fired events and starts subscribed flows
+ * Handles await.registered and await.resolved events
+ */
+export declare function createTriggerWiring(): {
+    start: () => Promise<void>;
+    stop: () => void;
+};
+/**
+ * Handle trigger.fired event
+ * Starts all subscribed flows (auto mode) or queues them (manual mode)
+ * Returns list of flows that were started for stream metadata
+ */
+export declare function handleTriggerFired(event: TriggerFiredEvent): Promise<string[]>;
+/**
+ * Start a flow from a trigger event
+ * Enqueues the entry step and publishes flow.start event
+ */
+export declare function startFlowFromTrigger(flowName: string, triggerName: string, triggerData: any): Promise<void>;