@delali/sirannon-db 0.1.1

package/dist/core/index.d.ts

@@ -0,0 +1,295 @@
+import Database from 'better-sqlite3';
+import { B as BackupScheduleOptions, D as DatabaseOptions, L as LifecycleConfig, P as Params, E as ExecuteResult } from '../types-DArCObcu.js';
+export { A as AfterQueryHook, a as BeforeConnectHook, b as BeforeQueryHook, c as BeforeSubscribeHook, C as CDCMetrics, d as ChangeEvent, e as ChangeOperation, f as ClientOptions, g as ConnectionHookContext, h as ConnectionMetrics, i as CorsOptions, j as DatabaseCloseHook, k as DatabaseOpenHook, H as HookConfig, M as MetricsConfig, O as OnRequestHook, Q as QueryHookContext, l as QueryMetrics, R as RequestContext, m as RequestDenial, S as ServerOptions, n as SirannonOptions, o as Subscription, p as SubscriptionBuilder, W as WSHandlerOptions } from '../types-DArCObcu.js';
+import { D as Database$1, M as Migration, a as MigrationResult, R as RollbackResult } from '../sirannon-BJ8Yd1Uf.js';
+export { A as AppliedMigration, b as AppliedMigrationEntry, H as HookDispose, c as HookEvent, d as HookEventContextMap, e as HookHandler, f as HookRegistry, g as MetricsCollector, S as Sirannon, h as SubscribeHookContext, T as Transaction } from '../sirannon-BJ8Yd1Uf.js';
+
+type SqliteDb$4 = InstanceType<typeof Database>;
+declare class BackupManager {
+    /**
+     * 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: SqliteDb$4, destPath: string): void;
+    /**
+     * 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(): string;
+    /**
+     * 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: string, maxFiles: number): void;
+}
+
+type SqliteDb$3 = InstanceType<typeof Database>;
+declare class BackupScheduler {
+    private readonly manager;
+    constructor(manager?: 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: SqliteDb$3, options: BackupScheduleOptions): () => void;
+}
+
+interface ConnectionPoolOptions {
+    path: string;
+    readOnly?: boolean;
+    readPoolSize?: number;
+    walMode?: boolean;
+}
+type SqliteDb$2 = InstanceType<typeof Database>;
+declare class ConnectionPool {
+    private readonly writer;
+    private readonly readers;
+    private readerIndex;
+    private closed;
+    constructor(options: ConnectionPoolOptions);
+    acquireReader(): SqliteDb$2;
+    acquireWriter(): SqliteDb$2;
+    get readerCount(): number;
+    get isReadOnly(): boolean;
+    loadExtension(extensionPath: string): void;
+    close(): void;
+}
+
+/**
+ * Base class for all sirannon-db errors. Extend this class to create
+ * domain-specific errors that carry a machine-readable {@link code}.
+ */
+declare class SirannonError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when a database ID cannot be resolved in the registry.
+ * This typically means the database was never opened or has already been closed.
+ */
+declare class DatabaseNotFoundError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when attempting to register a database with an ID that is already
+ * in use. Each database ID must be unique within the registry.
+ */
+declare class DatabaseAlreadyExistsError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when a write operation is attempted on a database that was opened
+ * in read-only mode.
+ */
+declare class ReadOnlyError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when SQLite fails to execute a statement. The {@link sql} property
+ * holds the original SQL string that caused the failure, which is useful for
+ * debugging and logging.
+ */
+declare class QueryError extends SirannonError {
+    readonly sql: string;
+    constructor(message: string, sql: string);
+}
+/**
+ * Thrown when a transaction cannot be committed or is forcibly rolled back.
+ * Check the message for the underlying cause.
+ */
+declare class TransactionError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a migration step fails. The {@link version} property identifies
+ * which schema version triggered the error so the failure can be pinpointed
+ * in the migration history.
+ */
+declare class MigrationError extends SirannonError {
+    readonly version: number;
+    constructor(message: string, version: number, code?: string);
+}
+/**
+ * Thrown when a before-hook explicitly rejects an operation. The optional
+ * `reason` string is surfaced in the message so callers can distinguish
+ * between different hook policies.
+ */
+declare class HookDeniedError extends SirannonError {
+    constructor(hookName: string, reason?: string);
+}
+/**
+ * Thrown when the change-data-capture pipeline encounters an unrecoverable
+ * error, such as a failed event dispatch or a corrupt change record.
+ */
+declare class CDCError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a backup operation fails, whether that is an online backup via
+ * the SQLite backup API or a file-level copy.
+ */
+declare class BackupError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the connection pool reaches its limit or is configured with
+ * invalid parameters such as a minimum size greater than the maximum.
+ */
+declare class ConnectionPoolError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when opening a new database would exceed the configured cap on
+ * concurrently open databases. Close an existing database before opening
+ * another one.
+ */
+declare class MaxDatabasesError extends SirannonError {
+    constructor(max: number);
+}
+/**
+ * Thrown when a native SQLite extension cannot be loaded. The `path` argument
+ * is the filesystem path passed to `load_extension`, and the optional `cause`
+ * string carries the error detail reported by SQLite.
+ */
+declare class ExtensionError extends SirannonError {
+    constructor(path: string, cause?: string);
+}
+
+/**
+ * Callbacks the LifecycleManager uses to interact with the database registry
+ * (Sirannon). Injected at construction to avoid circular dependencies.
+ */
+interface LifecycleCallbacks {
+    open: (id: string, path: string, options?: DatabaseOptions) => Database$1;
+    close: (id: string) => void;
+    count: () => number;
+    has: (id: string) => boolean;
+}
+/**
+ * Manages automatic database lifecycle: on-demand opening via a resolver,
+ * idle-timeout based closing, and LRU eviction when the maximum number of
+ * open databases is reached.
+ */
+declare class LifecycleManager {
+    private readonly config;
+    private readonly callbacks;
+    private readonly lastAccess;
+    private idleTimer;
+    private _disposed;
+    constructor(config: LifecycleConfig, callbacks: LifecycleCallbacks);
+    /**
+     * 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: string): Database$1 | undefined;
+    /** Record an access for the given database ID. */
+    markActive(id: string): void;
+    /**
+     * 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(): void;
+    /**
+     * Close the least-recently-used tracked database. Called internally
+     * by {@link resolve} when `maxOpen` capacity is reached.
+     */
+    evict(): void;
+    /** Remove a database from idle tracking (e.g. after an explicit close). */
+    untrack(id: string): void;
+    /** Whether this manager has been disposed. */
+    get disposed(): boolean;
+    /** The number of databases currently tracked for idle management. */
+    get trackedCount(): number;
+    /** Shut down the manager: stop the idle timer and clear all state. */
+    dispose(): void;
+    private ensureNotDisposed;
+}
+
+/**
+ * Options for {@link createTenantResolver}.
+ */
+interface TenantResolverOptions {
+    /** Base directory where tenant database files are stored. */
+    basePath: string;
+    /** File extension for database files. Default: `'.db'`. */
+    extension?: string;
+    /** Default options applied to every auto-opened tenant database. */
+    defaultOptions?: DatabaseOptions;
+}
+/**
+ * Validate and sanitize a tenant ID. Returns the ID unchanged when
+ * it passes validation, or `undefined` when it is invalid.
+ *
+ * Rules:
+ * - Must be 1–255 characters long
+ * - Must start with a letter or digit
+ * - May contain letters, digits, hyphens, and underscores
+ * - Must not contain `..` (redundant given the regex, but explicit)
+ */
+declare function sanitizeTenantId(id: string): string | undefined;
+/**
+ * Build a filesystem path for a tenant database.
+ *
+ * @throws {Error} when the tenant ID fails validation.
+ */
+declare function tenantPath(basePath: string, tenantId: string, extension?: string): string;
+/**
+ * Create a resolver function suitable for {@link LifecycleConfig.autoOpen}.
+ * Maps tenant IDs to database file paths under a common base directory.
+ *
+ * Invalid tenant IDs (path traversal, special characters) cause the
+ * resolver to return `undefined`, preventing the database from opening.
+ */
+declare function createTenantResolver(options: TenantResolverOptions): (id: string) => {
+    path: string;
+    options?: DatabaseOptions;
+} | undefined;
+
+type SqliteDb$1 = InstanceType<typeof Database>;
+declare class MigrationRunner {
+    static run(db: SqliteDb$1, input: string | Migration[]): MigrationResult;
+    static rollback(db: SqliteDb$1, input: string | Migration[], version?: number): RollbackResult;
+    private static validateMigrations;
+    private static getAppliedVersions;
+}
+
+type SqliteDb = InstanceType<typeof Database>;
+declare function query<T = Record<string, unknown>>(db: SqliteDb, sql: string, params?: Params): T[];
+declare function queryOne<T = Record<string, unknown>>(db: SqliteDb, sql: string, params?: Params): T | undefined;
+declare function execute(db: SqliteDb, sql: string, params?: Params): ExecuteResult;
+declare function executeBatch(db: SqliteDb, sql: string, paramsBatch: Params[]): ExecuteResult[];
+
+export { BackupError, BackupManager, BackupScheduleOptions, BackupScheduler, CDCError, ConnectionPool, ConnectionPoolError, type ConnectionPoolOptions, Database$1 as Database, DatabaseAlreadyExistsError, DatabaseNotFoundError, DatabaseOptions, ExecuteResult, ExtensionError, HookDeniedError, type LifecycleCallbacks, LifecycleConfig, LifecycleManager, MaxDatabasesError, Migration, MigrationError, MigrationResult, MigrationRunner, Params, QueryError, ReadOnlyError, RollbackResult, SirannonError, type TenantResolverOptions, TransactionError, createTenantResolver, execute, executeBatch, query, queryOne, sanitizeTenantId, tenantPath };