turbine-orm 0.15.0 → 0.16.0

package/dist/cjs/cli/index.js

@@ -14,6 +14,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine studio                — Launch local read-only web UI
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -63,6 +64,7 @@ const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
 const loader_js_1 = require("./loader.js");
 const migrate_js_1 = require("./migrate.js");
+const observe_js_1 = require("./observe.js");
 const studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
@@ -1005,6 +1007,65 @@ async function cmdStudio(args, config) {
     });
 }
 // ---------------------------------------------------------------------------
+// Command: observe
+// ---------------------------------------------------------------------------
+async function cmdObserve(args) {
+    (0, ui_js_1.banner)();
+    const url = process.env.TURBINE_OBSERVE_URL;
+    if (!url) {
+        (0, ui_js_1.error)('TURBINE_OBSERVE_URL environment variable is required for the observe command.');
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Set it to the Postgres connection string where metrics are stored.')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('TURBINE_OBSERVE_URL=postgres://... npx turbine observe')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    const port = args.port ?? 4984;
+    const host = args.host ?? '127.0.0.1';
+    const openBrowser = !args.noOpen;
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
+        process.exit(1);
+    }
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        console.log((0, ui_js_1.warn)(`Observe is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your metrics.`));
+    }
+    const spinner = new ui_js_1.Spinner('Connecting to metrics database').start();
+    let handle;
+    try {
+        handle = await (0, observe_js_1.startObserve)({ url, port, host, openBrowser });
+        spinner.succeed('Observe dashboard is running');
+    }
+    catch (err) {
+        spinner.fail(`Failed to start Observe: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    (0, ui_js_1.newline)();
+    console.log((0, ui_js_1.box)([
+        `${(0, ui_js_1.bold)('Turbine Observe')}  ${(0, ui_js_1.dim)('— query metrics dashboard')}`,
+        '',
+        `  ${(0, ui_js_1.cyan)('URL:')}  ${(0, ui_js_1.bold)(handle.url)}`,
+        '',
+        (0, ui_js_1.dim)('Open the URL above in your browser. Press Ctrl+C to stop.'),
+    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Observe')), padding: 1 }));
+    (0, ui_js_1.newline)();
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            console.log((0, ui_js_1.dim)('\n  shutting down…'));
+            try {
+                await handle.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+}
+// ---------------------------------------------------------------------------
 // Subcommand help
 // ---------------------------------------------------------------------------
 function showSubcommandHelp(command) {
@@ -1288,6 +1349,9 @@ async function main() {
             case 'studio':
                 await cmdStudio(args, config);
                 break;
+            case 'observe':
+                await cmdObserve(args);
+                break;
             default:
                 (0, ui_js_1.error)(`Unknown command: ${(0, ui_js_1.bold)(args.command)}`);
                 (0, ui_js_1.newline)();

package/dist/cjs/cli/observe-ui.js

@@ -0,0 +1,182 @@
+"use strict";
+// Embedded HTML for the Turbine Observe dashboard.
+// Same pattern as studio-ui.generated.ts but hand-authored (no build step needed).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVE_HTML = void 0;
+exports.OBSERVE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="color-scheme" content="dark" />
+  <title>Turbine Observe</title>
+  <style>
+    :root {
+      --bg: #0a0a0b;
+      --bg-elev: #111113;
+      --bg-hover: #1a1a1d;
+      --border: #26262b;
+      --text: #e6e6ea;
+      --text-dim: #8a8a93;
+      --accent: #60a5fa;
+      --green: #4ade80;
+      --red: #f87171;
+      --orange: #fb923c;
+      --purple: #a78bfa;
+      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+      --sans: system-ui, -apple-system, sans-serif;
+      --radius: 6px;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }
+    h1 { font-size: 20px; margin-bottom: 4px; }
+    .subtitle { color: var(--text-dim); margin-bottom: 24px; }
+    .controls { display: flex; gap: 8px; margin-bottom: 24px; }
+    .controls button {
+      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);
+      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;
+    }
+    .controls button.active { border-color: var(--accent); color: var(--accent); }
+    .card {
+      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);
+      padding: 16px; margin-bottom: 16px;
+    }
+    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
+    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }
+    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }
+    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }
+    .num { text-align: right; }
+    .error-rate { color: var(--red); }
+    .low-error { color: var(--green); }
+    svg { width: 100%; height: 200px; }
+    .chart-line { fill: none; stroke-width: 1.5; }
+    .line-avg { stroke: var(--accent); }
+    .line-p95 { stroke: var(--orange); }
+    .line-p99 { stroke: var(--red); }
+    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }
+    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }
+    .legend .l-avg::before { background: var(--accent); }
+    .legend .l-p95::before { background: var(--orange); }
+    .legend .l-p99::before { background: var(--red); }
+    .empty { color: var(--text-dim); text-align: center; padding: 40px; }
+  </style>
+</head>
+<body>
+  <h1>Turbine Observe</h1>
+  <p class="subtitle">Query performance metrics</p>
+  <div class="controls">
+    <button data-range="1h" class="active">1h</button>
+    <button data-range="6h">6h</button>
+    <button data-range="24h">24h</button>
+    <button data-range="7d">7d</button>
+  </div>
+  <div class="card" id="latency-card">
+    <h2>Latency over time</h2>
+    <div id="chart"></div>
+    <div class="legend">
+      <span class="l-avg">avg</span>
+      <span class="l-p95">p95</span>
+      <span class="l-p99">p99</span>
+    </div>
+  </div>
+  <div class="card" id="models-card">
+    <h2>Top models</h2>
+    <div id="models-table"></div>
+  </div>
+  <div class="card" id="errors-card">
+    <h2>Error rates</h2>
+    <div id="errors-table"></div>
+  </div>
+  <script>
+    let currentRange = '1h';
+    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';
+    const headers = { 'x-turbine-token': token };
+
+    document.querySelector('.controls').addEventListener('click', e => {
+      if (e.target.tagName !== 'BUTTON') return;
+      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));
+      e.target.classList.add('active');
+      currentRange = e.target.dataset.range;
+      refresh();
+    });
+
+    async function fetchJson(path) {
+      const res = await fetch(path, { headers });
+      if (!res.ok) return null;
+      return res.json();
+    }
+
+    function buildSvgPath(points, width, height, maxY) {
+      if (points.length === 0) return '';
+      const xStep = width / Math.max(points.length - 1, 1);
+      return points.map((y, i) => {
+        const px = i * xStep;
+        const py = height - (y / maxY) * height;
+        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);
+      }).join(' ');
+    }
+
+    function renderChart(data) {
+      const el = document.getElementById('chart');
+      if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
+      const width = 800; const height = 180;
+      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);
+      const maxY = Math.max(...allVals, 1) * 1.1;
+      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);
+      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);
+      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);
+      el.innerHTML = '<svg viewBox="0 0 ' + width + ' ' + height + '" preserveAspectRatio="none">'
+        + '<path class="chart-line line-avg" d="' + avgPath + '"/>'
+        + '<path class="chart-line line-p95" d="' + p95Path + '"/>'
+        + '<path class="chart-line line-p99" d="' + p99Path + '"/>'
+        + '</svg>';
+    }
+
+    function renderModels(data) {
+      const el = document.getElementById('models-table');
+      if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
+      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Count</th><th class="num">Avg (ms)</th><th class="num">P95 (ms)</th><th class="num">P99 (ms)</th></tr></thead><tbody>';
+      for (const row of data) {
+        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+          + '<td class="num">' + row.count + '</td>'
+          + '<td class="num">' + row.avg_ms.toFixed(1) + '</td>'
+          + '<td class="num">' + row.p95_ms.toFixed(1) + '</td>'
+          + '<td class="num">' + row.p99_ms.toFixed(1) + '</td></tr>';
+      }
+      html += '</tbody></table>';
+      el.innerHTML = html;
+    }
+
+    function renderErrors(data) {
+      const el = document.getElementById('errors-table');
+      if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No errors</p>'; return; }
+      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Total</th><th class="num">Errors</th><th class="num">Rate</th></tr></thead><tbody>';
+      for (const row of data) {
+        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';
+        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';
+        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+          + '<td class="num">' + row.count + '</td>'
+          + '<td class="num">' + row.error_count + '</td>'
+          + '<td class="num ' + cls + '">' + rate + '%</td></tr>';
+      }
+      html += '</tbody></table>';
+      el.innerHTML = html;
+    }
+
+    async function refresh() {
+      const [latency, models] = await Promise.all([
+        fetchJson('/api/latency?range=' + currentRange),
+        fetchJson('/api/models?range=' + currentRange),
+      ]);
+      renderChart(latency);
+      renderModels(models);
+      // Derive errors from models data
+      const withErrors = (models || []).filter(m => m.error_count > 0);
+      renderErrors(withErrors);
+    }
+
+    refresh();
+    setInterval(refresh, 60000);
+  </script>
+</body>
+</html>`;

package/dist/cjs/cli/observe.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * turbine-orm CLI — Observe
+ *
+ * A local, read-only dashboard for viewing query metrics stored in
+ * _turbine_metrics. Same security model as Studio: loopback binding,
+ * random token, HttpOnly cookie, CSP headers, read-only transactions.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startObserve = startObserve;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const pg_1 = __importDefault(require("pg"));
+const observe_ui_js_1 = require("./observe-ui.js");
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+async function startObserve(options) {
+    const pool = new pg_1.default.Pool({
+        connectionString: options.url,
+        max: 2,
+        idleTimeoutMillis: 10_000,
+    });
+    const probe = await pool.connect();
+    try {
+        await probe.query('SELECT 1');
+    }
+    finally {
+        probe.release();
+    }
+    const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
+    const server = (0, node_http_1.createServer)((req, res) => {
+        handleRequest(req, res, pool, options, authToken).catch((err) => {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const url = `http://${hostPart}:${options.port}/?token=${authToken}`;
+    if (options.openBrowser) {
+        openUrl(url);
+    }
+    return {
+        authToken,
+        url,
+        dispose: async () => {
+            await new Promise((resolve) => server.close(() => resolve()));
+            await pool.end();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Request routing
+// ---------------------------------------------------------------------------
+async function handleRequest(req, res, pool, options, authToken) {
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const expectedOrigin = `http://${hostPart}:${options.port}`;
+    const origin = req.headers.origin;
+    if (origin && origin !== expectedOrigin) {
+        sendJson(res, 403, { error: 'cross-origin requests not allowed' });
+        return;
+    }
+    const url = new URL(req.url ?? '/', expectedOrigin);
+    const pathname = url.pathname;
+    if (pathname === '/' || pathname === '/index.html') {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            sendText(res, 405, 'Method Not Allowed');
+            return;
+        }
+        const queryToken = url.searchParams.get('token');
+        if (queryToken && constantTimeEqual(queryToken, authToken)) {
+            res.writeHead(302, {
+                Location: '/',
+                'Set-Cookie': `turbine_observe_token=${authToken}; Path=/; HttpOnly; SameSite=Strict`,
+            });
+            res.end();
+            return;
+        }
+        sendHtml(res, 200, observe_ui_js_1.OBSERVE_HTML);
+        return;
+    }
+    if (!isAuthorized(req, authToken)) {
+        sendJson(res, 401, { error: 'unauthorized' });
+        return;
+    }
+    if (pathname === '/api/latency' && req.method === 'GET') {
+        return apiLatency(res, pool, url.searchParams);
+    }
+    if (pathname === '/api/models' && req.method === 'GET') {
+        return apiModels(res, pool, url.searchParams);
+    }
+    sendJson(res, 404, { error: 'not found' });
+}
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+function isAuthorized(req, expectedToken) {
+    const headerToken = req.headers['x-turbine-token'];
+    if (typeof headerToken === 'string' && constantTimeEqual(headerToken, expectedToken)) {
+        return true;
+    }
+    const cookieHeader = req.headers.cookie ?? '';
+    const match = /turbine_observe_token=([a-f0-9]+)/.exec(cookieHeader);
+    if (match?.[1] && constantTimeEqual(match[1], expectedToken)) {
+        return true;
+    }
+    return false;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+// ---------------------------------------------------------------------------
+// API handlers
+// ---------------------------------------------------------------------------
+function rangeToInterval(range) {
+    switch (range) {
+        case '6h':
+            return '6 hours';
+        case '24h':
+            return '24 hours';
+        case '7d':
+            return '7 days';
+        default:
+            return '1 hour';
+    }
+}
+async function apiLatency(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT bucket, SUM(count) as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY bucket
+       ORDER BY bucket`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+async function apiModels(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT model, action,
+              SUM(count)::int as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms,
+              SUM(error_count)::int as error_count
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY model, action
+       ORDER BY MAX(p95_ms) DESC
+       LIMIT 50`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+const SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
+};
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'application/json' });
+    res.end(payload);
+}
+function sendHtml(res, status, html) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+}
+function sendText(res, status, text) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/plain' });
+    res.end(text);
+}
+// ---------------------------------------------------------------------------
+// Browser open
+// ---------------------------------------------------------------------------
+function openUrl(url) {
+    const { platform: os } = process;
+    const { spawn } = require('node:child_process');
+    try {
+        if (os === 'darwin')
+            spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+        else if (os === 'win32')
+            spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+        else
+            spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // Best effort
+    }
+}

package/dist/cjs/client.js

@@ -30,6 +30,7 @@ exports.TurbineClient = exports.TransactionClient = void 0;
 exports.withRetry = withRetry;
 const pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("./errors.js");
+const observe_js_1 = require("./observe.js");
 const pipeline_js_1 = require("./pipeline.js");
 const index_js_1 = require("./query/index.js");
 async function withRetry(fn, options) {
@@ -191,7 +192,9 @@ class TurbineClient {
     logging;
     tableCache = new Map();
     middlewares = [];
+    queryListeners = new Set();
     queryOptions;
+    errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     ownsPool = true;
     constructor(config = {}, schema) {
@@ -225,12 +228,27 @@ class TurbineClient {
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
+        this.errorMessagesSafe = (config.errorMessages ?? 'safe') === 'safe';
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,
+            _onQuery: (event) => {
+                if (this.queryListeners.size === 0)
+                    return;
+                const emitted = this.errorMessagesSafe ? { ...event, params: event.params.map(() => '[REDACTED]') } : event;
+                for (const listener of this.queryListeners) {
+                    try {
+                        listener(emitted);
+                    }
+                    catch (e) {
+                        if (this.logging)
+                            console.error('[turbine] Query listener error:', e);
+                    }
+                }
+            },
         };
         // Apply NotFoundError message redaction mode (default: safe — values are
         // stripped from messages to avoid leaking PII into error logs).
@@ -283,6 +301,11 @@ class TurbineClient {
                 });
             }
         }
+        // Auto-start observability from env var
+        const observeUrl = typeof process !== 'undefined' ? process.env?.TURBINE_OBSERVE_URL : undefined;
+        if (observeUrl) {
+            this.$observe({ connectionString: observeUrl }).catch(() => { });
+        }
     }
     // -------------------------------------------------------------------------
     // Middleware — intercept all queries
@@ -324,6 +347,37 @@ class TurbineClient {
         this.tableCache.clear();
     }
     // -------------------------------------------------------------------------
+    // Event emitter — subscribe to query lifecycle events
+    // -------------------------------------------------------------------------
+    $on(_event, listener) {
+        this.queryListeners.add(listener);
+    }
+    $off(_event, listener) {
+        this.queryListeners.delete(listener);
+    }
+    // -------------------------------------------------------------------------
+    // Observability — automatic metrics collection
+    // -------------------------------------------------------------------------
+    observeEngine;
+    async $observe(config) {
+        if (this.observeEngine) {
+            await this.observeEngine.stop();
+            this.$off('query', this.observeEngine.getListener());
+        }
+        const engine = new observe_js_1.ObserveEngine(config);
+        this.observeEngine = engine;
+        await engine.init();
+        this.$on('query', engine.getListener());
+        return {
+            stop: async () => {
+                this.$off('query', engine.getListener());
+                await engine.stop();
+                if (this.observeEngine === engine)
+                    this.observeEngine = undefined;
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
     // Table accessor — creates QueryInterface for any table
     // -------------------------------------------------------------------------
     /**