nvent 0.4.4 → 0.4.5

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

@@ -0,0 +1,233 @@
+/**
+ * Store Adapter Interface
+ *
+ * Three-tier storage system:
+ * 1. Event Stream - Append-only event log (replaces EventStore)
+ * 2. Document Store - Generic document storage (for flow wiring, triggers, metadata)
+ * 3. Key-Value Store - Fast lookups (for state, caching)
+ */
+export interface StoreAdapter {
+    /**
+     * Close/cleanup the adapter
+     */
+    close(): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Save a document to a collection
+     * @param collection - Collection name (e.g., 'flow-wiring', 'triggers', 'flow-metadata')
+     * @param id - Document ID
+     * @param doc - Document data
+     */
+    save(collection: string, id: string, doc: Record<string, any>): Promise<void>;
+    /**
+     * Get a document from a collection
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @returns Document or null if not found
+     */
+    get(collection: string, id: string): Promise<Record<string, any> | null>;
+    /**
+     * List documents in a collection (optional, not all adapters may support complex queries)
+     * @param collection - Collection name
+     * @param opts - Query options (filtering, pagination, sorting)
+     * @returns Array of documents with their IDs
+     */
+    list?(collection: string, opts?: ListOptions): Promise<Array<{
+        id: string;
+        doc: any;
+    }>>;
+    /**
+     * Delete a document from a collection
+     * @param collection - Collection name
+     * @param id - Document ID
+     */
+    delete(collection: string, id: string): Promise<void>;
+    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>;
+    };
+    /**
+     * Add entry to a sorted index (optional, for efficient time-ordered listings)
+     * @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
+     */
+    indexAdd?(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
+     */
+    indexGet?(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
+     */
+    indexRead?(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
+     */
+    indexUpdate?(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)
+     */
+    indexUpdateWithRetry?(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
+     */
+    indexIncrement?(key: string, id: string, field: string, increment?: number): Promise<number>;
+}
+/**
+ * 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;

package/dist/runtime/adapters/registry.js

@@ -0,0 +1,161 @@
+export class AdapterRegistry {
+  queueAdapters = /* @__PURE__ */ new Map();
+  streamAdapters = /* @__PURE__ */ new Map();
+  storeAdapters = /* @__PURE__ */ new Map();
+  // ============================================================
+  // Registration
+  // ============================================================
+  /**
+   * Register a queue adapter
+   * @param name - Adapter name (e.g., 'redis', 'memory', 'postgres')
+   * @param adapter - QueueAdapter implementation
+   */
+  registerQueue(name, adapter) {
+    if (this.queueAdapters.has(name)) {
+      console.warn(`[nvent] Queue adapter "${name}" is already registered, overwriting`);
+    }
+    this.queueAdapters.set(name, adapter);
+  }
+  /**
+   * Register a stream adapter
+   * @param name - Adapter name (e.g., 'redis', 'memory', 'rabbitmq')
+   * @param adapter - StreamAdapter implementation
+   */
+  registerStream(name, adapter) {
+    if (this.streamAdapters.has(name)) {
+      console.warn(`[nvent] Stream adapter "${name}" is already registered, overwriting`);
+    }
+    this.streamAdapters.set(name, adapter);
+  }
+  /**
+   * Register a store adapter
+   * @param name - Adapter name (e.g., 'redis', 'memory', 'postgres')
+   * @param adapter - StoreAdapter implementation
+   */
+  registerStore(name, adapter) {
+    if (this.storeAdapters.has(name)) {
+      console.warn(`[nvent] Store adapter "${name}" is already registered, overwriting`);
+    }
+    this.storeAdapters.set(name, adapter);
+  }
+  // ============================================================
+  // Retrieval
+  // ============================================================
+  /**
+   * Get a queue adapter by name
+   * @throws Error if adapter not found
+   */
+  getQueue(name) {
+    const adapter = this.queueAdapters.get(name);
+    if (!adapter) {
+      throw new Error(
+        `[nvent] Queue adapter "${name}" not found. Available: ${Array.from(this.queueAdapters.keys()).join(", ")}`
+      );
+    }
+    return adapter;
+  }
+  /**
+   * Get a stream adapter by name
+   * @throws Error if adapter not found
+   */
+  getStream(name) {
+    const adapter = this.streamAdapters.get(name);
+    if (!adapter) {
+      throw new Error(
+        `[nvent] Stream adapter "${name}" not found. Available: ${Array.from(this.streamAdapters.keys()).join(", ")}`
+      );
+    }
+    return adapter;
+  }
+  /**
+   * Get a store adapter by name
+   * @throws Error if adapter not found
+   */
+  getStore(name) {
+    const adapter = this.storeAdapters.get(name);
+    if (!adapter) {
+      throw new Error(
+        `[nvent] Store adapter "${name}" not found. Available: ${Array.from(this.storeAdapters.keys()).join(", ")}`
+      );
+    }
+    return adapter;
+  }
+  // ============================================================
+  // Utilities
+  // ============================================================
+  /**
+   * Check if a queue adapter is registered
+   */
+  hasQueue(name) {
+    return this.queueAdapters.has(name);
+  }
+  /**
+   * Check if a stream adapter is registered
+   */
+  hasStream(name) {
+    return this.streamAdapters.has(name);
+  }
+  /**
+   * Check if a store adapter is registered
+   */
+  hasStore(name) {
+    return this.storeAdapters.has(name);
+  }
+  /**
+   * List all registered queue adapters
+   */
+  listQueueAdapters() {
+    return Array.from(this.queueAdapters.keys());
+  }
+  /**
+   * List all registered stream adapters
+   */
+  listStreamAdapters() {
+    return Array.from(this.streamAdapters.keys());
+  }
+  /**
+   * List all registered store adapters
+   */
+  listStoreAdapters() {
+    return Array.from(this.storeAdapters.keys());
+  }
+  /**
+   * Initialize all registered adapters
+   */
+  async initAll() {
+    const promises = [];
+    Array.from(this.queueAdapters.values()).forEach((adapter) => {
+      promises.push(adapter.init());
+    });
+    Array.from(this.streamAdapters.values()).forEach((adapter) => {
+      promises.push(adapter.init());
+    });
+    await Promise.all(promises);
+  }
+  /**
+   * Close/cleanup all registered adapters
+   */
+  async closeAll() {
+    const promises = [];
+    Array.from(this.queueAdapters.values()).forEach((adapter) => {
+      promises.push(adapter.close());
+    });
+    Array.from(this.streamAdapters.values()).forEach((adapter) => {
+      promises.push(adapter.shutdown());
+    });
+    Array.from(this.storeAdapters.values()).forEach((adapter) => {
+      promises.push(adapter.close());
+    });
+    await Promise.all(promises);
+  }
+}
+let registry = null;
+export function useAdapterRegistry() {
+  if (!registry) {
+    registry = new AdapterRegistry();
+  }
+  return registry;
+}
+export function resetAdapterRegistry() {
+  registry = null;
+}

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

@@ -0,0 +1,29 @@
+import type { ModuleOptions, ModuleConfig } from './types.js';
+/**
+ * Merge and normalize module options with defaults (v0.4.1).
+ * Applies connection fallback: adapter-specific connections override connections.redis/postgres.
+ * Only includes connection defaults for adapters that are actually used.
+ */
+export declare function normalizeModuleOptions(options: ModuleOptions): Required<ModuleOptions>;
+/**
+ * Convert normalized module options to runtime config format (v0.4.1).
+ */
+export declare function toRuntimeConfig(normalizedOptions: Required<ModuleOptions>): ModuleConfig;
+/**
+ * Get Redis connection config for nitro storage.
+ * Uses shared connections.redis as primary source.
+ */
+export declare function getRedisStorageConfig(normalizedOptions: Required<ModuleOptions>): {
+    host: string;
+    port: number;
+    username?: undefined;
+    password?: undefined;
+    db?: undefined;
+} | {
+    host: string | undefined;
+    port: number | undefined;
+    username: string | undefined;
+    password: string | undefined;
+    db: number | undefined;
+};
+export type { ModuleOptions, ModuleConfig } from './types.js';