nvent 0.5.3 → 0.5.5

package/dist/runtime/nitro/utils/awaitPatterns/event.js

@@ -18,6 +18,9 @@ export async function registerEventAwait(runId, stepName, flowName, config, posi
     await resolveEventAwait(runId, stepName, flowName, position, event.data);
     unsubscribe();
   });
+  const { useAwaitDefaults } = await import("../useAwait.js");
+  const { eventTimeout: defaultTimeout, timeoutAction: defaultTimeoutAction } = useAwaitDefaults();
+  const timeoutMs = config.timeout && config.timeout > 0 ? config.timeout : defaultTimeout;
   eventBus.publish({
     type: "await.registered",
     flowName,
@@ -27,66 +30,69 @@ export async function registerEventAwait(runId, stepName, flowName, config, posi
     position,
     config,
     data: {
+      position,
+      // Store position in data for database persistence
       eventName: config.event,
       filterKey: config.filterKey,
-      timeout: config.timeout,
-      registeredAt: Date.now()
+      timeout: timeoutMs,
+      // Store resolved timeout (with default)
+      registeredAt: Date.now(),
+      timeoutAction: config.timeoutAction || defaultTimeoutAction
     }
   });
-  if (config.timeout && config.timeout > 0) {
-    const scheduler = useScheduler();
-    const timeoutAt = Date.now() + config.timeout;
-    const jobId = `await-event-timeout-${runId}-${stepName}-${position}`;
-    await scheduler.schedule({
-      id: jobId,
-      name: `Event Await Timeout: ${flowName} - ${stepName}`,
-      type: "one-time",
-      executeAt: timeoutAt,
-      handler: async () => {
-        logger.warn("Event await timeout", {
-          runId,
-          stepName,
-          flowName,
-          eventName: config.event,
-          timeout: config.timeout,
-          timeoutAction: config.timeoutAction || "fail"
-        });
-        eventBus.publish({
-          type: "await.timeout",
-          flowName,
-          runId,
-          stepName,
-          position,
-          awaitType: "event",
-          timeoutAction: config.timeoutAction || "fail",
-          data: {
-            eventName: config.event,
-            timeout: config.timeout,
-            registeredAt: Date.now() - (config.timeout || 0),
-            timedOutAt: Date.now()
-          }
-        });
-        unsubscribe();
-      },
-      metadata: {
-        component: "await-pattern",
-        awaitType: "event",
+  const scheduler = useScheduler();
+  const timeoutAt = Date.now() + timeoutMs;
+  const jobId = `await-event-timeout-${runId}-${stepName}-${position}`;
+  await scheduler.schedule({
+    id: jobId,
+    name: `Event Await Timeout: ${flowName} - ${stepName}`,
+    type: "one-time",
+    executeAt: timeoutAt,
+    handler: async () => {
+      logger.warn("Event await timeout", {
         runId,
         stepName,
         flowName,
+        eventName: config.event,
+        timeout: timeoutMs,
+        timeoutAction: config.timeoutAction || "fail"
+      });
+      eventBus.publish({
+        type: "await.timeout",
+        flowName,
+        runId,
+        stepName,
         position,
-        timeout: config.timeout,
-        eventName: config.event
-      }
-    });
-    logger.debug(`Event timeout scheduled`, {
+        awaitType: "event",
+        timeoutAction: config.timeoutAction || "fail",
+        data: {
+          eventName: config.event,
+          timeout: timeoutMs,
+          registeredAt: Date.now() - timeoutMs,
+          timedOutAt: Date.now()
+        }
+      });
+      unsubscribe();
+    },
+    metadata: {
+      component: "await-pattern",
+      awaitType: "event",
       runId,
       stepName,
-      eventName: config.event,
-      timeout: config.timeout,
-      timeoutAction: config.timeoutAction
-    });
-  }
+      flowName,
+      position,
+      timeout: timeoutMs,
+      eventName: config.event
+    }
+  });
+  logger.debug(`Event timeout scheduled`, {
+    runId,
+    stepName,
+    eventName: config.event,
+    timeout: timeoutMs,
+    timeoutAction: config.timeoutAction,
+    isDefault: !config.timeout || config.timeout <= 0
+  });
   logger.debug(`Event await registered: ${config.event}`, { runId, stepName });
   return {
     eventName: config.event,
@@ -113,6 +119,8 @@ export async function resolveEventAwait(runId, stepName, flowName, position, eve
     position,
     triggerData: eventData,
     data: {
+      position,
+      // Store position in data for database persistence
       resolvedAt: Date.now()
     }
   });

package/dist/runtime/nitro/utils/awaitPatterns/schedule.js

@@ -43,6 +43,8 @@ export async function registerScheduleAwait(runId, stepName, flowName, config, p
     position,
     config,
     data: {
+      position,
+      // Store position in data for database persistence
       cron: config.cron,
       nextOccurrence,
       timeUntilNext,
@@ -63,14 +65,17 @@ export async function resolveScheduleAwait(runId, stepName, flowName, position,
   const logger = useNventLogger("await-schedule");
   const eventBus = getEventBus();
   logger.info(`Resolving schedule await`, { runId, stepName });
+  const scheduledAt = scheduleData?.scheduledAt || Date.now();
   eventBus.publish({
     type: "await.resolved",
     flowName,
     runId,
     stepName,
     position,
-    triggerData: scheduleData,
+    triggerData: { scheduledAt },
     data: {
+      position,
+      // Store position in data for database persistence
       resolvedAt: Date.now()
     }
   });

package/dist/runtime/nitro/utils/awaitPatterns/time.d.ts

@@ -12,4 +12,4 @@ export declare function registerTimeAwait(runId: string, stepName: string, flowN
 /**
  * Resolve time await when delay completes
  */
-export declare function resolveTimeAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', timeData: any): Promise<void>;
+export declare function resolveTimeAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', _timeData: any): Promise<void>;

package/dist/runtime/nitro/utils/awaitPatterns/time.js

@@ -37,6 +37,8 @@ export async function registerTimeAwait(runId, stepName, flowName, config, posit
     position,
     config,
     data: {
+      position,
+      // Store position in data for database persistence
       delay: config.delay,
       resolveAt,
       registeredAt: Date.now()
@@ -48,7 +50,7 @@ export async function registerTimeAwait(runId, stepName, flowName, config, posit
     resolveAt
   };
 }
-export async function resolveTimeAwait(runId, stepName, flowName, position, timeData) {
+export async function resolveTimeAwait(runId, stepName, flowName, position, _timeData) {
   const logger = useNventLogger("await-time");
   const eventBus = getEventBus();
   logger.info(`Resolving time await`, { runId, stepName });
@@ -58,8 +60,10 @@ export async function resolveTimeAwait(runId, stepName, flowName, position, time
     runId,
     stepName,
     position,
-    triggerData: timeData,
+    triggerData: {},
     data: {
+      position,
+      // Store position in data for database persistence
       resolvedAt: Date.now()
     }
   });

package/dist/runtime/nitro/utils/awaitPatterns/webhook.js

@@ -22,6 +22,9 @@ export async function registerWebhookAwait(runId, stepName, flowName, config, po
   const webhookPath = `/api/_webhook/await${path}`;
   const fullWebhookUrl = `${baseUrl.replace(/\/$/, "")}${webhookPath}`;
   logger.info(`Registering webhook await: ${fullWebhookUrl}`, { runId, stepName });
+  const { useAwaitDefaults } = await import("../useAwait.js");
+  const { webhookTimeout: defaultTimeout, timeoutAction: defaultTimeoutAction } = useAwaitDefaults();
+  const timeoutMs = config.timeout && config.timeout > 0 ? config.timeout : defaultTimeout;
   eventBus.publish({
     type: "await.registered",
     flowName,
@@ -31,62 +34,65 @@ export async function registerWebhookAwait(runId, stepName, flowName, config, po
     position,
     config,
     data: {
+      position,
+      // Store position in data for database persistence
       path,
       method: config.method || "POST",
-      timeout: config.timeout,
+      timeout: timeoutMs,
+      // Store resolved timeout (with default)
       registeredAt: Date.now(),
-      webhookUrl: fullWebhookUrl
+      webhookUrl: fullWebhookUrl,
+      timeoutAction: config.timeoutAction || defaultTimeoutAction
     }
   });
-  if (config.timeout && config.timeout > 0) {
-    const scheduler = useScheduler();
-    const timeoutAt = Date.now() + config.timeout;
-    const jobId = `await-webhook-timeout-${runId}-${stepName}-${position}`;
-    await scheduler.schedule({
-      id: jobId,
-      name: `Webhook Timeout: ${flowName} - ${stepName}`,
-      type: "one-time",
-      executeAt: timeoutAt,
-      handler: async () => {
-        logger.warn("Webhook await timeout", {
-          runId,
-          stepName,
-          flowName,
-          timeout: config.timeout,
-          timeoutAction: config.timeoutAction || "fail"
-        });
-        eventBus.publish({
-          type: "await.timeout",
-          flowName,
-          runId,
-          stepName,
-          position,
-          awaitType: "webhook",
-          timeoutAction: config.timeoutAction || "fail",
-          data: {
-            timeout: config.timeout,
-            registeredAt: Date.now() - (config.timeout || 0),
-            timedOutAt: Date.now()
-          }
-        });
-      },
-      metadata: {
-        component: "await-pattern",
-        awaitType: "webhook",
+  const scheduler = useScheduler();
+  const timeoutAt = Date.now() + timeoutMs;
+  const jobId = `await-webhook-timeout-${runId}-${stepName}-${position}`;
+  await scheduler.schedule({
+    id: jobId,
+    name: `Webhook Timeout: ${flowName} - ${stepName}`,
+    type: "one-time",
+    executeAt: timeoutAt,
+    handler: async () => {
+      logger.warn("Webhook await timeout", {
         runId,
         stepName,
         flowName,
+        timeout: timeoutMs,
+        timeoutAction: config.timeoutAction || "fail"
+      });
+      eventBus.publish({
+        type: "await.timeout",
+        flowName,
+        runId,
+        stepName,
         position,
-        timeout: config.timeout
-      }
-    });
-    logger.debug(`Webhook timeout scheduled`, {
+        awaitType: "webhook",
+        timeoutAction: config.timeoutAction || "fail",
+        data: {
+          timeout: timeoutMs,
+          registeredAt: Date.now() - timeoutMs,
+          timedOutAt: Date.now()
+        }
+      });
+    },
+    metadata: {
+      component: "await-pattern",
+      awaitType: "webhook",
       runId,
       stepName,
-      timeout: config.timeout,
-      timeoutAction: config.timeoutAction
-    });
-  }
+      flowName,
+      position,
+      timeout: timeoutMs
+    }
+  });
+  logger.debug(`Webhook timeout scheduled`, {
+    runId,
+    stepName,
+    timeout: timeoutMs,
+    timeoutAction: config.timeoutAction,
+    isDefault: !config.timeout || config.timeout <= 0
+  });
   logger.debug(`Webhook await registered: ${fullWebhookUrl}`, { runId, stepName });
   return {
     webhookUrl: fullWebhookUrl,
@@ -113,6 +119,8 @@ export async function resolveWebhookAwait(runId, stepName, flowName, position, w
     position,
     triggerData: webhookData,
     data: {
+      position,
+      // Store position in data for database persistence
       resolvedAt: Date.now()
     }
   });

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

@@ -1,10 +1,3 @@
-import { useFlow, useQueueAdapter } from '#imports';
-import type { RunContext, NodeHandler } from '../worker/node/runner.js';
-export type ExtendedRunContext = RunContext & {
-    provider: ReturnType<typeof useQueueAdapter>;
-    flow: ReturnType<typeof useFlow>;
-    registry: any;
-};
-export type DefineFunction = (handler: (input: any, ctx: ExtendedRunContext) => Promise<any>) => NodeHandler;
-export declare const defineFunction: DefineFunction;
+import type { RunContext, NodeHandler } from '../../worker/node/runner.js';
+export declare const defineFunction: <TInput = any, TOutput = any>(handler: (input: TInput, ctx: RunContext) => Promise<TOutput>) => NodeHandler;
 export default defineFunction;

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

@@ -1,17 +1,4 @@
-import { $useFunctionRegistry, useFlow, useQueueAdapter } from "#imports";
 export const defineFunction = (handler) => {
-  const wrapped = async (input, ctx) => {
-    const provider = useQueueAdapter();
-    const flow = ctx.flow || useFlow();
-    const registry = $useFunctionRegistry();
-    const extended = {
-      ...ctx,
-      provider,
-      flow,
-      registry
-    };
-    return handler(input, extended);
-  };
-  return wrapped;
+  return handler;
 };
 export default defineFunction;

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

@@ -110,6 +110,14 @@ export interface FlowConfig {
          */
         mode?: 'auto' | 'manual';
     };
+    /**
+     * Step execution timeout in milliseconds (v0.5.1)
+     * Overrides global flow.stepTimeout and queue.defaultJobOptions.timeout for this specific step
+     *
+     * @example 600000 // 10 minutes
+     * @example 3600000 // 1 hour
+     */
+    stepTimeout?: number;
     /**
      * Await pattern: Wait BEFORE step execution (v0.5)
      * Step won't execute until trigger fires
@@ -123,53 +131,113 @@ export interface FlowConfig {
 }
 /**
  * Await configuration (run-scoped triggers)
- * Declared in config, no functions allowed (AST-parsed)
+ *
+ * Pauses flow execution until a specific condition is met. Can be used with:
+ * - `awaitBefore`: Wait before step execution starts
+ * - `awaitAfter`: Wait after step completes before triggering next steps
+ *
+ * Declared in config, no functions allowed (AST-parsed at build time)
  */
 export interface AwaitConfig {
     /**
-     * Trigger type
+     * Type of trigger to wait for
+     * - `webhook`: Wait for HTTP request to specific endpoint
+     * - `event`: Wait for custom event with optional data matching
+     * - `schedule`: Wait until specific cron schedule time
+     * - `time`: Wait for fixed time delay
      */
     type: 'webhook' | 'event' | 'schedule' | 'time';
     /**
-     * URL path for webhook (supports template variables: {runId}, {stepId})
+     * URL path for webhook trigger (supports template variables)
+     *
+     * Only used when `type: 'webhook'`
+     *
+     * Template variables available:
+     * - `{runId}`: Current flow run ID
+     * - `{stepId}`: Current step execution ID
+     *
+     * @example '/webhooks/approve/{runId}'
+     * @example '/api/confirm/{stepId}'
      */
     path?: string;
     /**
-     * HTTP method for webhook
+     * HTTP method for webhook endpoint
+     *
+     * Only used when `type: 'webhook'`
+     *
+     * @default 'POST'
      */
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /**
      * Event name to wait for
+     *
+     * Only used when `type: 'event'`
+     *
+     * @example 'payment.completed'
+     * @example 'order.shipped'
      */
     event?: string;
     /**
-     * Key to match between event and step data
-     * e.g., 'orderId' matches event.orderId === step.orderId
-     * Supports nested paths: 'order.id' matches event.order.id === step.order.id
+     * Key to match between event data and step output
+     *
+     * Only used when `type: 'event'`
+     *
+     * Matches incoming event data against step output data.
+     * Supports nested paths using dot notation.
+     *
+     * @example 'orderId' - matches event.orderId === stepOutput.orderId
+     * @example 'order.id' - matches event.order.id === stepOutput.order.id
      */
     filterKey?: string;
     /**
-     * Cron expression (e.g., '0 9 * * *' for 9 AM daily)
+     * Cron expression defining when to trigger (one-time schedule)
+     *
+     * Only used when `type: 'schedule'`
+     *
+     * Note: This is a one-time trigger, not recurring. The next occurrence
+     * of the cron expression after step completion will trigger continuation.
+     *
+     * @example '0 9 * * *' - 9 AM daily (triggers at next 9 AM occurrence)
+     * @example '0 0 * * MON' - Midnight every Monday
      */
     cron?: string;
     /**
-     * Hours to add after step completion before calculating next cron occurrence
-     */
-    nextAfterHours?: number;
-    /**
-     * Timezone for cron expression
+     * Timezone for cron expression evaluation
+     *
+     * Only used when `type: 'schedule'`
+     *
+     * @example 'America/New_York'
+     * @example 'Europe/Berlin'
+     * @default 'UTC'
      */
     timezone?: string;
     /**
-     * Delay in milliseconds
+     * Fixed delay in milliseconds before continuation
+     *
+     * Only used when `type: 'time'`
+     *
+     * @example 60000 - 1 minute
+     * @example 3600000 - 1 hour
      */
     delay?: number;
     /**
-     * Maximum wait time in milliseconds
+     * Maximum wait time in milliseconds before timeout
+     *
+     * Applies to all trigger types. If the trigger doesn't fire within
+     * this duration, the timeout action will be taken.
+     *
+     * @example 86400000 - 24 hours
+     * @example 604800000 - 7 days
      */
     timeout?: number;
     /**
-     * Action to take on timeout
+     * Action to take when timeout is reached
+     *
+     * - `fail`: Mark step/flow as failed
+     * - `continue`: Continue flow execution anyway
+     * - `retry`: Retry waiting (reset timeout)
+     *
+     * @default 'fail'
      */
     timeoutAction?: 'fail' | 'continue' | 'retry';
 }

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

@@ -2,30 +2,65 @@
  * Type-safe hook definitions for await patterns
  * v0.5 - Await Integration
  */
-import type { RunContext } from '../worker/node/runner.js';
-export interface AwaitRegisterContext extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
-    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+import type { RunContext } from '../../worker/node/runner.js';
+export type AwaitType = 'webhook' | 'event' | 'schedule' | 'time';
+/**
+ * Hook data types specific to each await type
+ */
+export interface WebhookHookData {
+    webhookUrl: string;
+}
+export interface EventHookData {
+    eventName: string;
+}
+export interface ScheduleHookData {
+    cronExpression: string;
+    nextOccurrence: Date;
+}
+export interface TimeHookData {
+    delayMs: number;
+}
+/**
+ * Conditional type to get the correct hook data based on await type
+ */
+export type HookDataForAwaitType<T extends AwaitType> = T extends 'webhook' ? WebhookHookData : T extends 'event' ? EventHookData : T extends 'schedule' ? ScheduleHookData : T extends 'time' ? TimeHookData : never;
+export interface AwaitRegisterContext<T extends AwaitType = AwaitType> extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: T;
     awaitConfig: any;
+    position: 'before' | 'after';
 }
-export interface AwaitResolveContext extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
-    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+export interface AwaitResolveContext<T extends AwaitType = AwaitType> extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: T;
     resolvedData: any;
+    position: 'before' | 'after';
+}
+export interface AwaitTimeoutContext<T extends AwaitType = AwaitType> extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: T;
+    timeoutAction: 'fail' | 'continue' | 'retry';
+    position: 'before' | 'after';
 }
 /**
  * Define onAwaitRegister hook with proper types
  * Called when an await pattern is registered (before handler execution or after completion)
  *
  * @example
- * export const onAwaitRegister = defineAwaitRegisterHook(async (webhookUrl, stepData, ctx) => {
- *   // Send notification email with webhook URL
+ * // Webhook example
+ * export const onAwaitRegister = defineAwaitRegisterHook(async (hookData, stepData, ctx) => {
+ *   // hookData.webhookUrl is typed correctly for webhook awaits
  *   await sendEmail({
  *     to: stepData.reviewerEmail,
  *     subject: 'Approval Required',
- *     approveUrl: webhookUrl
+ *     approveUrl: hookData.webhookUrl
  *   })
  * })
+ *
+ * // Event example
+ * export const onAwaitRegister = defineAwaitRegisterHook(async (hookData, stepData, ctx) => {
+ *   // hookData.eventName is available for event awaits
+ *   console.log(`Waiting for event: ${hookData.eventName}`)
+ * })
  */
-export declare function defineAwaitRegisterHook(hook: (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>): (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>;
+export declare function defineAwaitRegisterHook<T extends AwaitType = AwaitType>(hook: (hookData: HookDataForAwaitType<T>, stepData: any, ctx: AwaitRegisterContext<T>) => Promise<void>): (hookData: HookDataForAwaitType<T>, stepData: any, ctx: AwaitRegisterContext<T>) => Promise<void>;
 /**
  * Define onAwaitResolve hook with proper types
  * Called when an await pattern is resolved (external trigger fired)
@@ -38,4 +73,23 @@ export declare function defineAwaitRegisterHook(hook: (webhookUrl: string, stepD
  *   await updateTicketStatus(stepData.ticketId, resolvedData.approved ? 'approved' : 'rejected')
  * })
  */
-export declare function defineAwaitResolveHook(hook: (resolvedData: any, stepData: any, ctx: AwaitResolveContext) => Promise<void>): (resolvedData: any, stepData: any, ctx: AwaitResolveContext) => Promise<void>;
+export declare function defineAwaitResolveHook<T extends AwaitType = AwaitType>(hook: (resolvedData: any, stepData: any, ctx: AwaitResolveContext<T>) => Promise<void>): (resolvedData: any, stepData: any, ctx: AwaitResolveContext<T>) => Promise<void>;
+/**
+ * Define onAwaitTimeout hook with proper types
+ * Called when an await pattern times out (timeout exceeded without resolution)
+ *
+ * @example
+ * export const onAwaitTimeout = defineAwaitTimeoutHook(async (stepData, ctx) => {
+ *   ctx.logger.log('warn', 'Approval request timed out', {
+ *     action: ctx.timeoutAction
+ *   })
+ *
+ *   // Send timeout notification
+ *   await sendEmail({
+ *     to: stepData.reviewerEmail,
+ *     subject: 'Approval Request Expired',
+ *     message: 'The approval request was not completed in time'
+ *   })
+ * })
+ */
+export declare function defineAwaitTimeoutHook<T extends AwaitType = AwaitType>(hook: (stepData: any, ctx: AwaitTimeoutContext<T>) => Promise<void>): (stepData: any, ctx: AwaitTimeoutContext<T>) => Promise<void>;

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

@@ -4,3 +4,6 @@ export function defineAwaitRegisterHook(hook) {
 export function defineAwaitResolveHook(hook) {
   return hook;
 }
+export function defineAwaitTimeoutHook(hook) {
+  return hook;
+}

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

@@ -1,5 +1,17 @@
 import type { AwaitConfig } from '../../../registry/types.js';
 import { registerAwaitPattern, resolveAwaitPattern, registerWebhookAwait, resolveWebhookAwait, registerEventAwait, resolveEventAwait, registerScheduleAwait, resolveScheduleAwait, registerTimeAwait, resolveTimeAwait } from './awaitPatterns/index.js';
+/**
+ * Get default timeout values for await patterns from runtime config
+ * These are configurable via module options and used throughout the system
+ * Exported for use by await pattern implementations
+ */
+export declare function useAwaitDefaults(): {
+    webhookTimeout: any;
+    eventTimeout: any;
+    timeTimeout: any;
+    scheduleTimeout: any;
+    timeoutAction: any;
+};
 /**
  * Await pattern composable
  * Provides unified API for managing await patterns in flows