nvent 0.4.4 → 0.5.0

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

@@ -0,0 +1,71 @@
+import type { AwaitConfig } from '../../../registry/types.js';
+import { registerAwaitPattern, resolveAwaitPattern, registerWebhookAwait, resolveWebhookAwait, registerEventAwait, resolveEventAwait, registerScheduleAwait, resolveScheduleAwait, registerTimeAwait, resolveTimeAwait } from './awaitPatterns/index.js';
+/**
+ * Await pattern composable
+ * Provides unified API for managing await patterns in flows
+ * Separate from useTrigger which handles entry triggers (manual, webhook, schedule, event)
+ */
+export declare function useAwait(): {
+    /**
+     * Register an await pattern based on config type
+     * Automatically routes to appropriate implementation
+     */
+    register: typeof registerAwaitPattern;
+    /**
+     * Resolve an await pattern by type
+     */
+    resolve: typeof resolveAwaitPattern;
+    /**
+     * Direct access to specific await pattern implementations
+     */
+    webhook: {
+        register: typeof registerWebhookAwait;
+        resolve: typeof resolveWebhookAwait;
+    };
+    event: {
+        register: typeof registerEventAwait;
+        resolve: typeof resolveEventAwait;
+    };
+    schedule: {
+        register: typeof registerScheduleAwait;
+        resolve: typeof resolveScheduleAwait;
+    };
+    time: {
+        register: typeof registerTimeAwait;
+        resolve: typeof resolveTimeAwait;
+    };
+    /**
+     * Query methods for await state
+     */
+    /**
+     * Get await state for a specific flow run and step
+     */
+    getAwaitState(flowName: string, runId: string, stepName?: string): Promise<any>;
+    /**
+     * Check if a step is currently awaiting
+     */
+    isAwaiting(flowName: string, runId: string, stepName: string): Promise<boolean>;
+    /**
+     * Get all active awaits across all flows
+     */
+    getAllActiveAwaits(flowName?: string): Promise<{
+        flowName: string;
+        runId: string;
+        stepName: string;
+        awaitType: string;
+        position: "before" | "after";
+        registeredAt: string;
+    }[]>;
+    /**
+     * Get await history for a specific flow run from stream
+     */
+    getAwaitHistory(runId: string, opts?: {
+        limit?: number;
+        stepName?: string;
+    }): Promise<any>;
+    /**
+     * Cancel/timeout an active await
+     */
+    timeoutAwait(flowName: string, runId: string, stepName: string, reason?: string): Promise<void>;
+};
+export type { AwaitConfig };

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

@@ -0,0 +1,139 @@
+import {
+  registerAwaitPattern,
+  resolveAwaitPattern,
+  registerWebhookAwait,
+  resolveWebhookAwait,
+  registerEventAwait,
+  resolveEventAwait,
+  registerScheduleAwait,
+  resolveScheduleAwait,
+  registerTimeAwait,
+  resolveTimeAwait
+} from "./awaitPatterns/index.js";
+import { useStoreAdapter, useStreamTopics, useNventLogger } from "#imports";
+export function useAwait() {
+  const logger = useNventLogger("await");
+  const store = useStoreAdapter();
+  const { StoreSubjects } = useStreamTopics();
+  return {
+    /**
+     * Register an await pattern based on config type
+     * Automatically routes to appropriate implementation
+     */
+    register: registerAwaitPattern,
+    /**
+     * Resolve an await pattern by type
+     */
+    resolve: resolveAwaitPattern,
+    /**
+     * Direct access to specific await pattern implementations
+     */
+    webhook: {
+      register: registerWebhookAwait,
+      resolve: resolveWebhookAwait
+    },
+    event: {
+      register: registerEventAwait,
+      resolve: resolveEventAwait
+    },
+    schedule: {
+      register: registerScheduleAwait,
+      resolve: resolveScheduleAwait
+    },
+    time: {
+      register: registerTimeAwait,
+      resolve: resolveTimeAwait
+    },
+    /**
+     * Query methods for await state
+     */
+    /**
+     * Get await state for a specific flow run and step
+     */
+    async getAwaitState(flowName, runId, stepName) {
+      const indexKey = StoreSubjects.flowRunIndex(flowName);
+      if (!store.index.get) {
+        logger.warn("Store does not support indexGet");
+        return null;
+      }
+      const entry = await store.index.get(indexKey, runId);
+      if (!entry?.metadata) {
+        return null;
+      }
+      const awaitingSteps = entry.metadata.awaitingSteps || {};
+      if (stepName) {
+        return awaitingSteps[stepName] || null;
+      }
+      return awaitingSteps;
+    },
+    /**
+     * Check if a step is currently awaiting
+     */
+    async isAwaiting(flowName, runId, stepName) {
+      const awaitState = await this.getAwaitState(flowName, runId, stepName);
+      return awaitState?.status === "awaiting";
+    },
+    /**
+     * Get all active awaits across all flows
+     */
+    async getAllActiveAwaits(flowName) {
+      const activeAwaits = [];
+      if (!store.indexScan) {
+        logger.warn("Store does not support indexScan");
+        return activeAwaits;
+      }
+      if (flowName) {
+        const indexKey = StoreSubjects.flowRunIndex(flowName);
+        const entries = await store.index.read(indexKey, { limit: 1e3 });
+        for (const entry of entries) {
+          const awaitingSteps = entry.metadata?.awaitingSteps || {};
+          for (const [stepName, awaitState] of Object.entries(awaitingSteps)) {
+            if (awaitState.status === "awaiting") {
+              activeAwaits.push({
+                flowName,
+                runId: entry.id,
+                stepName,
+                awaitType: awaitState.awaitType,
+                position: awaitState.position,
+                registeredAt: awaitState.registeredAt
+              });
+            }
+          }
+        }
+      } else {
+        logger.warn("Scanning all flows not yet implemented - provide flowName parameter");
+      }
+      return activeAwaits;
+    },
+    /**
+     * Get await history for a specific flow run from stream
+     */
+    async getAwaitHistory(runId, opts) {
+      const streamName = StoreSubjects.flowRun(runId);
+      const events = await store.stream.read(streamName, {
+        limit: opts?.limit || 100,
+        types: ["await.registered", "await.resolved", "await.timeout"],
+        order: "desc"
+      });
+      if (opts?.stepName) {
+        return events.filter((e) => e.stepName === opts.stepName);
+      }
+      return events;
+    },
+    /**
+     * Cancel/timeout an active await
+     */
+    async timeoutAwait(flowName, runId, stepName, reason = "Manual timeout") {
+      const indexKey = StoreSubjects.flowRunIndex(flowName);
+      if (store.index.updateWithRetry) {
+        await store.index.updateWithRetry(indexKey, runId, {
+          [`awaitingSteps.${stepName}.status`]: "timeout",
+          [`awaitingSteps.${stepName}.timeoutReason`]: reason,
+          [`awaitingSteps.${stepName}.timeoutAt`]: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        logger.info("Await timed out", { flowName, runId, stepName, reason });
+      }
+      logger.warn("await.timeout event publishing not yet implemented in useAwait");
+    }
+  };
+}

package/dist/runtime/{server-utils → nitro}/utils/useEventManager.d.ts

@@ -1,5 +1,5 @@
-import { getEventBus } from '../events/eventBus.js';
-import type { EventRecord } from '../types.js';
+import { getEventBus } from '../../events/eventBus.js';
+import type { EventRecord } from '../../adapters/interfaces/store.js';
 export interface EventManager {
     /**
      * Publish an event directly to the in-proc bus.

package/dist/runtime/{server-utils → nitro}/utils/useEventManager.js

@@ -1,4 +1,4 @@
-import { getEventBus } from "../events/eventBus.js";
+import { getEventBus } from "../../events/eventBus.js";
 import { useNventLogger } from "#imports";
 export function useEventManager() {
   if (globalThis.__nq_event_manager) return globalThis.__nq_event_manager;

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

@@ -0,0 +1,68 @@
+export interface FlowStats {
+    name: string;
+    displayName?: string;
+    registeredAt: string;
+    lastRunAt?: string;
+    lastCompletedAt?: string;
+    stats: {
+        total: number;
+        success: number;
+        failure: number;
+        cancel: number;
+        running: number;
+        awaiting: number;
+    };
+    version?: number;
+}
+/**
+ * Flow composable for managing flows and accessing flow statistics
+ * Provides methods for starting, canceling, and querying flows
+ */
+export declare function useFlow(): {
+    /**
+     * Start a flow with the given payload
+     */
+    startFlow(flowName: string, payload?: any): Promise<{
+        id: any;
+        queue: any;
+        step: any;
+        flowId: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+    /**
+     * Emit a trigger event for flow coordination
+     */
+    emit(trigger: string, payload?: any): Promise<never[]>;
+    /**
+     * Cancel a running flow
+     */
+    cancelFlow(flowName: string, runId: string): Promise<{
+        success: boolean;
+        runId: string;
+        flowName: string;
+    }>;
+    /**
+     * Check if a flow is currently running
+     */
+    isRunning(flowName: string, runId?: string): Promise<any>;
+    /**
+     * Get all currently running flows
+     */
+    getRunningFlows(flowName: string): Promise<any>;
+    /**
+     * Get flow statistics by name
+     */
+    getFlowStats(flowName: string): Promise<FlowStats | null>;
+    /**
+     * Get all flows with their statistics
+     */
+    getAllFlowStats(options?: {
+        sortBy?: "registeredAt" | "lastRunAt" | "name";
+        order?: "asc" | "desc";
+        limit?: number;
+        offset?: number;
+    }): Promise<FlowStats[]>;
+    /**
+     * Check if a flow has statistics in the index
+     */
+    hasFlowStats(flowName: string): Promise<boolean>;
+};

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

@@ -0,0 +1,226 @@
+import { $useFunctionRegistry, useQueueAdapter, useEventManager, useStoreAdapter, useNventLogger, useStreamTopics } from "#imports";
+import { randomUUID } from "node:crypto";
+export function useFlow() {
+  const registry = $useFunctionRegistry();
+  const queueAdapter = useQueueAdapter();
+  const eventsManager = useEventManager();
+  const store = useStoreAdapter();
+  const logger = useNventLogger("use-flow");
+  const { StoreSubjects } = useStreamTopics();
+  return {
+    /**
+     * Start a flow with the given payload
+     */
+    async startFlow(flowName, payload = {}) {
+      const flow = registry?.flows?.[flowName];
+      if (!flow || !flow.entry) throw new Error("Flow not found");
+      const queueName = typeof flow.entry.queue === "string" ? flow.entry.queue : flow.entry.queue?.name || flow.entry.queue;
+      const entryWorker = registry?.workers?.find(
+        (w) => w?.flow?.step === flow.entry.step && w?.queue?.name === queueName
+      );
+      const opts = entryWorker?.queue?.defaultJobOptions || {};
+      const flowId = randomUUID();
+      const id = await queueAdapter.enqueue(queueName, { name: flow.entry.step, data: { ...payload, flowId, flowName }, opts });
+      try {
+        await eventsManager.publishBus({ type: "flow.start", runId: flowId, flowName, data: { input: payload } });
+      } catch {
+      }
+      return { id, queue: queueName, step: flow.entry.step, flowId };
+    },
+    /**
+     * Emit a trigger event for flow coordination
+     */
+    async emit(trigger, payload = {}) {
+      const flowId = payload?.flowId;
+      const flowName = payload?.flowName || "unknown";
+      const stepName = payload?.stepName;
+      if (!flowId) {
+        logger.warn("emit called without flowId, trigger may not work", { trigger });
+      }
+      const { flowId: _, flowName: __, stepName: ___, ...actualPayload } = payload;
+      try {
+        await eventsManager.publishBus({
+          type: "emit",
+          runId: flowId || "unknown",
+          flowName,
+          stepName,
+          data: {
+            name: trigger,
+            payload: actualPayload
+          }
+        });
+      } catch (err) {
+        logger.error("Failed to emit trigger event", { trigger, error: err });
+      }
+      return [];
+    },
+    /**
+     * Cancel a running flow
+     */
+    async cancelFlow(flowName, runId) {
+      try {
+        await eventsManager.publishBus({
+          type: "flow.cancel",
+          runId,
+          flowName,
+          data: {
+            canceledAt: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        logger.info("Flow canceled", { flowName, runId });
+        return { success: true, runId, flowName };
+      } catch (err) {
+        logger.error("Failed to cancel flow", { flowName, runId, error: err });
+        throw err;
+      }
+    },
+    /**
+     * Check if a flow is currently running
+     */
+    async isRunning(flowName, runId) {
+      try {
+        if (!store.index.read) {
+          return false;
+        }
+        const runIndexKey = StoreSubjects.flowRunIndex(flowName);
+        const entries = await store.index.read(runIndexKey, { limit: 1e3 });
+        if (runId) {
+          const run = entries.find((e) => e.id === runId);
+          return run?.metadata?.status === "running";
+        }
+        return entries.some((e) => e.metadata?.status === "running");
+      } catch (err) {
+        logger.error("Error checking flow status:", err);
+        return false;
+      }
+    },
+    /**
+     * Get all currently running flows
+     */
+    async getRunningFlows(flowName) {
+      try {
+        if (!store.index.read) {
+          return [];
+        }
+        const runIndexKey = StoreSubjects.flowRunIndex(flowName);
+        const entries = await store.index.read(runIndexKey, { limit: 1e3 });
+        return entries.filter((e) => e.metadata?.status === "running").map((e) => ({
+          id: e.id,
+          flowName,
+          status: e.metadata?.status,
+          startedAt: e.metadata?.startedAt,
+          stepCount: e.metadata?.stepCount || 0,
+          completedSteps: e.metadata?.completedSteps || 0
+        }));
+      } catch (err) {
+        logger.error("Error getting running flows:", err);
+        return [];
+      }
+    },
+    /**
+     * Get flow statistics by name
+     */
+    async getFlowStats(flowName) {
+      try {
+        const indexKey = StoreSubjects.flowIndex();
+        if (!store.index.get) {
+          logger.warn("Store adapter does not support indexGet");
+          return null;
+        }
+        const entry = await store.index.get(indexKey, flowName);
+        if (!entry) {
+          return null;
+        }
+        const metadata = entry.metadata;
+        return {
+          name: metadata.name || flowName,
+          displayName: metadata.displayName,
+          registeredAt: metadata.registeredAt,
+          lastRunAt: metadata.lastRunAt,
+          lastCompletedAt: metadata.lastCompletedAt,
+          stats: {
+            total: metadata.stats?.total || 0,
+            success: metadata.stats?.success || 0,
+            failure: metadata.stats?.failure || 0,
+            cancel: metadata.stats?.cancel || 0,
+            running: metadata.stats?.running || 0,
+            awaiting: metadata.stats?.awaiting || 0
+          },
+          version: metadata.version
+        };
+      } catch (err) {
+        logger.error("Error getting flow stats", {
+          flowName,
+          error: err?.message
+        });
+        return null;
+      }
+    },
+    /**
+     * Get all flows with their statistics
+     */
+    async getAllFlowStats(options) {
+      try {
+        const indexKey = StoreSubjects.flowIndex();
+        if (!store.index.read) {
+          logger.warn("Store adapter does not support indexRead");
+          return [];
+        }
+        const entries = await store.index.read(indexKey, {
+          limit: options?.limit || 1e3,
+          offset: options?.offset || 0
+        });
+        const flows = entries.map((entry) => {
+          const metadata = entry.metadata;
+          return {
+            name: metadata.name || entry.id,
+            displayName: metadata.displayName,
+            registeredAt: metadata.registeredAt,
+            lastRunAt: metadata.lastRunAt,
+            lastCompletedAt: metadata.lastCompletedAt,
+            stats: {
+              total: metadata.stats?.total || 0,
+              success: metadata.stats?.success || 0,
+              failure: metadata.stats?.failure || 0,
+              cancel: metadata.stats?.cancel || 0,
+              running: metadata.stats?.running || 0,
+              awaiting: metadata.stats?.awaiting || 0
+            },
+            version: metadata.version
+          };
+        });
+        if (options?.sortBy) {
+          flows.sort((a, b) => {
+            let aVal;
+            let bVal;
+            if (options.sortBy === "name") {
+              aVal = a.name;
+              bVal = b.name;
+            } else if (options.sortBy === "registeredAt") {
+              aVal = new Date(a.registeredAt).getTime();
+              bVal = new Date(b.registeredAt).getTime();
+            } else if (options.sortBy === "lastRunAt") {
+              aVal = a.lastRunAt ? new Date(a.lastRunAt).getTime() : 0;
+              bVal = b.lastRunAt ? new Date(b.lastRunAt).getTime() : 0;
+            }
+            const order = options.order === "desc" ? -1 : 1;
+            return (aVal > bVal ? 1 : aVal < bVal ? -1 : 0) * order;
+          });
+        }
+        return flows;
+      } catch (err) {
+        logger.error("Error getting all flow stats", {
+          error: err?.message
+        });
+        return [];
+      }
+    },
+    /**
+     * Check if a flow has statistics in the index
+     */
+    async hasFlowStats(flowName) {
+      const stats = await this.getFlowStats(flowName);
+      return stats !== null;
+    }
+  };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Lifecycle hooks registry for await patterns
+ * v0.5 - Await Integration
+ */
+export interface LifecycleHooks {
+    /**
+     * Called when await pattern is registered
+     * @param webhookUrl - Generated webhook URL (for webhook awaits) or event/schedule info
+     * @param stepData - Current step data
+     * @param ctx - Worker context
+     */
+    onAwaitRegister?: (webhookUrl: string, stepData: any, ctx: any) => Promise<void>;
+    /**
+     * Called when await pattern is resolved
+     * @param resolvedData - Data from the trigger that resolved the await
+     * @param stepData - Current step data
+     * @param ctx - Worker context
+     */
+    onAwaitResolve?: (resolvedData: any, stepData: any, ctx: any) => Promise<void>;
+}
+export declare function useHookRegistry(): {
+    /**
+     * Register lifecycle hooks for a specific flow step
+     */
+    register(flowName: string, stepName: string, hooks: LifecycleHooks): void;
+    /**
+     * Load lifecycle hooks for a specific flow step
+     */
+    load(flowName: string, stepName: string): LifecycleHooks | null;
+    /**
+     * Clear all registered hooks (useful for testing)
+     */
+    clear(): void;
+};

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

@@ -0,0 +1,25 @@
+const hookRegistry = /* @__PURE__ */ new Map();
+export function useHookRegistry() {
+  return {
+    /**
+     * Register lifecycle hooks for a specific flow step
+     */
+    register(flowName, stepName, hooks) {
+      const key = `${flowName}:${stepName}`;
+      hookRegistry.set(key, hooks);
+    },
+    /**
+     * Load lifecycle hooks for a specific flow step
+     */
+    load(flowName, stepName) {
+      const key = `${flowName}:${stepName}`;
+      return hookRegistry.get(key) || null;
+    },
+    /**
+     * Clear all registered hooks (useful for testing)
+     */
+    clear() {
+      hookRegistry.clear();
+    }
+  };
+}

package/dist/runtime/{server-utils → nitro}/utils/useNventLogger.js

@@ -9,7 +9,7 @@ const LOG_LEVELS = {
 const loggerCache = /* @__PURE__ */ new Map();
 export function useNventLogger(scope) {
   const rc = useRuntimeConfig();
-  const debugConfig = rc?.queue?.debug;
+  const debugConfig = rc?.nvent?.debug;
   const configLevel = debugConfig?.level || process.env.NQ_DEBUG_LEVEL || "info";
   const globalLevelNum = configLevel === "silent" ? Infinity : LOG_LEVELS[configLevel] ?? LOG_LEVELS.info;
   const scopeKey = scope.replace(/[^a-z0-9]/gi, "_").toLowerCase();
@@ -48,7 +48,7 @@ export function useNventLogger(scope) {
 }
 export function isDebugEnabled() {
   const rc = useRuntimeConfig();
-  const debugConfig = rc?.queue?.debug;
+  const debugConfig = rc?.nvent?.debug;
   const level = debugConfig?.level || process.env.NQ_DEBUG_LEVEL;
   return level === "debug" || Object.keys(debugConfig || {}).some((key) => key !== "level");
 }

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

@@ -0,0 +1,6 @@
+import type { RunContext } from '../worker/node/runner.js';
+/**
+ * Create a minimal RunContext for use in lifecycle hooks and event handlers
+ * This is a lightweight version without the full worker context
+ */
+export declare function useRunContext(partial?: Partial<RunContext>): RunContext;