@delali/sirannon-db 0.1.1

package/dist/core/index.mjs

@@ -0,0 +1,1346 @@
+import { BackupError, ConnectionPoolError, QueryError, MigrationError, ReadOnlyError, SubscriptionBuilderImpl, ExtensionError, SirannonError, ChangeTracker, SubscriptionManager, startPolling, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError } from '../chunk-VI4UP4RR.mjs';
+export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, SirannonError, TransactionError } from '../chunk-VI4UP4RR.mjs';
+import { existsSync, mkdirSync, rmSync, readdirSync, lstatSync, readFileSync, statSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { Cron } from 'croner';
+import Database from 'better-sqlite3';
+
+var BACKUP_FILE_PREFIX = "backup";
+function hasControlCharacters(s) {
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code <= 31 && code !== 9 && code !== 10 && code !== 13) {
+      return true;
+    }
+  }
+  return false;
+}
+var BackupManager = class {
+  /**
+   * Creates a one-shot backup of the database using VACUUM INTO.
+   * Produces a fresh, defragmented copy at the specified destination path.
+   *
+   * The destination file must not already exist. Parent directories are
+   * created automatically when missing.
+   *
+   * Note: there is a narrow TOCTOU window between the existence check and
+   * the VACUUM INTO statement. In the unlikely event that another process
+   * creates a file at the same path during that window, VACUUM INTO may
+   * silently overwrite it depending on the SQLite version.
+   */
+  backup(db, destPath) {
+    if (hasControlCharacters(destPath)) {
+      throw new BackupError("Backup path contains invalid characters");
+    }
+    const resolved = resolve(destPath);
+    const dir = dirname(resolved);
+    if (!existsSync(dir)) {
+      try {
+        mkdirSync(dir, { recursive: true });
+      } catch (err) {
+        throw new BackupError(
+          `Failed to create backup directory '${dir}': ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    if (existsSync(resolved)) {
+      throw new BackupError(`Backup destination '${destPath}' already exists`);
+    }
+    const escaped = resolved.replace(/'/g, "''");
+    try {
+      db.exec(`VACUUM INTO '${escaped}'`);
+    } catch (err) {
+      try {
+        rmSync(resolved, { force: true });
+      } catch {
+      }
+      throw new BackupError(`Backup to '${destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  /**
+   * Generates a timestamped backup filename.
+   *
+   * Format: `backup-YYYY-MM-DDTHH-MM-SS-mmmZ.db`
+   *
+   * Colons and dots in the ISO timestamp are replaced with hyphens so the
+   * filename is safe on every major filesystem.
+   */
+  generateFilename() {
+    const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    return `${BACKUP_FILE_PREFIX}-${ts}.db`;
+  }
+  /**
+   * Removes old backup files in {@link dir}, keeping the {@link maxFiles}
+   * most recent entries. Only files matching the `backup-*.db` naming
+   * convention are considered; other files in the directory are left alone.
+   *
+   * When {@link maxFiles} is zero or negative the method is a no-op.
+   * A non-existent directory is silently ignored.
+   */
+  rotate(dir, maxFiles) {
+    if (maxFiles <= 0) return;
+    const resolved = resolve(dir);
+    if (!existsSync(resolved)) return;
+    let entries;
+    try {
+      entries = readdirSync(resolved).filter((f) => f.startsWith(`${BACKUP_FILE_PREFIX}-`) && f.endsWith(".db")).map((f) => {
+        const filePath = join(resolved, f);
+        return { path: filePath, mtimeMs: lstatSync(filePath).mtimeMs };
+      }).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    } catch (err) {
+      throw new BackupError(
+        `Failed to list backup files in '${dir}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    for (const entry of entries.slice(maxFiles)) {
+      try {
+        rmSync(entry.path, { force: true });
+      } catch {
+      }
+    }
+  }
+};
+var DEFAULT_MAX_FILES = 5;
+var BackupScheduler = class {
+  manager;
+  constructor(manager) {
+    this.manager = manager ?? new BackupManager();
+  }
+  /**
+   * Schedules periodic backups on a cron expression.
+   *
+   * Each tick creates a timestamped backup file inside {@link options.destDir}
+   * and rotates old files so no more than {@link options.maxFiles} (default 5)
+   * are retained.
+   *
+   * Provide {@link options.onError} to receive notification when a scheduled
+   * backup fails. Without it, errors are silently discarded to prevent
+   * unhandled exceptions from crashing the process.
+   *
+   * The underlying timer is unreferenced so it won't keep the Node.js
+   * process alive on its own (consistent with the CDC polling timer).
+   *
+   * Returns a cancel function that stops the scheduled job immediately.
+   */
+  schedule(db, options) {
+    const { cron: cronExpr, destDir, maxFiles = DEFAULT_MAX_FILES, onError } = options;
+    const resolvedDir = resolve(destDir);
+    if (!existsSync(resolvedDir)) {
+      try {
+        mkdirSync(resolvedDir, { recursive: true });
+      } catch (err) {
+        throw new BackupError(
+          `Failed to create backup directory '${destDir}': ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    let job;
+    try {
+      job = new Cron(
+        cronExpr,
+        {
+          unref: true,
+          catch: (err) => {
+            if (onError) {
+              const error = err instanceof Error ? err : new BackupError(typeof err === "string" ? err : "Scheduled backup failed");
+              onError(error);
+            }
+          }
+        },
+        () => {
+          const filename = this.manager.generateFilename();
+          const destPath = join(resolvedDir, filename);
+          this.manager.backup(db, destPath);
+          this.manager.rotate(resolvedDir, maxFiles);
+        }
+      );
+    } catch (err) {
+      throw new BackupError(
+        `Invalid cron expression '${cronExpr}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return () => {
+      job.stop();
+    };
+  }
+};
+function closeAllSilently(connections) {
+  for (const conn of connections) {
+    if (!conn) continue;
+    try {
+      conn.close();
+    } catch {
+    }
+  }
+}
+var ConnectionPool = class {
+  writer;
+  readers;
+  readerIndex = 0;
+  closed = false;
+  constructor(options) {
+    const { path, readOnly = false, readPoolSize = 4, walMode = true } = options;
+    let writer = null;
+    const readers = [];
+    try {
+      if (!readOnly) {
+        writer = new Database(path);
+        if (walMode) {
+          writer.pragma("journal_mode = WAL");
+        }
+        writer.pragma("synchronous = NORMAL");
+        writer.pragma("foreign_keys = ON");
+        writer.pragma("busy_timeout = 5000");
+      }
+      const poolSize = Math.max(readPoolSize, 1);
+      for (let i = 0; i < poolSize; i++) {
+        const reader = new Database(path, { readonly: true });
+        readers.push(reader);
+        reader.pragma("foreign_keys = ON");
+      }
+    } catch (err) {
+      closeAllSilently([...readers, writer]);
+      throw err;
+    }
+    this.writer = writer;
+    this.readers = readers;
+  }
+  acquireReader() {
+    if (this.closed) {
+      throw new ConnectionPoolError("Connection pool is closed");
+    }
+    const reader = this.readers[this.readerIndex % this.readers.length];
+    this.readerIndex = (this.readerIndex + 1) % this.readers.length;
+    return reader;
+  }
+  acquireWriter() {
+    if (this.closed) {
+      throw new ConnectionPoolError("Connection pool is closed");
+    }
+    if (!this.writer) {
+      throw new ConnectionPoolError("No write connection available (database is read-only)");
+    }
+    return this.writer;
+  }
+  get readerCount() {
+    return this.readers.length;
+  }
+  get isReadOnly() {
+    return this.writer === null;
+  }
+  loadExtension(extensionPath) {
+    if (this.closed) {
+      throw new ConnectionPoolError("Connection pool is closed");
+    }
+    if (this.writer) {
+      this.writer.loadExtension(extensionPath);
+    }
+    for (const reader of this.readers) {
+      reader.loadExtension(extensionPath);
+    }
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    const errors = [];
+    for (const reader of this.readers) {
+      try {
+        reader.close();
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+    if (this.writer) {
+      try {
+        this.writer.close();
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+    if (errors.length > 0) {
+      throw new ConnectionPoolError(`Failed to close ${errors.length} connection(s)`);
+    }
+  }
+};
+
+// src/core/hooks/registry.ts
+var HOOK_CONFIG_MAP = {
+  onBeforeQuery: "beforeQuery",
+  onAfterQuery: "afterQuery",
+  onBeforeConnect: "beforeConnect",
+  onDatabaseOpen: "databaseOpen",
+  onDatabaseClose: "databaseClose",
+  onBeforeSubscribe: "beforeSubscribe"
+};
+var HookRegistry = class {
+  hooks = /* @__PURE__ */ new Map();
+  constructor(config) {
+    if (config) {
+      this.loadConfig(config);
+    }
+  }
+  register(event, hook) {
+    const stored = hook;
+    this.addHook(event, stored);
+    let disposed = false;
+    return () => {
+      if (disposed) return;
+      disposed = true;
+      const current = this.hooks.get(event);
+      if (!current) return;
+      const idx = current.indexOf(stored);
+      if (idx !== -1) current.splice(idx, 1);
+    };
+  }
+  async invoke(event, ctx) {
+    const list = this.hooks.get(event);
+    if (!list || list.length === 0) return;
+    const snapshot = list.slice();
+    for (const hook of snapshot) {
+      await hook(ctx);
+    }
+  }
+  invokeSync(event, ctx) {
+    const list = this.hooks.get(event);
+    if (!list || list.length === 0) return;
+    const snapshot = list.slice();
+    for (const hook of snapshot) {
+      const result = hook(ctx);
+      if (result != null && typeof result.then === "function") {
+        throw new Error(`Hook for '${event}' returned a Promise. Use invoke() for async hooks.`);
+      }
+    }
+  }
+  has(event) {
+    const list = this.hooks.get(event);
+    return list !== void 0 && list.length > 0;
+  }
+  count(event) {
+    return this.hooks.get(event)?.length ?? 0;
+  }
+  clear(event) {
+    if (event) {
+      this.hooks.delete(event);
+    } else {
+      this.hooks.clear();
+    }
+  }
+  addHook(event, hook) {
+    const list = this.hooks.get(event);
+    if (list) {
+      list.push(hook);
+    } else {
+      this.hooks.set(event, [hook]);
+    }
+  }
+  loadConfig(config) {
+    for (const [configKey, event] of Object.entries(HOOK_CONFIG_MAP)) {
+      const value = config[configKey];
+      if (!value) continue;
+      const hooks = Array.isArray(value) ? value : [value];
+      for (const hook of hooks) {
+        this.addHook(event, hook);
+      }
+    }
+  }
+};
+
+// src/core/query-executor.ts
+var STATEMENT_CACHE_CAPACITY = 128;
+var statementCaches = /* @__PURE__ */ new WeakMap();
+function getStatement(db, sql) {
+  let cache = statementCaches.get(db);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    statementCaches.set(db, cache);
+  }
+  const cached = cache.get(sql);
+  if (cached) {
+    cache.delete(sql);
+    cache.set(sql, cached);
+    return cached;
+  }
+  const stmt = db.prepare(sql);
+  cache.set(sql, stmt);
+  if (cache.size > STATEMENT_CACHE_CAPACITY) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== void 0) {
+      cache.delete(oldest);
+    }
+  }
+  return stmt;
+}
+function bindParams(params) {
+  if (params === void 0) return [];
+  if (Array.isArray(params)) return params;
+  return [params];
+}
+function query(db, sql, params) {
+  try {
+    const stmt = getStatement(db, sql);
+    return stmt.all(...bindParams(params));
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+function queryOne(db, sql, params) {
+  try {
+    const stmt = getStatement(db, sql);
+    return stmt.get(...bindParams(params));
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+function execute(db, sql, params) {
+  try {
+    const stmt = getStatement(db, sql);
+    const result = stmt.run(...bindParams(params));
+    return {
+      changes: result.changes,
+      lastInsertRowId: result.lastInsertRowid
+    };
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+function executeBatch(db, sql, paramsBatch) {
+  try {
+    const stmt = getStatement(db, sql);
+    const run = db.transaction(() => {
+      const results = [];
+      for (const params of paramsBatch) {
+        const result = stmt.run(...bindParams(params));
+        results.push({
+          changes: result.changes,
+          lastInsertRowId: result.lastInsertRowid
+        });
+      }
+      return results;
+    });
+    return run();
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+
+// src/core/transaction.ts
+var Transaction = class _Transaction {
+  constructor(db) {
+    this.db = db;
+  }
+  _lastInsertRowId = 0;
+  query(sql, params) {
+    return query(this.db, sql, params);
+  }
+  execute(sql, params) {
+    const result = execute(this.db, sql, params);
+    this._lastInsertRowId = result.lastInsertRowId;
+    return result;
+  }
+  executeBatch(sql, paramsBatch) {
+    const results = executeBatch(this.db, sql, paramsBatch);
+    if (results.length > 0) {
+      this._lastInsertRowId = results[results.length - 1].lastInsertRowId;
+    }
+    return results;
+  }
+  get lastInsertRowId() {
+    return this._lastInsertRowId;
+  }
+  static run(db, fn) {
+    const tx = new _Transaction(db);
+    return db.transaction(() => fn(tx))();
+  }
+};
+var MIGRATION_FILENAME_PATTERN = /^(\d+)_(\w+)\.(up|down)\.sql$/;
+function scanDirectory(dirPath) {
+  if (dirPath.includes("\0")) {
+    throw new MigrationError("Migration path contains null bytes", 0, "MIGRATION_VALIDATION_ERROR");
+  }
+  const segments = dirPath.split(/[/\\]/);
+  if (segments.includes("..")) {
+    throw new MigrationError(
+      "Migration path must not contain directory traversal segments",
+      0,
+      "MIGRATION_VALIDATION_ERROR"
+    );
+  }
+  const resolvedPath = resolve(dirPath);
+  let stat;
+  try {
+    stat = statSync(resolvedPath);
+  } catch {
+    throw new MigrationError(`Migrations path does not exist: ${resolvedPath}`, 0);
+  }
+  if (!stat.isDirectory()) {
+    throw new MigrationError(`Migrations path is not a directory: ${resolvedPath}`, 0);
+  }
+  const entries = readdirSync(resolvedPath, { withFileTypes: true });
+  const grouped = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const match = MIGRATION_FILENAME_PATTERN.exec(entry.name);
+    if (!match) continue;
+    const version = parseInt(match[1], 10);
+    const name = match[2];
+    const direction = match[3];
+    if (!Number.isFinite(version) || version <= 0 || !Number.isSafeInteger(version)) {
+      throw new MigrationError(`Invalid migration version: ${match[1]}`, version, "MIGRATION_VALIDATION_ERROR");
+    }
+    const existing = grouped.get(version);
+    if (existing && existing.name !== name) {
+      throw new MigrationError(
+        `Duplicate migration version ${version}: '${existing.name}' and '${name}'`,
+        version,
+        "MIGRATION_DUPLICATE_VERSION"
+      );
+    }
+    const filePath = join(resolvedPath, entry.name);
+    if (!existing) {
+      grouped.set(version, {
+        name,
+        [direction === "up" ? "upPath" : "downPath"]: filePath
+      });
+    } else {
+      if (direction === "up") existing.upPath = filePath;
+      else existing.downPath = filePath;
+    }
+  }
+  const results = [];
+  for (const [version, entry] of grouped) {
+    if (!entry.upPath) {
+      throw new MigrationError(
+        `Migration version ${version} (${entry.name}) is missing an .up.sql file`,
+        version,
+        "MIGRATION_VALIDATION_ERROR"
+      );
+    }
+    results.push({
+      version,
+      name: entry.name,
+      upPath: entry.upPath,
+      downPath: entry.downPath ?? null
+    });
+  }
+  results.sort((a, b) => a.version - b.version);
+  return results;
+}
+function readUpMigrations(scanned) {
+  return scanned.map((entry) => {
+    const sql = readFileSync(entry.upPath, "utf-8").trim();
+    if (sql.length === 0) {
+      throw new MigrationError(`Migration file is empty: ${entry.upPath}`, entry.version, "MIGRATION_VALIDATION_ERROR");
+    }
+    return {
+      version: entry.version,
+      name: entry.name,
+      up: sql
+    };
+  });
+}
+function readDownMigrations(scanned, versions) {
+  const versionSet = new Set(versions);
+  const filtered = scanned.filter((s) => versionSet.has(s.version));
+  return filtered.map((entry) => {
+    if (!entry.downPath) {
+      throw new MigrationError(
+        `Migration version ${entry.version} (${entry.name}) has no .down.sql file`,
+        entry.version,
+        "MIGRATION_NO_DOWN"
+      );
+    }
+    const downSql = readFileSync(entry.downPath, "utf-8").trim();
+    if (downSql.length === 0) {
+      throw new MigrationError(
+        `Down migration file is empty: ${entry.downPath}`,
+        entry.version,
+        "MIGRATION_VALIDATION_ERROR"
+      );
+    }
+    return {
+      version: entry.version,
+      name: entry.name,
+      up: "",
+      down: downSql
+    };
+  });
+}
+
+// src/core/migrations/runner.ts
+var CREATE_TRACKING_TABLE = `
+  CREATE TABLE IF NOT EXISTS _sirannon_migrations (
+    version INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    applied_at REAL NOT NULL DEFAULT (unixepoch('subsec'))
+  )
+`;
+var MigrationRunner = class _MigrationRunner {
+  static run(db, input) {
+    db.exec(CREATE_TRACKING_TABLE);
+    const migrations = typeof input === "string" ? readUpMigrations(scanDirectory(input)) : _MigrationRunner.validateMigrations(input);
+    const applied = _MigrationRunner.getAppliedVersions(db);
+    const pending = migrations.filter((m) => !applied.has(m.version));
+    if (pending.length === 0) {
+      return { applied: [], skipped: migrations.length };
+    }
+    const insertMigration = db.prepare("INSERT INTO _sirannon_migrations (version, name) VALUES (?, ?)");
+    const appliedEntries = [];
+    db.transaction(() => {
+      for (const migration of pending) {
+        try {
+          if (typeof migration.up === "string") {
+            db.exec(migration.up);
+          } else {
+            migration.up(new Transaction(db));
+          }
+        } catch (err) {
+          if (err instanceof MigrationError) throw err;
+          throw new MigrationError(
+            `Migration ${migration.version}_${migration.name} failed: ${err instanceof Error ? err.message : String(err)}`,
+            migration.version
+          );
+        }
+        insertMigration.run(migration.version, migration.name);
+        appliedEntries.push({ version: migration.version, name: migration.name });
+      }
+    })();
+    return {
+      applied: appliedEntries,
+      skipped: migrations.length - pending.length
+    };
+  }
+  static rollback(db, input, version) {
+    if (version !== void 0 && (!Number.isSafeInteger(version) || version < 0)) {
+      throw new MigrationError(
+        `Invalid rollback target version: ${version}`,
+        typeof version === "number" && Number.isFinite(version) ? version : 0,
+        "MIGRATION_VALIDATION_ERROR"
+      );
+    }
+    db.exec(CREATE_TRACKING_TABLE);
+    const appliedRows = db.prepare("SELECT version, name FROM _sirannon_migrations ORDER BY version DESC").all();
+    if (appliedRows.length === 0) {
+      return { rolledBack: [] };
+    }
+    let rollbackSet;
+    if (version === void 0) {
+      rollbackSet = [appliedRows[0]];
+    } else {
+      rollbackSet = appliedRows.filter((row) => row.version > version);
+    }
+    if (rollbackSet.length === 0) {
+      return { rolledBack: [] };
+    }
+    const rollbackVersions = rollbackSet.map((r) => r.version);
+    let downByVersion;
+    if (typeof input === "string") {
+      const scanned = scanDirectory(input);
+      const downMigrations = readDownMigrations(scanned, rollbackVersions);
+      downByVersion = new Map(downMigrations.map((m) => [m.version, m]));
+    } else {
+      const inputByVersion = new Map(input.map((m) => [m.version, m]));
+      downByVersion = /* @__PURE__ */ new Map();
+      for (const v of rollbackVersions) {
+        const m = inputByVersion.get(v);
+        if (!m || m.down === void 0) {
+          throw new MigrationError(`Migration version ${v} has no down migration`, v, "MIGRATION_NO_DOWN");
+        }
+        downByVersion.set(v, m);
+      }
+    }
+    const deleteMigration = db.prepare("DELETE FROM _sirannon_migrations WHERE version = ?");
+    const rolledBackEntries = [];
+    db.transaction(() => {
+      for (const entry of rollbackSet) {
+        const migration = downByVersion.get(entry.version);
+        if (!migration) {
+          throw new MigrationError(
+            `No down migration found for version ${entry.version}`,
+            entry.version,
+            "MIGRATION_ROLLBACK_ERROR"
+          );
+        }
+        try {
+          if (typeof migration.down === "string") {
+            db.exec(migration.down);
+          } else {
+            migration.down?.(new Transaction(db));
+          }
+        } catch (err) {
+          if (err instanceof MigrationError) throw err;
+          throw new MigrationError(
+            `Rollback of migration ${entry.version}_${entry.name} failed: ${err instanceof Error ? err.message : String(err)}`,
+            entry.version,
+            "MIGRATION_ROLLBACK_ERROR"
+          );
+        }
+        deleteMigration.run(entry.version);
+        rolledBackEntries.push({ version: entry.version, name: entry.name });
+      }
+    })();
+    return { rolledBack: rolledBackEntries };
+  }
+  static validateMigrations(migrations) {
+    const seenVersions = /* @__PURE__ */ new Map();
+    for (const m of migrations) {
+      if (!Number.isSafeInteger(m.version) || m.version <= 0) {
+        throw new MigrationError(
+          `Invalid migration version: ${m.version}`,
+          typeof m.version === "number" && Number.isFinite(m.version) ? m.version : 0,
+          "MIGRATION_VALIDATION_ERROR"
+        );
+      }
+      if (!/^\w+$/.test(m.name)) {
+        throw new MigrationError(`Invalid migration name: '${m.name}'`, m.version, "MIGRATION_VALIDATION_ERROR");
+      }
+      const existing = seenVersions.get(m.version);
+      if (existing) {
+        throw new MigrationError(
+          `Duplicate migration version ${m.version}: '${existing}' and '${m.name}'`,
+          m.version,
+          "MIGRATION_DUPLICATE_VERSION"
+        );
+      }
+      seenVersions.set(m.version, m.name);
+      if (typeof m.up === "string" && m.up.trim().length === 0) {
+        throw new MigrationError(
+          `Migration ${m.version}_${m.name} has empty up SQL`,
+          m.version,
+          "MIGRATION_VALIDATION_ERROR"
+        );
+      }
+      if (m.down !== void 0 && typeof m.down === "string" && m.down.trim().length === 0) {
+        throw new MigrationError(
+          `Migration ${m.version}_${m.name} has empty down SQL`,
+          m.version,
+          "MIGRATION_VALIDATION_ERROR"
+        );
+      }
+    }
+    return [...migrations].sort((a, b) => a.version - b.version);
+  }
+  static getAppliedVersions(db) {
+    const rows = db.prepare("SELECT version FROM _sirannon_migrations ORDER BY version").all();
+    return new Set(rows.map((r) => r.version));
+  }
+};
+
+// src/core/database.ts
+var Database2 = class {
+  id;
+  path;
+  readOnly;
+  pool;
+  closeListeners = [];
+  _closed = false;
+  changeTracker = null;
+  subscriptionManager = null;
+  stopCdcPolling = null;
+  cdcPollInterval;
+  cdcRetention;
+  hookRegistry = new HookRegistry();
+  parentHooks;
+  metricsCollector;
+  backupManager = new BackupManager();
+  backupScheduler = new BackupScheduler(this.backupManager);
+  scheduledBackupCancellers = [];
+  constructor(id, path, options, internals) {
+    this.id = id;
+    this.path = path;
+    this.readOnly = options?.readOnly ?? false;
+    this.cdcPollInterval = options?.cdcPollInterval ?? 50;
+    this.cdcRetention = options?.cdcRetention ?? 36e5;
+    this.parentHooks = internals?.parentHooks ?? null;
+    this.metricsCollector = internals?.metrics ?? null;
+    this.pool = new ConnectionPool({
+      path,
+      readOnly: this.readOnly,
+      readPoolSize: options?.readPoolSize ?? 4,
+      walMode: options?.walMode ?? true
+    });
+  }
+  query(sql, params) {
+    this.ensureOpen();
+    this.fireBeforeQueryHooks(sql, params);
+    const start = performance.now();
+    try {
+      const reader = this.pool.acquireReader();
+      if (this.metricsCollector) {
+        return this.metricsCollector.trackQuery(() => query(reader, sql, params), {
+          databaseId: this.id,
+          sql
+        });
+      }
+      return query(reader, sql, params);
+    } finally {
+      this.fireAfterQueryHooks(sql, params, performance.now() - start);
+    }
+  }
+  queryOne(sql, params) {
+    this.ensureOpen();
+    this.fireBeforeQueryHooks(sql, params);
+    const start = performance.now();
+    try {
+      const reader = this.pool.acquireReader();
+      if (this.metricsCollector) {
+        return this.metricsCollector.trackQuery(() => queryOne(reader, sql, params), {
+          databaseId: this.id,
+          sql
+        });
+      }
+      return queryOne(reader, sql, params);
+    } finally {
+      this.fireAfterQueryHooks(sql, params, performance.now() - start);
+    }
+  }
+  execute(sql, params) {
+    this.ensureOpen();
+    this.fireBeforeQueryHooks(sql, params);
+    const start = performance.now();
+    try {
+      const writer = this.pool.acquireWriter();
+      if (this.metricsCollector) {
+        return this.metricsCollector.trackQuery(() => execute(writer, sql, params), {
+          databaseId: this.id,
+          sql
+        });
+      }
+      return execute(writer, sql, params);
+    } finally {
+      this.fireAfterQueryHooks(sql, params, performance.now() - start);
+    }
+  }
+  executeBatch(sql, paramsBatch) {
+    this.ensureOpen();
+    this.fireBeforeQueryHooks(sql);
+    const start = performance.now();
+    try {
+      const writer = this.pool.acquireWriter();
+      if (this.metricsCollector) {
+        return this.metricsCollector.trackQuery(() => executeBatch(writer, sql, paramsBatch), {
+          databaseId: this.id,
+          sql
+        });
+      }
+      return executeBatch(writer, sql, paramsBatch);
+    } finally {
+      this.fireAfterQueryHooks(sql, void 0, performance.now() - start);
+    }
+  }
+  transaction(fn) {
+    this.ensureOpen();
+    const writer = this.pool.acquireWriter();
+    return Transaction.run(writer, fn);
+  }
+  watch(table) {
+    this.ensureOpen();
+    if (this.readOnly) {
+      throw new ReadOnlyError(this.id);
+    }
+    this.ensureCdc();
+    const writer = this.pool.acquireWriter();
+    this.changeTracker?.watch(writer, table);
+    this.ensureCdcPolling();
+  }
+  unwatch(table) {
+    this.ensureOpen();
+    if (!this.changeTracker) return;
+    const writer = this.pool.acquireWriter();
+    this.changeTracker.unwatch(writer, table);
+    if (this.changeTracker.watchedTables.size === 0) {
+      this.stopCdcPollingLoop();
+    }
+  }
+  on(table) {
+    this.ensureOpen();
+    this.ensureCdc();
+    const manager = this.subscriptionManager;
+    if (!manager) throw new Error("subscriptionManager not initialized");
+    return new SubscriptionBuilderImpl(table, manager);
+  }
+  migrate(input) {
+    this.ensureOpen();
+    const writer = this.pool.acquireWriter();
+    return MigrationRunner.run(writer, input);
+  }
+  rollback(input, version) {
+    this.ensureOpen();
+    const writer = this.pool.acquireWriter();
+    return MigrationRunner.rollback(writer, input, version);
+  }
+  backup(destPath) {
+    this.ensureOpen();
+    const writer = this.pool.acquireWriter();
+    this.backupManager.backup(writer, destPath);
+  }
+  scheduleBackup(options) {
+    this.ensureOpen();
+    const writer = this.pool.acquireWriter();
+    const cancel = this.backupScheduler.schedule(writer, options);
+    this.scheduledBackupCancellers.push(cancel);
+  }
+  loadExtension(extensionPath) {
+    this.ensureOpen();
+    if (!extensionPath || extensionPath.includes("\0")) {
+      throw new ExtensionError(extensionPath || "", "Extension path is empty or contains null bytes");
+    }
+    const segments = extensionPath.split(/[/\\]/);
+    if (segments.includes("..")) {
+      throw new ExtensionError(extensionPath, "Extension path must not contain directory traversal segments");
+    }
+    const resolved = resolve(extensionPath);
+    try {
+      this.pool.loadExtension(resolved);
+    } catch (err) {
+      throw new ExtensionError(extensionPath, err instanceof Error ? err.message : String(err));
+    }
+  }
+  onBeforeQuery(hook) {
+    this.hookRegistry.register("beforeQuery", hook);
+  }
+  onAfterQuery(hook) {
+    this.hookRegistry.register("afterQuery", hook);
+  }
+  addCloseListener(fn) {
+    this.ensureOpen();
+    this.closeListeners.push(fn);
+  }
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this.stopCdcPollingLoop();
+    for (const cancel of this.scheduledBackupCancellers) {
+      try {
+        cancel();
+      } catch {
+      }
+    }
+    this.scheduledBackupCancellers.length = 0;
+    let poolError;
+    try {
+      this.pool.close();
+    } catch (err) {
+      poolError = err;
+    }
+    for (const fn of this.closeListeners) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+    if (poolError) {
+      throw poolError;
+    }
+  }
+  get closed() {
+    return this._closed;
+  }
+  get readerCount() {
+    return this.pool.readerCount;
+  }
+  ensureOpen() {
+    if (this._closed) {
+      throw new SirannonError(`Database '${this.id}' is closed`, "DATABASE_CLOSED");
+    }
+  }
+  ensureCdc() {
+    if (!this.changeTracker) {
+      this.changeTracker = new ChangeTracker({ retention: this.cdcRetention });
+    }
+    if (!this.subscriptionManager) {
+      this.subscriptionManager = new SubscriptionManager();
+    }
+  }
+  ensureCdcPolling() {
+    if (this.stopCdcPolling) return;
+    if (!this.changeTracker || !this.subscriptionManager) return;
+    const writer = this.pool.acquireWriter();
+    this.stopCdcPolling = startPolling(writer, this.changeTracker, this.subscriptionManager, this.cdcPollInterval);
+  }
+  stopCdcPollingLoop() {
+    if (this.stopCdcPolling) {
+      this.stopCdcPolling();
+      this.stopCdcPolling = null;
+    }
+  }
+  fireBeforeQueryHooks(sql, params) {
+    const hasParent = this.parentHooks?.has("beforeQuery");
+    const hasLocal = this.hookRegistry.has("beforeQuery");
+    if (!hasParent && !hasLocal) return;
+    const ctx = { databaseId: this.id, sql, params };
+    this.parentHooks?.invokeSync("beforeQuery", ctx);
+    this.hookRegistry.invokeSync("beforeQuery", ctx);
+  }
+  fireAfterQueryHooks(sql, params, durationMs) {
+    const hasParent = this.parentHooks?.has("afterQuery");
+    const hasLocal = this.hookRegistry.has("afterQuery");
+    if (!hasParent && !hasLocal) return;
+    const ctx = { databaseId: this.id, sql, params, durationMs };
+    try {
+      this.parentHooks?.invokeSync("afterQuery", ctx);
+    } catch {
+    }
+    try {
+      this.hookRegistry.invokeSync("afterQuery", ctx);
+    } catch {
+    }
+  }
+};
+
+// src/core/lifecycle/manager.ts
+var LifecycleManager = class {
+  config;
+  callbacks;
+  lastAccess = /* @__PURE__ */ new Map();
+  idleTimer = null;
+  _disposed = false;
+  constructor(config, callbacks) {
+    this.config = config;
+    this.callbacks = callbacks;
+    const timeout = config.idleTimeout;
+    if (timeout && timeout > 0) {
+      const interval = Math.min(Math.max(Math.floor(timeout / 2), 100), 6e4);
+      this.idleTimer = setInterval(() => this.checkIdle(), interval);
+      if (typeof this.idleTimer === "object" && "unref" in this.idleTimer) {
+        this.idleTimer.unref();
+      }
+    }
+  }
+  /**
+   * Attempt to auto-open a database by ID using the configured resolver.
+   * Returns the opened Database, or `undefined` when no resolver is
+   * configured or the resolver does not recognise the ID.
+   *
+   * Throws {@link MaxDatabasesError} when the registry is at capacity and
+   * eviction cannot free a slot.
+   */
+  resolve(id) {
+    this.ensureNotDisposed();
+    const resolver = this.config.autoOpen?.resolver;
+    if (!resolver) return void 0;
+    const resolved = resolver(id);
+    if (!resolved) return void 0;
+    const maxOpen = this.config.maxOpen;
+    if (maxOpen && maxOpen > 0 && this.callbacks.count() >= maxOpen) {
+      this.evict();
+      if (this.callbacks.count() >= maxOpen) {
+        throw new MaxDatabasesError(maxOpen);
+      }
+    }
+    const db = this.callbacks.open(id, resolved.path, resolved.options);
+    this.markActive(id);
+    return db;
+  }
+  /** Record an access for the given database ID. */
+  markActive(id) {
+    if (!this._disposed) {
+      this.lastAccess.set(id, Date.now());
+    }
+  }
+  /**
+   * Close every database whose last access was longer ago than the
+   * configured idle timeout. Also cleans up tracking entries for
+   * databases that were closed externally.
+   */
+  checkIdle() {
+    const timeout = this.config.idleTimeout;
+    if (!timeout || timeout <= 0) return;
+    const now = Date.now();
+    const toRemove = [];
+    const toClose = [];
+    for (const [id, lastTime] of this.lastAccess) {
+      if (!this.callbacks.has(id)) {
+        toRemove.push(id);
+        continue;
+      }
+      if (now - lastTime >= timeout) {
+        toClose.push(id);
+      }
+    }
+    for (const id of toClose) {
+      try {
+        this.callbacks.close(id);
+      } catch {
+      }
+      toRemove.push(id);
+    }
+    for (const id of toRemove) {
+      this.lastAccess.delete(id);
+    }
+  }
+  /**
+   * Close the least-recently-used tracked database. Called internally
+   * by {@link resolve} when `maxOpen` capacity is reached.
+   */
+  evict() {
+    let oldestId = null;
+    let oldestTime = Infinity;
+    const stale = [];
+    for (const [id, time] of this.lastAccess) {
+      if (!this.callbacks.has(id)) {
+        stale.push(id);
+        continue;
+      }
+      if (time < oldestTime) {
+        oldestTime = time;
+        oldestId = id;
+      }
+    }
+    for (const id of stale) {
+      this.lastAccess.delete(id);
+    }
+    if (oldestId) {
+      try {
+        this.callbacks.close(oldestId);
+      } catch {
+      }
+      this.lastAccess.delete(oldestId);
+    }
+  }
+  /** Remove a database from idle tracking (e.g. after an explicit close). */
+  untrack(id) {
+    this.lastAccess.delete(id);
+  }
+  /** Whether this manager has been disposed. */
+  get disposed() {
+    return this._disposed;
+  }
+  /** The number of databases currently tracked for idle management. */
+  get trackedCount() {
+    return this.lastAccess.size;
+  }
+  /** Shut down the manager: stop the idle timer and clear all state. */
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    if (this.idleTimer !== null) {
+      clearInterval(this.idleTimer);
+      this.idleTimer = null;
+    }
+    this.lastAccess.clear();
+  }
+  ensureNotDisposed() {
+    if (this._disposed) {
+      throw new SirannonError("LifecycleManager has been disposed", "LIFECYCLE_DISPOSED");
+    }
+  }
+};
+var SAFE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+var MAX_ID_LENGTH = 255;
+var MAX_FILENAME_LENGTH = 255;
+function sanitizeTenantId(id) {
+  if (!id || id.length > MAX_ID_LENGTH) return void 0;
+  if (!SAFE_ID_PATTERN.test(id)) return void 0;
+  return id;
+}
+function tenantPath(basePath, tenantId, extension = ".db") {
+  const sanitized = sanitizeTenantId(tenantId);
+  if (!sanitized) {
+    throw new Error(`Invalid tenant ID: '${tenantId}'`);
+  }
+  const filename = `${sanitized}${extension}`;
+  if (filename.length > MAX_FILENAME_LENGTH) {
+    throw new Error(`Tenant filename exceeds maximum length of ${MAX_FILENAME_LENGTH} characters`);
+  }
+  return join(basePath, filename);
+}
+function createTenantResolver(options) {
+  const ext = options.extension ?? ".db";
+  const defaultOpts = options.defaultOptions;
+  return (id) => {
+    const sanitized = sanitizeTenantId(id);
+    if (!sanitized) return void 0;
+    const filename = `${sanitized}${ext}`;
+    if (filename.length > MAX_FILENAME_LENGTH) return void 0;
+    return {
+      path: join(options.basePath, filename),
+      options: defaultOpts
+    };
+  };
+}
+
+// src/core/metrics/collector.ts
+var MetricsCollector = class {
+  config;
+  constructor(config) {
+    this.config = config ?? {};
+  }
+  trackQuery(fn, context) {
+    if (!this.config.onQueryComplete) {
+      return fn();
+    }
+    const start = performance.now();
+    let failed = false;
+    try {
+      return fn();
+    } catch (err) {
+      failed = true;
+      throw err;
+    } finally {
+      const durationMs = performance.now() - start;
+      try {
+        this.config.onQueryComplete({
+          ...context,
+          durationMs,
+          error: failed
+        });
+      } catch {
+      }
+    }
+  }
+  trackConnection(metrics) {
+    try {
+      if (metrics.event === "open") {
+        this.config.onConnectionOpen?.(metrics);
+      } else {
+        this.config.onConnectionClose?.(metrics);
+      }
+    } catch {
+    }
+  }
+  trackCDCEvent(metrics) {
+    try {
+      this.config.onCDCEvent?.(metrics);
+    } catch {
+    }
+  }
+  get active() {
+    return !!(this.config.onQueryComplete || this.config.onConnectionOpen || this.config.onConnectionClose || this.config.onCDCEvent);
+  }
+};
+
+// src/core/sirannon.ts
+var Sirannon = class {
+  constructor(options) {
+    this.options = options;
+    this.hookRegistry = new HookRegistry(options?.hooks);
+    this.metricsCollector = options?.metrics ? new MetricsCollector(options.metrics) : null;
+    this.lifecycleManager = options?.lifecycle ? new LifecycleManager(options.lifecycle, {
+      open: (id, path, opts) => this.open(id, path, opts),
+      close: (id) => this.close(id),
+      count: () => this.dbs.size,
+      has: (id) => this.dbs.has(id)
+    }) : null;
+  }
+  dbs = /* @__PURE__ */ new Map();
+  _shutdown = false;
+  hookRegistry;
+  metricsCollector;
+  lifecycleManager;
+  open(id, path, options) {
+    this.ensureRunning();
+    if (this.dbs.has(id)) {
+      throw new DatabaseAlreadyExistsError(id);
+    }
+    if (this.hookRegistry.has("beforeConnect")) {
+      this.hookRegistry.invokeSync("beforeConnect", { databaseId: id, path });
+    }
+    let db;
+    try {
+      db = new Database2(id, path, options, {
+        parentHooks: this.hookRegistry,
+        metrics: this.metricsCollector ?? void 0
+      });
+    } catch (err) {
+      if (err instanceof SirannonError) throw err;
+      throw new SirannonError(
+        `Failed to open database '${id}' at '${path}': ${err instanceof Error ? err.message : String(err)}`,
+        "DATABASE_OPEN_FAILED"
+      );
+    }
+    db.addCloseListener(() => {
+      this.dbs.delete(id);
+      this.lifecycleManager?.untrack(id);
+      if (this.hookRegistry.has("databaseClose")) {
+        try {
+          this.hookRegistry.invokeSync("databaseClose", { databaseId: id, path });
+        } catch {
+        }
+      }
+      this.metricsCollector?.trackConnection({
+        databaseId: id,
+        path,
+        readerCount: 0,
+        event: "close"
+      });
+    });
+    this.dbs.set(id, db);
+    this.lifecycleManager?.markActive(id);
+    if (this.hookRegistry.has("databaseOpen")) {
+      try {
+        this.hookRegistry.invokeSync("databaseOpen", { databaseId: id, path });
+      } catch {
+      }
+    }
+    this.metricsCollector?.trackConnection({
+      databaseId: id,
+      path,
+      readerCount: db.readerCount,
+      event: "open"
+    });
+    return db;
+  }
+  close(id) {
+    this.ensureRunning();
+    const db = this.dbs.get(id);
+    if (!db) {
+      throw new DatabaseNotFoundError(id);
+    }
+    db.close();
+  }
+  get(id) {
+    const db = this.dbs.get(id);
+    if (db) {
+      this.lifecycleManager?.markActive(id);
+      return db;
+    }
+    if (this._shutdown) return void 0;
+    return this.lifecycleManager?.resolve(id);
+  }
+  has(id) {
+    return this.dbs.has(id);
+  }
+  databases() {
+    return new Map(this.dbs);
+  }
+  shutdown() {
+    if (this._shutdown) return;
+    this._shutdown = true;
+    this.lifecycleManager?.dispose();
+    const errors = [];
+    const snapshot = [...this.dbs.values()];
+    for (const db of snapshot) {
+      try {
+        db.close();
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+    this.dbs.clear();
+    if (errors.length > 0) {
+      throw new SirannonError(`Shutdown completed with ${errors.length} error(s)`, "SHUTDOWN_ERROR");
+    }
+  }
+  onBeforeQuery(hook) {
+    this.hookRegistry.register("beforeQuery", hook);
+  }
+  onAfterQuery(hook) {
+    this.hookRegistry.register("afterQuery", hook);
+  }
+  onBeforeConnect(hook) {
+    this.hookRegistry.register("beforeConnect", hook);
+  }
+  onDatabaseOpen(hook) {
+    this.hookRegistry.register("databaseOpen", hook);
+  }
+  onDatabaseClose(hook) {
+    this.hookRegistry.register("databaseClose", hook);
+  }
+  ensureRunning() {
+    if (this._shutdown) {
+      throw new SirannonError("Sirannon has been shut down", "SHUTDOWN");
+    }
+  }
+};
+
+export { BackupManager, BackupScheduler, ConnectionPool, Database2 as Database, HookRegistry, LifecycleManager, MetricsCollector, MigrationRunner, Sirannon, Transaction, createTenantResolver, execute, executeBatch, query, queryOne, sanitizeTenantId, tenantPath };