@delali/sirannon-db 0.1.1 → 0.1.4

package/dist/core/index.d.ts

@@ -1,88 +1,36 @@
-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-hXiis3N-.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 '../sirannon-B1oTfebD.js';
+export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as Sirannon, e as SubscribeHookContext } from '../sirannon-B1oTfebD.js';
+import { D as DatabaseOptions, L as LifecycleConfig, P as Params, E as ExecuteResult } from '../types-DtDutWRU.js';
+export { A as AfterQueryHook, e as BackupScheduleOptions, h as BeforeConnectHook, f as BeforeQueryHook, B as BeforeSubscribeHook, c as CDCMetrics, k as ChangeEvent, l as ChangeOperation, m as ClientOptions, C as ConnectionHookContext, b as ConnectionMetrics, n as CorsOptions, j as DatabaseCloseHook, i as DatabaseOpenHook, H as HookConfig, M as MetricsConfig, O as OnRequestHook, Q as QueryHookContext, a as QueryMetrics, R as RequestContext, o as RequestDenial, S as ServerOptions, g as SirannonOptions, p as Subscription, d as SubscriptionBuilder, W as WSHandlerOptions } from '../types-DtDutWRU.js';
+import { M as Migration, a as MigrationResult, R as RollbackResult } from '../types-DRkJlqex.js';
+export { A as AppliedMigration, b as AppliedMigrationEntry, T as Transaction } from '../types-DRkJlqex.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>;
 }
 
+declare function defineDriver(config: SQLiteDriver): SQLiteDriver;
+
 /**
  * Base class for all sirannon-db errors. Extend this class to create
  * domain-specific errors that carry a machine-readable {@link code}.
@@ -183,113 +131,53 @@ 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;
+    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 { BackupError, CDCError, ConnectionPool, ConnectionPoolError, type ConnectionPoolOptions, Database, DatabaseAlreadyExistsError, DatabaseNotFoundError, DatabaseOptions, ExecuteResult, ExtensionError, HookDeniedError, type LifecycleCallbacks, LifecycleConfig, LifecycleManager, MaxDatabasesError, Migration, MigrationError, MigrationResult, MigrationRunner, Params, QueryError, ReadOnlyError, RollbackResult, SQLiteConnection, SQLiteDriver, SirannonError, type TenantResolverOptions, TransactionError, createTenantResolver, defineDriver, execute, executeBatch, query, queryOne, sanitizeTenantId, tenantPath };