routeflow-api 0.2.0

package/dist/adapters/postgres.cjs

@@ -0,0 +1,271 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/postgres.ts
+var postgres_exports = {};
+__export(postgres_exports, {
+  PostgresAdapter: () => PostgresAdapter
+});
+module.exports = __toCommonJS(postgres_exports);
+
+// src/adapters/postgres/postgres-adapter.ts
+var import_pg = require("pg");
+
+// src/core/errors.ts
+var ReactiveApiError = class extends Error {
+  /** Machine-readable error code (e.g. 'ADAPTER_NOT_CONNECTED', 'INVALID_ROUTE') */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ReactiveApiError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/adapters/postgres/trigger-sql.ts
+function notifyChannel(prefix) {
+  return `${prefix}_changes`;
+}
+function createTriggerFunctionSQL(schema, prefix) {
+  const fnName = `${schema}.${prefix}_notify_changes`;
+  const channel = notifyChannel(prefix);
+  return `
+CREATE OR REPLACE FUNCTION ${fnName}()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  payload TEXT;
+  new_row  JSON;
+  old_row  JSON;
+BEGIN
+  IF (TG_OP = 'DELETE') THEN
+    new_row := NULL;
+    old_row := row_to_json(OLD);
+  ELSIF (TG_OP = 'INSERT') THEN
+    new_row := row_to_json(NEW);
+    old_row := NULL;
+  ELSE
+    new_row := row_to_json(NEW);
+    old_row := row_to_json(OLD);
+  END IF;
+
+  payload := json_build_object(
+    'table',     TG_TABLE_NAME,
+    'operation', TG_OP,
+    'new_row',   new_row,
+    'old_row',   old_row
+  )::text;
+
+  -- Truncate gracefully if payload exceeds pg's 8000-byte NOTIFY limit
+  IF octet_length(payload) > 7900 THEN
+    payload := json_build_object(
+      'table',     TG_TABLE_NAME,
+      'operation', TG_OP,
+      'new_row',   NULL,
+      'old_row',   NULL,
+      '_truncated', true
+    )::text;
+  END IF;
+
+  PERFORM pg_notify('${channel}', payload);
+  RETURN COALESCE(NEW, OLD);
+END;
+$$;
+`.trim();
+}
+function createTableTriggerSQL(schema, prefix, table) {
+  const triggerName = `${prefix}_notify_${table}`;
+  const fnName = `${schema}.${prefix}_notify_changes`;
+  return `
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_trigger
+    WHERE tgname = '${triggerName}'
+      AND tgrelid = '${schema}.${table}'::regclass
+  ) THEN
+    CREATE TRIGGER ${triggerName}
+    AFTER INSERT OR UPDATE OR DELETE ON ${schema}.${table}
+    FOR EACH ROW EXECUTE FUNCTION ${fnName}();
+  END IF;
+END;
+$$;
+`.trim();
+}
+function dropTableTriggerSQL(schema, prefix, table) {
+  const triggerName = `${prefix}_notify_${table}`;
+  return `DROP TRIGGER IF EXISTS ${triggerName} ON ${schema}.${table};`;
+}
+function dropTriggerFunctionSQL(schema, prefix) {
+  return `DROP FUNCTION IF EXISTS ${schema}.${prefix}_notify_changes();`;
+}
+
+// src/adapters/postgres/postgres-adapter.ts
+var PostgresAdapter = class {
+  listenClient = null;
+  schema;
+  prefix;
+  connectionString;
+  /** table → Set<callback> */
+  listeners = /* @__PURE__ */ new Map();
+  /** Tables for which a trigger has already been installed */
+  installedTriggers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.connectionString = options.connectionString;
+    this.schema = options.schema ?? "public";
+    this.prefix = options.triggerPrefix ?? "reactive_api";
+  }
+  // ---------------------------------------------------------------------------
+  // DatabaseAdapter interface
+  // ---------------------------------------------------------------------------
+  /** Connect the LISTEN client and install the shared trigger function. */
+  async connect() {
+    if (this.listenClient) return;
+    const client = new import_pg.Client({ connectionString: this.connectionString });
+    try {
+      await client.connect();
+    } catch (err) {
+      throw new ReactiveApiError(
+        "POSTGRES_CONNECT_FAILED",
+        `Failed to connect to PostgreSQL: ${errorMessage(err)}`
+      );
+    }
+    try {
+      await client.query(createTriggerFunctionSQL(this.schema, this.prefix));
+    } catch (err) {
+      await client.end().catch(() => void 0);
+      throw new ReactiveApiError(
+        "POSTGRES_TRIGGER_FUNCTION_FAILED",
+        `Failed to install trigger function: ${errorMessage(err)}`
+      );
+    }
+    const channel = notifyChannel(this.prefix);
+    await client.query(`LISTEN "${channel}"`);
+    client.on("notification", (msg) => {
+      if (msg.channel !== channel || !msg.payload) return;
+      this.handleNotification(msg.payload);
+    });
+    client.on("error", (err) => {
+      console.error("[RouteFlow/postgres] LISTEN client error:", err.message);
+    });
+    this.listenClient = client;
+  }
+  /** Disconnect the LISTEN client and optionally clean up triggers. */
+  async disconnect() {
+    if (!this.listenClient) return;
+    const client = this.listenClient;
+    this.listenClient = null;
+    for (const table of this.installedTriggers) {
+      await client.query(dropTableTriggerSQL(this.schema, this.prefix, table)).catch(() => void 0);
+    }
+    this.installedTriggers.clear();
+    await client.query(dropTriggerFunctionSQL(this.schema, this.prefix)).catch(() => void 0);
+    await client.end().catch(() => void 0);
+    this.listeners.clear();
+  }
+  /**
+   * Register a callback for changes on `table`.
+   * Installs a PostgreSQL trigger on first registration for this table.
+   *
+   * @returns An unsubscribe function.
+   */
+  onChange(table, callback) {
+    if (!this.listeners.has(table)) {
+      this.listeners.set(table, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(table).add(callback);
+    this.ensureTriggerInstalled(table).catch((err) => {
+      console.error(
+        `[RouteFlow/postgres] Failed to install trigger for table "${table}":`,
+        errorMessage(err)
+      );
+    });
+    return () => {
+      this.listeners.get(table)?.delete(callback);
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  async ensureTriggerInstalled(table) {
+    if (this.installedTriggers.has(table)) return;
+    if (!this.listenClient) return;
+    try {
+      await this.listenClient.query(
+        createTableTriggerSQL(this.schema, this.prefix, table)
+      );
+      this.installedTriggers.add(table);
+    } catch (err) {
+      if (err instanceof import_pg.DatabaseError) {
+        throw new ReactiveApiError(
+          "POSTGRES_TRIGGER_INSTALL_FAILED",
+          `Failed to install trigger on "${table}": ${err.message}`
+        );
+      }
+      throw err;
+    }
+  }
+  handleNotification(rawPayload) {
+    let payload;
+    try {
+      payload = JSON.parse(rawPayload);
+    } catch {
+      console.error("[RouteFlow/postgres] Malformed NOTIFY payload:", rawPayload);
+      return;
+    }
+    if (!isNotifyPayload(payload)) {
+      console.error("[RouteFlow/postgres] Unexpected payload shape:", payload);
+      return;
+    }
+    const event = {
+      table: payload.table,
+      operation: payload.operation,
+      newRow: payload.new_row,
+      oldRow: payload.old_row,
+      timestamp: Date.now()
+    };
+    const callbacks = this.listeners.get(payload.table);
+    if (!callbacks) return;
+    for (const cb of callbacks) {
+      try {
+        cb(event);
+      } catch (err) {
+        console.error(
+          `[RouteFlow/postgres] Listener error on table "${payload.table}":`,
+          errorMessage(err)
+        );
+      }
+    }
+  }
+};
+function isNotifyPayload(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v["table"] === "string" && (v["operation"] === "INSERT" || v["operation"] === "UPDATE" || v["operation"] === "DELETE");
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PostgresAdapter
+});
+//# sourceMappingURL=postgres.cjs.map

package/dist/adapters/postgres.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/postgres.ts","../../src/adapters/postgres/postgres-adapter.ts","../../src/core/errors.ts","../../src/adapters/postgres/trigger-sql.ts"],"sourcesContent":["export { PostgresAdapter } from './postgres/postgres-adapter.js'\nexport type { PostgresAdapterOptions, NotifyPayload } from './postgres/types.js'\n","import { Client, DatabaseError } from 'pg'\nimport type { ChangeEvent, DatabaseAdapter } from '../../core/types.js'\nimport { ReactiveApiError } from '../../core/errors.js'\nimport type { NotifyPayload, PostgresAdapterOptions } from './types.js'\nimport {\n  notifyChannel,\n  createTriggerFunctionSQL,\n  createTableTriggerSQL,\n  dropTableTriggerSQL,\n  dropTriggerFunctionSQL,\n} from './trigger-sql.js'\n\n/**\n * PostgreSQL database adapter for RouteFlow.\n *\n * Uses a dedicated `pg.Client` (not a pool) for LISTEN so the connection\n * stays open and notifications are never missed. A separate pool/client\n * can still be used by the application for regular queries.\n *\n * Change detection mechanism:\n * - On `onChange(table)`: installs a per-table AFTER INSERT/UPDATE/DELETE trigger\n *   that calls `pg_notify` with a JSON payload.\n * - A single LISTEN connection subscribes to one shared channel for all tables.\n * - Payloads > 7900 bytes are sent without row data (`_truncated: true`);\n *   subscribers receive a ChangeEvent with `newRow: null` / `oldRow: null`.\n *\n * @example\n * ```ts\n * const adapter = new PostgresAdapter({\n *   connectionString: process.env.DATABASE_URL,\n * })\n * await adapter.connect()\n * ```\n */\nexport class PostgresAdapter implements DatabaseAdapter {\n  private listenClient: Client | null = null\n  private readonly schema: string\n  private readonly prefix: string\n  private readonly connectionString: string\n\n  /** table → Set<callback> */\n  private readonly listeners: Map<string, Set<(event: ChangeEvent) => void>> = new Map()\n  /** Tables for which a trigger has already been installed */\n  private readonly installedTriggers: Set<string> = new Set()\n\n  constructor(options: PostgresAdapterOptions) {\n    this.connectionString = options.connectionString\n    this.schema = options.schema ?? 'public'\n    this.prefix = options.triggerPrefix ?? 'reactive_api'\n  }\n\n  // ---------------------------------------------------------------------------\n  // DatabaseAdapter interface\n  // ---------------------------------------------------------------------------\n\n  /** Connect the LISTEN client and install the shared trigger function. */\n  async connect(): Promise<void> {\n    if (this.listenClient) return\n\n    const client = new Client({ connectionString: this.connectionString })\n    try {\n      await client.connect()\n    } catch (err) {\n      throw new ReactiveApiError(\n        'POSTGRES_CONNECT_FAILED',\n        `Failed to connect to PostgreSQL: ${errorMessage(err)}`,\n      )\n    }\n\n    // Install (or replace) the shared trigger function once per connection\n    try {\n      await client.query(createTriggerFunctionSQL(this.schema, this.prefix))\n    } catch (err) {\n      await client.end().catch(() => undefined)\n      throw new ReactiveApiError(\n        'POSTGRES_TRIGGER_FUNCTION_FAILED',\n        `Failed to install trigger function: ${errorMessage(err)}`,\n      )\n    }\n\n    // Start listening on the shared channel\n    const channel = notifyChannel(this.prefix)\n    await client.query(`LISTEN \"${channel}\"`)\n\n    client.on('notification', (msg) => {\n      if (msg.channel !== channel || !msg.payload) return\n      this.handleNotification(msg.payload)\n    })\n\n    client.on('error', (err) => {\n      // Log but don't crash — the adapter becomes unavailable; the app can\n      // call disconnect() + connect() to recover.\n      console.error('[RouteFlow/postgres] LISTEN client error:', err.message)\n    })\n\n    this.listenClient = client\n  }\n\n  /** Disconnect the LISTEN client and optionally clean up triggers. */\n  async disconnect(): Promise<void> {\n    if (!this.listenClient) return\n\n    const client = this.listenClient\n    this.listenClient = null\n\n    // Remove all installed table triggers and the shared function\n    for (const table of this.installedTriggers) {\n      await client\n        .query(dropTableTriggerSQL(this.schema, this.prefix, table))\n        .catch(() => undefined)\n    }\n    this.installedTriggers.clear()\n\n    await client\n      .query(dropTriggerFunctionSQL(this.schema, this.prefix))\n      .catch(() => undefined)\n\n    await client.end().catch(() => undefined)\n    this.listeners.clear()\n  }\n\n  /**\n   * Register a callback for changes on `table`.\n   * Installs a PostgreSQL trigger on first registration for this table.\n   *\n   * @returns An unsubscribe function.\n   */\n  onChange(table: string, callback: (event: ChangeEvent) => void): () => void {\n    if (!this.listeners.has(table)) {\n      this.listeners.set(table, new Set())\n    }\n    this.listeners.get(table)!.add(callback)\n\n    // Install trigger asynchronously; errors are surfaced to the console\n    // rather than throwing so registration can happen before connect().\n    this.ensureTriggerInstalled(table).catch((err) => {\n      console.error(\n        `[RouteFlow/postgres] Failed to install trigger for table \"${table}\":`,\n        errorMessage(err),\n      )\n    })\n\n    return () => {\n      this.listeners.get(table)?.delete(callback)\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Private helpers\n  // ---------------------------------------------------------------------------\n\n  private async ensureTriggerInstalled(table: string): Promise<void> {\n    if (this.installedTriggers.has(table)) return\n    if (!this.listenClient) return // will be retried via connect() flow\n\n    try {\n      await this.listenClient.query(\n        createTableTriggerSQL(this.schema, this.prefix, table),\n      )\n      this.installedTriggers.add(table)\n    } catch (err) {\n      if (err instanceof DatabaseError) {\n        throw new ReactiveApiError(\n          'POSTGRES_TRIGGER_INSTALL_FAILED',\n          `Failed to install trigger on \"${table}\": ${err.message}`,\n        )\n      }\n      throw err\n    }\n  }\n\n  private handleNotification(rawPayload: string): void {\n    let payload: unknown\n    try {\n      payload = JSON.parse(rawPayload)\n    } catch {\n      console.error('[RouteFlow/postgres] Malformed NOTIFY payload:', rawPayload)\n      return\n    }\n\n    if (!isNotifyPayload(payload)) {\n      console.error('[RouteFlow/postgres] Unexpected payload shape:', payload)\n      return\n    }\n\n    const event: ChangeEvent = {\n      table: payload.table,\n      operation: payload.operation,\n      newRow: payload.new_row,\n      oldRow: payload.old_row,\n      timestamp: Date.now(),\n    }\n\n    const callbacks = this.listeners.get(payload.table)\n    if (!callbacks) return\n\n    for (const cb of callbacks) {\n      try {\n        cb(event)\n      } catch (err) {\n        console.error(\n          `[RouteFlow/postgres] Listener error on table \"${payload.table}\":`,\n          errorMessage(err),\n        )\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Type guards / utilities\n// ---------------------------------------------------------------------------\n\nfunction isNotifyPayload(value: unknown): value is NotifyPayload {\n  if (typeof value !== 'object' || value === null) return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['table'] === 'string' &&\n    (v['operation'] === 'INSERT' || v['operation'] === 'UPDATE' || v['operation'] === 'DELETE')\n  )\n}\n\nfunction errorMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err)\n}\n","/**\n * Base error class for all RouteFlow errors.\n * Always use this instead of plain `Error` throughout the framework.\n */\nexport class ReactiveApiError extends Error {\n  /** Machine-readable error code (e.g. 'ADAPTER_NOT_CONNECTED', 'INVALID_ROUTE') */\n  readonly code: string\n\n  constructor(code: string, message: string) {\n    super(message)\n    this.name = 'ReactiveApiError'\n    this.code = code\n    // Restore prototype chain (required when extending built-ins in TS)\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n","/**\n * Generates the SQL that installs a per-table NOTIFY trigger.\n *\n * Strategy:\n * - One shared trigger function per (schema, prefix) pair — handles all tables.\n * - One trigger per table that calls that function.\n *\n * Payload sent via NOTIFY (channel = triggerPrefix):\n * ```json\n * { \"table\": \"orders\", \"operation\": \"INSERT\", \"new_row\": {...}, \"old_row\": null }\n * ```\n *\n * IMPORTANT: PostgreSQL NOTIFY payloads are limited to 8000 bytes.\n * For larger rows the payload is truncated and only the primary-key columns\n * are guaranteed to be present. Callers that need the full row should\n * re-query after receiving the event.\n */\n\n/** Channel name used for LISTEN/NOTIFY — one shared channel for all tables. */\nexport function notifyChannel(prefix: string): string {\n  return `${prefix}_changes`\n}\n\n/**\n * SQL to create (or replace) the shared trigger function.\n * The function encodes NEW/OLD as JSON and notifies the channel.\n */\nexport function createTriggerFunctionSQL(schema: string, prefix: string): string {\n  const fnName = `${schema}.${prefix}_notify_changes`\n  const channel = notifyChannel(prefix)\n\n  return `\nCREATE OR REPLACE FUNCTION ${fnName}()\nRETURNS trigger\nLANGUAGE plpgsql\nAS $$\nDECLARE\n  payload TEXT;\n  new_row  JSON;\n  old_row  JSON;\nBEGIN\n  IF (TG_OP = 'DELETE') THEN\n    new_row := NULL;\n    old_row := row_to_json(OLD);\n  ELSIF (TG_OP = 'INSERT') THEN\n    new_row := row_to_json(NEW);\n    old_row := NULL;\n  ELSE\n    new_row := row_to_json(NEW);\n    old_row := row_to_json(OLD);\n  END IF;\n\n  payload := json_build_object(\n    'table',     TG_TABLE_NAME,\n    'operation', TG_OP,\n    'new_row',   new_row,\n    'old_row',   old_row\n  )::text;\n\n  -- Truncate gracefully if payload exceeds pg's 8000-byte NOTIFY limit\n  IF octet_length(payload) > 7900 THEN\n    payload := json_build_object(\n      'table',     TG_TABLE_NAME,\n      'operation', TG_OP,\n      'new_row',   NULL,\n      'old_row',   NULL,\n      '_truncated', true\n    )::text;\n  END IF;\n\n  PERFORM pg_notify('${channel}', payload);\n  RETURN COALESCE(NEW, OLD);\nEND;\n$$;\n`.trim()\n}\n\n/**\n * SQL to attach the trigger to a specific table.\n * Idempotent — uses CREATE OR REPLACE (Postgres 14+).\n * Falls back to DROP + CREATE for older versions.\n */\nexport function createTableTriggerSQL(\n  schema: string,\n  prefix: string,\n  table: string,\n): string {\n  const triggerName = `${prefix}_notify_${table}`\n  const fnName = `${schema}.${prefix}_notify_changes`\n\n  return `\nDO $$\nBEGIN\n  IF NOT EXISTS (\n    SELECT 1 FROM pg_trigger\n    WHERE tgname = '${triggerName}'\n      AND tgrelid = '${schema}.${table}'::regclass\n  ) THEN\n    CREATE TRIGGER ${triggerName}\n    AFTER INSERT OR UPDATE OR DELETE ON ${schema}.${table}\n    FOR EACH ROW EXECUTE FUNCTION ${fnName}();\n  END IF;\nEND;\n$$;\n`.trim()\n}\n\n/**\n * SQL to drop the trigger from a table (used on disconnect/cleanup).\n */\nexport function dropTableTriggerSQL(\n  schema: string,\n  prefix: string,\n  table: string,\n): string {\n  const triggerName = `${prefix}_notify_${table}`\n  return `DROP TRIGGER IF EXISTS ${triggerName} ON ${schema}.${table};`\n}\n\n/**\n * SQL to drop the shared trigger function (used on full adapter teardown).\n */\nexport function dropTriggerFunctionSQL(schema: string, prefix: string): string {\n  return `DROP FUNCTION IF EXISTS ${schema}.${prefix}_notify_changes();`\n}\n"],"mappings":"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","names":[]}

package/dist/adapters/postgres.d.cts

@@ -0,0 +1,81 @@
+import { D as DatabaseAdapter, C as ChangeEvent } from '../types-tPDla8AE.cjs';
+
+/**
+ * Configuration options for PostgresAdapter.
+ */
+interface PostgresAdapterOptions {
+    /**
+     * PostgreSQL connection string.
+     * e.g. 'postgresql://user:password@localhost:5432/dbname'
+     */
+    connectionString: string;
+    /**
+     * Schema to install trigger functions in.
+     * Defaults to 'public'.
+     */
+    schema?: string;
+    /**
+     * Name prefix for generated trigger functions and triggers.
+     * Defaults to 'reactive_api'.
+     */
+    triggerPrefix?: string;
+}
+/**
+ * The raw JSON payload delivered by the PostgreSQL NOTIFY.
+ * Must stay in sync with the trigger function SQL in trigger-sql.ts.
+ */
+interface NotifyPayload {
+    table: string;
+    operation: 'INSERT' | 'UPDATE' | 'DELETE';
+    new_row: Record<string, unknown> | null;
+    old_row: Record<string, unknown> | null;
+}
+
+/**
+ * PostgreSQL database adapter for RouteFlow.
+ *
+ * Uses a dedicated `pg.Client` (not a pool) for LISTEN so the connection
+ * stays open and notifications are never missed. A separate pool/client
+ * can still be used by the application for regular queries.
+ *
+ * Change detection mechanism:
+ * - On `onChange(table)`: installs a per-table AFTER INSERT/UPDATE/DELETE trigger
+ *   that calls `pg_notify` with a JSON payload.
+ * - A single LISTEN connection subscribes to one shared channel for all tables.
+ * - Payloads > 7900 bytes are sent without row data (`_truncated: true`);
+ *   subscribers receive a ChangeEvent with `newRow: null` / `oldRow: null`.
+ *
+ * @example
+ * ```ts
+ * const adapter = new PostgresAdapter({
+ *   connectionString: process.env.DATABASE_URL,
+ * })
+ * await adapter.connect()
+ * ```
+ */
+declare class PostgresAdapter implements DatabaseAdapter {
+    private listenClient;
+    private readonly schema;
+    private readonly prefix;
+    private readonly connectionString;
+    /** table → Set<callback> */
+    private readonly listeners;
+    /** Tables for which a trigger has already been installed */
+    private readonly installedTriggers;
+    constructor(options: PostgresAdapterOptions);
+    /** Connect the LISTEN client and install the shared trigger function. */
+    connect(): Promise<void>;
+    /** Disconnect the LISTEN client and optionally clean up triggers. */
+    disconnect(): Promise<void>;
+    /**
+     * Register a callback for changes on `table`.
+     * Installs a PostgreSQL trigger on first registration for this table.
+     *
+     * @returns An unsubscribe function.
+     */
+    onChange(table: string, callback: (event: ChangeEvent) => void): () => void;
+    private ensureTriggerInstalled;
+    private handleNotification;
+}
+
+export { type NotifyPayload, PostgresAdapter, type PostgresAdapterOptions };

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,81 @@
+import { D as DatabaseAdapter, C as ChangeEvent } from '../types-tPDla8AE.js';
+
+/**
+ * Configuration options for PostgresAdapter.
+ */
+interface PostgresAdapterOptions {
+    /**
+     * PostgreSQL connection string.
+     * e.g. 'postgresql://user:password@localhost:5432/dbname'
+     */
+    connectionString: string;
+    /**
+     * Schema to install trigger functions in.
+     * Defaults to 'public'.
+     */
+    schema?: string;
+    /**
+     * Name prefix for generated trigger functions and triggers.
+     * Defaults to 'reactive_api'.
+     */
+    triggerPrefix?: string;
+}
+/**
+ * The raw JSON payload delivered by the PostgreSQL NOTIFY.
+ * Must stay in sync with the trigger function SQL in trigger-sql.ts.
+ */
+interface NotifyPayload {
+    table: string;
+    operation: 'INSERT' | 'UPDATE' | 'DELETE';
+    new_row: Record<string, unknown> | null;
+    old_row: Record<string, unknown> | null;
+}
+
+/**
+ * PostgreSQL database adapter for RouteFlow.
+ *
+ * Uses a dedicated `pg.Client` (not a pool) for LISTEN so the connection
+ * stays open and notifications are never missed. A separate pool/client
+ * can still be used by the application for regular queries.
+ *
+ * Change detection mechanism:
+ * - On `onChange(table)`: installs a per-table AFTER INSERT/UPDATE/DELETE trigger
+ *   that calls `pg_notify` with a JSON payload.
+ * - A single LISTEN connection subscribes to one shared channel for all tables.
+ * - Payloads > 7900 bytes are sent without row data (`_truncated: true`);
+ *   subscribers receive a ChangeEvent with `newRow: null` / `oldRow: null`.
+ *
+ * @example
+ * ```ts
+ * const adapter = new PostgresAdapter({
+ *   connectionString: process.env.DATABASE_URL,
+ * })
+ * await adapter.connect()
+ * ```
+ */
+declare class PostgresAdapter implements DatabaseAdapter {
+    private listenClient;
+    private readonly schema;
+    private readonly prefix;
+    private readonly connectionString;
+    /** table → Set<callback> */
+    private readonly listeners;
+    /** Tables for which a trigger has already been installed */
+    private readonly installedTriggers;
+    constructor(options: PostgresAdapterOptions);
+    /** Connect the LISTEN client and install the shared trigger function. */
+    connect(): Promise<void>;
+    /** Disconnect the LISTEN client and optionally clean up triggers. */
+    disconnect(): Promise<void>;
+    /**
+     * Register a callback for changes on `table`.
+     * Installs a PostgreSQL trigger on first registration for this table.
+     *
+     * @returns An unsubscribe function.
+     */
+    onChange(table: string, callback: (event: ChangeEvent) => void): () => void;
+    private ensureTriggerInstalled;
+    private handleNotification;
+}
+
+export { type NotifyPayload, PostgresAdapter, type PostgresAdapterOptions };