@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/core/index.d.ts

@@ -1,295 +1,86 @@
-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;
-}
+export { B as BackupManager, a as BackupScheduler } from '../index-CLdNrcPz.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-CFTQ9TSn.js';
+import { S as SQLiteDriver, a as SQLiteConnection } from '../types-BFSsG77t.js';
+export { D as DriverCapabilities, O as OpenOptions, R as RunResult, b as SQLiteStatement } from '../types-BFSsG77t.js';
+import { D as Database } from '../database-BVY1GqE7.js';
+export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-BVY1GqE7.js';
+export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, S as SirannonError, T as TransactionError } from '../errors-C00ed08Q.js';
+import { D as DatabaseOptions, L as LifecycleConfig, P as Params, E as ExecuteResult } from '../types-D-74JiXb.js';
+export { A as AfterQueryHook, m as BackupScheduleOptions, a as BeforeConnectHook, B as BeforeQueryHook, g as BeforeSubscribeHook, j as CDCMetrics, C as ChangeEvent, n as ChangeOperation, o as ClientOptions, p as ClusterReadEndpointInfo, q as ClusterStatusInfo, f as ConnectionHookContext, i as ConnectionMetrics, r as CorsOptions, c as DatabaseCloseHook, b as DatabaseOpenHook, H as HookConfig, M as MetricsConfig, O as OnRequestHook, Q as QueryHookContext, h as QueryMetrics, k as QueryOptions, R as ReadConcern, s as ReadConcernLevel, t as ReplicationStatusInfo, u as RequestContext, v as RequestDenial, w as ServerExecutionTarget, x as ServerExecutionTargetResolver, d as ServerOptions, S as SirannonOptions, y as Subscription, l as SubscriptionBuilder, T as Transaction, e as WSHandlerOptions, W as WriteConcern, z as WriteConcernLevel } from '../types-D-74JiXb.js';
+import { M as Migration, a as MigrationResult, R as RollbackResult } from '../types-BeozgNPr.js';
+export { A as AppliedMigration, b as AppliedMigrationEntry } from '../types-BeozgNPr.js';
+export { S as Sirannon } from '../sirannon-Cd-lK6T0.js';
 
 interface ConnectionPoolOptions {
+    driver: SQLiteDriver;
     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;
+    private constructor();
+    static create(options: ConnectionPoolOptions): Promise<ConnectionPool>;
+    acquireReader(): SQLiteConnection;
+    acquireWriter(): SQLiteConnection;
     get readerCount(): number;
     get isReadOnly(): boolean;
-    loadExtension(extensionPath: string): void;
-    close(): void;
+    close(): Promise<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);
-}
+declare function defineDriver(config: SQLiteDriver): SQLiteDriver;
 
-/**
- * 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;
+    open: (id: string, path: string, options?: DatabaseOptions) => Promise<Database>;
+    close: (id: string) => Promise<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;
     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. */
+    resolve(id: string): Promise<Database | undefined>;
     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). */
+    checkIdle(): Promise<void>;
+    evict(): Promise<void>;
     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;
+    static run(conn: SQLiteConnection, migrations: Migration[]): Promise<MigrationResult>;
+    static rollback(conn: SQLiteConnection, migrations: Migration[], version?: number): Promise<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[];
+declare function query<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T[]>;
+declare function queryOne<T = Record<string, unknown>>(conn: SQLiteConnection, sql: string, params?: Params): Promise<T | undefined>;
+declare function execute(conn: SQLiteConnection, sql: string, params?: Params): Promise<ExecuteResult>;
+declare function executeBatch(conn: SQLiteConnection, sql: string, paramsBatch: Params[]): Promise<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 };
+export { ConnectionPool, type ConnectionPoolOptions, Database, DatabaseOptions, ExecuteResult, type LifecycleCallbacks, LifecycleConfig, LifecycleManager, Migration, MigrationResult, MigrationRunner, Params, RollbackResult, SQLiteConnection, SQLiteDriver, type TenantResolverOptions, createTenantResolver, defineDriver, execute, executeBatch, query, queryOne, sanitizeTenantId, tenantPath };