@delali/sirannon-db 0.1.3 → 0.1.4

package/dist/server/index.d.ts

@@ -1,7 +1,108 @@
-export { E as ErrorResponse, a as ExecuteRequest, b as ExecuteResponse, Q as QueryRequest, c as QueryResponse, T as TransactionRequest, d as TransactionResponse, e as TransactionStatement, W as WSChangeMessage, f as WSClientMessage, g as WSErrorMessage, h as WSExecuteMessage, i as WSQueryMessage, j as WSResultMessage, k as WSServerMessage, l as WSSubscribeMessage, m as WSSubscribedMessage, n as WSUnsubscribeMessage, o as WSUnsubscribedMessage, t as toExecuteResponse } from '../protocol-BX1H-_Mz.js';
-import { S as Sirannon } from '../sirannon-BJ8Yd1Uf.js';
-import { S as ServerOptions, W as WSHandlerOptions } from '../types-DArCObcu.js';
-import 'better-sqlite3';
+import { E as ExecuteResult, S as ServerOptions, W as WSHandlerOptions } from '../types-DtDutWRU.js';
+import { S as Sirannon } from '../sirannon-B1oTfebD.js';
+import '../types-BFSsG77t.js';
+import '../types-DRkJlqex.js';
+
+/** Body for POST /db/:id/query */
+interface QueryRequest {
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** Body for POST /db/:id/execute */
+interface ExecuteRequest {
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** A single statement within a transaction batch. */
+interface TransactionStatement {
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** Body for POST /db/:id/transaction */
+interface TransactionRequest {
+    statements: TransactionStatement[];
+}
+/** Response for a successful query. */
+interface QueryResponse {
+    rows: Record<string, unknown>[];
+}
+/** Response for a successful execute. */
+interface ExecuteResponse {
+    changes: number;
+    lastInsertRowId: number | string;
+}
+/** Response for a successful transaction. */
+interface TransactionResponse {
+    results: ExecuteResponse[];
+}
+/** Standard error response envelope. */
+interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Inbound WS message types. */
+type WSClientMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSQueryMessage | WSExecuteMessage;
+interface WSSubscribeMessage {
+    type: 'subscribe';
+    id: string;
+    table: string;
+    filter?: Record<string, unknown>;
+}
+interface WSUnsubscribeMessage {
+    type: 'unsubscribe';
+    id: string;
+}
+interface WSQueryMessage {
+    type: 'query';
+    id: string;
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+interface WSExecuteMessage {
+    type: 'execute';
+    id: string;
+    sql: string;
+    params?: Record<string, unknown> | unknown[];
+}
+/** Outbound WS message types. */
+type WSServerMessage = WSSubscribedMessage | WSUnsubscribedMessage | WSChangeMessage | WSResultMessage | WSErrorMessage;
+interface WSSubscribedMessage {
+    type: 'subscribed';
+    id: string;
+}
+interface WSUnsubscribedMessage {
+    type: 'unsubscribed';
+    id: string;
+}
+interface WSChangeMessage {
+    type: 'change';
+    id: string;
+    event: {
+        type: 'insert' | 'update' | 'delete';
+        table: string;
+        row: Record<string, unknown>;
+        oldRow?: Record<string, unknown>;
+        seq: string;
+        timestamp: number;
+    };
+}
+interface WSResultMessage {
+    type: 'result';
+    id: string;
+    data: QueryResponse | ExecuteResponse;
+}
+interface WSErrorMessage {
+    type: 'error';
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Convert an ExecuteResult (with possible bigint) to a JSON-safe response. */
+declare function toExecuteResponse(result: ExecuteResult): ExecuteResponse;
 
 declare class SirannonServer {
     private app;
@@ -23,73 +124,29 @@ declare class SirannonServer {
 }
 declare function createServer(sirannon: Sirannon, options?: ServerOptions): SirannonServer;
 
-/** Transport-agnostic WebSocket connection. */
 interface WSConnection {
     send(data: string): void;
     close(code?: number, reason?: string): void;
 }
-/**
- * Manages WebSocket connections, routes messages to databases, and integrates
- * with CDC for real-time change subscriptions.
- *
- * Designed to be transport-agnostic: any WebSocket implementation can drive
- * this handler by calling handleOpen/handleMessage/handleClose with a
- * WSConnection adapter.
- */
 declare class WSHandler {
     private readonly sirannon;
     private readonly maxPayloadLength;
     private readonly connections;
     private readonly cdcContexts;
+    private readonly cdcPending;
     private closed;
     constructor(sirannon: Sirannon, options?: WSHandlerOptions);
-    /**
-     * Register a new WebSocket connection for the given database.
-     *
-     * Sends an error and closes the connection if the database does not exist,
-     * is closed, or the handler itself has been shut down.
-     */
-    handleOpen(conn: WSConnection, databaseId: string): void;
-    /**
-     * Process an incoming WebSocket message.
-     *
-     * Validates the JSON payload, extracts the message type and correlation ID,
-     * and routes to the appropriate handler.
-     */
+    handleOpen(conn: WSConnection, databaseId: string): Promise<void>;
     handleMessage(conn: WSConnection, data: string): void;
-    /**
-     * Clean up after a WebSocket connection closes.
-     *
-     * Unsubscribes all active CDC subscriptions for this connection and
-     * releases the per-database CDC context if no subscribers remain.
-     */
     handleClose(conn: WSConnection): void;
-    /** Number of active WebSocket connections. */
     get connectionCount(): number;
-    /**
-     * Shut down the handler.
-     *
-     * Unsubscribes all CDC subscriptions, closes all WebSocket connections
-     * with code 1001 (Going Away), and releases all CDC resources.
-     */
-    close(): void;
+    close(): Promise<void>;
     private handleQuery;
     private handleExecute;
     private handleSubscribe;
     private handleUnsubscribe;
-    /**
-     * Get or create a CDC context for the given database.
-     *
-     * Opens a separate better-sqlite3 connection for trigger installation and
-     * change polling. WAL mode and a 5-second busy timeout are set so that
-     * the CDC connection coexists with the Database class's connection pool.
-     */
     private ensureCDC;
-    /**
-     * Release CDC resources for a database if no subscribers remain.
-     *
-     * Stops the polling loop and closes the dedicated CDC connection.
-     */
+    private createCDCContext;
     private maybeCleanupCDC;
     private isValidParams;
     private send;
@@ -97,7 +154,6 @@ declare class WSHandler {
     private sendSirannonError;
     private sendChange;
 }
-/** Create a transport-agnostic WebSocket handler bound to a Sirannon registry. */
 declare function createWSHandler(sirannon: Sirannon, options?: WSHandlerOptions): WSHandler;
 
-export { SirannonServer, type WSConnection, WSHandler, createServer, createWSHandler };
+export { type ErrorResponse, type ExecuteRequest, type ExecuteResponse, type QueryRequest, type QueryResponse, SirannonServer, type TransactionRequest, type TransactionResponse, type TransactionStatement, type WSChangeMessage, type WSClientMessage, type WSConnection, type WSErrorMessage, type WSExecuteMessage, WSHandler, type WSQueryMessage, type WSResultMessage, type WSServerMessage, type WSSubscribeMessage, type WSSubscribedMessage, type WSUnsubscribeMessage, type WSUnsubscribedMessage, createServer, createWSHandler, toExecuteResponse };

package/dist/server/index.mjs

@@ -1,6 +1,6 @@
-import { ChangeTracker, SubscriptionManager, SirannonError } from '../chunk-VI4UP4RR.mjs';
+import { ChangeTracker, SubscriptionManager } from '../chunk-AX66KWBR.mjs';
+import { SirannonError } from '../chunk-O7BHI3CF.mjs';
 import uWS from 'uWebSockets.js';
-import SqliteDatabase from 'better-sqlite3';
 
 // src/server/protocol.ts
 function toExecuteResponse(result) {
@@ -141,8 +141,18 @@ function httpStatusForError(err) {
       return 500;
   }
 }
-function resolveDatabase(res, sirannon, id) {
-  const db = sirannon.get(id);
+async function resolveDatabase(res, sirannon, id) {
+  let db;
+  try {
+    db = await sirannon.resolve(id);
+  } catch (err) {
+    if (err instanceof SirannonError) {
+      sendError(res, httpStatusForError(err), err.code, err.message);
+    } else {
+      sendError(res, 500, "INTERNAL_ERROR", "An unexpected error occurred");
+    }
+    return null;
+  }
   if (!db) {
     sendError(res, 404, "DATABASE_NOT_FOUND", `Database '${id}' not found`);
     return null;
@@ -150,19 +160,21 @@ function resolveDatabase(res, sirannon, id) {
   return db;
 }
 function handleQuery(sirannon) {
-  return (res, dbId, rawBody) => {
+  return async (res, dbId, rawBody, abort) => {
     const body = parseBody(res, rawBody);
     if (!body) return;
     if (!body.sql || typeof body.sql !== "string") {
       sendError(res, 400, "INVALID_REQUEST", 'Field "sql" is required and must be a string');
       return;
     }
-    const db = resolveDatabase(res, sirannon, dbId);
+    const db = await resolveDatabase(res, sirannon, dbId);
     if (!db) return;
     try {
-      const rows = db.query(body.sql, body.params);
+      const rows = await db.query(body.sql, body.params);
+      if (abort.aborted) return;
       sendJson(res, { rows });
     } catch (err) {
+      if (abort.aborted) return;
       if (err instanceof SirannonError) {
         sendError(res, httpStatusForError(err), err.code, err.message);
       } else {
@@ -172,19 +184,21 @@ function handleQuery(sirannon) {
   };
 }
 function handleExecute(sirannon) {
-  return (res, dbId, rawBody) => {
+  return async (res, dbId, rawBody, abort) => {
     const body = parseBody(res, rawBody);
     if (!body) return;
     if (!body.sql || typeof body.sql !== "string") {
       sendError(res, 400, "INVALID_REQUEST", 'Field "sql" is required and must be a string');
       return;
     }
-    const db = resolveDatabase(res, sirannon, dbId);
+    const db = await resolveDatabase(res, sirannon, dbId);
     if (!db) return;
     try {
-      const result = db.execute(body.sql, body.params);
+      const result = await db.execute(body.sql, body.params);
+      if (abort.aborted) return;
       sendJson(res, toExecuteResponse(result));
     } catch (err) {
+      if (abort.aborted) return;
       if (err instanceof SirannonError) {
         sendError(res, httpStatusForError(err), err.code, err.message);
       } else {
@@ -194,7 +208,7 @@ function handleExecute(sirannon) {
   };
 }
 function handleTransaction(sirannon) {
-  return (res, dbId, rawBody) => {
+  return async (res, dbId, rawBody, abort) => {
     const body = parseBody(res, rawBody);
     if (!body) return;
     if (!Array.isArray(body.statements)) {
@@ -212,16 +226,23 @@ function handleTransaction(sirannon) {
         return;
       }
     }
-    const db = resolveDatabase(res, sirannon, dbId);
+    const db = await resolveDatabase(res, sirannon, dbId);
     if (!db) return;
     try {
-      const results = db.transaction((tx) => {
-        return body.statements.map((stmt) => tx.execute(stmt.sql, stmt.params));
+      const results = await db.transaction(async (tx) => {
+        const txResults = [];
+        for (const stmt of body.statements) {
+          if (abort.aborted) throw new Error("Request aborted");
+          txResults.push(await tx.execute(stmt.sql, stmt.params));
+        }
+        return txResults;
       });
+      if (abort.aborted) return;
       sendJson(res, {
         results: results.map(toExecuteResponse)
       });
     } catch (err) {
+      if (abort.aborted) return;
       if (err instanceof SirannonError) {
         sendError(res, httpStatusForError(err), err.code, err.message);
       } else {
@@ -230,6 +251,8 @@ function handleTransaction(sirannon) {
     }
   };
 }
+
+// src/server/ws-handler.ts
 var DEFAULT_POLL_INTERVAL_MS = 50;
 var DEFAULT_MAX_PAYLOAD_LENGTH = 1048576;
 var WSHandler = class {
@@ -237,25 +260,19 @@ var WSHandler = class {
   maxPayloadLength;
   connections = /* @__PURE__ */ new Map();
   cdcContexts = /* @__PURE__ */ new Map();
+  cdcPending = /* @__PURE__ */ new Map();
   closed = false;
   constructor(sirannon, options) {
     this.sirannon = sirannon;
     this.maxPayloadLength = options?.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
   }
-  // --- Public API ---
-  /**
-   * Register a new WebSocket connection for the given database.
-   *
-   * Sends an error and closes the connection if the database does not exist,
-   * is closed, or the handler itself has been shut down.
-   */
-  handleOpen(conn, databaseId) {
+  async handleOpen(conn, databaseId) {
     if (this.closed) {
       this.sendError(conn, "", "HANDLER_CLOSED", "WebSocket handler is shut down");
       conn.close(1013, "Handler shutting down");
       return;
     }
-    const database = this.sirannon.get(databaseId);
+    const database = await this.sirannon.resolve(databaseId);
     if (!database) {
       this.sendError(conn, "", "DATABASE_NOT_FOUND", `Database '${databaseId}' not found`);
       conn.close(1008, "Database not found");
@@ -272,12 +289,6 @@ var WSHandler = class {
       subscriptions: /* @__PURE__ */ new Map()
     });
   }
-  /**
-   * Process an incoming WebSocket message.
-   *
-   * Validates the JSON payload, extracts the message type and correlation ID,
-   * and routes to the appropriate handler.
-   */
   handleMessage(conn, data) {
     const state = this.connections.get(conn);
     if (!state) return;
@@ -322,12 +333,6 @@ var WSHandler = class {
         this.sendError(conn, id, "UNKNOWN_TYPE", `Unknown message type: '${msg.type}'`);
     }
   }
-  /**
-   * Clean up after a WebSocket connection closes.
-   *
-   * Unsubscribes all active CDC subscriptions for this connection and
-   * releases the per-database CDC context if no subscribers remain.
-   */
   handleClose(conn) {
     const state = this.connections.get(conn);
     if (!state) return;
@@ -338,17 +343,10 @@ var WSHandler = class {
     this.maybeCleanupCDC(state.databaseId);
     this.connections.delete(conn);
   }
-  /** Number of active WebSocket connections. */
   get connectionCount() {
     return this.connections.size;
   }
-  /**
-   * Shut down the handler.
-   *
-   * Unsubscribes all CDC subscriptions, closes all WebSocket connections
-   * with code 1001 (Going Away), and releases all CDC resources.
-   */
-  close() {
+  async close() {
     if (this.closed) return;
     this.closed = true;
     for (const [conn, state] of this.connections) {
@@ -362,14 +360,13 @@ var WSHandler = class {
     for (const ctx of this.cdcContexts.values()) {
       ctx.stopPolling();
       try {
-        ctx.cdcDb.close();
+        await ctx.cdcConn.close();
       } catch {
       }
     }
     this.cdcContexts.clear();
   }
-  // --- Private message handlers ---
-  handleQuery(conn, state, msg, id) {
+  async handleQuery(conn, state, msg, id) {
     if (typeof msg.sql !== "string") {
       this.sendError(conn, id, "INVALID_MESSAGE", 'Query message requires a "sql" string field');
       return;
@@ -380,13 +377,13 @@ var WSHandler = class {
     }
     try {
       const params = msg.params ?? void 0;
-      const rows = state.database.query(msg.sql, params);
+      const rows = await state.database.query(msg.sql, params);
       this.send(conn, { type: "result", id, data: { rows } });
     } catch (err) {
       this.sendSirannonError(conn, id, err);
     }
   }
-  handleExecute(conn, state, msg, id) {
+  async handleExecute(conn, state, msg, id) {
     if (typeof msg.sql !== "string") {
       this.sendError(conn, id, "INVALID_MESSAGE", 'Execute message requires a "sql" string field');
       return;
@@ -397,7 +394,7 @@ var WSHandler = class {
     }
     try {
       const params = msg.params ?? void 0;
-      const result = state.database.execute(msg.sql, params);
+      const result = await state.database.execute(msg.sql, params);
       this.send(conn, {
         type: "result",
         id,
@@ -407,7 +404,7 @@ var WSHandler = class {
       this.sendSirannonError(conn, id, err);
     }
   }
-  handleSubscribe(conn, state, msg, id) {
+  async handleSubscribe(conn, state, msg, id) {
     if (typeof msg.table !== "string") {
       this.sendError(conn, id, "INVALID_MESSAGE", 'Subscribe message requires a "table" string field');
       return;
@@ -430,8 +427,8 @@ var WSHandler = class {
     }
     const filter = msg.filter ?? void 0;
     try {
-      const ctx = this.ensureCDC(state.databaseId, state.database);
-      ctx.tracker.watch(ctx.cdcDb, msg.table);
+      const ctx = await this.ensureCDC(state.databaseId, state.database);
+      await ctx.tracker.watch(ctx.cdcConn, msg.table);
       const sub = ctx.manager.subscribe(msg.table, filter, (event) => {
         this.sendChange(conn, id, event);
       });
@@ -452,31 +449,43 @@ var WSHandler = class {
     this.send(conn, { type: "unsubscribed", id });
     this.maybeCleanupCDC(state.databaseId);
   }
-  // --- CDC management ---
-  /**
-   * Get or create a CDC context for the given database.
-   *
-   * Opens a separate better-sqlite3 connection for trigger installation and
-   * change polling. WAL mode and a 5-second busy timeout are set so that
-   * the CDC connection coexists with the Database class's connection pool.
-   */
-  ensureCDC(databaseId, database) {
+  async ensureCDC(databaseId, database) {
     const existing = this.cdcContexts.get(databaseId);
     if (existing) return existing;
-    const cdcDb = new SqliteDatabase(database.path);
-    cdcDb.pragma("journal_mode = WAL");
-    cdcDb.pragma("busy_timeout = 5000");
+    const pending = this.cdcPending.get(databaseId);
+    if (pending) return pending;
+    const promise = this.createCDCContext(database);
+    this.cdcPending.set(databaseId, promise);
+    try {
+      const ctx = await promise;
+      if (this.closed) {
+        ctx.stopPolling();
+        await ctx.cdcConn.close().catch(() => {
+        });
+        throw new SirannonError("WebSocket handler is shut down", "HANDLER_CLOSED");
+      }
+      this.cdcContexts.set(databaseId, ctx);
+      return ctx;
+    } finally {
+      this.cdcPending.delete(databaseId);
+    }
+  }
+  async createCDCContext(database) {
+    const cdcConn = await this.sirannon.driver.open(database.path, { walMode: true });
     const tracker = new ChangeTracker();
     const manager = new SubscriptionManager();
+    let polling = false;
     let consecutiveErrors = 0;
     const MAX_CONSECUTIVE_ERRORS = 10;
     const stopPolling = () => {
       clearInterval(interval);
     };
-    const tick = () => {
+    const tick = async () => {
       if (manager.size === 0) return;
+      if (polling) return;
+      polling = true;
       try {
-        const events = tracker.poll(cdcDb);
+        const events = await tracker.poll(cdcConn);
         if (events.length > 0) {
           manager.dispatch(events);
         }
@@ -486,35 +495,28 @@ var WSHandler = class {
         if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
           stopPolling();
         }
+      } finally {
+        polling = false;
       }
     };
     const interval = setInterval(tick, DEFAULT_POLL_INTERVAL_MS);
-    if (typeof interval.unref === "function") interval.unref();
-    const ctx = { cdcDb, tracker, manager, stopPolling };
-    this.cdcContexts.set(databaseId, ctx);
-    return ctx;
-  }
-  /**
-   * Release CDC resources for a database if no subscribers remain.
-   *
-   * Stops the polling loop and closes the dedicated CDC connection.
-   */
+    if (typeof interval === "object" && "unref" in interval && typeof interval.unref === "function") {
+      interval.unref();
+    }
+    return { cdcConn, tracker, manager, stopPolling };
+  }
   maybeCleanupCDC(databaseId) {
     const ctx = this.cdcContexts.get(databaseId);
     if (!ctx || ctx.manager.size > 0) return;
     ctx.stopPolling();
-    try {
-      ctx.cdcDb.close();
-    } catch {
-    }
+    ctx.cdcConn.close().catch(() => {
+    });
     this.cdcContexts.delete(databaseId);
   }
-  // --- Validation ---
   isValidParams(params) {
     if (params === void 0 || params === null) return true;
     return typeof params === "object";
   }
-  // --- Send helpers ---
   send(conn, msg) {
     try {
       conn.send(JSON.stringify(msg));
@@ -628,15 +630,15 @@ var SirannonServer = class {
       });
     });
   }
-  close() {
-    return new Promise((resolve) => {
-      this.wsHandler.close();
+  async close() {
+    try {
+      await this.wsHandler.close();
+    } finally {
       if (this.listenSocket) {
         uWS.us_listen_socket_close(this.listenSocket);
         this.listenSocket = null;
       }
-      resolve();
-    });
+    }
   }
   get listeningPort() {
     if (!this.listenSocket) return -1;
@@ -735,7 +737,8 @@ var SirannonServer = class {
           }
         };
         userData.conn = conn;
-        wsHandler.handleOpen(conn, userData.databaseId);
+        wsHandler.handleOpen(conn, userData.databaseId).catch(() => {
+        });
       },
       message: (ws, message) => {
         const userData = ws.getUserData();
@@ -773,9 +776,15 @@ var SirannonServer = class {
       const abort = initAbortHandler(res);
       const bodyPromise = readBody(res, MAX_BODY, abort);
       if (!onRequestHook) {
-        bodyPromise.then((rawBody) => {
+        bodyPromise.then(async (rawBody) => {
           if (abort.aborted) return;
-          handler(res, dbId, rawBody);
+          try {
+            await handler(res, dbId, rawBody, abort);
+          } catch {
+            if (!abort.aborted) {
+              sendError(res, 500, "INTERNAL_ERROR", "An unexpected error occurred");
+            }
+          }
         }).catch(() => {
         });
         return;
@@ -793,9 +802,15 @@ var SirannonServer = class {
         remoteAddress
       };
       const hookPromise = runOnRequest(res, ctx, onRequestHook);
-      Promise.all([bodyPromise, hookPromise]).then(([rawBody, allowed]) => {
+      Promise.all([bodyPromise, hookPromise]).then(async ([rawBody, allowed]) => {
         if (abort.aborted || !allowed) return;
-        handler(res, dbId, rawBody);
+        try {
+          await handler(res, dbId, rawBody, abort);
+        } catch {
+          if (!abort.aborted) {
+            sendError(res, 500, "INTERNAL_ERROR", "An unexpected error occurred");
+          }
+        }
       }).catch(() => {
       });
     };