@delali/sirannon-db 0.1.1

package/dist/chunk-VI4UP4RR.mjs

@@ -0,0 +1,417 @@
+// src/core/errors.ts
+var SirannonError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SirannonError";
+  }
+};
+var DatabaseNotFoundError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' not found`, "DATABASE_NOT_FOUND");
+    this.name = "DatabaseNotFoundError";
+  }
+};
+var DatabaseAlreadyExistsError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' already exists`, "DATABASE_ALREADY_EXISTS");
+    this.name = "DatabaseAlreadyExistsError";
+  }
+};
+var ReadOnlyError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' is read-only`, "READ_ONLY");
+    this.name = "ReadOnlyError";
+  }
+};
+var QueryError = class extends SirannonError {
+  constructor(message, sql) {
+    super(message, "QUERY_ERROR");
+    this.sql = sql;
+    this.name = "QueryError";
+  }
+};
+var TransactionError = class extends SirannonError {
+  constructor(message) {
+    super(message, "TRANSACTION_ERROR");
+    this.name = "TransactionError";
+  }
+};
+var MigrationError = class extends SirannonError {
+  constructor(message, version, code = "MIGRATION_ERROR") {
+    super(message, code);
+    this.version = version;
+    this.name = "MigrationError";
+  }
+};
+var HookDeniedError = class extends SirannonError {
+  constructor(hookName, reason) {
+    super(
+      reason ? `Hook '${hookName}' denied the operation: ${reason}` : `Hook '${hookName}' denied the operation`,
+      "HOOK_DENIED"
+    );
+    this.name = "HookDeniedError";
+  }
+};
+var CDCError = class extends SirannonError {
+  constructor(message) {
+    super(message, "CDC_ERROR");
+    this.name = "CDCError";
+  }
+};
+var BackupError = class extends SirannonError {
+  constructor(message) {
+    super(message, "BACKUP_ERROR");
+    this.name = "BackupError";
+  }
+};
+var ConnectionPoolError = class extends SirannonError {
+  constructor(message) {
+    super(message, "CONNECTION_POOL_ERROR");
+    this.name = "ConnectionPoolError";
+  }
+};
+var MaxDatabasesError = class extends SirannonError {
+  constructor(max) {
+    super(`Maximum number of open databases (${max}) reached`, "MAX_DATABASES");
+    this.name = "MaxDatabasesError";
+  }
+};
+var ExtensionError = class extends SirannonError {
+  constructor(path, cause) {
+    super(
+      cause ? `Failed to load extension '${path}': ${cause}` : `Failed to load extension '${path}'`,
+      "EXTENSION_ERROR"
+    );
+    this.name = "ExtensionError";
+  }
+};
+
+// src/core/cdc/change-tracker.ts
+var DEFAULT_RETENTION_MS = 36e5;
+var DEFAULT_CHANGES_TABLE = "_sirannon_changes";
+var DEFAULT_POLL_BATCH_SIZE = 1e3;
+var IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var ChangeTracker = class {
+  watched = /* @__PURE__ */ new Map();
+  lastSeq = 0;
+  retentionMs;
+  changesTable;
+  pollBatchSize;
+  changesTableReady = false;
+  watchedTablesCache = null;
+  stmtCache = /* @__PURE__ */ new WeakMap();
+  constructor(options) {
+    this.retentionMs = options?.retention ?? DEFAULT_RETENTION_MS;
+    this.changesTable = options?.changesTable ?? DEFAULT_CHANGES_TABLE;
+    this.pollBatchSize = options?.pollBatchSize ?? DEFAULT_POLL_BATCH_SIZE;
+    this.assertIdentifier(this.changesTable, "changes table name");
+  }
+  watch(db, table) {
+    this.assertIdentifier(table, "table name");
+    this.ensureChangesTable(db);
+    const columns = this.getColumns(db, table);
+    if (columns.length === 0) {
+      throw new CDCError(`Table '${table}' does not exist or has no columns`);
+    }
+    for (const col of columns) {
+      this.assertIdentifier(col, `column name in table '${table}'`);
+    }
+    const pkColumns = this.getPkColumns(db, table);
+    const existing = this.watched.get(table);
+    if (existing) {
+      const same = existing.columns.length === columns.length && existing.columns.every((col, i) => col === columns[i]);
+      if (same) {
+        return;
+      }
+      this.dropTriggers(db, table);
+    }
+    this.installTriggers(db, table, columns, pkColumns);
+    this.watched.set(table, { table, columns, pkColumns });
+    this.watchedTablesCache = null;
+  }
+  unwatch(db, table) {
+    if (!this.watched.has(table)) {
+      return;
+    }
+    this.dropTriggers(db, table);
+    this.watched.delete(table);
+    this.watchedTablesCache = null;
+  }
+  poll(db) {
+    if (!this.changesTableReady) {
+      this.detectChangesTable(db);
+      if (!this.changesTableReady) {
+        return [];
+      }
+    }
+    const stmt = this.getStmt(
+      db,
+      "poll",
+      `SELECT seq, table_name, operation, row_id, changed_at, old_data, new_data
+			 FROM "${this.changesTable}"
+			 WHERE seq > ?
+			 ORDER BY seq ASC
+			 LIMIT ?`
+    );
+    const rows = stmt.all(this.lastSeq, this.pollBatchSize);
+    if (rows.length === 0) {
+      return [];
+    }
+    const events = [];
+    for (const row of rows) {
+      events.push({
+        type: row.operation.toLowerCase(),
+        table: row.table_name,
+        row: row.new_data ? JSON.parse(row.new_data) : {},
+        oldRow: row.old_data ? JSON.parse(row.old_data) : void 0,
+        seq: BigInt(row.seq),
+        timestamp: row.changed_at
+      });
+    }
+    this.lastSeq = rows[rows.length - 1].seq;
+    return events;
+  }
+  cleanup(db) {
+    if (!this.changesTableReady) {
+      this.detectChangesTable(db);
+      if (!this.changesTableReady) {
+        return 0;
+      }
+    }
+    const cutoff = Date.now() / 1e3 - this.retentionMs / 1e3;
+    if (this.lastSeq > 0) {
+      const stmt2 = this.getStmt(
+        db,
+        "cleanup_coordinated",
+        `DELETE FROM "${this.changesTable}" WHERE changed_at < ? AND seq <= ?`
+      );
+      return stmt2.run(cutoff, this.lastSeq).changes;
+    }
+    const stmt = this.getStmt(db, "cleanup", `DELETE FROM "${this.changesTable}" WHERE changed_at < ?`);
+    return stmt.run(cutoff).changes;
+  }
+  get watchedTables() {
+    if (!this.watchedTablesCache) {
+      this.watchedTablesCache = new Set(this.watched.keys());
+    }
+    return this.watchedTablesCache;
+  }
+  assertIdentifier(name, label) {
+    if (!IDENTIFIER_RE.test(name)) {
+      throw new CDCError(
+        `Invalid ${label} '${name}': must contain only letters, digits, and underscores, and start with a letter or underscore`
+      );
+    }
+  }
+  detectChangesTable(db) {
+    const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(this.changesTable);
+    if (row) {
+      this.changesTableReady = true;
+    }
+  }
+  ensureChangesTable(db) {
+    if (this.changesTableReady) {
+      return;
+    }
+    db.exec(`
+CREATE TABLE IF NOT EXISTS "${this.changesTable}" (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  table_name TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  row_id TEXT NOT NULL,
+  changed_at REAL NOT NULL DEFAULT (unixepoch('subsec')),
+  old_data TEXT,
+  new_data TEXT
+)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS "idx_${this.changesTable}_changed_at" ON "${this.changesTable}" (changed_at)`);
+    this.changesTableReady = true;
+  }
+  getColumns(db, table) {
+    const info = db.prepare(`PRAGMA table_info("${table}")`).all();
+    return info.map((col) => col.name);
+  }
+  getPkColumns(db, table) {
+    const info = db.prepare(`PRAGMA table_info("${table}")`).all();
+    return info.filter((col) => col.pk > 0).sort((a, b) => a.pk - b.pk).map((col) => col.name);
+  }
+  dropTriggers(db, table) {
+    db.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_insert"`);
+    db.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_update"`);
+    db.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_delete"`);
+  }
+  getStmt(db, key, sql) {
+    let stmts = this.stmtCache.get(db);
+    if (!stmts) {
+      stmts = /* @__PURE__ */ new Map();
+      this.stmtCache.set(db, stmts);
+    }
+    let stmt = stmts.get(key);
+    if (!stmt) {
+      stmt = db.prepare(sql);
+      stmts.set(key, stmt);
+    }
+    return stmt;
+  }
+  buildPkRef(pkColumns, ref) {
+    if (pkColumns.length === 0) {
+      return `${ref}.rowid`;
+    }
+    if (pkColumns.length === 1) {
+      return `${ref}."${this.escId(pkColumns[0])}"`;
+    }
+    return pkColumns.map((col) => `${ref}."${this.escId(col)}"`).join(" || '-' || ");
+  }
+  installTriggers(db, table, columns, pkColumns) {
+    const newJson = this.buildJsonObject(columns, "NEW");
+    const oldJson = this.buildJsonObject(columns, "OLD");
+    const newPk = this.buildPkRef(pkColumns, "NEW");
+    const oldPk = this.buildPkRef(pkColumns, "OLD");
+    db.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_insert"
+			AFTER INSERT ON "${table}"
+			BEGIN
+				INSERT INTO "${this.changesTable}" (table_name, operation, row_id, new_data)
+				VALUES ('${table}', 'INSERT', ${newPk}, ${newJson});
+			END
+		`);
+    db.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_update"
+			AFTER UPDATE ON "${table}"
+			BEGIN
+				INSERT INTO "${this.changesTable}" (table_name, operation, row_id, old_data, new_data)
+				VALUES ('${table}', 'UPDATE', ${newPk}, ${oldJson}, ${newJson});
+			END
+		`);
+    db.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_delete"
+			AFTER DELETE ON "${table}"
+			BEGIN
+				INSERT INTO "${this.changesTable}" (table_name, operation, row_id, old_data)
+				VALUES ('${table}', 'DELETE', ${oldPk}, ${oldJson});
+			END
+		`);
+  }
+  buildJsonObject(columns, ref) {
+    const pairs = columns.map((col) => `'${this.escStr(col)}', ${ref}."${this.escId(col)}"`).join(", ");
+    return `json_object(${pairs})`;
+  }
+  escId(name) {
+    return name.replace(/"/g, '""');
+  }
+  escStr(name) {
+    return name.replace(/'/g, "''");
+  }
+};
+
+// src/core/cdc/subscription.ts
+var SubscriptionManager = class {
+  nextId = 1;
+  subscriptions = /* @__PURE__ */ new Map();
+  byTable = /* @__PURE__ */ new Map();
+  subscribe(table, filter, callback) {
+    const id = this.nextId++;
+    this.subscriptions.set(id, { id, table, filter, callback });
+    let tableSet = this.byTable.get(table);
+    if (!tableSet) {
+      tableSet = /* @__PURE__ */ new Set();
+      this.byTable.set(table, tableSet);
+    }
+    tableSet.add(id);
+    return {
+      unsubscribe: () => {
+        this.subscriptions.delete(id);
+        const set = this.byTable.get(table);
+        if (set) {
+          set.delete(id);
+          if (set.size === 0) {
+            this.byTable.delete(table);
+          }
+        }
+      }
+    };
+  }
+  dispatch(events) {
+    for (const event of events) {
+      const ids = this.byTable.get(event.table);
+      if (!ids) continue;
+      for (const id of ids) {
+        const sub = this.subscriptions.get(id);
+        if (!sub) continue;
+        if (sub.filter && !matchesFilter(event, sub.filter)) {
+          continue;
+        }
+        try {
+          sub.callback(event);
+        } catch {
+        }
+      }
+    }
+  }
+  get size() {
+    return this.subscriptions.size;
+  }
+  subscriberCount(table) {
+    return this.byTable.get(table)?.size ?? 0;
+  }
+};
+var SubscriptionBuilderImpl = class {
+  constructor(table, manager) {
+    this.table = table;
+    this.manager = manager;
+  }
+  conditions;
+  filter(conditions) {
+    this.conditions = { ...this.conditions, ...conditions };
+    return this;
+  }
+  subscribe(callback) {
+    return this.manager.subscribe(this.table, this.conditions, callback);
+  }
+};
+function startPolling(db, tracker, manager, intervalMs, onError) {
+  let consecutiveErrors = 0;
+  let tickCount = 0;
+  const MAX_CONSECUTIVE_ERRORS = 10;
+  const CLEANUP_INTERVAL_TICKS = 100;
+  const tick = () => {
+    if (manager.size === 0) return;
+    try {
+      const events = tracker.poll(db);
+      if (events.length > 0) {
+        manager.dispatch(events);
+      }
+      consecutiveErrors = 0;
+      tickCount++;
+      if (tickCount >= CLEANUP_INTERVAL_TICKS) {
+        tickCount = 0;
+        tracker.cleanup(db);
+      }
+    } catch (err) {
+      consecutiveErrors++;
+      if (onError) {
+        onError(err instanceof Error ? err : new Error(String(err)));
+      }
+      if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        stop();
+      }
+    }
+  };
+  const interval = setInterval(tick, intervalMs);
+  interval.unref();
+  const stop = () => {
+    clearInterval(interval);
+  };
+  return stop;
+}
+function matchesFilter(event, filter) {
+  const target = event.type === "delete" ? event.oldRow ?? {} : event.row;
+  for (const [key, value] of Object.entries(filter)) {
+    if (target[key] !== value) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export { BackupError, CDCError, ChangeTracker, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, SirannonError, SubscriptionBuilderImpl, SubscriptionManager, TransactionError, startPolling };

package/dist/client/index.d.ts

@@ -0,0 +1,223 @@
+import { P as Params, d as ChangeEvent, f as ClientOptions } from '../types-DArCObcu.js';
+import { c as QueryResponse, b as ExecuteResponse, d as TransactionResponse } from '../protocol-BX1H-_Mz.js';
+
+/**
+ * Transport layer for communicating with a sirannon-db server.
+ * Each transport instance is bound to a specific database.
+ */
+interface Transport {
+    query(sql: string, params?: Params): Promise<QueryResponse>;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    transaction(statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<TransactionResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    close(): void;
+}
+/** Handle for an active remote subscription. */
+interface RemoteSubscription {
+    unsubscribe(): void;
+}
+/** Builder for creating remote CDC subscriptions with optional filters. */
+interface RemoteSubscriptionBuilder {
+    filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
+    subscribe(callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+}
+/**
+ * Error originating from a remote sirannon-db server.
+ * Carries the machine-readable error code from the server's error response.
+ */
+declare class RemoteError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+/**
+ * Proxy for a remote sirannon-db database. Mirrors the core
+ * {@link Database} query interface with async methods that send
+ * requests to the server via the configured transport.
+ */
+declare class RemoteDatabase {
+    readonly id: string;
+    private readonly transport;
+    private readonly onDispose?;
+    constructor(id: string, transport: Transport, onDispose?: (() => void) | undefined);
+    /**
+     * Execute a SELECT and return all matching rows.
+     *
+     * ```ts
+     * const users = await db.query<{ id: number; name: string }>(
+     *   'SELECT * FROM users WHERE age > ?',
+     *   [21],
+     * )
+     * ```
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: Params): Promise<T[]>;
+    /**
+     * Execute a mutation (INSERT, UPDATE, DELETE) and return
+     * the number of affected rows and last insert row ID.
+     */
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    /**
+     * Execute multiple statements as a single atomic transaction.
+     * Returns an array of results, one per statement.
+     *
+     * Requires HTTP transport. WebSocket transport does not
+     * support server-side transactions.
+     */
+    transaction(statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<ExecuteResponse[]>;
+    /**
+     * Start building a CDC subscription for the given table.
+     * Chain `.filter()` to narrow the events, then call `.subscribe()`
+     * with a callback to begin receiving real-time change events.
+     *
+     * ```ts
+     * const sub = await db
+     *   .on('orders')
+     *   .filter({ status: 'pending' })
+     *   .subscribe(event => console.log(event))
+     *
+     * // Later:
+     * sub.unsubscribe()
+     * ```
+     */
+    on(table: string): RemoteSubscriptionBuilder;
+    /**
+     * Close the transport for this database. After calling `close()`,
+     * all pending requests are rejected and new calls will throw.
+     */
+    close(): void;
+}
+
+/**
+ * Client for a remote sirannon-db server. Creates {@link RemoteDatabase}
+ * instances that communicate with the server over HTTP or WebSocket.
+ *
+ * ```ts
+ * const client = new SirannonClient('http://localhost:9876', {
+ *   transport: 'websocket',
+ * })
+ *
+ * const db = client.database('main')
+ * const rows = await db.query('SELECT * FROM users')
+ *
+ * client.close()
+ * ```
+ */
+declare class SirannonClient {
+    private readonly baseUrl;
+    private readonly wsBaseUrl;
+    private readonly transport;
+    private readonly headers;
+    private readonly autoReconnect;
+    private readonly reconnectInterval;
+    private readonly databases;
+    private closed;
+    constructor(url: string, options?: ClientOptions);
+    /**
+     * Get a {@link RemoteDatabase} proxy for the given database ID.
+     * Returns a cached instance if one already exists for this ID.
+     *
+     * The underlying transport connection is established lazily on
+     * the first operation (query, execute, or subscribe).
+     */
+    database(id: string): RemoteDatabase;
+    /**
+     * Close all database connections and release resources.
+     * After calling `close()`, new calls to `database()` will throw.
+     */
+    close(): void;
+    private createTransport;
+}
+
+/**
+ * Builds a remote CDC subscription with optional row-level filters.
+ * Mirrors the core {@link SubscriptionBuilder} interface but returns
+ * a promise from `subscribe()` since confirming the subscription
+ * requires a server round-trip.
+ */
+declare class RemoteSubscriptionBuilderImpl implements RemoteSubscriptionBuilder {
+    private readonly table;
+    private readonly transport;
+    private conditions;
+    constructor(table: string, transport: Transport);
+    filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
+    subscribe(callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+}
+
+/**
+ * HTTP transport for sirannon-db. Sends requests via `fetch` to the
+ * server's REST endpoints. Supports query, execute, and transaction
+ * operations. Real-time subscriptions are not available over HTTP;
+ * use {@link WebSocketTransport} for CDC subscriptions.
+ */
+declare class HttpTransport implements Transport {
+    private readonly baseUrl;
+    private readonly headers;
+    private closed;
+    constructor(baseUrl: string, headers?: Record<string, string>);
+    query(sql: string, params?: Params): Promise<QueryResponse>;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    transaction(statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<TransactionResponse>;
+    subscribe(_table: string, _filter: Record<string, unknown> | undefined, _callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    close(): void;
+    private post;
+}
+
+/**
+ * WebSocket transport for sirannon-db. Connects to
+ * `ws(s)://host:port/db/{id}` and supports query, execute,
+ * and real-time CDC subscriptions over a single persistent connection.
+ *
+ * Connections are established lazily on first use and will
+ * auto-reconnect (with subscription restoration) when
+ * `autoReconnect` is enabled.
+ *
+ * Transactions are not supported over WebSocket; use
+ * {@link HttpTransport} for batch transactions.
+ */
+declare class WebSocketTransport implements Transport {
+    private ws;
+    private readonly url;
+    private readonly autoReconnect;
+    private readonly reconnectInterval;
+    private readonly requestTimeout;
+    private pendingRequests;
+    private activeSubscriptions;
+    private idCounter;
+    private closed;
+    private connectPromise;
+    private reconnectTimer;
+    constructor(url: string, options?: {
+        autoReconnect?: boolean;
+        reconnectInterval?: number;
+        requestTimeout?: number;
+    });
+    query(sql: string, params?: Params): Promise<QueryResponse>;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    transaction(_statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<TransactionResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    close(): void;
+    private nextId;
+    private ensureConnected;
+    private connect;
+    private handleMessage;
+    private handleDisconnect;
+    private scheduleReconnect;
+    private resubscribeAll;
+    private request;
+    private rejectAllPending;
+    private cancelReconnect;
+}
+
+export { HttpTransport, RemoteDatabase, RemoteError, type RemoteSubscription, type RemoteSubscriptionBuilder, RemoteSubscriptionBuilderImpl, SirannonClient, type Transport, WebSocketTransport };