nvent 0.4.5 → 0.5.1

package/dist/runtime/nitro/utils/useStreamTopics.d.ts

@@ -0,0 +1,83 @@
+export declare function useStreamTopics(): {
+    StoreSubjects: {
+        /**
+         * Flow run event stream
+         * Pattern: {prefix}:flow:run:{runId}
+         * Type: Redis Stream (XADD/XRANGE)
+         * Contains: All events for a specific flow run
+         */
+        readonly flowRun: (runId: string) => string;
+        /**
+         * Flow runs index (sorted set)
+         * Pattern: {prefix}:flow:runs:{flowName}
+         * Type: Sorted Set + Hash metadata
+         * Contains: List of run IDs for a flow, sorted by timestamp
+         */
+        readonly flowRunIndex: (flowName: string) => string;
+        /**
+         * Flows index (sorted set)
+         * Pattern: {prefix}:flows
+         * Type: Sorted Set + Hash metadata
+         * Contains: Flow metadata and statistics
+         */
+        readonly flowIndex: () => string;
+        /**
+         * Trigger event stream
+         * Pattern: {prefix}:trigger:event:{triggerName}
+         * Type: Redis Stream (XADD/XRANGE)
+         * Contains: All events for a specific trigger
+         */
+        readonly triggerStream: (triggerName: string) => string;
+        /**
+         * Triggers index (sorted set)
+         * Pattern: {prefix}:triggers
+         * Type: Sorted Set + Hash metadata
+         * Contains: Trigger metadata, subscriptions, and statistics
+         */
+        readonly triggerIndex: () => string;
+        /**
+         * Scheduler job index
+         * Pattern: {prefix}:scheduler:jobs
+         * Type: Sorted Set + Hash metadata
+         * Contains: Scheduled job metadata
+         */
+        readonly schedulerJobs: () => string;
+        /**
+         * Scheduler lock index
+         * Pattern: {prefix}:scheduler:locks
+         * Type: Sorted Set + Hash metadata
+         * Contains: Distributed scheduler lock metadata
+         */
+        readonly schedulerLocks: () => string;
+    };
+    StreamTopics: {
+        /**
+         * Flow events for a specific run
+         * Pattern: {prefix}:stream:flow:events:{runId}
+         * Published: When flow events occur (StreamWiring)
+         * Subscribed: By WebSocket clients watching a specific flow run
+         */
+        readonly flowEvents: (runId: string) => string;
+        /**
+         * Flow statistics updates
+         * Pattern: {prefix}:stream:flow:stats
+         * Published: When flow stats change (StreamWiring)
+         * Subscribed: By WebSocket clients watching flow overview
+         */
+        readonly flowStats: () => string;
+        /**
+         * Trigger events for a specific trigger
+         * Pattern: {prefix}:stream:trigger:events:{triggerName}
+         * Published: When trigger events occur (StreamWiring)
+         * Subscribed: By WebSocket clients watching a specific trigger
+         */
+        readonly triggerEvents: (triggerName: string) => string;
+        /**
+         * Trigger statistics updates
+         * Pattern: {prefix}:stream:trigger:stats
+         * Published: When trigger stats change (StreamWiring)
+         * Subscribed: By WebSocket clients watching trigger overview
+         */
+        readonly triggerStats: () => string;
+    };
+};

package/dist/runtime/nitro/utils/useStreamTopics.js

@@ -0,0 +1,94 @@
+import { useRuntimeConfig } from "#imports";
+function getStoreSubjects(prefix) {
+  return {
+    /**
+     * Flow run event stream
+     * Pattern: {prefix}:flow:run:{runId}
+     * Type: Redis Stream (XADD/XRANGE)
+     * Contains: All events for a specific flow run
+     */
+    flowRun: (runId) => `${prefix}:flow:run:${runId}`,
+    /**
+     * Flow runs index (sorted set)
+     * Pattern: {prefix}:flow:runs:{flowName}
+     * Type: Sorted Set + Hash metadata
+     * Contains: List of run IDs for a flow, sorted by timestamp
+     */
+    flowRunIndex: (flowName) => `${prefix}:flow:runs:${flowName}`,
+    /**
+     * Flows index (sorted set)
+     * Pattern: {prefix}:flows
+     * Type: Sorted Set + Hash metadata
+     * Contains: Flow metadata and statistics
+     */
+    flowIndex: () => `${prefix}:flows`,
+    /**
+     * Trigger event stream
+     * Pattern: {prefix}:trigger:event:{triggerName}
+     * Type: Redis Stream (XADD/XRANGE)
+     * Contains: All events for a specific trigger
+     */
+    triggerStream: (triggerName) => `${prefix}:trigger:event:${triggerName}`,
+    /**
+     * Triggers index (sorted set)
+     * Pattern: {prefix}:triggers
+     * Type: Sorted Set + Hash metadata
+     * Contains: Trigger metadata, subscriptions, and statistics
+     */
+    triggerIndex: () => `${prefix}:triggers`,
+    /**
+     * Scheduler job index
+     * Pattern: {prefix}:scheduler:jobs
+     * Type: Sorted Set + Hash metadata
+     * Contains: Scheduled job metadata
+     */
+    schedulerJobs: () => `${prefix}:scheduler:jobs`,
+    /**
+     * Scheduler lock index
+     * Pattern: {prefix}:scheduler:locks
+     * Type: Sorted Set + Hash metadata
+     * Contains: Distributed scheduler lock metadata
+     */
+    schedulerLocks: () => `${prefix}:scheduler:locks`
+  };
+}
+function getStreamTopics(prefix) {
+  return {
+    /**
+     * Flow events for a specific run
+     * Pattern: {prefix}:stream:flow:events:{runId}
+     * Published: When flow events occur (StreamWiring)
+     * Subscribed: By WebSocket clients watching a specific flow run
+     */
+    flowEvents: (runId) => `${prefix}:stream:flow:events:${runId}`,
+    /**
+     * Flow statistics updates
+     * Pattern: {prefix}:stream:flow:stats
+     * Published: When flow stats change (StreamWiring)
+     * Subscribed: By WebSocket clients watching flow overview
+     */
+    flowStats: () => `${prefix}:stream:flow:stats`,
+    /**
+     * Trigger events for a specific trigger
+     * Pattern: {prefix}:stream:trigger:events:{triggerName}
+     * Published: When trigger events occur (StreamWiring)
+     * Subscribed: By WebSocket clients watching a specific trigger
+     */
+    triggerEvents: (triggerName) => `${prefix}:stream:trigger:events:${triggerName}`,
+    /**
+     * Trigger statistics updates
+     * Pattern: {prefix}:stream:trigger:stats
+     * Published: When trigger stats change (StreamWiring)
+     * Subscribed: By WebSocket clients watching trigger overview
+     */
+    triggerStats: () => `${prefix}:stream:trigger:stats`
+  };
+}
+export function useStreamTopics() {
+  const config = useRuntimeConfig();
+  const prefix = config.nvent.store?.prefix || "nvent";
+  return {
+    StoreSubjects: getStoreSubjects(prefix),
+    StreamTopics: getStreamTopics(prefix)
+  };
+}

package/dist/runtime/nitro/utils/useTrigger.d.ts

@@ -0,0 +1,150 @@
+import type { TriggerEntry, TriggerSubscription } from '../../../registry/types.js';
+/**
+ * Public export for resolving payload references
+ * Allows external code to resolve references if needed
+ */
+export declare function resolvePayload(data: any): Promise<any>;
+export interface RegisterTriggerOptions {
+    name: string;
+    type: 'event' | 'webhook' | 'schedule' | 'manual';
+    scope: 'flow' | 'run';
+    status?: 'active' | 'inactive' | 'retired';
+    displayName?: string;
+    description?: string;
+    source?: string;
+    expectedSubscribers?: string[];
+    webhook?: {
+        path: string;
+        method?: string;
+        auth?: any;
+    };
+    schedule?: {
+        cron: string;
+        timezone?: string;
+        enabled?: boolean;
+    };
+    schema?: any;
+    transform?: (data: any) => any;
+    config?: {
+        persistData?: boolean;
+        payloadThreshold?: number;
+        retentionDays?: number;
+        rateLimit?: {
+            max: number;
+            window: number;
+        };
+    };
+}
+export interface SubscribeTriggerOptions {
+    trigger: string;
+    flow: string;
+    mode?: 'auto' | 'manual';
+    filter?: (data: any) => boolean;
+    transform?: (data: any) => any;
+}
+/**
+ * Core trigger composable
+ * Provides runtime API for trigger registration and emission
+ */
+export declare function useTrigger(): {
+    /**
+     * Register a trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    registerTrigger(opts: RegisterTriggerOptions): Promise<void>;
+    /**
+     * Subscribe flow to trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    subscribeTrigger(opts: SubscribeTriggerOptions): Promise<void>;
+    /**
+     * Unsubscribe flow from trigger
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    unsubscribeTrigger(trigger: string, flow: string): Promise<void>;
+    /**
+     * Emit trigger (fire event)
+     * Publishes event to bus - triggerWiring handles persistence, stats, and orchestration
+     *
+     * Large payloads are automatically stored in KV store and replaced with references
+     * to keep stream events small and memory-efficient.
+     */
+    emitTrigger(name: string, data: any, opts?: {
+        payloadThreshold?: number;
+    }): Promise<void>;
+    /**
+     * Query methods
+     */
+    /**
+     * Check if a trigger exists in the registry
+     */
+    hasTrigger(name: string): boolean;
+    /**
+     * Get trigger entry by name
+     */
+    getTrigger(name: string): TriggerEntry | undefined;
+    /**
+     * Get all registered triggers
+     * @param options - Sorting and pagination options
+     * @param options.sortBy - Field to sort by
+     * @param options.order - Sort order (asc or desc)
+     * @param options.limit - Maximum number of results
+     * @param options.offset - Number of results to skip
+     */
+    getAllTriggers(options?: {
+        sortBy?: "registeredAt" | "lastActivityAt" | "name";
+        order?: "asc" | "desc";
+        limit?: number;
+        offset?: number;
+    }): TriggerEntry[];
+    /**
+     * Get all flows subscribed to a specific trigger
+     */
+    getSubscribedFlows(trigger: string): string[];
+    /**
+     * Get all triggers that a flow is subscribed to
+     */
+    getFlowTriggers(flow: string): string[];
+    /**
+     * Get subscription details for a specific trigger-flow pair
+     */
+    getSubscription(trigger: string, flow: string): TriggerSubscription | undefined;
+    getAllSubscriptions(): TriggerSubscription[];
+    /**
+     * Initialize runtime from store (called on startup)
+     * Uses index + stream architecture (v0.5.1)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get runtime state (for debugging)
+     */
+    getRuntime(): {
+        triggerCount: number;
+        subscriptionCount: number;
+        flowCount: number;
+        initialized: boolean;
+    };
+    /**
+     * Delete a trigger completely (removes all data)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    deleteTrigger(name: string): Promise<void>;
+    /**
+     * Update trigger status (active/inactive/retired)
+     * For future status management UI
+     */
+    updateTriggerStatus(name: string, status: "active" | "inactive" | "retired"): Promise<void>;
+    /**
+     * Get trigger statistics
+     * v0.5.1: New analytics method
+     */
+    getTriggerStats(name: string): Promise<any>;
+    /**
+     * Get trigger history from stream
+     * v0.5.1: New analytics method
+     */
+    getTriggerHistory(name: string, opts?: {
+        limit?: number;
+        types?: string[];
+    }): Promise<any>;
+};

package/dist/runtime/nitro/utils/useTrigger.js

@@ -0,0 +1,320 @@
+import { useStoreAdapter, useNventLogger, useStreamTopics } from "#imports";
+import { getEventBus } from "../../events/eventBus.js";
+import { getTriggerRuntime } from "../../events/utils/triggerRuntime.js";
+export async function resolvePayload(data) {
+  const logger = useNventLogger("trigger");
+  const store = useStoreAdapter();
+  const runtime = getTriggerRuntime(store, logger);
+  return runtime.resolvePayload(data);
+}
+export function useTrigger() {
+  const logger = useNventLogger("trigger");
+  const store = useStoreAdapter();
+  const runtime = getTriggerRuntime(store, logger);
+  return {
+    /**
+     * Register a trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async registerTrigger(opts) {
+      const eventBus = getEventBus();
+      const existing = runtime.getTrigger(opts.name);
+      const isUpdate = !!existing;
+      if (isUpdate) {
+        logger.info(`Updating trigger: ${opts.name}`);
+        await eventBus.publish({
+          type: "trigger.updated",
+          triggerName: opts.name,
+          data: {
+            type: opts.type,
+            scope: opts.scope,
+            status: opts.status,
+            displayName: opts.displayName,
+            description: opts.description,
+            source: opts.source || "programmatic",
+            webhook: opts.webhook,
+            schedule: opts.schedule,
+            config: opts.config,
+            expectedSubscribers: opts.expectedSubscribers
+          }
+        });
+      } else {
+        logger.info(`Registering trigger: ${opts.name}`);
+        await eventBus.publish({
+          type: "trigger.registered",
+          triggerName: opts.name,
+          data: {
+            name: opts.name,
+            type: opts.type,
+            scope: opts.scope,
+            displayName: opts.displayName,
+            description: opts.description,
+            source: opts.source || "programmatic",
+            expectedSubscribers: opts.expectedSubscribers,
+            webhook: opts.webhook,
+            schedule: opts.schedule,
+            config: opts.config
+          }
+        });
+      }
+    },
+    /**
+     * Subscribe flow to trigger (programmatic)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async subscribeTrigger(opts) {
+      const eventBus = getEventBus();
+      const { trigger, flow, mode = "auto" } = opts;
+      const existingSub = runtime.getSubscription(trigger, flow);
+      const isUpdate = !!existingSub;
+      logger.info(`${isUpdate ? "Updating" : "Subscribing"} flow '${flow}' to trigger '${trigger}' (${mode})`);
+      await eventBus.publish({
+        type: "subscription.added",
+        triggerName: trigger,
+        data: {
+          trigger,
+          flow,
+          mode,
+          isUpdate
+        }
+      });
+    },
+    /**
+     * Unsubscribe flow from trigger
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async unsubscribeTrigger(trigger, flow) {
+      const eventBus = getEventBus();
+      logger.info(`Unsubscribing flow '${flow}' from trigger '${trigger}'`);
+      await eventBus.publish({
+        type: "subscription.removed",
+        triggerName: trigger,
+        data: {
+          trigger,
+          flow
+        }
+      });
+    },
+    /**
+     * Emit trigger (fire event)
+     * Publishes event to bus - triggerWiring handles persistence, stats, and orchestration
+     *
+     * Large payloads are automatically stored in KV store and replaced with references
+     * to keep stream events small and memory-efficient.
+     */
+    async emitTrigger(name, data, opts) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(
+          `Emitting unregistered trigger '${name}'. Consider registering it first with registerTrigger().`
+        );
+      }
+      const threshold = opts?.payloadThreshold || trigger?.config?.payloadThreshold || 10 * 1024;
+      const eventData = await runtime.handleLargePayload(name, data, threshold);
+      logger.debug(`Emitting trigger: ${name}`, {
+        hasReference: !!eventData.__payloadRef,
+        size: eventData.__size
+      });
+      await eventBus.publish({
+        type: "trigger.fired",
+        triggerName: name,
+        data: eventData
+      });
+    },
+    /**
+     * Query methods
+     */
+    /**
+     * Check if a trigger exists in the registry
+     */
+    hasTrigger(name) {
+      return runtime.hasTrigger(name);
+    },
+    /**
+     * Get trigger entry by name
+     */
+    getTrigger(name) {
+      return runtime.getTrigger(name);
+    },
+    /**
+     * Get all registered triggers
+     * @param options - Sorting and pagination options
+     * @param options.sortBy - Field to sort by
+     * @param options.order - Sort order (asc or desc)
+     * @param options.limit - Maximum number of results
+     * @param options.offset - Number of results to skip
+     */
+    getAllTriggers(options) {
+      return runtime.getAllTriggers(options);
+    },
+    /**
+     * Get all flows subscribed to a specific trigger
+     */
+    getSubscribedFlows(trigger) {
+      return runtime.getSubscribedFlows(trigger);
+    },
+    /**
+     * Get all triggers that a flow is subscribed to
+     */
+    getFlowTriggers(flow) {
+      return runtime.getFlowTriggers(flow);
+    },
+    /**
+     * Get subscription details for a specific trigger-flow pair
+     */
+    getSubscription(trigger, flow) {
+      return runtime.getSubscription(trigger, flow);
+    },
+    getAllSubscriptions() {
+      return runtime.getAllSubscriptions();
+    },
+    /**
+     * Initialize runtime from store (called on startup)
+     * Uses index + stream architecture (v0.5.1)
+     */
+    async initialize() {
+      if (runtime.initialized) return;
+      const { StoreSubjects } = useStreamTopics();
+      const indexKey = StoreSubjects.triggerIndex();
+      logger.info("Initializing trigger runtime from index...");
+      if (store.index.read) {
+        const entries = await store.index.read(indexKey, { limit: 1e3 });
+        let activeCount = 0;
+        let totalSubscriptions = 0;
+        for (const entry of entries) {
+          const metadata = entry.metadata;
+          const triggerEntry = {
+            name: metadata.name,
+            type: metadata.type,
+            scope: metadata.scope,
+            status: metadata.status || "active",
+            displayName: metadata.displayName,
+            description: metadata.description,
+            source: metadata.source,
+            registeredAt: metadata.registeredAt,
+            registeredBy: metadata.registeredBy,
+            lastActivityAt: metadata.lastActivityAt,
+            subscriptions: metadata.subscriptions || {},
+            stats: metadata.stats || { totalFires: 0, activeSubscribers: 0 },
+            webhook: metadata.webhook,
+            schedule: metadata.schedule,
+            config: metadata.config,
+            version: metadata.version || 1
+          };
+          runtime.addTrigger(entry.id, triggerEntry);
+          if (metadata.status === "active") {
+            activeCount++;
+          }
+          if (metadata.subscriptions) {
+            for (const [flowName, subData] of Object.entries(metadata.subscriptions)) {
+              const subscription = {
+                triggerName: entry.id,
+                flowName,
+                mode: subData.mode || "auto",
+                source: "programmatic",
+                registeredAt: subData.subscribedAt
+              };
+              runtime.addSubscription(entry.id, flowName, subscription);
+              totalSubscriptions++;
+            }
+          }
+        }
+        logger.info(
+          `Loaded ${activeCount} active triggers with ${totalSubscriptions} subscriptions from index`
+        );
+      } else {
+        logger.warn("Store does not support indexRead, falling back to doc-based loading");
+        if (store.list) {
+          const triggers = await store.list("triggers");
+          for (const { id, doc } of triggers) {
+            runtime.addTrigger(id, doc);
+          }
+          const subscriptions = await store.list("trigger-subscriptions");
+          for (const { doc } of subscriptions) {
+            const sub = doc;
+            runtime.addSubscription(sub.triggerName, sub.flowName, sub);
+          }
+          logger.info(
+            `Loaded ${triggers.length} triggers and ${subscriptions.length} subscriptions from doc store (legacy)`
+          );
+        }
+      }
+      runtime.setInitialized(true);
+    },
+    /**
+     * Get runtime state (for debugging)
+     */
+    getRuntime() {
+      return runtime.getRuntimeStats();
+    },
+    /**
+     * Delete a trigger completely (removes all data)
+     * Publishes event to bus - triggerWiring handles persistence and orchestration
+     */
+    async deleteTrigger(name) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(`Cannot delete non-existent trigger: ${name}`);
+        return;
+      }
+      logger.info(`Deleting trigger: ${name}`);
+      await eventBus.publish({
+        type: "trigger.deleted",
+        triggerName: name,
+        data: {}
+      });
+    },
+    /**
+     * Update trigger status (active/inactive/retired)
+     * For future status management UI
+     */
+    async updateTriggerStatus(name, status) {
+      const eventBus = getEventBus();
+      const trigger = runtime.getTrigger(name);
+      if (!trigger) {
+        logger.warn(`Cannot update status of non-existent trigger: ${name}`);
+        return;
+      }
+      logger.info(`Updating trigger ${name} status to: ${status}`);
+      await eventBus.publish({
+        type: "trigger.updated",
+        triggerName: name,
+        data: {
+          ...trigger,
+          status
+        }
+      });
+    },
+    /**
+     * Get trigger statistics
+     * v0.5.1: New analytics method
+     */
+    async getTriggerStats(name) {
+      const { StoreSubjects } = useStreamTopics();
+      const indexKey = StoreSubjects.triggerIndex();
+      if (!store.index.get) {
+        const trigger = runtime.getTrigger(name);
+        return trigger?.stats;
+      }
+      const entry = await store.index.get(indexKey, name);
+      if (!entry?.metadata) return null;
+      return entry.metadata.stats;
+    },
+    /**
+     * Get trigger history from stream
+     * v0.5.1: New analytics method
+     */
+    async getTriggerHistory(name, opts) {
+      const { StoreSubjects } = useStreamTopics();
+      const streamName = StoreSubjects.triggerStream(name);
+      const events = await store.stream.read(streamName, {
+        limit: opts?.limit || 100,
+        types: opts?.types,
+        order: "desc"
+      });
+      return events;
+    }
+  };
+}

package/dist/runtime/scheduler/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Scheduler Factory and Composable
+ *
+ * Provides a unified scheduler interface for the entire application.
+ * Uses Scheduler with store adapter (supports both distributed and single-instance modes).
+ */
+import type { SchedulerAdapter } from './types.js';
+/**
+ * Create a scheduler instance
+ * Uses Scheduler which adapts based on store capabilities:
+ * - With indexAdd/indexGet: Full distributed locking
+ * - Without: Degrades gracefully to KV-based locking (single instance)
+ */
+export declare function createScheduler(store: any): SchedulerAdapter;
+/**
+ * Get the global scheduler instance
+ * Must be initialized first with initializeScheduler()
+ */
+export declare function useScheduler(): SchedulerAdapter;
+/**
+ * Initialize the scheduler
+ * Should be called once during app startup
+ */
+export declare function initializeScheduler(store: any): Promise<SchedulerAdapter>;
+/**
+ * Shutdown the scheduler
+ * Should be called during app shutdown
+ */
+export declare function shutdownScheduler(): Promise<void>;
+/**
+ * Reset the scheduler instance (for testing)
+ */
+export declare function resetScheduler(): void;