routeflow-api 0.2.0

package/dist/index.cjs

@@ -0,0 +1,935 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  MemoryAdapter: () => MemoryAdapter,
+  PollingAdapter: () => PollingAdapter,
+  Reactive: () => Reactive,
+  ReactiveApiError: () => ReactiveApiError,
+  ReactiveApp: () => ReactiveApp,
+  Route: () => Route,
+  SUPPORTED_DATABASES: () => SUPPORTED_DATABASES,
+  createApp: () => createApp,
+  getDatabaseSupport: () => getDatabaseSupport,
+  listOfficialDatabases: () => listOfficialDatabases,
+  listSupportedDatabases: () => listSupportedDatabases
+});
+module.exports = __toCommonJS(src_exports);
+var import_reflect_metadata = require("reflect-metadata");
+var import_fastify = __toESM(require("fastify"), 1);
+
+// src/core/decorator/route.ts
+var ROUTE_METADATA = /* @__PURE__ */ Symbol("reactive-api:route");
+function Route(method, path) {
+  return function(target, propertyKey) {
+    const metadata = { method, path };
+    Reflect.defineMetadata(ROUTE_METADATA, metadata, target, propertyKey);
+  };
+}
+
+// src/core/decorator/reactive.ts
+var REACTIVE_METADATA = /* @__PURE__ */ Symbol("reactive-api:reactive");
+function Reactive(options) {
+  return function(target, propertyKey) {
+    Reflect.defineMetadata(REACTIVE_METADATA, options, target, propertyKey);
+  };
+}
+
+// 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/core/reactive/engine.ts
+var ReactiveEngine = class {
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  adapter;
+  endpoints = [];
+  /** clientId → Subscription */
+  subscriptions = /* @__PURE__ */ new Map();
+  /** table → adapter unsubscribe fn */
+  tableWatchers = /* @__PURE__ */ new Map();
+  /** "clientId:path" → debounce timer id */
+  debounceTimers = /* @__PURE__ */ new Map();
+  /**
+   * Register a reactive endpoint so the engine can fan-out pushes to subscribers.
+   */
+  registerEndpoint(endpoint) {
+    this.endpoints.push(endpoint);
+    const tables = Array.isArray(endpoint.options.watch) ? endpoint.options.watch : [endpoint.options.watch];
+    for (const table of tables) {
+      this.setupTableWatcher(table);
+    }
+  }
+  /**
+   * Subscribe a WebSocket client to a path.
+   * When the watched table(s) change and the filter passes, pushFn is called.
+   *
+   * @param clientId - Unique identifier for the client connection
+   * @param path     - The concrete path the client subscribed to
+   * @param ctx      - Context built from the subscribed path
+   * @param pushFn   - Callback to deliver data to the client
+   */
+  subscribe(clientId, path, ctx, pushFn) {
+    this.subscriptions.set(clientId, { path, ctx, pushFn });
+  }
+  /**
+   * Remove a client's subscription and clean up any pending debounce timers.
+   */
+  unsubscribe(clientId) {
+    this.subscriptions.delete(clientId);
+    for (const key of this.debounceTimers.keys()) {
+      if (key.startsWith(`${clientId}:`)) {
+        clearTimeout(this.debounceTimers.get(key));
+        this.debounceTimers.delete(key);
+      }
+    }
+  }
+  /**
+   * Tear down all table watchers. Call this when the app shuts down.
+   */
+  destroy() {
+    for (const unsubscribe of this.tableWatchers.values()) {
+      unsubscribe();
+    }
+    this.tableWatchers.clear();
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  setupTableWatcher(table) {
+    if (this.tableWatchers.has(table)) return;
+    const unsubscribe = this.adapter.onChange(table, (event) => {
+      this.onChangeEvent(event);
+    });
+    this.tableWatchers.set(table, unsubscribe);
+  }
+  onChangeEvent(event) {
+    const matchingEndpoints = this.endpoints.filter((ep) => {
+      const tables = Array.isArray(ep.options.watch) ? ep.options.watch : [ep.options.watch];
+      return tables.includes(event.table);
+    });
+    for (const endpoint of matchingEndpoints) {
+      for (const [clientId, sub] of this.subscriptions) {
+        if (!pathMatchesPattern(sub.path, endpoint.routePath)) continue;
+        if (endpoint.options.filter) {
+          try {
+            if (!endpoint.options.filter(event, sub.ctx)) continue;
+          } catch (err) {
+            continue;
+          }
+        }
+        this.schedulePush(clientId, endpoint, sub, event);
+      }
+    }
+  }
+  schedulePush(clientId, endpoint, sub, _event) {
+    const debounceMs = endpoint.options.debounce;
+    if (debounceMs !== void 0 && debounceMs > 0) {
+      const timerKey = `${clientId}:${sub.path}`;
+      const existing = this.debounceTimers.get(timerKey);
+      if (existing !== void 0) clearTimeout(existing);
+      const timer = setTimeout(() => {
+        this.debounceTimers.delete(timerKey);
+        this.executePush(endpoint, sub);
+      }, debounceMs);
+      this.debounceTimers.set(timerKey, timer);
+    } else {
+      this.executePush(endpoint, sub);
+    }
+  }
+  executePush(endpoint, sub) {
+    endpoint.handler(sub.ctx).then(
+      (data) => sub.pushFn(sub.path, data),
+      (err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ReactiveApiError("HANDLER_ERROR", `Reactive handler failed: ${message}`);
+      }
+    );
+  }
+};
+function pathMatchesPattern(concretePath, pattern) {
+  const regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "([^/]+)");
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(concretePath);
+}
+function extractParams(concretePath, pattern) {
+  const paramNames = [];
+  const regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+  const regex = new RegExp(`^${regexStr}$`);
+  const match = concretePath.match(regex);
+  if (!match) return {};
+  return Object.fromEntries(paramNames.map((name, i) => [name, match[i + 1]]));
+}
+
+// src/core/transport/websocket-transport.ts
+var import_node_crypto = require("crypto");
+var import_ws = require("ws");
+function isSubscribeMessage(value) {
+  return typeof value === "object" && value !== null && value["type"] === "subscribe" && typeof value["path"] === "string";
+}
+var WebSocketTransport = class {
+  constructor(engine, routePatterns) {
+    this.engine = engine;
+    this.routePatterns = routePatterns;
+    this.wss = new import_ws.WebSocketServer({ noServer: true });
+    this.wss.on("connection", (ws, req) => this.handleConnection(ws, req));
+  }
+  engine;
+  routePatterns;
+  wss;
+  /** Maps clientId → registered route pattern, for param extraction */
+  clientPatterns = /* @__PURE__ */ new Map();
+  /**
+   * Attach to the raw Node.js HTTP server so WebSocket upgrade requests are
+   * handled alongside Fastify routes.
+   */
+  attach(httpServer) {
+    httpServer.on("upgrade", (req, socket, head) => {
+      this.wss.handleUpgrade(req, socket, head, (ws) => {
+        this.wss.emit("connection", ws, req);
+      });
+    });
+  }
+  /** Gracefully close all connections. */
+  async close() {
+    return new Promise((resolve, reject) => {
+      this.wss.close((err) => err ? reject(err) : resolve());
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Connection handling
+  // ---------------------------------------------------------------------------
+  handleConnection(ws, _req) {
+    const clientId = (0, import_node_crypto.randomUUID)();
+    ws.on("message", (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw.toString());
+      } catch {
+        this.sendError(ws, "INVALID_JSON", "Message must be valid JSON");
+        return;
+      }
+      if (!isSubscribeMessage(parsed)) {
+        this.sendError(ws, "INVALID_MESSAGE", 'Expected { type: "subscribe", path: string }');
+        return;
+      }
+      this.handleSubscribe(ws, clientId, parsed);
+    });
+    ws.on("close", () => {
+      this.engine.unsubscribe(clientId);
+      this.clientPatterns.delete(clientId);
+    });
+    ws.on("error", (err) => {
+      this.engine.unsubscribe(clientId);
+      this.clientPatterns.delete(clientId);
+      if (process.env["NODE_ENV"] !== "production") {
+        console.error("[RouteFlow] WebSocket error:", err.message);
+      }
+    });
+  }
+  handleSubscribe(ws, clientId, msg) {
+    const { path, query = {} } = msg;
+    const pattern = this.routePatterns.find((p) => this.matchesPattern(path, p));
+    if (!pattern) {
+      this.sendError(ws, "NO_REACTIVE_ENDPOINT", `No reactive endpoint found for path: ${path}`);
+      return;
+    }
+    const params = extractParams(path, pattern);
+    const ctx = {
+      params,
+      query,
+      body: void 0,
+      headers: {}
+    };
+    const pushFn = (subscribedPath, data) => {
+      if (ws.readyState !== import_ws.WebSocket.OPEN) return;
+      const msg2 = { type: "update", path: subscribedPath, data };
+      ws.send(JSON.stringify(msg2));
+    };
+    this.engine.unsubscribe(clientId);
+    this.clientPatterns.set(clientId, pattern);
+    this.engine.subscribe(clientId, path, ctx, pushFn);
+  }
+  matchesPattern(concretePath, pattern) {
+    const regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "([^/]+)");
+    return new RegExp(`^${regexStr}$`).test(concretePath);
+  }
+  sendError(ws, code, message) {
+    if (ws.readyState !== import_ws.WebSocket.OPEN) return;
+    const msg = { type: "error", code, message };
+    ws.send(JSON.stringify(msg));
+  }
+};
+
+// src/core/transport/sse-transport.ts
+var import_node_crypto2 = require("crypto");
+var SseTransport = class {
+  constructor(engine, routePatterns) {
+    this.engine = engine;
+    this.routePatterns = routePatterns;
+  }
+  engine;
+  routePatterns;
+  /** clientId → reply (kept open) */
+  connections = /* @__PURE__ */ new Map();
+  /**
+   * Register the SSE subscription endpoint on the Fastify instance.
+   * Must be called before `fastify.listen()`.
+   */
+  register(fastify) {
+    fastify.get("/_sse/subscribe", async (req, reply) => {
+      const query = req.query;
+      const path = query["path"];
+      if (!path) {
+        throw new ReactiveApiError("SSE_MISSING_PATH", 'Query param "path" is required');
+      }
+      const decodedPath = decodeURIComponent(path);
+      const pattern = this.routePatterns.find((p) => this.matchesPattern(decodedPath, p));
+      if (!pattern) {
+        reply.code(404);
+        throw new ReactiveApiError(
+          "SSE_NO_REACTIVE_ENDPOINT",
+          `No reactive endpoint found for path: ${decodedPath}`
+        );
+      }
+      const params = extractParams(decodedPath, pattern);
+      const clientQuery = { ...query };
+      delete clientQuery["path"];
+      const ctx = {
+        params,
+        query: clientQuery,
+        body: void 0,
+        headers: req.headers
+      };
+      const clientId = (0, import_node_crypto2.randomUUID)();
+      reply.raw.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no"
+        // disable nginx buffering
+      });
+      reply.raw.write(": connected\n\n");
+      this.connections.set(clientId, reply);
+      const pushFn = (subscribedPath, data) => {
+        if (reply.raw.destroyed) return;
+        const payload = JSON.stringify({ type: "update", path: subscribedPath, data });
+        reply.raw.write(`data: ${payload}
+
+`);
+      };
+      this.engine.subscribe(clientId, decodedPath, ctx, pushFn);
+      req.raw.on("close", () => {
+        this.engine.unsubscribe(clientId);
+        this.connections.delete(clientId);
+        if (!reply.raw.destroyed) reply.raw.end();
+      });
+      await new Promise((resolve) => {
+        req.raw.on("close", resolve);
+        req.raw.on("error", resolve);
+      });
+    });
+  }
+  /** Close all open SSE connections. */
+  async close() {
+    for (const reply of this.connections.values()) {
+      if (!reply.raw.destroyed) reply.raw.end();
+    }
+    this.connections.clear();
+  }
+  matchesPattern(concretePath, pattern) {
+    const regexStr = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "([^/]+)");
+    return new RegExp(`^${regexStr}$`).test(concretePath);
+  }
+};
+
+// src/core/database-support.ts
+var SUPPORTED_DATABASES = [
+  {
+    key: "postgresql",
+    name: "PostgreSQL",
+    aliases: ["postgres", "psql"],
+    categories: ["rdbms"],
+    supportedModes: ["native-adapter", "polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "mysql",
+    name: "MySQL",
+    aliases: [],
+    categories: ["rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "mariadb",
+    name: "MariaDB",
+    aliases: [],
+    categories: ["rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "oracle-db",
+    name: "Oracle DB",
+    aliases: ["oracle", "oracle database"],
+    categories: ["rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "ms-sql-server",
+    name: "MS SQL Server",
+    aliases: ["sql server", "mssql", "ms sql"],
+    categories: ["rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "sqlite",
+    name: "SQLite",
+    aliases: [],
+    categories: ["rdbms"],
+    supportedModes: ["polling-adapter"],
+    tier: "experimental"
+  },
+  {
+    key: "mongodb",
+    name: "MongoDB",
+    aliases: ["mongo"],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "redis",
+    name: "Redis",
+    aliases: [],
+    categories: ["nosql", "in-memory"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "cassandra",
+    name: "Cassandra",
+    aliases: ["apache cassandra"],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "dynamodb",
+    name: "DynamoDB",
+    aliases: ["dynamo"],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "neo4j",
+    name: "Neo4j",
+    aliases: [],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "elasticsearch",
+    name: "Elasticsearch",
+    aliases: ["elastic"],
+    categories: ["nosql", "search-engine"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "hbase",
+    name: "HBase",
+    aliases: ["apache hbase"],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "couchdb",
+    name: "CouchDB",
+    aliases: ["apache couchdb"],
+    categories: ["nosql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "influxdb",
+    name: "InfluxDB",
+    aliases: ["influx"],
+    categories: ["time-series"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "timescaledb",
+    name: "TimescaleDB",
+    aliases: ["timescale"],
+    categories: ["time-series", "rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "prometheus",
+    name: "Prometheus",
+    aliases: ["prom"],
+    categories: ["time-series"],
+    supportedModes: ["polling-adapter"],
+    tier: "experimental"
+  },
+  {
+    key: "opensearch",
+    name: "OpenSearch",
+    aliases: [],
+    categories: ["search-engine"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "solr",
+    name: "Solr",
+    aliases: ["apache solr"],
+    categories: ["search-engine"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "snowflake",
+    name: "Snowflake",
+    aliases: [],
+    categories: ["cloud-data-warehouse"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "official"
+  },
+  {
+    key: "bigquery",
+    name: "BigQuery",
+    aliases: ["google bigquery"],
+    categories: ["cloud-data-warehouse"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "redshift",
+    name: "Redshift",
+    aliases: ["amazon redshift"],
+    categories: ["cloud-data-warehouse"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "azure-synapse",
+    name: "Azure Synapse",
+    aliases: ["synapse", "azure synapse analytics"],
+    categories: ["cloud-data-warehouse"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "memcached",
+    name: "Memcached",
+    aliases: [],
+    categories: ["in-memory"],
+    supportedModes: ["polling-adapter"],
+    tier: "experimental"
+  },
+  {
+    key: "voltdb",
+    name: "VoltDB",
+    aliases: [],
+    categories: ["in-memory"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "cockroachdb",
+    name: "CockroachDB",
+    aliases: ["cockroach"],
+    categories: ["newsql", "rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "tidb",
+    name: "TiDB",
+    aliases: [],
+    categories: ["newsql", "rdbms"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  },
+  {
+    key: "spanner",
+    name: "Spanner",
+    aliases: ["google spanner", "cloud spanner"],
+    categories: ["newsql"],
+    supportedModes: ["polling-adapter", "external-cdc-bridge"],
+    tier: "experimental"
+  }
+];
+function normaliseDatabaseName(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function getDatabaseSupport(name) {
+  const normalised = normaliseDatabaseName(name);
+  return SUPPORTED_DATABASES.find((database) => {
+    if (normaliseDatabaseName(database.name) === normalised) return true;
+    if (normaliseDatabaseName(database.key) === normalised) return true;
+    return database.aliases.some((alias) => normaliseDatabaseName(alias) === normalised);
+  });
+}
+function listSupportedDatabases(category) {
+  if (!category) return SUPPORTED_DATABASES;
+  return SUPPORTED_DATABASES.filter((database) => database.categories.includes(category));
+}
+function listOfficialDatabases(category) {
+  const databases = listSupportedDatabases(category);
+  return databases.filter((database) => database.tier === "official");
+}
+
+// src/core/adapter/memory-adapter.ts
+var MemoryAdapter = class {
+  listeners = /* @__PURE__ */ new Map();
+  connected = false;
+  /** No-op — MemoryAdapter requires no real connection. */
+  async connect() {
+    this.connected = true;
+  }
+  /** No-op — clears all listeners on disconnect. */
+  async disconnect() {
+    this.listeners.clear();
+    this.connected = false;
+  }
+  /**
+   * Register a listener for changes on a specific 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);
+    return () => {
+      this.listeners.get(table)?.delete(callback);
+    };
+  }
+  /**
+   * Manually emit a change event on a table.
+   * Useful in tests and examples to simulate DB changes without a real database.
+   *
+   * @param table - Table name to emit the event on
+   * @param event - Change event data (table and timestamp are filled in automatically)
+   */
+  emit(table, event) {
+    const fullEvent = {
+      ...event,
+      table,
+      timestamp: Date.now()
+    };
+    const callbacks = this.listeners.get(table);
+    if (!callbacks) return;
+    for (const cb of callbacks) {
+      cb(fullEvent);
+    }
+  }
+  /** Returns true if connect() has been called and disconnect() has not. */
+  get isConnected() {
+    return this.connected;
+  }
+};
+
+// src/core/adapter/polling-adapter.ts
+var PollingAdapter = class {
+  listeners = /* @__PURE__ */ new Map();
+  cursors = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  activeTables = /* @__PURE__ */ new Set();
+  intervalMs;
+  now;
+  readChanges;
+  onError;
+  connected = false;
+  constructor(options) {
+    this.intervalMs = options.intervalMs ?? 1e3;
+    this.now = options.now ?? (() => Date.now());
+    this.readChanges = options.readChanges;
+    this.onError = options.onError;
+  }
+  async connect() {
+    this.connected = true;
+    for (const table of this.listeners.keys()) {
+      this.ensurePolling(table);
+    }
+  }
+  async disconnect() {
+    this.connected = false;
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.activeTables.clear();
+  }
+  onChange(table, callback) {
+    if (!this.listeners.has(table)) {
+      this.listeners.set(table, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(table).add(callback);
+    this.ensurePolling(table);
+    return () => {
+      const callbacks = this.listeners.get(table);
+      if (!callbacks) return;
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        this.listeners.delete(table);
+        this.stopPolling(table);
+      }
+    };
+  }
+  ensurePolling(table) {
+    if (!this.connected || this.activeTables.has(table)) return;
+    this.activeTables.add(table);
+    void this.poll(table);
+  }
+  stopPolling(table) {
+    const timer = this.timers.get(table);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(table);
+    this.activeTables.delete(table);
+    this.cursors.delete(table);
+  }
+  scheduleNext(table) {
+    if (!this.connected || !this.listeners.has(table)) {
+      this.stopPolling(table);
+      return;
+    }
+    const timer = setTimeout(() => {
+      void this.poll(table);
+    }, this.intervalMs);
+    this.timers.set(table, timer);
+  }
+  async poll(table) {
+    if (!this.connected || !this.listeners.has(table)) {
+      this.stopPolling(table);
+      return;
+    }
+    try {
+      const result = await this.readChanges({
+        table,
+        cursor: this.cursors.get(table)
+      });
+      this.cursors.set(table, result.cursor);
+      for (const event of result.events) {
+        this.emit(table, event);
+      }
+    } catch (error) {
+      this.onError?.(error, { table });
+    } finally {
+      this.activeTables.delete(table);
+      this.scheduleNext(table);
+    }
+  }
+  emit(defaultTable, event) {
+    const fullEvent = {
+      ...event,
+      table: event.table ?? defaultTable,
+      timestamp: event.timestamp ?? this.now()
+    };
+    const callbacks = this.listeners.get(fullEvent.table);
+    if (!callbacks) return;
+    for (const callback of callbacks) {
+      callback(fullEvent);
+    }
+  }
+};
+
+// src/index.ts
+var ReactiveApp = class {
+  fastify;
+  engine;
+  transport = null;
+  options;
+  /** Collected route patterns for reactive endpoints */
+  reactivePatterns = [];
+  constructor(options) {
+    this.options = {
+      transport: "websocket",
+      port: 3e3,
+      ...options
+    };
+    this.fastify = (0, import_fastify.default)({ logger: false });
+    this.engine = new ReactiveEngine(this.options.adapter);
+    this.fastify.setErrorHandler((error, _req, reply) => {
+      if (error instanceof ReactiveApiError) {
+        const status = error.statusCode ?? 500;
+        reply.status(status).send({ error: error.code, message: error.message });
+      } else {
+        reply.status(500).send({ error: "INTERNAL_ERROR", message: error.message });
+      }
+    });
+  }
+  /**
+   * Register a controller class. Scans its methods for @Route and @Reactive
+   * decorators and registers HTTP routes and reactive endpoints accordingly.
+   *
+   * @param ControllerClass - A class constructor whose methods may be decorated
+   *                          with @Route and/or @Reactive.
+   */
+  register(ControllerClass) {
+    const instance = new ControllerClass();
+    const proto = Object.getPrototypeOf(instance);
+    const methodNames = Object.getOwnPropertyNames(proto).filter(
+      (name) => name !== "constructor" && typeof proto[name] === "function"
+    );
+    for (const methodName of methodNames) {
+      const routeMeta = Reflect.getMetadata(
+        ROUTE_METADATA,
+        proto,
+        methodName
+      );
+      if (!routeMeta) continue;
+      const reactiveMeta = Reflect.getMetadata(
+        REACTIVE_METADATA,
+        proto,
+        methodName
+      );
+      const handler = instance[methodName];
+      this.fastify.route({
+        method: routeMeta.method,
+        url: routeMeta.path,
+        handler: async (req, reply) => {
+          const ctx = {
+            params: req.params,
+            query: req.query,
+            body: req.body,
+            headers: req.headers
+          };
+          try {
+            const result = await handler.call(instance, ctx);
+            return reply.send(result);
+          } catch (err) {
+            if (err instanceof ReactiveApiError) throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new ReactiveApiError("HANDLER_ERROR", msg);
+          }
+        }
+      });
+      if (reactiveMeta) {
+        const endpoint = {
+          routePath: routeMeta.path,
+          options: reactiveMeta,
+          handler: (ctx) => handler.call(instance, ctx)
+        };
+        this.engine.registerEndpoint(endpoint);
+        this.reactivePatterns.push(routeMeta.path);
+      }
+    }
+    return this;
+  }
+  /**
+   * Access the underlying Fastify instance for supplemental routes such as
+   * health checks, static assets, or demo pages.
+   */
+  getFastify() {
+    return this.fastify;
+  }
+  /**
+   * Start the HTTP server.
+   * Connects the database adapter before accepting connections.
+   *
+   * @param port - Override the port set in AppOptions
+   */
+  async listen(port) {
+    const listenPort = port ?? this.options.port;
+    await this.options.adapter.connect();
+    if (this.options.transport === "websocket") {
+      this.transport = new WebSocketTransport(this.engine, this.reactivePatterns);
+    } else if (this.options.transport === "sse") {
+      const sseTransport = new SseTransport(this.engine, this.reactivePatterns);
+      sseTransport.register(this.fastify);
+      this.transport = sseTransport;
+    }
+    await this.fastify.ready();
+    if (this.transport instanceof WebSocketTransport) {
+      this.transport.attach(this.fastify.server);
+    }
+    await this.fastify.listen({ port: listenPort, host: "0.0.0.0" });
+    console.log(
+      `[RouteFlow] Listening on port ${listenPort} (transport: ${this.options.transport})`
+    );
+  }
+  /**
+   * Gracefully shut down the server and disconnect from the database.
+   */
+  async close() {
+    this.engine.destroy();
+    if (this.transport) await this.transport.close();
+    await this.fastify.close();
+    await this.options.adapter.disconnect();
+  }
+};
+function createApp(options) {
+  return new ReactiveApp(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryAdapter,
+  PollingAdapter,
+  Reactive,
+  ReactiveApiError,
+  ReactiveApp,
+  Route,
+  SUPPORTED_DATABASES,
+  createApp,
+  getDatabaseSupport,
+  listOfficialDatabases,
+  listSupportedDatabases
+});
+//# sourceMappingURL=index.cjs.map