@stepflowjs/trigger-nats 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { Trigger, TriggerHandler } from '@stepflowjs/core';
+
+interface NatsTriggerConfig {
+    /** NATS server URLs */
+    servers: string[];
+    /** Subject to subscribe to */
+    subject: string;
+    /** Queue group name for load balancing (optional) */
+    queue?: string;
+    /** Durable consumer name (optional) */
+    durableName?: string;
+    /** Message delivery policy (optional) */
+    deliverPolicy?: "all" | "last" | "new";
+    /** Authentication credentials (optional) */
+    credentials?: {
+        user?: string;
+        pass?: string;
+        token?: string;
+        nkey?: string;
+    };
+}
+interface NatsTriggerResponse {
+    success: boolean;
+    error?: string;
+}
+/**
+ * NATS trigger for Stepflow workflows
+ *
+ * Allows workflows to be triggered via NATS messages with support for queue groups,
+ * durable consumers, and various delivery policies.
+ *
+ * @example
+ * ```typescript
+ * const trigger = new NatsTrigger({
+ *   servers: ['nats://localhost:4222'],
+ *   subject: 'orders.created',
+ *   queue: 'order-processors',
+ *   deliverPolicy: 'new',
+ * });
+ *
+ * await trigger.start(async (event) => {
+ *   await stepflow.trigger('process-order', event.data);
+ * });
+ * ```
+ */
+declare class NatsTrigger implements Trigger<NatsTriggerConfig> {
+    readonly config: NatsTriggerConfig;
+    readonly type = "nats";
+    private connection?;
+    private subscription?;
+    private handler?;
+    private processingLoop?;
+    constructor(config: NatsTriggerConfig);
+    /**
+     * Start the trigger with a handler function
+     * @param handler Function to call when NATS messages are received
+     */
+    start(handler: TriggerHandler): Promise<void>;
+    /**
+     * Stop the trigger
+     */
+    stop(): Promise<void>;
+    /**
+     * Health check - returns true if connected to NATS
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Process incoming NATS messages
+     * @private
+     */
+    private processMessages;
+    /**
+     * Handle a single NATS message
+     * @private
+     */
+    private handleMessage;
+}
+
+export { NatsTrigger, type NatsTriggerConfig, type NatsTriggerResponse };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/index.ts
+import {
+  connect
+} from "nats";
+var NatsTrigger = class {
+  constructor(config) {
+    this.config = config;
+  }
+  type = "nats";
+  connection;
+  subscription;
+  handler;
+  processingLoop;
+  /**
+   * Start the trigger with a handler function
+   * @param handler Function to call when NATS messages are received
+   */
+  async start(handler) {
+    this.handler = handler;
+    const connectionOptions = {
+      servers: this.config.servers
+    };
+    if (this.config.credentials) {
+      if (this.config.credentials.user && this.config.credentials.pass) {
+        connectionOptions.user = this.config.credentials.user;
+        connectionOptions.pass = this.config.credentials.pass;
+      } else if (this.config.credentials.token) {
+        connectionOptions.token = this.config.credentials.token;
+      }
+    }
+    try {
+      this.connection = await connect(connectionOptions);
+    } catch (error) {
+      throw new Error(`Failed to connect to NATS: ${error.message}`);
+    }
+    try {
+      this.subscription = this.connection.subscribe(this.config.subject, {
+        queue: this.config.queue
+      });
+    } catch (error) {
+      await this.connection.close();
+      throw new Error(
+        `Failed to subscribe to subject "${this.config.subject}": ${error.message}`
+      );
+    }
+    this.processingLoop = this.processMessages();
+  }
+  /**
+   * Stop the trigger
+   */
+  async stop() {
+    this.handler = void 0;
+    if (this.subscription) {
+      try {
+        this.subscription.unsubscribe();
+      } catch (error) {
+        console.error("Error unsubscribing:", error);
+      }
+      this.subscription = void 0;
+    }
+    if (this.processingLoop) {
+      try {
+        await this.processingLoop;
+      } catch (error) {
+      }
+      this.processingLoop = void 0;
+    }
+    if (this.connection) {
+      try {
+        await this.connection.close();
+      } catch (error) {
+        console.error("Error closing NATS connection:", error);
+      }
+      this.connection = void 0;
+    }
+  }
+  /**
+   * Health check - returns true if connected to NATS
+   */
+  async healthCheck() {
+    return this.connection?.isClosed() === false;
+  }
+  /**
+   * Process incoming NATS messages
+   * @private
+   */
+  async processMessages() {
+    if (!this.subscription || !this.handler) {
+      return;
+    }
+    try {
+      for await (const msg of this.subscription) {
+        if (!this.handler) {
+          break;
+        }
+        await this.handleMessage(msg);
+      }
+    } catch (error) {
+      if (this.handler !== void 0) {
+        console.error("Error processing NATS messages:", error);
+      }
+    }
+  }
+  /**
+   * Handle a single NATS message
+   * @private
+   */
+  async handleMessage(msg) {
+    if (!this.handler) {
+      return;
+    }
+    try {
+      let data;
+      try {
+        const text = new TextDecoder().decode(msg.data);
+        data = JSON.parse(text);
+      } catch (error) {
+        data = new TextDecoder().decode(msg.data);
+      }
+      const headers = {};
+      if (msg.headers) {
+        for (const [key, values] of msg.headers) {
+          headers[key] = values.join(", ");
+        }
+      }
+      const event = {
+        id: crypto.randomUUID(),
+        type: this.type,
+        source: msg.subject,
+        data,
+        metadata: {
+          subject: msg.subject,
+          reply: msg.reply,
+          headers,
+          sid: msg.sid
+        },
+        timestamp: /* @__PURE__ */ new Date()
+      };
+      await this.handler(event);
+      if (msg.reply) {
+        const response = {
+          success: true
+        };
+        msg.respond(new TextEncoder().encode(JSON.stringify(response)));
+      }
+    } catch (error) {
+      if (msg.reply) {
+        const response = {
+          success: false,
+          error: error.message
+        };
+        try {
+          msg.respond(new TextEncoder().encode(JSON.stringify(response)));
+        } catch (respondError) {
+          console.error("Error sending NATS response:", respondError);
+        }
+      }
+      throw error;
+    }
+  }
+};
+export {
+  NatsTrigger
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Trigger, TriggerHandler, TriggerEvent } from \"@stepflowjs/core\";\nimport {\n  connect,\n  type NatsConnection,\n  type Subscription,\n  type Msg,\n  type ConnectionOptions,\n} from \"nats\";\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface NatsTriggerConfig {\n  /** NATS server URLs */\n  servers: string[];\n  /** Subject to subscribe to */\n  subject: string;\n  /** Queue group name for load balancing (optional) */\n  queue?: string;\n  /** Durable consumer name (optional) */\n  durableName?: string;\n  /** Message delivery policy (optional) */\n  deliverPolicy?: \"all\" | \"last\" | \"new\";\n  /** Authentication credentials (optional) */\n  credentials?: {\n    user?: string;\n    pass?: string;\n    token?: string;\n    nkey?: string;\n  };\n}\n\nexport interface NatsTriggerResponse {\n  success: boolean;\n  error?: string;\n}\n\n// ============================================================================\n// NatsTrigger Implementation\n// ============================================================================\n\n/**\n * NATS trigger for Stepflow workflows\n *\n * Allows workflows to be triggered via NATS messages with support for queue groups,\n * durable consumers, and various delivery policies.\n *\n * @example\n * ```typescript\n * const trigger = new NatsTrigger({\n *   servers: ['nats://localhost:4222'],\n *   subject: 'orders.created',\n *   queue: 'order-processors',\n *   deliverPolicy: 'new',\n * });\n *\n * await trigger.start(async (event) => {\n *   await stepflow.trigger('process-order', event.data);\n * });\n * ```\n */\nexport class NatsTrigger implements Trigger<NatsTriggerConfig> {\n  readonly type = \"nats\";\n  private connection?: NatsConnection;\n  private subscription?: Subscription;\n  private handler?: TriggerHandler;\n  private processingLoop?: Promise<void>;\n\n  constructor(readonly config: NatsTriggerConfig) {}\n\n  /**\n   * Start the trigger with a handler function\n   * @param handler Function to call when NATS messages are received\n   */\n  async start(handler: TriggerHandler): Promise<void> {\n    this.handler = handler;\n\n    // Build connection options\n    const connectionOptions: ConnectionOptions = {\n      servers: this.config.servers,\n    };\n\n    // Add credentials if provided\n    if (this.config.credentials) {\n      if (this.config.credentials.user && this.config.credentials.pass) {\n        connectionOptions.user = this.config.credentials.user;\n        connectionOptions.pass = this.config.credentials.pass;\n      } else if (this.config.credentials.token) {\n        connectionOptions.token = this.config.credentials.token;\n      }\n      // Note: nkey authentication would require additional setup\n    }\n\n    // Connect to NATS\n    try {\n      this.connection = await connect(connectionOptions);\n    } catch (error) {\n      throw new Error(`Failed to connect to NATS: ${(error as Error).message}`);\n    }\n\n    // Subscribe to subject\n    try {\n      this.subscription = this.connection.subscribe(this.config.subject, {\n        queue: this.config.queue,\n      });\n    } catch (error) {\n      await this.connection.close();\n      throw new Error(\n        `Failed to subscribe to subject \"${this.config.subject}\": ${(error as Error).message}`,\n      );\n    }\n\n    // Start processing messages\n    this.processingLoop = this.processMessages();\n  }\n\n  /**\n   * Stop the trigger\n   */\n  async stop(): Promise<void> {\n    this.handler = undefined;\n\n    // Unsubscribe\n    if (this.subscription) {\n      try {\n        this.subscription.unsubscribe();\n      } catch (error) {\n        console.error(\"Error unsubscribing:\", error);\n      }\n      this.subscription = undefined;\n    }\n\n    // Wait for processing loop to finish\n    if (this.processingLoop) {\n      try {\n        await this.processingLoop;\n      } catch (error) {\n        // Ignore errors during shutdown\n      }\n      this.processingLoop = undefined;\n    }\n\n    // Close connection\n    if (this.connection) {\n      try {\n        await this.connection.close();\n      } catch (error) {\n        console.error(\"Error closing NATS connection:\", error);\n      }\n      this.connection = undefined;\n    }\n  }\n\n  /**\n   * Health check - returns true if connected to NATS\n   */\n  async healthCheck(): Promise<boolean> {\n    return this.connection?.isClosed() === false;\n  }\n\n  /**\n   * Process incoming NATS messages\n   * @private\n   */\n  private async processMessages(): Promise<void> {\n    if (!this.subscription || !this.handler) {\n      return;\n    }\n\n    try {\n      for await (const msg of this.subscription) {\n        // Skip if handler was removed (during shutdown)\n        if (!this.handler) {\n          break;\n        }\n\n        await this.handleMessage(msg);\n      }\n    } catch (error) {\n      // Only log if not during shutdown\n      if (this.handler !== undefined) {\n        console.error(\"Error processing NATS messages:\", error);\n      }\n    }\n  }\n\n  /**\n   * Handle a single NATS message\n   * @private\n   */\n  private async handleMessage(msg: Msg): Promise<void> {\n    if (!this.handler) {\n      return;\n    }\n\n    try {\n      // Parse message data\n      let data: unknown;\n      try {\n        const text = new TextDecoder().decode(msg.data);\n        data = JSON.parse(text);\n      } catch (error) {\n        // If JSON parsing fails, use raw text\n        data = new TextDecoder().decode(msg.data);\n      }\n\n      // Extract headers if present\n      const headers: Record<string, string> = {};\n      if (msg.headers) {\n        for (const [key, values] of msg.headers) {\n          headers[key] = values.join(\", \");\n        }\n      }\n\n      // Create trigger event\n      const event: TriggerEvent = {\n        id: crypto.randomUUID(),\n        type: this.type,\n        source: msg.subject,\n        data,\n        metadata: {\n          subject: msg.subject,\n          reply: msg.reply,\n          headers,\n          sid: msg.sid,\n        },\n        timestamp: new Date(),\n      };\n\n      // Invoke handler\n      await this.handler(event);\n\n      // Send success response if reply subject is set\n      if (msg.reply) {\n        const response: NatsTriggerResponse = {\n          success: true,\n        };\n        msg.respond(new TextEncoder().encode(JSON.stringify(response)));\n      }\n    } catch (error) {\n      // Send error response if reply subject is set\n      if (msg.reply) {\n        const response: NatsTriggerResponse = {\n          success: false,\n          error: (error as Error).message,\n        };\n        try {\n          msg.respond(new TextEncoder().encode(JSON.stringify(response)));\n        } catch (respondError) {\n          console.error(\"Error sending NATS response:\", respondError);\n        }\n      }\n\n      // Re-throw to allow error handling upstream\n      throw error;\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@stepflowjs/trigger-nats",
+  "version": "0.0.1",
+  "description": "NATS trigger for Stepflow with queue groups and JetStream support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "nats": "^2.29.0",
+    "@stepflowjs/core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "author": "Stepflow Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://stepflow-production.up.railway.app",
+    "directory": "packages/triggers/nats"
+  },
+  "homepage": "https://stepflow-production.up.railway.app",
+  "bugs": {
+    "url": "https://stepflow-production.up.railway.app"
+  },
+  "keywords": [
+    "stepflow",
+    "trigger",
+    "nats",
+    "jetstream",
+    "workflow",
+    "orchestration"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  }
+}