@delali/sirannon-db 0.1.1

package/dist/protocol-BX1H-_Mz.d.ts

@@ -0,0 +1,104 @@
+import { E as ExecuteResult } from './types-DArCObcu.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;
+
+export { type ErrorResponse as E, type QueryRequest as Q, type TransactionRequest as T, type WSChangeMessage as W, type ExecuteRequest as a, type ExecuteResponse as b, type QueryResponse as c, type TransactionResponse as d, type TransactionStatement as e, type WSClientMessage as f, type WSErrorMessage as g, type WSExecuteMessage as h, type WSQueryMessage as i, type WSResultMessage as j, type WSServerMessage as k, type WSSubscribeMessage as l, type WSSubscribedMessage as m, type WSUnsubscribeMessage as n, type WSUnsubscribedMessage as o, toExecuteResponse as t };

package/dist/server/index.d.ts

@@ -0,0 +1,103 @@
+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';
+
+declare class SirannonServer {
+    private app;
+    private listenSocket;
+    private readonly host;
+    private readonly port;
+    private readonly cors;
+    private readonly onRequestHook;
+    private readonly sirannon;
+    private readonly wsHandler;
+    constructor(sirannon: Sirannon, options?: ServerOptions);
+    listen(): Promise<void>;
+    close(): Promise<void>;
+    get listeningPort(): number;
+    private registerRoutes;
+    private registerWebSocketRoute;
+    private withCors;
+    private wrapDbRoute;
+}
+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 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.
+     */
+    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;
+    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 maybeCleanupCDC;
+    private isValidParams;
+    private send;
+    private sendError;
+    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 };