nvent 0.4.4 → 0.5.0

package/dist/runtime/config/types.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Redis connection configuration
+ */
+export interface RedisConfig {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    db?: number;
+    url?: string;
+}
+/**
+ * PostgreSQL connection configuration
+ */
+export interface PostgresConfig {
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean | object;
+}
+/**
+ * RabbitMQ connection configuration
+ */
+export interface RabbitMQConfig {
+    url?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    vhost?: string;
+}
+/**
+ * Kafka connection configuration
+ */
+export interface KafkaConfig {
+    brokers?: string[];
+    clientId?: string;
+    groupId?: string;
+}
+/**
+ * File storage configuration
+ */
+export interface FileConfig {
+    /**
+     * Base directory for file storage
+     * @default '.data'
+     */
+    dataDir?: string;
+}
+/**
+ * Shared connection configurations (v0.4.1)
+ * Provides fallback connections for all adapters
+ */
+export interface ConnectionsConfig {
+    /**
+     * Shared Redis connection - used by adapters that specify 'redis' but don't provide connection details
+     */
+    redis?: RedisConfig;
+    /**
+     * Shared Postgres connection - used by adapters that specify 'postgres' but don't provide connection details
+     */
+    postgres?: PostgresConfig;
+    /**
+     * Shared RabbitMQ connection - used by stream adapter when 'rabbitmq' is specified
+     */
+    rabbitmq?: RabbitMQConfig;
+    /**
+     * Shared Kafka connection - used by stream adapter when 'kafka' is specified
+     */
+    kafka?: KafkaConfig;
+    /**
+     * Shared file storage configuration - used by file adapters
+     */
+    file?: FileConfig;
+}
+/**
+ * Worker configuration
+ */
+export interface WorkerConfig {
+    /**
+     * Number of concurrent jobs to process
+     * @default 2
+     */
+    concurrency?: number;
+    /**
+     * Lock duration for jobs in milliseconds
+     */
+    lockDurationMs?: number;
+    /**
+     * Maximum number of times a job can be stalled before failing
+     */
+    maxStalledCount?: number;
+    /**
+     * Delay before draining the queue on shutdown
+     */
+    drainDelayMs?: number;
+    /**
+     * Automatically start workers
+     * @default true
+     */
+    autorun?: boolean;
+    /**
+     * Polling interval for file adapter (milliseconds)
+     * @default 1000
+     */
+    pollingIntervalMs?: number;
+}
+/**
+ * Queue adapter configuration (v0.4.1)
+ */
+export interface QueueConfig {
+    /**
+     * Queue backend adapter
+     * @default 'file'
+     */
+    adapter?: 'memory' | 'file' | 'redis' | 'postgres';
+    /**
+     * Redis connection (overrides connections.redis if specified)
+     */
+    redis?: RedisConfig;
+    /**
+     * Postgres connection (overrides connections.postgres if specified)
+     */
+    postgres?: PostgresConfig;
+    /**
+     * File storage configuration (overrides connections.file if specified)
+     */
+    file?: FileConfig;
+    /**
+     * Queue-specific options (BullMQ/PGBoss configuration)
+     */
+    prefix?: string;
+    /**
+     * PostgreSQL schema name for pg-boss tables
+     * Only applies when adapter is 'postgres'
+     * @default 'pgboss'
+     */
+    schema?: string;
+    defaultJobOptions?: {
+        attempts?: number;
+        backoff?: number | {
+            type: 'fixed' | 'exponential';
+            delay: number;
+        };
+        delay?: number;
+        priority?: number;
+        timeout?: number;
+        lifo?: boolean;
+        removeOnComplete?: boolean | number;
+        removeOnFail?: boolean | number;
+    };
+    limiter?: {
+        max?: number;
+        duration?: number;
+        groupKey?: string;
+    };
+    /**
+     * Worker configuration
+     */
+    worker?: WorkerConfig;
+}
+/**
+ * Stream adapter configuration (v0.4.1)
+ * Cross-instance pub/sub messaging
+ */
+export interface StreamConfig {
+    /**
+     * Stream adapter
+     * @default 'memory'
+     */
+    adapter?: 'memory' | 'redis' | 'rabbitmq' | 'kafka';
+    /**
+     * Redis connection (overrides connections.redis if specified)
+     */
+    redis?: RedisConfig;
+    /**
+     * Postgres connection (overrides connections.postgres if specified)
+     */
+    postgres?: PostgresConfig;
+    /**
+     * RabbitMQ connection (overrides connections.rabbitmq if specified)
+     */
+    rabbitmq?: RabbitMQConfig;
+    /**
+     * Kafka connection (overrides connections.kafka if specified)
+     */
+    kafka?: KafkaConfig;
+    /**
+     * Stream-specific options
+     */
+    prefix?: string;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
+/**
+ * Webhooks configuration
+ */
+export interface WebhooksConfig {
+    /**
+     * Base URL for webhook endpoints
+     * Auto-detected from Nitro context in development
+     * Set explicitly for production or to override auto-detection
+     * @default Auto-detected from NUXT_PUBLIC_SITE_URL, NITRO_URL, or dev server (http://localhost:3000 fallback)
+     */
+    baseUrl?: string;
+}
+/**
+ * Flow configuration
+ */
+export interface FlowConfig {
+    /**
+     * Stall detection configuration
+     * Detects and marks flows that have been running without activity for too long
+     */
+    stallDetection?: {
+        /**
+         * Enable stall detection
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Time in milliseconds after which a running flow without activity is considered stalled
+         * @default 1800000 (30 minutes)
+         */
+        stallTimeout?: number;
+        /**
+         * Interval in milliseconds for periodic stall checks
+         * @default 900000 (15 minutes)
+         */
+        checkInterval?: number;
+        /**
+         * Enable periodic background checks
+         * Set to false to use only lazy detection (when flows are queried)
+         * @default true
+         */
+        enablePeriodicCheck?: boolean;
+    };
+}
+/**
+ * State management configuration
+ */
+export interface StateManagementConfig {
+    /**
+     * Automatic scope/flow ID assignment for state operations
+     * - 'always': Always create a new flow ID (recommended for most cases)
+     * - 'flow': Only use flow ID if provided in context
+     * - 'never': Never scope state to flow IDs
+     * @default 'always'
+     */
+    autoScope?: 'always' | 'flow' | 'never';
+    /**
+     * State cleanup strategy
+     */
+    cleanup?: {
+        /**
+         * Cleanup strategy
+         * - 'never': State persists indefinitely
+         * - 'immediate': Cleanup after each step (not recommended)
+         * - 'on-complete': Cleanup when flow completes (recommended)
+         * - 'ttl': Automatic expiration via TTL
+         * @default 'never'
+         */
+        strategy?: 'never' | 'immediate' | 'on-complete' | 'ttl';
+        /**
+         * TTL in milliseconds for 'ttl' strategy
+         * @default 3600000 (1 hour)
+         */
+        ttlMs?: number;
+    };
+}
+/**
+ * Store adapter configuration (v0.4.1)
+ * Three-tier storage: events (NDJSON), documents (JSON), KV (JSON), indices (JSON)
+ * Replaces both state and eventStore configs from v0.4.0
+ */
+export interface StoreConfig {
+    /**
+     * Store adapter
+     * @default 'file'
+     */
+    adapter?: 'memory' | 'file' | 'redis' | 'postgres';
+    /**
+     * Redis connection (overrides connections.redis if specified)
+     */
+    redis?: RedisConfig;
+    /**
+     * Postgres connection (overrides connections.postgres if specified)
+     */
+    postgres?: PostgresConfig;
+    /**
+     * File storage configuration (overrides connections.file if specified)
+     */
+    file?: FileConfig;
+    /**
+     * Key prefix/namespace for all store operations
+     * @default 'nq'
+     */
+    prefix?: string;
+    /**
+     * PostgreSQL schema name for store tables
+     * Only applies when adapter is 'postgres'
+     * @default 'public'
+     */
+    schema?: string;
+    /**
+     * State management configuration (KV store behavior)
+     */
+    state?: StateManagementConfig;
+    /**
+     * Event stream TTL in seconds
+     * @default 604800 (7 days)
+     */
+    eventTTL?: number;
+    /**
+     * Metadata document TTL in seconds
+     * @default 2592000 (30 days)
+     */
+    metadataTTL?: number;
+    /**
+     * KV store TTL in seconds
+     */
+    kvTTL?: number;
+    /**
+     * Index TTL in seconds
+     */
+    indexTTL?: number;
+    /**
+     * Enable compression for stored data
+     */
+    compression?: boolean;
+}
+/**
+ * Module options for nvent (v0.4.1+)
+ */
+export interface ModuleOptions {
+    /**
+     * Directory to scan for function definitions
+     * @default 'server/functions'
+     */
+    dir?: string;
+    /**
+     * Enable dev UI
+     * @default true in development
+     */
+    ui?: boolean;
+    /**
+     * Debug configuration
+     */
+    debug?: Record<string, any>;
+    /**
+     * Queue adapter configuration (job execution)
+     */
+    queue?: QueueConfig;
+    /**
+     * Stream adapter configuration (pub/sub messaging)
+     * @since v0.4.1
+     */
+    stream?: StreamConfig;
+    /**
+     * Store adapter configuration (persistence)
+     * Three-tier storage: events, documents, KV, indices
+     * @since v0.4.1
+     */
+    store?: StoreConfig;
+    /**
+     * Flow-specific configuration
+     * @since v0.4.1
+     */
+    flow?: FlowConfig;
+    /**
+     * Webhooks configuration
+     * @since v0.5.0
+     */
+    webhooks?: WebhooksConfig;
+    /**
+     * Shared connection configurations
+     * Used as fallback if adapters don't specify their own connections
+     * @since v0.4.1
+     */
+    connections?: ConnectionsConfig;
+}
+/**
+ * Runtime config shape for nvent module (v0.4.1+)
+ */
+export interface ModuleConfig {
+    debug?: Record<string, any>;
+    queue: Required<QueueConfig>;
+    stream: Required<StreamConfig>;
+    store: Required<StoreConfig>;
+    flow: Required<FlowConfig>;
+    webhooks: Required<WebhooksConfig>;
+    connections: Required<ConnectionsConfig>;
+    rootDir?: string;
+}

package/dist/runtime/{server-utils/events → events}/eventBus.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { EventRecord } from '../types.js';
+import type { EventRecord } from './types.js';
 type Handler = (e: EventRecord) => void;
 declare global {
     var __nq_bus_emitter: EventEmitter | undefined;

package/dist/runtime/events/types.d.ts

@@ -0,0 +1,145 @@
+export interface PublishContext {
+    queue?: string;
+    jobId?: string;
+    /** Flow run ID for flow events */
+    flowId?: string;
+    /** Trigger ID for trigger events */
+    triggerId?: string;
+}
+export interface PublishPayload<T = any> {
+    type: string;
+    runId: string;
+    flowName: string;
+    stepName?: string;
+    stepId?: string;
+    attempt?: number;
+    data?: T;
+}
+export type EventType = 'flow.start' | 'flow.completed' | 'flow.failed' | 'flow.cancel' | 'step.started' | 'step.completed' | 'step.failed' | 'step.retry' | 'log' | 'emit' | 'state' | 'flow.stalled' | 'trigger.fired' | 'trigger.registered' | 'await.registered' | 'await.resolved' | 'await.timeout';
+export interface BaseEvent {
+    id?: string;
+    ts?: string;
+    type: EventType;
+    runId: string;
+    flowName: string;
+}
+export interface StepEvent extends BaseEvent {
+    stepName: string;
+    stepId: string;
+    attempt: number;
+}
+export interface FlowStartEvent extends BaseEvent {
+    type: 'flow.start';
+    data?: {
+        input?: any;
+    };
+}
+export interface FlowCompletedEvent extends BaseEvent {
+    type: 'flow.completed';
+    data?: {
+        result?: any;
+    };
+}
+export interface FlowFailedEvent extends BaseEvent {
+    type: 'flow.failed';
+    data?: {
+        error?: string;
+        stack?: string;
+    };
+}
+export interface FlowCancelEvent extends BaseEvent {
+    type: 'flow.cancel';
+    data?: {
+        canceledAt?: string;
+    };
+}
+export interface FlowStalledEvent extends BaseEvent {
+    type: 'flow.stalled';
+    data?: {
+        lastActivityAt?: number;
+        stallTimeout?: number;
+    };
+}
+export interface StepStartedEvent extends StepEvent {
+    type: 'step.started';
+    data?: {
+        input?: any;
+    };
+}
+export interface StepCompletedEvent extends StepEvent {
+    type: 'step.completed';
+    data?: {
+        result?: any;
+    };
+}
+export interface StepFailedEvent extends StepEvent {
+    type: 'step.failed';
+    data?: {
+        error?: string;
+        stack?: string;
+    };
+}
+export interface StepRetryEvent extends StepEvent {
+    type: 'step.retry';
+    data?: {
+        stepName: string;
+        queue: string;
+        attempt: number;
+        maxAttempts: number;
+        nextAttempt: number;
+    };
+}
+export interface LogEvent extends StepEvent {
+    type: 'log';
+    data: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        [key: string]: any;
+    };
+}
+export interface EmitEvent extends StepEvent {
+    type: 'emit';
+    data: {
+        topic: string;
+        payload: any;
+    };
+}
+export interface StateEvent extends StepEvent {
+    type: 'state';
+    data: {
+        operation: 'get' | 'set' | 'delete';
+        scope?: string;
+        key: string;
+        value?: any;
+    };
+}
+export interface TriggerFiredEvent extends BaseEvent {
+    type: 'trigger.fired';
+    triggerName: string;
+    data: any;
+}
+export interface TriggerRegisteredEvent {
+    type: 'trigger.registered';
+    triggerName: string;
+    triggerType: 'event' | 'webhook' | 'schedule' | 'manual';
+    scope: 'flow' | 'run';
+}
+export interface AwaitRegisteredEvent extends BaseEvent {
+    type: 'await.registered';
+    stepName: string;
+    awaitType: 'webhook' | 'event' | 'schedule' | 'time';
+    position: 'before' | 'after';
+    config: any;
+}
+export interface AwaitResolvedEvent extends BaseEvent {
+    type: 'await.resolved';
+    stepName: string;
+    triggerData: any;
+    position: 'before' | 'after';
+}
+export interface AwaitTimeoutEvent extends BaseEvent {
+    type: 'await.timeout';
+    stepName: string;
+    action: 'fail' | 'continue' | 'retry';
+}
+export type FlowEvent = FlowStartEvent | FlowCompletedEvent | FlowFailedEvent | FlowCancelEvent | FlowStalledEvent | StepStartedEvent | StepCompletedEvent | StepFailedEvent | StepRetryEvent | LogEvent | EmitEvent | StateEvent | TriggerFiredEvent | TriggerRegisteredEvent | AwaitRegisteredEvent | AwaitResolvedEvent | AwaitTimeoutEvent;

package/dist/runtime/events/utils/scheduleTrigger.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Schedule or update a schedule trigger in the scheduler
+ */
+export declare function scheduleTrigger(triggerName: string, scheduleConfig: any, triggerStatus?: string): Promise<void>;
+/**
+ * Unschedule a schedule trigger from the scheduler
+ */
+export declare function unscheduleTrigger(triggerName: string): Promise<void>;

package/dist/runtime/events/utils/scheduleTrigger.js

@@ -0,0 +1,69 @@
+import { useNventLogger, useScheduler } from "#imports";
+import { getEventBus } from "../eventBus.js";
+export async function scheduleTrigger(triggerName, scheduleConfig, triggerStatus) {
+  const logger = useNventLogger("trigger-wiring");
+  const scheduler = useScheduler();
+  const eventBus = getEventBus();
+  try {
+    const jobId = `trigger:${triggerName}`;
+    const handler = async () => {
+      logger.debug("Schedule trigger fired", { trigger: triggerName });
+      await eventBus.publish({
+        type: "trigger.fired",
+        triggerName,
+        data: {
+          scheduledAt: Date.now(),
+          timezone: scheduleConfig.timezone || "UTC"
+        }
+      });
+    };
+    await scheduler.unschedule(jobId);
+    const jobConfig = {
+      id: jobId,
+      type: scheduleConfig.cron ? "cron" : "interval",
+      name: `Schedule Trigger: ${triggerName}`,
+      handler,
+      metadata: {
+        triggerName,
+        type: "schedule-trigger",
+        scheduleConfig
+      },
+      enabled: triggerStatus === "active"
+    };
+    if (scheduleConfig.cron) {
+      jobConfig.cron = scheduleConfig.cron;
+      jobConfig.timezone = scheduleConfig.timezone || "UTC";
+    } else if (scheduleConfig.interval) {
+      jobConfig.interval = scheduleConfig.interval * 1e3;
+    }
+    await scheduler.schedule(jobConfig);
+    logger.info("Scheduled trigger", {
+      trigger: triggerName,
+      cron: scheduleConfig.cron,
+      interval: scheduleConfig.interval,
+      timezone: scheduleConfig.timezone
+    });
+  } catch (error) {
+    logger.error("Failed to schedule trigger", {
+      trigger: triggerName,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+export async function unscheduleTrigger(triggerName) {
+  const logger = useNventLogger("trigger-wiring");
+  const scheduler = useScheduler();
+  try {
+    const jobId = `trigger:${triggerName}`;
+    const removed = await scheduler.unschedule(jobId);
+    if (removed) {
+      logger.info("Unscheduled trigger", { trigger: triggerName });
+    }
+  } catch (error) {
+    logger.error("Failed to unschedule trigger", {
+      trigger: triggerName,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}