nvent 0.4.4 → 0.5.0

package/dist/runtime/adapters/interfaces/queue.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Queue Adapter Interface
+ *
+ * Handles job queue operations only (enqueue, retrieve, manage)
+ * Does NOT handle event storage, state, or logging - those are separate concerns
+ */
+export interface QueueAdapter {
+    /**
+     * Initialize the queue adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Add a job to the queue
+     * @returns Job ID
+     */
+    enqueue(queueName: string, job: JobInput): Promise<string>;
+    /**
+     * Schedule a job (delayed or recurring)
+     * @returns Job ID
+     */
+    schedule(queueName: string, job: JobInput, opts?: ScheduleOptions): Promise<string>;
+    /**
+     * Get a specific job by ID
+     */
+    getJob(queueName: string, id: string): Promise<Job | null>;
+    /**
+     * Get multiple jobs with optional filtering
+     */
+    getJobs(queueName: string, query?: JobsQuery): Promise<Job[]>;
+    /**
+     * Subscribe to queue events
+     * @returns Unsubscribe function
+     */
+    on(queueName: string, event: QueueEvent, callback: (payload: any) => void): () => void;
+    /**
+     * Check if queue is paused
+     */
+    isPaused(queueName: string): Promise<boolean>;
+    /**
+     * Get job counts by state
+     */
+    getJobCounts(queueName: string): Promise<JobCounts>;
+    /**
+     * Get scheduled/repeatable jobs (cron jobs)
+     */
+    getScheduledJobs?(queueName: string): Promise<ScheduledJobInfo[]>;
+    /**
+     * Remove a scheduled/repeatable job
+     * @returns true if removed, false if not found
+     */
+    removeScheduledJob?(scheduleId: string): Promise<boolean>;
+    /**
+     * Pause the queue
+     */
+    pause(queueName: string): Promise<void>;
+    /**
+     * Resume the queue
+     */
+    resume(queueName: string): Promise<void>;
+    /**
+     * Register a worker handler for processing jobs
+     * This is called by the worker registration system
+     */
+    registerWorker(queueName: string, jobName: string, handler: WorkerHandler, opts?: WorkerOptions): void;
+    /**
+     * Start processing waiting jobs for a queue
+     * Should be called after all handlers are registered
+     */
+    startProcessingQueue?(queueName: string): void;
+    /**
+     * Close/cleanup the adapter
+     */
+    close(): Promise<void>;
+}
+export interface JobInput {
+    name: string;
+    data: any;
+    opts?: JobOptions;
+}
+export interface JobOptions {
+    jobId?: string;
+    attempts?: number;
+    backoff?: {
+        type: 'exponential' | 'fixed';
+        delay: number;
+    };
+    delay?: number;
+    priority?: number;
+    timeout?: number;
+    removeOnComplete?: boolean | number;
+    removeOnFail?: boolean | number;
+}
+export interface Job {
+    id: string;
+    name: string;
+    data: any;
+    returnvalue?: any;
+    failedReason?: string;
+    state: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+    timestamp?: number;
+    processedOn?: number;
+    finishedOn?: number;
+    attemptsMade?: number;
+    progress?: number;
+}
+export interface JobsQuery {
+    state?: JobState[];
+    limit?: number;
+    offset?: number;
+}
+export type JobState = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+export interface ScheduleOptions {
+    delay?: number;
+    cron?: string;
+    repeat?: {
+        pattern?: string;
+        limit?: number;
+    };
+}
+export interface JobCounts {
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+    waiting: number;
+    paused: number;
+}
+export interface ScheduledJobInfo {
+    id: string;
+    jobName: string;
+    queueName: string;
+    cron?: string;
+    pattern?: string;
+    nextRun?: Date;
+    repeatCount?: number;
+    limit?: number;
+}
+export type QueueEvent = 'waiting' | 'active' | 'progress' | 'completed' | 'failed' | 'delayed' | 'paused' | 'stalled';
+export interface WorkerHandler {
+    (payload: any, ctx: WorkerContext): Promise<any>;
+}
+export interface WorkerContext {
+    jobId: string;
+    queueName: string;
+    [key: string]: any;
+}
+export interface WorkerOptions {
+    concurrency?: number;
+    autorun?: boolean;
+}

package/dist/runtime/adapters/interfaces/store.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Store Adapter Interface
+ *
+ * Three-tier storage system:
+ * 1. Event Stream - Append-only event log
+ * 2. Sorted Index - Time-ordered metadata storage
+ * 3. Key-Value Store - Fast lookups (for state, caching)
+ *
+ * ## Critical Implementation Requirements
+ *
+ * ### 1. Index Operations - add() vs update()
+ *
+ * **index.add()** - MUST completely REPLACE metadata when entry exists:
+ * ```typescript
+ * // First call
+ * await index.add('flows', 'my-flow', 123, { name: 'Flow', stats: {...} })
+ * // Second call - REPLACES entire metadata
+ * await index.add('flows', 'my-flow', 456, { lastRunAt: 789 })
+ * // Result: { lastRunAt: 789 } ← stats are LOST!
+ * ```
+ *
+ * **index.update()** - MUST perform DEEP MERGE of metadata:
+ * ```typescript
+ * // Initial state: { status: 'running', emittedEvents: { test: { completed: 1 } } }
+ * await index.update('runs', 'run-id', { emittedEvents: { another: { fired: 2 } } })
+ * // Result: { status: 'running', emittedEvents: { test: { completed: 1 }, another: { fired: 2 } } }
+ * ```
+ *
+ * ⚠️ **CRITICAL**: update() must perform DEEP merge at ALL nesting levels, not just top-level!
+ * - PostgreSQL `||` operator: Only shallow merge (top-level keys)
+ * - Redis HSET loop: Field-level merge (simulates deep merge for flat structures)
+ * - Memory defu(): True deep merge
+ *
+ * ### 2. Nested Metadata Structure
+ *
+ * Flow orchestration stores deeply nested metadata:
+ * ```typescript
+ * {
+ *   emittedEvents: {
+ *     'step1': {
+ *       'completed': 1234567890,
+ *       'custom_event': 1234567891
+ *     },
+ *     'step2': {
+ *       'completed': 1234567892
+ *     }
+ *   },
+ *   awaitingSteps: {
+ *     'step_name': {
+ *       status: 'awaiting',
+ *       position: 'after',
+ *       awaitType: 'event'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Multiple updates add to nested structures incrementally. If deep merge fails,
+ * flow orchestration will miss events and steps won't trigger.
+ *
+ * ### 3. Concurrent Updates
+ *
+ * Flow steps run in parallel and update metadata concurrently:
+ * - Multiple steps emit events simultaneously
+ * - Each emits triggers index.updateWithRetry() with partial metadata
+ * - Updates must NOT overwrite each other
+ * - Use optimistic locking (version field) + retries
+ *
+ * ### 4. Testing Deep Merge
+ *
+ * Test that your adapter correctly handles:
+ * ```typescript
+ * // Setup
+ * await index.add('test', 'id', 1, { a: { b: 1 }, c: 2 })
+ *
+ * // Update nested property
+ * await index.update('test', 'id', { a: { d: 3 } })
+ * const result = await index.get('test', 'id')
+ *
+ * // MUST preserve existing nested data
+ * expect(result.metadata).toEqual({ a: { b: 1, d: 3 }, c: 2 })
+ * // NOT: { a: { d: 3 }, c: 2 } ← b is lost!
+ * ```
+ *
+ */
+export interface StoreAdapter {
+    /**
+     * Close/cleanup the adapter
+     */
+    close(): Promise<void>;
+    stream: {
+        /**
+         * Append an event to a subject's event stream
+         * @param subject - Event stream identifier (e.g., 'nq:flow:abc-123')
+         * @param event - Event to append (id and ts will be auto-generated)
+         * @returns The complete event record with generated id and timestamp
+         */
+        append(subject: string, event: Omit<EventRecord, 'id' | 'ts'>): Promise<EventRecord>;
+        /**
+         * Read events from a subject's event stream
+         * @param subject - Event stream identifier
+         * @param opts - Query options (filtering, pagination, etc.)
+         * @returns Array of event records
+         */
+        read(subject: string, opts?: EventReadOptions): Promise<EventRecord[]>;
+        /**
+         * Subscribe to new events in a subject's event stream (optional, not all adapters support this)
+         * @param subject - Event stream identifier (supports wildcards if adapter allows)
+         * @param onEvent - Callback for new events
+         * @returns Subscription handle for unsubscribing
+         */
+        subscribe?(subject: string, onEvent: (event: EventRecord) => void): Promise<EventSubscription>;
+        /**
+         * Delete an entire event stream
+         * @param subject - Event stream identifier
+         * @returns True if stream was deleted, false if not found
+         */
+        delete?(subject: string): Promise<boolean>;
+    };
+    kv: {
+        /**
+         * Get a value by key
+         */
+        get<T = any>(key: string): Promise<T | null>;
+        /**
+         * Set a value with optional TTL
+         * @param key - Key
+         * @param value - Value to store
+         * @param ttl - Time to live in seconds (optional)
+         */
+        set<T = any>(key: string, value: T, ttl?: number): Promise<void>;
+        /**
+         * Delete a key
+         */
+        delete(key: string): Promise<void>;
+        /**
+         * Delete all keys matching a pattern (optional, not all adapters support patterns)
+         * @returns Number of keys deleted
+         */
+        clear?(pattern: string): Promise<number>;
+        /**
+         * Atomic increment operation (optional, for counters)
+         * @returns New value after increment
+         */
+        increment?(key: string, by?: number): Promise<number>;
+    };
+    index: {
+        /**
+         * Add entry to a sorted index
+         * @param key - Index key (e.g., 'nq:flows:flowName')
+         * @param id - Entry ID
+         * @param score - Sort score (typically timestamp)
+         * @param metadata - Optional metadata to store with entry
+         */
+        add(key: string, id: string, score: number, metadata?: Record<string, any>): Promise<void>;
+        /**
+         * Get a single entry from a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @returns Entry with score and metadata, or null if not found
+         */
+        get(key: string, id: string): Promise<{
+            id: string;
+            score: number;
+            metadata?: any;
+        } | null>;
+        /**
+         * Read entries from a sorted index (ordered by score descending)
+         * @param key - Index key
+         * @param opts - Pagination options
+         * @param opts.offset - Number of entries to skip
+         * @param opts.limit - Maximum number of entries to return
+         * @returns Array of entries with scores and metadata
+         */
+        read(key: string, opts?: {
+            offset?: number;
+            limit?: number;
+        }): Promise<Array<{
+            id: string;
+            score: number;
+            metadata?: any;
+        }>>;
+        /**
+         * Update metadata for an entry in a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param metadata - Metadata to update
+         * @returns True if update succeeded, false if version conflict
+         */
+        update(key: string, id: string, metadata: Record<string, any>): Promise<boolean>;
+        /**
+         * Update with automatic retries on version conflicts
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param metadata - Metadata to update
+         * @param maxRetries - Maximum retry attempts (default: 3)
+         */
+        updateWithRetry(key: string, id: string, metadata: Record<string, any>, maxRetries?: number): Promise<void>;
+        /**
+         * Atomic increment of a metadata field in an index entry
+         * @param key - Index key
+         * @param id - Entry ID
+         * @param field - Field name to increment
+         * @param increment - Amount to increment by (default: 1)
+         * @returns New value after increment
+         */
+        increment(key: string, id: string, field: string, increment?: number): Promise<number>;
+        /**
+         * Delete an entry from a sorted index
+         * @param key - Index key
+         * @param id - Entry ID
+         * @returns True if entry was deleted, false if not found
+         */
+        delete(key: string, id: string): Promise<boolean>;
+    };
+}
+/**
+ * Event record in the event stream
+ * This is the storage representation - converts FlowEvent to/from storage format
+ */
+export interface EventRecord {
+    id: string;
+    ts: number;
+    type: string;
+    runId: string;
+    flowName: string;
+    stepName?: string;
+    stepId?: string;
+    attempt?: number;
+    data?: any;
+}
+/**
+ * Options for reading events from the event stream
+ */
+export interface EventReadOptions {
+    /**
+     * Filter by event types
+     */
+    types?: string[];
+    /**
+     * Read events after this ID
+     */
+    after?: string;
+    /**
+     * Read events before this ID
+     */
+    before?: string;
+    /**
+     * Read events from this timestamp
+     */
+    from?: number;
+    /**
+     * Read events until this timestamp
+     */
+    to?: number;
+    /**
+     * Maximum number of events to return
+     */
+    limit?: number;
+    /**
+     * Sort order ('asc' or 'desc')
+     */
+    order?: 'asc' | 'desc';
+}
+/**
+ * Subscription handle for event stream subscriptions
+ */
+export interface EventSubscription {
+    id: string;
+    subject: string;
+    unsubscribe: () => Promise<void>;
+}
+/**
+ * Options for listing documents
+ */
+export interface ListOptions {
+    /**
+     * Filter documents by field values
+     */
+    filter?: Record<string, any>;
+    /**
+     * Maximum number of documents to return
+     */
+    limit?: number;
+    /**
+     * Number of documents to skip
+     */
+    offset?: number;
+    /**
+     * Sort by field
+     */
+    sortBy?: string;
+    /**
+     * Sort order
+     */
+    order?: 'asc' | 'desc';
+}

package/dist/runtime/adapters/interfaces/stream.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Stream Adapter Interface
+ *
+ * Handles pub/sub messaging for cross-instance communication
+ * Replaces the pub/sub functionality from EventStoreAdapter.subscribe()
+ */
+export interface StreamAdapter {
+    /**
+     * Initialize the stream adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Publish an event to a topic
+     */
+    publish(topic: string, event: StreamEvent): Promise<void>;
+    /**
+     * Subscribe to a topic
+     * @returns Subscription handle for unsubscribing
+     */
+    subscribe(topic: string, handler: (event: StreamEvent) => void | Promise<void>, opts?: SubscribeOptions): Promise<SubscriptionHandle>;
+    /**
+     * Unsubscribe from a topic
+     */
+    unsubscribe(handle: SubscriptionHandle): Promise<void>;
+    /**
+     * List all active topics
+     */
+    listTopics(): Promise<string[]>;
+    /**
+     * Get number of subscribers for a topic
+     */
+    getSubscriptionCount(topic: string): Promise<number>;
+    /**
+     * Shutdown the adapter and cleanup resources
+     */
+    shutdown(): Promise<void>;
+}
+export interface StreamEvent {
+    type: string;
+    data: any;
+    metadata?: Record<string, any>;
+    timestamp?: number;
+}
+export interface SubscribeOptions {
+    /**
+     * Consumer group for load balancing (if supported)
+     */
+    group?: string;
+    /**
+     * Filter events by type pattern
+     */
+    filter?: string | RegExp;
+    /**
+     * Starting position (if supported by adapter)
+     */
+    fromBeginning?: boolean;
+}
+export interface SubscriptionHandle {
+    id: string;
+    topic: string;
+    unsubscribe: () => Promise<void>;
+}

package/dist/runtime/adapters/registry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Adapter Registry
+ *
+ * Central registry for all adapter types (queue, stream, store)
+ * Adapters are registered via the nvent:registerAdapter Nuxt hook
+ */
+import type { QueueAdapter, StreamAdapter, StoreAdapter } from './interfaces/index.js';
+export declare class AdapterRegistry {
+    private queueAdapters;
+    private streamAdapters;
+    private storeAdapters;
+    /**
+     * Register a queue adapter
+     * @param name - Adapter name (e.g., 'redis', 'memory', 'postgres')
+     * @param adapter - QueueAdapter implementation
+     */
+    registerQueue(name: string, adapter: QueueAdapter): void;
+    /**
+     * Register a stream adapter
+     * @param name - Adapter name (e.g., 'redis', 'memory', 'rabbitmq')
+     * @param adapter - StreamAdapter implementation
+     */
+    registerStream(name: string, adapter: StreamAdapter): void;
+    /**
+     * Register a store adapter
+     * @param name - Adapter name (e.g., 'redis', 'memory', 'postgres')
+     * @param adapter - StoreAdapter implementation
+     */
+    registerStore(name: string, adapter: StoreAdapter): void;
+    /**
+     * Get a queue adapter by name
+     * @throws Error if adapter not found
+     */
+    getQueue(name: string): QueueAdapter;
+    /**
+     * Get a stream adapter by name
+     * @throws Error if adapter not found
+     */
+    getStream(name: string): StreamAdapter;
+    /**
+     * Get a store adapter by name
+     * @throws Error if adapter not found
+     */
+    getStore(name: string): StoreAdapter;
+    /**
+     * Check if a queue adapter is registered
+     */
+    hasQueue(name: string): boolean;
+    /**
+     * Check if a stream adapter is registered
+     */
+    hasStream(name: string): boolean;
+    /**
+     * Check if a store adapter is registered
+     */
+    hasStore(name: string): boolean;
+    /**
+     * List all registered queue adapters
+     */
+    listQueueAdapters(): string[];
+    /**
+     * List all registered stream adapters
+     */
+    listStreamAdapters(): string[];
+    /**
+     * List all registered store adapters
+     */
+    listStoreAdapters(): string[];
+    /**
+     * Initialize all registered adapters
+     */
+    initAll(): Promise<void>;
+    /**
+     * Close/cleanup all registered adapters
+     */
+    closeAll(): Promise<void>;
+}
+/**
+ * Get the global adapter registry instance
+ */
+export declare function useAdapterRegistry(): AdapterRegistry;
+/**
+ * Reset the registry (useful for testing)
+ */
+export declare function resetAdapterRegistry(): void;