@stepflowjs/trigger-postgres 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { Trigger, TriggerHandler } from '@stepflowjs/core';
+
+interface PostgresChangeTriggerConfig {
+    /** PostgreSQL connection string */
+    connectionString: string;
+    /** LISTEN/NOTIFY channel name */
+    channel: string;
+    /** Optional table to watch for changes */
+    table?: string;
+    /** Operations to watch (if table is specified) */
+    operations?: ("INSERT" | "UPDATE" | "DELETE")[];
+}
+interface PostgresChangePayload {
+    operation?: "INSERT" | "UPDATE" | "DELETE";
+    table?: string;
+    old?: Record<string, unknown>;
+    new?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * PostgreSQL LISTEN/NOTIFY trigger for Stepflow workflows
+ *
+ * Listens to PostgreSQL NOTIFY events on a specified channel. Optionally creates
+ * database triggers to automatically notify on table changes (INSERT, UPDATE, DELETE).
+ *
+ * @example
+ * ```typescript
+ * const trigger = new PostgresChangeTrigger({
+ *   connectionString: process.env.DATABASE_URL,
+ *   channel: 'order_changes',
+ *   table: 'orders',
+ *   operations: ['INSERT', 'UPDATE'],
+ * });
+ *
+ * await trigger.start(async (event) => {
+ *   await stepflow.trigger('process-order', event.data);
+ * });
+ * ```
+ */
+declare class PostgresChangeTrigger implements Trigger<PostgresChangeTriggerConfig> {
+    readonly config: PostgresChangeTriggerConfig;
+    readonly type = "postgres-change";
+    private client?;
+    private pool;
+    private handler?;
+    constructor(config: PostgresChangeTriggerConfig);
+    /**
+     * Start the trigger with a handler function
+     * @param handler Function to call when PostgreSQL notifications are received
+     */
+    start(handler: TriggerHandler): Promise<void>;
+    /**
+     * Set up database trigger function and trigger on the specified table
+     * @private
+     */
+    private setupTableTrigger;
+    /**
+     * Stop the trigger and clean up resources
+     */
+    stop(): Promise<void>;
+    /**
+     * Health check - verifies database connection
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+export { type PostgresChangePayload, PostgresChangeTrigger, type PostgresChangeTriggerConfig };

package/dist/index.js

@@ -0,0 +1,166 @@
+// src/index.ts
+import pg from "pg";
+var { Pool } = pg;
+var PostgresChangeTrigger = class {
+  constructor(config) {
+    this.config = config;
+    this.pool = new Pool({ connectionString: config.connectionString });
+  }
+  type = "postgres-change";
+  client;
+  pool;
+  handler;
+  /**
+   * Start the trigger with a handler function
+   * @param handler Function to call when PostgreSQL notifications are received
+   */
+  async start(handler) {
+    this.handler = handler;
+    this.client = await this.pool.connect();
+    if (this.config.table) {
+      await this.setupTableTrigger();
+    }
+    await this.client.query(`LISTEN ${this.config.channel}`);
+    this.client.on("notification", async (msg) => {
+      if (msg.channel === this.config.channel && this.handler) {
+        try {
+          let payload = {};
+          if (msg.payload) {
+            try {
+              payload = JSON.parse(msg.payload);
+            } catch {
+              payload = { message: msg.payload };
+            }
+          }
+          const event = {
+            id: crypto.randomUUID(),
+            type: this.type,
+            source: this.config.channel,
+            data: payload,
+            metadata: {
+              channel: msg.channel,
+              table: this.config.table,
+              operation: payload.operation
+            },
+            timestamp: /* @__PURE__ */ new Date()
+          };
+          await this.handler(event);
+        } catch (error) {
+          console.error("Error handling PostgreSQL notification:", error);
+        }
+      }
+    });
+    this.client.on("error", (error) => {
+      console.error("PostgreSQL client error:", error);
+    });
+  }
+  /**
+   * Set up database trigger function and trigger on the specified table
+   * @private
+   */
+  async setupTableTrigger() {
+    if (!this.client || !this.config.table) {
+      return;
+    }
+    const {
+      table,
+      channel,
+      operations = ["INSERT", "UPDATE", "DELETE"]
+    } = this.config;
+    const functionName = `${table}_notify_${channel}`;
+    const triggerName = `${table}_trigger_${channel}`;
+    try {
+      await this.client.query(`
+        CREATE OR REPLACE FUNCTION ${functionName}()
+        RETURNS trigger AS $$
+        DECLARE
+          payload json;
+        BEGIN
+          -- Build JSON payload with operation and row data
+          IF (TG_OP = 'DELETE') THEN
+            payload = json_build_object(
+              'operation', TG_OP,
+              'table', TG_TABLE_NAME,
+              'old', row_to_json(OLD)
+            );
+          ELSIF (TG_OP = 'UPDATE') THEN
+            payload = json_build_object(
+              'operation', TG_OP,
+              'table', TG_TABLE_NAME,
+              'old', row_to_json(OLD),
+              'new', row_to_json(NEW)
+            );
+          ELSIF (TG_OP = 'INSERT') THEN
+            payload = json_build_object(
+              'operation', TG_OP,
+              'table', TG_TABLE_NAME,
+              'new', row_to_json(NEW)
+            );
+          END IF;
+
+          -- Send notification
+          PERFORM pg_notify('${channel}', payload::text);
+
+          -- Return appropriate row
+          IF (TG_OP = 'DELETE') THEN
+            RETURN OLD;
+          ELSE
+            RETURN NEW;
+          END IF;
+        END;
+        $$ LANGUAGE plpgsql;
+      `);
+      await this.client.query(`
+        DROP TRIGGER IF EXISTS ${triggerName} ON ${table};
+      `);
+      const triggerOps = operations.join(" OR ");
+      await this.client.query(`
+        CREATE TRIGGER ${triggerName}
+        AFTER ${triggerOps} ON ${table}
+        FOR EACH ROW
+        EXECUTE FUNCTION ${functionName}();
+      `);
+    } catch (error) {
+      console.error("Error setting up table trigger:", error);
+      throw new Error(
+        `Failed to set up trigger on table "${table}": ${error.message}`
+      );
+    }
+  }
+  /**
+   * Stop the trigger and clean up resources
+   */
+  async stop() {
+    if (this.client) {
+      try {
+        await this.client.query(`UNLISTEN ${this.config.channel}`);
+      } catch (error) {
+        console.error("Error during UNLISTEN:", error);
+      } finally {
+        this.client.release();
+        this.client = void 0;
+      }
+    }
+    try {
+      await this.pool.end();
+    } catch (error) {
+      console.error("Error closing pool:", error);
+    }
+    this.handler = void 0;
+  }
+  /**
+   * Health check - verifies database connection
+   */
+  async healthCheck() {
+    try {
+      await this.pool.query("SELECT 1");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+export {
+  PostgresChangeTrigger
+};
+//# 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 pg from \"pg\";\n\nconst { Pool } = pg;\ntype PoolClient = pg.PoolClient;\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface PostgresChangeTriggerConfig {\n  /** PostgreSQL connection string */\n  connectionString: string;\n  /** LISTEN/NOTIFY channel name */\n  channel: string;\n  /** Optional table to watch for changes */\n  table?: string;\n  /** Operations to watch (if table is specified) */\n  operations?: (\"INSERT\" | \"UPDATE\" | \"DELETE\")[];\n}\n\nexport interface PostgresChangePayload {\n  operation?: \"INSERT\" | \"UPDATE\" | \"DELETE\";\n  table?: string;\n  old?: Record<string, unknown>;\n  new?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n// ============================================================================\n// PostgresChangeTrigger Implementation\n// ============================================================================\n\n/**\n * PostgreSQL LISTEN/NOTIFY trigger for Stepflow workflows\n *\n * Listens to PostgreSQL NOTIFY events on a specified channel. Optionally creates\n * database triggers to automatically notify on table changes (INSERT, UPDATE, DELETE).\n *\n * @example\n * ```typescript\n * const trigger = new PostgresChangeTrigger({\n *   connectionString: process.env.DATABASE_URL,\n *   channel: 'order_changes',\n *   table: 'orders',\n *   operations: ['INSERT', 'UPDATE'],\n * });\n *\n * await trigger.start(async (event) => {\n *   await stepflow.trigger('process-order', event.data);\n * });\n * ```\n */\nexport class PostgresChangeTrigger implements Trigger<PostgresChangeTriggerConfig> {\n  readonly type = \"postgres-change\";\n  private client?: PoolClient;\n  private pool: pg.Pool;\n  private handler?: TriggerHandler;\n\n  constructor(readonly config: PostgresChangeTriggerConfig) {\n    this.pool = new Pool({ connectionString: config.connectionString });\n  }\n\n  /**\n   * Start the trigger with a handler function\n   * @param handler Function to call when PostgreSQL notifications are received\n   */\n  async start(handler: TriggerHandler): Promise<void> {\n    this.handler = handler;\n\n    // Connect a dedicated client for LISTEN\n    this.client = await this.pool.connect();\n\n    // Set up table trigger if table is specified\n    if (this.config.table) {\n      await this.setupTableTrigger();\n    }\n\n    // Start listening on the channel\n    await this.client.query(`LISTEN ${this.config.channel}`);\n\n    // Handle notifications\n    this.client.on(\"notification\", async (msg) => {\n      if (msg.channel === this.config.channel && this.handler) {\n        try {\n          // Parse payload (may be JSON or plain text)\n          let payload: PostgresChangePayload = {};\n          if (msg.payload) {\n            try {\n              payload = JSON.parse(msg.payload);\n            } catch {\n              // If not JSON, treat as plain text\n              payload = { message: msg.payload };\n            }\n          }\n\n          // Create trigger event\n          const event: TriggerEvent = {\n            id: crypto.randomUUID(),\n            type: this.type,\n            source: this.config.channel,\n            data: payload,\n            metadata: {\n              channel: msg.channel,\n              table: this.config.table,\n              operation: payload.operation,\n            },\n            timestamp: new Date(),\n          };\n\n          await this.handler(event);\n        } catch (error) {\n          console.error(\"Error handling PostgreSQL notification:\", error);\n        }\n      }\n    });\n\n    // Handle connection errors\n    this.client.on(\"error\", (error) => {\n      console.error(\"PostgreSQL client error:\", error);\n    });\n  }\n\n  /**\n   * Set up database trigger function and trigger on the specified table\n   * @private\n   */\n  private async setupTableTrigger(): Promise<void> {\n    if (!this.client || !this.config.table) {\n      return;\n    }\n\n    const {\n      table,\n      channel,\n      operations = [\"INSERT\", \"UPDATE\", \"DELETE\"],\n    } = this.config;\n    const functionName = `${table}_notify_${channel}`;\n    const triggerName = `${table}_trigger_${channel}`;\n\n    try {\n      // Create or replace the trigger function\n      await this.client.query(`\n        CREATE OR REPLACE FUNCTION ${functionName}()\n        RETURNS trigger AS $$\n        DECLARE\n          payload json;\n        BEGIN\n          -- Build JSON payload with operation and row data\n          IF (TG_OP = 'DELETE') THEN\n            payload = json_build_object(\n              'operation', TG_OP,\n              'table', TG_TABLE_NAME,\n              'old', row_to_json(OLD)\n            );\n          ELSIF (TG_OP = 'UPDATE') THEN\n            payload = json_build_object(\n              'operation', TG_OP,\n              'table', TG_TABLE_NAME,\n              'old', row_to_json(OLD),\n              'new', row_to_json(NEW)\n            );\n          ELSIF (TG_OP = 'INSERT') THEN\n            payload = json_build_object(\n              'operation', TG_OP,\n              'table', TG_TABLE_NAME,\n              'new', row_to_json(NEW)\n            );\n          END IF;\n\n          -- Send notification\n          PERFORM pg_notify('${channel}', payload::text);\n\n          -- Return appropriate row\n          IF (TG_OP = 'DELETE') THEN\n            RETURN OLD;\n          ELSE\n            RETURN NEW;\n          END IF;\n        END;\n        $$ LANGUAGE plpgsql;\n      `);\n\n      // Drop existing trigger if it exists\n      await this.client.query(`\n        DROP TRIGGER IF EXISTS ${triggerName} ON ${table};\n      `);\n\n      // Create trigger for specified operations\n      const triggerOps = operations.join(\" OR \");\n      await this.client.query(`\n        CREATE TRIGGER ${triggerName}\n        AFTER ${triggerOps} ON ${table}\n        FOR EACH ROW\n        EXECUTE FUNCTION ${functionName}();\n      `);\n    } catch (error) {\n      console.error(\"Error setting up table trigger:\", error);\n      throw new Error(\n        `Failed to set up trigger on table \"${table}\": ${(error as Error).message}`,\n      );\n    }\n  }\n\n  /**\n   * Stop the trigger and clean up resources\n   */\n  async stop(): Promise<void> {\n    if (this.client) {\n      try {\n        // Stop listening\n        await this.client.query(`UNLISTEN ${this.config.channel}`);\n      } catch (error) {\n        console.error(\"Error during UNLISTEN:\", error);\n      } finally {\n        // Release the client back to the pool\n        this.client.release();\n        this.client = undefined;\n      }\n    }\n\n    // Close the pool\n    try {\n      await this.pool.end();\n    } catch (error) {\n      console.error(\"Error closing pool:\", error);\n    }\n\n    this.handler = undefined;\n  }\n\n  /**\n   * Health check - verifies database connection\n   */\n  async healthCheck(): Promise<boolean> {\n    try {\n      await this.pool.query(\"SELECT 1\");\n      return true;\n    } catch {\n      return false;\n    }\n  }\n}\n"],"mappings":";AACA,OAAO,QAAQ;AAEf,IAAM,EAAE,KAAK,IAAI;AAkDV,IAAM,wBAAN,MAA4E;AAAA,EAMjF,YAAqB,QAAqC;AAArC;AACnB,SAAK,OAAO,IAAI,KAAK,EAAE,kBAAkB,OAAO,iBAAiB,CAAC;AAAA,EACpE;AAAA,EAPS,OAAO;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUR,MAAM,MAAM,SAAwC;AAClD,SAAK,UAAU;AAGf,SAAK,SAAS,MAAM,KAAK,KAAK,QAAQ;AAGtC,QAAI,KAAK,OAAO,OAAO;AACrB,YAAM,KAAK,kBAAkB;AAAA,IAC/B;AAGA,UAAM,KAAK,OAAO,MAAM,UAAU,KAAK,OAAO,OAAO,EAAE;AAGvD,SAAK,OAAO,GAAG,gBAAgB,OAAO,QAAQ;AAC5C,UAAI,IAAI,YAAY,KAAK,OAAO,WAAW,KAAK,SAAS;AACvD,YAAI;AAEF,cAAI,UAAiC,CAAC;AACtC,cAAI,IAAI,SAAS;AACf,gBAAI;AACF,wBAAU,KAAK,MAAM,IAAI,OAAO;AAAA,YAClC,QAAQ;AAEN,wBAAU,EAAE,SAAS,IAAI,QAAQ;AAAA,YACnC;AAAA,UACF;AAGA,gBAAM,QAAsB;AAAA,YAC1B,IAAI,OAAO,WAAW;AAAA,YACtB,MAAM,KAAK;AAAA,YACX,QAAQ,KAAK,OAAO;AAAA,YACpB,MAAM;AAAA,YACN,UAAU;AAAA,cACR,SAAS,IAAI;AAAA,cACb,OAAO,KAAK,OAAO;AAAA,cACnB,WAAW,QAAQ;AAAA,YACrB;AAAA,YACA,WAAW,oBAAI,KAAK;AAAA,UACtB;AAEA,gBAAM,KAAK,QAAQ,KAAK;AAAA,QAC1B,SAAS,OAAO;AACd,kBAAQ,MAAM,2CAA2C,KAAK;AAAA,QAChE;AAAA,MACF;AAAA,IACF,CAAC;AAGD,SAAK,OAAO,GAAG,SAAS,CAAC,UAAU;AACjC,cAAQ,MAAM,4BAA4B,KAAK;AAAA,IACjD,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,oBAAmC;AAC/C,QAAI,CAAC,KAAK,UAAU,CAAC,KAAK,OAAO,OAAO;AACtC;AAAA,IACF;AAEA,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA,aAAa,CAAC,UAAU,UAAU,QAAQ;AAAA,IAC5C,IAAI,KAAK;AACT,UAAM,eAAe,GAAG,KAAK,WAAW,OAAO;AAC/C,UAAM,cAAc,GAAG,KAAK,YAAY,OAAO;AAE/C,QAAI;AAEF,YAAM,KAAK,OAAO,MAAM;AAAA,qCACO,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,+BA4BlB,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,OAU/B;AAGD,YAAM,KAAK,OAAO,MAAM;AAAA,iCACG,WAAW,OAAO,KAAK;AAAA,OACjD;AAGD,YAAM,aAAa,WAAW,KAAK,MAAM;AACzC,YAAM,KAAK,OAAO,MAAM;AAAA,yBACL,WAAW;AAAA,gBACpB,UAAU,OAAO,KAAK;AAAA;AAAA,2BAEX,YAAY;AAAA,OAChC;AAAA,IACH,SAAS,OAAO;AACd,cAAQ,MAAM,mCAAmC,KAAK;AACtD,YAAM,IAAI;AAAA,QACR,sCAAsC,KAAK,MAAO,MAAgB,OAAO;AAAA,MAC3E;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAsB;AAC1B,QAAI,KAAK,QAAQ;AACf,UAAI;AAEF,cAAM,KAAK,OAAO,MAAM,YAAY,KAAK,OAAO,OAAO,EAAE;AAAA,MAC3D,SAAS,OAAO;AACd,gBAAQ,MAAM,0BAA0B,KAAK;AAAA,MAC/C,UAAE;AAEA,aAAK,OAAO,QAAQ;AACpB,aAAK,SAAS;AAAA,MAChB;AAAA,IACF;AAGA,QAAI;AACF,YAAM,KAAK,KAAK,IAAI;AAAA,IACtB,SAAS,OAAO;AACd,cAAQ,MAAM,uBAAuB,KAAK;AAAA,IAC5C;AAEA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAgC;AACpC,QAAI;AACF,YAAM,KAAK,KAAK,MAAM,UAAU;AAChC,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@stepflowjs/trigger-postgres",
+  "version": "0.0.1",
+  "description": "PostgreSQL LISTEN/NOTIFY trigger for Stepflow",
+  "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": {
+    "pg": "^8.13.0",
+    "@stepflowjs/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.0",
+    "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/postgres"
+  },
+  "homepage": "https://stepflow-production.up.railway.app",
+  "bugs": {
+    "url": "https://stepflow-production.up.railway.app"
+  },
+  "keywords": [
+    "stepflow",
+    "trigger",
+    "postgres",
+    "postgresql",
+    "listen",
+    "notify",
+    "workflow",
+    "orchestration"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  }
+}