nvent 0.4.4 → 0.5.0

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

@@ -0,0 +1,67 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+export async function registerTimeAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-time");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  if (!config.delay) {
+    throw new Error("Time await requires delay configuration (in milliseconds)");
+  }
+  logger.info(`Registering time await: ${config.delay}ms`, { runId, stepName });
+  const resolveAt = Date.now() + config.delay;
+  const jobId = `await-time-${runId}-${stepName}-${position}`;
+  await scheduler.schedule({
+    id: jobId,
+    name: `Time Await: ${flowName} - ${stepName}`,
+    type: "one-time",
+    executeAt: resolveAt,
+    handler: async () => {
+      await resolveTimeAwait(runId, stepName, flowName, position, { delayCompleted: true });
+    },
+    metadata: {
+      component: "await-pattern",
+      awaitType: "time",
+      runId,
+      stepName,
+      flowName,
+      position,
+      delay: config.delay
+    }
+  });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "time",
+    position,
+    config,
+    data: {
+      delay: config.delay,
+      resolveAt,
+      registeredAt: Date.now()
+    }
+  });
+  logger.debug(`Time await registered: ${config.delay}ms`, { runId, stepName });
+  return {
+    delay: config.delay,
+    resolveAt
+  };
+}
+export async function resolveTimeAwait(runId, stepName, flowName, position, timeData) {
+  const logger = useNventLogger("await-time");
+  const eventBus = getEventBus();
+  logger.info(`Resolving time await`, { runId, stepName });
+  eventBus.publish({
+    type: "await.resolved",
+    flowName,
+    runId,
+    stepName,
+    position,
+    triggerData: timeData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Time await resolved`, { runId, stepName });
+}

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

@@ -0,0 +1,15 @@
+import type { AwaitConfig } from '../../../../registry/types.js';
+/**
+ * Await Pattern: Webhook
+ *
+ * Creates a dynamic webhook endpoint that resolves when called
+ * Useful for human approval flows, external integrations
+ */
+export declare function registerWebhookAwait(runId: string, stepName: string, flowName: string, config: AwaitConfig, position?: 'before' | 'after'): Promise<{
+    webhookUrl: string;
+    timeout: number | undefined;
+}>;
+/**
+ * Resolve webhook await when webhook is called
+ */
+export declare function resolveWebhookAwait(runId: string, stepName: string, flowName: string, position: 'before' | 'after', webhookData: any): Promise<void>;

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

@@ -0,0 +1,120 @@
+import { useNventLogger, useRuntimeConfig, useScheduler } from "#imports";
+import { getEventBus } from "../../../events/eventBus.js";
+export async function registerWebhookAwait(runId, stepName, flowName, config, position = "after") {
+  const logger = useNventLogger("await-webhook");
+  const eventBus = getEventBus();
+  const runtimeConfig = useRuntimeConfig();
+  const path = `/${flowName}/${runId}/${stepName}`;
+  let baseUrl = runtimeConfig.nvent?.webhooks?.baseUrl;
+  if (!baseUrl) {
+    const nitroApp = runtimeConfig.nitro?.app;
+    if (nitroApp?.baseURL) {
+      baseUrl = `${nitroApp.baseURL}`;
+    }
+    if (!baseUrl) {
+      baseUrl = process.env.NITRO_URL || process.env.URL || (process.env.NODE_ENV === "development" ? "http://localhost:3000" : void 0);
+    }
+  }
+  if (!baseUrl) {
+    logger.warn("No baseUrl configured for webhooks. Set NUXT_PUBLIC_SITE_URL or nvent.webhooks.baseUrl");
+    baseUrl = "http://localhost:3000";
+  }
+  const webhookPath = `/api/_webhook/await${path}`;
+  const fullWebhookUrl = `${baseUrl.replace(/\/$/, "")}${webhookPath}`;
+  logger.info(`Registering webhook await: ${fullWebhookUrl}`, { runId, stepName });
+  eventBus.publish({
+    type: "await.registered",
+    flowName,
+    runId,
+    stepName,
+    awaitType: "webhook",
+    position,
+    config,
+    data: {
+      path,
+      method: config.method || "POST",
+      timeout: config.timeout,
+      registeredAt: Date.now(),
+      webhookUrl: fullWebhookUrl
+    }
+  });
+  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",
+        runId,
+        stepName,
+        flowName,
+        position,
+        timeout: config.timeout
+      }
+    });
+    logger.debug(`Webhook timeout scheduled`, {
+      runId,
+      stepName,
+      timeout: config.timeout,
+      timeoutAction: config.timeoutAction
+    });
+  }
+  logger.debug(`Webhook await registered: ${fullWebhookUrl}`, { runId, stepName });
+  return {
+    webhookUrl: fullWebhookUrl,
+    timeout: config.timeout
+  };
+}
+export async function resolveWebhookAwait(runId, stepName, flowName, position, webhookData) {
+  const logger = useNventLogger("await-webhook");
+  const eventBus = getEventBus();
+  const scheduler = useScheduler();
+  logger.info(`Resolving webhook await`, { runId, stepName });
+  const jobId = `await-webhook-timeout-${runId}-${stepName}-${position}`;
+  try {
+    await scheduler.unschedule(jobId);
+    logger.debug("Unscheduled webhook timeout job", { runId, stepName, jobId });
+  } catch {
+    logger.debug("Could not unschedule timeout job (may not exist)", { runId, stepName, jobId });
+  }
+  eventBus.publish({
+    type: "await.resolved",
+    flowName,
+    runId,
+    stepName,
+    position,
+    triggerData: webhookData,
+    data: {
+      resolvedAt: Date.now()
+    }
+  });
+  logger.debug(`Webhook await resolved`, { runId, stepName });
+}

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

@@ -0,0 +1,10 @@
+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;
+export default defineFunction;

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

@@ -0,0 +1,17 @@
+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;
+};
+export default defineFunction;

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

@@ -0,0 +1,310 @@
+export type FlowRole = 'entry' | 'step';
+/**
+ * Trigger definition for inline trigger registration
+ * Can be defined in function config alongside subscription
+ */
+export interface TriggerDefinition {
+    /**
+     * Unique trigger name (e.g., 'manual.approve-order')
+     */
+    name: string;
+    /**
+     * Trigger type
+     */
+    type: 'event' | 'webhook' | 'schedule' | 'manual';
+    /**
+     * Trigger scope: 'flow' for entry triggers, 'await' for await patterns
+     */
+    scope?: 'flow' | 'await';
+    /**
+     * Human-readable display name
+     */
+    displayName?: string;
+    /**
+     * Description of what this trigger does
+     */
+    description?: string;
+    /**
+     * Expected flows that should subscribe to this trigger (for validation)
+     */
+    expectedSubscribers?: string[];
+    /**
+     * Webhook-specific configuration
+     */
+    webhook?: {
+        /**
+         * URL path for webhook (e.g., '/api/webhooks/stripe')
+         */
+        path: string;
+        /**
+         * HTTP method
+         */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        /**
+         * Authentication configuration
+         */
+        auth?: any;
+    };
+    /**
+     * Schedule-specific configuration
+     */
+    schedule?: {
+        /**
+         * Cron expression (e.g., '0 9 * * *' for 9 AM daily)
+         */
+        cron: string;
+        /**
+         * Timezone for cron expression
+         */
+        timezone?: string;
+        /**
+         * Whether schedule is enabled
+         */
+        enabled?: boolean;
+    };
+    /**
+     * Additional configuration options
+     */
+    config?: Record<string, any>;
+}
+export interface FlowConfig {
+    /**
+     * One or more flow names this step belongs to.
+     * A single worker step can participate in multiple flows.
+     */
+    name: string | string[];
+    /**
+     * Role of this step in the flow.
+     */
+    role: FlowRole;
+    /**
+     * Logical step name (used as job name and event kind on start).
+     */
+    step: string;
+    /**
+     * Event kinds this step emits (e.g., `${step}.completed`).
+     */
+    emits?: string[];
+    /**
+     * Event kinds this step subscribes to; can be a single string or an array.
+     * The compiler normalizes this to `string[]` under `subscribes`.
+     */
+    subscribes?: string | string[];
+    /**
+     * Entry trigger configuration (v0.5)
+     * Define and/or subscribe to triggers to start flow runs
+     */
+    triggers?: {
+        /**
+         * Define a new trigger inline (optional)
+         * If provided, this trigger will be registered at build time
+         */
+        define?: TriggerDefinition;
+        /**
+         * Array of trigger names to subscribe to
+         * Can include the defined trigger or external triggers
+         */
+        subscribe: string[];
+        /**
+         * Trigger mode: 'auto' (immediate) or 'manual' (requires approval)
+         */
+        mode?: 'auto' | 'manual';
+    };
+    /**
+     * Await pattern: Wait BEFORE step execution (v0.5)
+     * Step won't execute until trigger fires
+     */
+    awaitBefore?: AwaitConfig;
+    /**
+     * Await pattern: Wait AFTER step execution (v0.5)
+     * Next steps won't trigger until trigger fires
+     */
+    awaitAfter?: AwaitConfig;
+}
+/**
+ * Await configuration (run-scoped triggers)
+ * Declared in config, no functions allowed (AST-parsed)
+ */
+export interface AwaitConfig {
+    /**
+     * Trigger type
+     */
+    type: 'webhook' | 'event' | 'schedule' | 'time';
+    /**
+     * URL path for webhook (supports template variables: {runId}, {stepId})
+     */
+    path?: string;
+    /**
+     * HTTP method for webhook
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /**
+     * Event name to wait for
+     */
+    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
+     */
+    filterKey?: string;
+    /**
+     * Cron expression (e.g., '0 9 * * *' for 9 AM daily)
+     */
+    cron?: string;
+    /**
+     * Hours to add after step completion before calculating next cron occurrence
+     */
+    nextAfterHours?: number;
+    /**
+     * Timezone for cron expression
+     */
+    timezone?: string;
+    /**
+     * Delay in milliseconds
+     */
+    delay?: number;
+    /**
+     * Maximum wait time in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Action to take on timeout
+     */
+    timeoutAction?: 'fail' | 'continue' | 'retry';
+}
+export interface QueueJobDefaults {
+    /**
+     * Number of retry attempts for failed jobs.
+     * BullMQ: attempts, PGBoss: retryLimit
+     */
+    attempts?: number;
+    /**
+     * Backoff strategy for retries.
+     * BullMQ: backoff, PGBoss: retryBackoff + exponentialBackoff
+     */
+    backoff?: number | {
+        type: 'fixed' | 'exponential';
+        delay: number;
+    };
+    /**
+     * Delay in milliseconds before the job is processed.
+     * BullMQ: delay, PGBoss: startAfter
+     */
+    delay?: number;
+    /**
+     * Job priority (higher number = higher priority).
+     * BullMQ: priority, PGBoss: priority
+     */
+    priority?: number;
+    /**
+     * Job timeout in milliseconds.
+     * BullMQ: timeout, PGBoss: expireInSeconds (converted)
+     */
+    timeout?: number;
+    /**
+     * Process jobs in LIFO (Last In First Out) order.
+     * BullMQ: lifo, PGBoss: not supported
+     */
+    lifo?: boolean;
+    /**
+     * Remove job from queue when completed.
+     * BullMQ: removeOnComplete, PGBoss: deleteAfterSeconds
+     */
+    removeOnComplete?: boolean | number;
+    /**
+     * Remove job from queue when failed.
+     * BullMQ: removeOnFail, PGBoss: deleteAfterSeconds
+     */
+    removeOnFail?: boolean | number;
+    /**
+     * Repeatable job configuration.
+     * BullMQ: repeat, PGBoss: schedule pattern
+     */
+    repeat?: {
+        cron?: string;
+        every?: number;
+        limit?: number;
+        tz?: string;
+    };
+}
+export interface QueueConfig {
+    /**
+     * Queue name. If not provided, the filename will be used.
+     */
+    name?: string;
+    /**
+     * Default options for jobs enqueued to this queue.
+     */
+    defaultJobOptions?: QueueJobDefaults;
+    /**
+     * Prefix for queue keys in Redis/storage.
+     * BullMQ: prefix, PGBoss: schema
+     */
+    prefix?: string;
+    /**
+     * Rate limiting configuration.
+     * BullMQ: limiter, PGBoss: teamSize + teamConcurrency (partial)
+     */
+    limiter?: {
+        /**
+         * Maximum number of jobs to process in the duration window.
+         */
+        max?: number;
+        /**
+         * Duration of the rate limit window in milliseconds.
+         */
+        duration?: number;
+        /**
+         * Group key for rate limiting (optional).
+         * BullMQ only: allows per-group rate limiting
+         */
+        groupKey?: string;
+    };
+}
+export interface WorkerConfig {
+    /**
+     * Number of jobs to process concurrently.
+     * BullMQ: concurrency, PGBoss: teamSize
+     */
+    concurrency?: number;
+    /**
+     * Lock duration in milliseconds.
+     * BullMQ: lockDuration, PGBoss: newJobCheckInterval (similar concept)
+     */
+    lockDurationMs?: number;
+    /**
+     * Maximum number of times a job can be stalled before being failed.
+     * BullMQ: maxStalledCount, PGBoss: not directly supported
+     */
+    maxStalledCount?: number;
+    /**
+     * Delay in milliseconds before processing jobs after queue is drained.
+     * BullMQ: drainDelay, PGBoss: not directly supported
+     */
+    drainDelayMs?: number;
+    /**
+     * Automatically run worker on startup.
+     * BullMQ: autorun, PGBoss: workers start automatically
+     */
+    autorun?: boolean;
+    /**
+     * Polling interval in milliseconds for checking new jobs.
+     * PGBoss: newJobCheckInterval, BullMQ: uses blocking wait
+     */
+    pollingIntervalMs?: number;
+}
+export interface QueueWorkerConfig {
+    queue?: QueueConfig;
+    flow?: FlowConfig;
+    worker?: WorkerConfig;
+}
+export type DefineFunctionConfig = <T extends QueueWorkerConfig>(cfg: T) => T;
+export declare const defineFunctionConfig: DefineFunctionConfig;
+/**
+ * Helper for defining trigger configurations inline
+ * This is just a type helper, actual value is the same as defineFunctionConfig
+ */
+export type DefineTriggerConfig = <T extends TriggerDefinition>(cfg: T) => T;
+export declare const defineTriggerConfig: DefineTriggerConfig;
+export default defineFunctionConfig;

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

@@ -0,0 +1,3 @@
+export const defineFunctionConfig = (cfg) => cfg;
+export const defineTriggerConfig = (cfg) => cfg;
+export default defineFunctionConfig;

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

@@ -0,0 +1,41 @@
+/**
+ * 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';
+    awaitConfig: any;
+}
+export interface AwaitResolveContext extends Pick<RunContext, 'flowId' | 'flowName' | 'stepName' | 'logger' | 'state'> {
+    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+    resolvedData: any;
+}
+/**
+ * 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
+ *   await sendEmail({
+ *     to: stepData.reviewerEmail,
+ *     subject: 'Approval Required',
+ *     approveUrl: webhookUrl
+ *   })
+ * })
+ */
+export declare function defineAwaitRegisterHook(hook: (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>): (webhookUrl: string, stepData: any, ctx: AwaitRegisterContext) => Promise<void>;
+/**
+ * Define onAwaitResolve hook with proper types
+ * Called when an await pattern is resolved (external trigger fired)
+ *
+ * @example
+ * export const onAwaitResolve = defineAwaitResolveHook(async (resolvedData, stepData, ctx) => {
+ *   ctx.logger.log('info', 'Approval received', { approved: resolvedData.approved })
+ *
+ *   // Update external system
+ *   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>;

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

@@ -0,0 +1,6 @@
+export function defineAwaitRegisterHook(hook) {
+  return hook;
+}
+export function defineAwaitResolveHook(hook) {
+  return hook;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Adapter Registration Utilities
+ *
+ * Used by external adapter modules to register their adapters with nvent
+ */
+import type { QueueAdapter } from '../../adapters/interfaces/queue.js';
+import type { StreamAdapter } from '../../adapters/interfaces/stream.js';
+import type { StoreAdapter } from '../../adapters/interfaces/store.js';
+/**
+ * Register a queue adapter
+ *
+ * Called by external adapter modules (e.g., @nvent/adapter-queue-redis)
+ * to register their adapter implementation.
+ *
+ * @param name - Adapter name (e.g., 'redis', 'postgres', 'rabbitmq')
+ * @param adapter - QueueAdapter implementation
+ *
+ * @example
+ * import { registerQueueAdapter } from '#imports'
+ * import { RedisQueueAdapter } from './adapter'
+ *
+ * const adapter = new RedisQueueAdapter({ connection })
+ * registerQueueAdapter('redis', adapter)
+ */
+export declare function registerQueueAdapter(name: string, adapter: QueueAdapter): void;
+/**
+ * Register a stream adapter
+ *
+ * Called by external adapter modules (e.g., @nvent/adapter-stream-redis)
+ * to register their adapter implementation.
+ *
+ * @param name - Adapter name (e.g., 'redis', 'rabbitmq', 'kafka')
+ * @param adapter - StreamAdapter implementation
+ *
+ * @example
+ * import { registerStreamAdapter } from '#imports'
+ * import { RedisStreamAdapter } from './adapter'
+ *
+ * const adapter = new RedisStreamAdapter({ connection })
+ * registerStreamAdapter('redis', adapter)
+ */
+export declare function registerStreamAdapter(name: string, adapter: StreamAdapter): void;
+/**
+ * Register a store adapter
+ *
+ * Called by external adapter modules (e.g., @nvent/adapter-store-redis)
+ * to register their adapter implementation.
+ *
+ * @param name - Adapter name (e.g., 'redis', 'postgres')
+ * @param adapter - StoreAdapter implementation
+ *
+ * @example
+ * import { registerStoreAdapter } from '#imports'
+ * import { RedisStoreAdapter } from './adapter'
+ *
+ * const adapter = new RedisStoreAdapter({ connection })
+ * registerStoreAdapter('redis', adapter)
+ */
+export declare function registerStoreAdapter(name: string, adapter: StoreAdapter): void;

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

@@ -0,0 +1,13 @@
+import { useAdapterRegistry } from "../../adapters/registry.js";
+export function registerQueueAdapter(name, adapter) {
+  const registry = useAdapterRegistry();
+  registry.registerQueue(name, adapter);
+}
+export function registerStreamAdapter(name, adapter) {
+  const registry = useAdapterRegistry();
+  registry.registerStream(name, adapter);
+}
+export function registerStoreAdapter(name, adapter) {
+  const registry = useAdapterRegistry();
+  registry.registerStore(name, adapter);
+}