@delali/sirannon-db 0.1.1

package/dist/sirannon-BJ8Yd1Uf.d.ts

@@ -0,0 +1,148 @@
+import { Q as QueryHookContext, g as ConnectionHookContext, c as BeforeSubscribeHook, H as HookConfig, M as MetricsConfig, l as QueryMetrics, h as ConnectionMetrics, C as CDCMetrics, P as Params, E as ExecuteResult, D as DatabaseOptions, p as SubscriptionBuilder, B as BackupScheduleOptions, b as BeforeQueryHook, A as AfterQueryHook, n as SirannonOptions, a as BeforeConnectHook, k as DatabaseOpenHook, j as DatabaseCloseHook } from './types-DArCObcu.js';
+import Database$1 from 'better-sqlite3';
+
+type HookEvent = 'beforeQuery' | 'afterQuery' | 'beforeConnect' | 'databaseOpen' | 'databaseClose' | 'beforeSubscribe';
+type SubscribeHookContext = Parameters<BeforeSubscribeHook>[0];
+interface HookEventContextMap {
+    beforeQuery: QueryHookContext;
+    afterQuery: QueryHookContext & {
+        durationMs: number;
+    };
+    beforeConnect: ConnectionHookContext;
+    databaseOpen: ConnectionHookContext;
+    databaseClose: ConnectionHookContext;
+    beforeSubscribe: SubscribeHookContext;
+}
+type HookHandler<E extends HookEvent> = (ctx: HookEventContextMap[E]) => void | Promise<void>;
+type HookDispose = () => void;
+
+declare class HookRegistry {
+    private hooks;
+    constructor(config?: HookConfig);
+    register<E extends HookEvent>(event: E, hook: HookHandler<E>): HookDispose;
+    invoke<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): Promise<void>;
+    invokeSync<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): void;
+    has(event: HookEvent): boolean;
+    count(event: HookEvent): number;
+    clear(event?: HookEvent): void;
+    private addHook;
+    private loadConfig;
+}
+
+declare class MetricsCollector {
+    private config;
+    constructor(config?: MetricsConfig);
+    trackQuery<T>(fn: () => T, context: Omit<QueryMetrics, 'durationMs' | 'error'>): T;
+    trackConnection(metrics: ConnectionMetrics): void;
+    trackCDCEvent(metrics: CDCMetrics): void;
+    get active(): boolean;
+}
+
+type SqliteDb = InstanceType<typeof Database$1>;
+declare class Transaction {
+    private readonly db;
+    private _lastInsertRowId;
+    constructor(db: SqliteDb);
+    query<T = Record<string, unknown>>(sql: string, params?: Params): T[];
+    execute(sql: string, params?: Params): ExecuteResult;
+    executeBatch(sql: string, paramsBatch: Params[]): ExecuteResult[];
+    get lastInsertRowId(): number | bigint;
+    static run<T>(db: SqliteDb, fn: (tx: Transaction) => T): T;
+}
+
+interface AppliedMigration {
+    version: number;
+    name: string;
+    applied_at: number;
+}
+interface Migration {
+    version: number;
+    name: string;
+    up: string | ((tx: Transaction) => void);
+    down?: string | ((tx: Transaction) => void);
+}
+interface AppliedMigrationEntry {
+    version: number;
+    name: string;
+}
+interface MigrationResult {
+    applied: AppliedMigrationEntry[];
+    skipped: number;
+}
+interface RollbackResult {
+    rolledBack: AppliedMigrationEntry[];
+}
+
+interface DatabaseInternals {
+    parentHooks?: HookRegistry;
+    metrics?: MetricsCollector;
+}
+declare class Database {
+    readonly id: string;
+    readonly path: string;
+    readonly readOnly: boolean;
+    private readonly pool;
+    private readonly closeListeners;
+    private _closed;
+    private changeTracker;
+    private subscriptionManager;
+    private stopCdcPolling;
+    private readonly cdcPollInterval;
+    private readonly cdcRetention;
+    private readonly hookRegistry;
+    private readonly parentHooks;
+    private readonly metricsCollector;
+    private readonly backupManager;
+    private readonly backupScheduler;
+    private readonly scheduledBackupCancellers;
+    constructor(id: string, path: string, options?: DatabaseOptions, internals?: DatabaseInternals);
+    query<T = Record<string, unknown>>(sql: string, params?: Params): T[];
+    queryOne<T = Record<string, unknown>>(sql: string, params?: Params): T | undefined;
+    execute(sql: string, params?: Params): ExecuteResult;
+    executeBatch(sql: string, paramsBatch: Params[]): ExecuteResult[];
+    transaction<T>(fn: (tx: Transaction) => T): T;
+    watch(table: string): void;
+    unwatch(table: string): void;
+    on(table: string): SubscriptionBuilder;
+    migrate(input: string | Migration[]): MigrationResult;
+    rollback(input: string | Migration[], version?: number): RollbackResult;
+    backup(destPath: string): void;
+    scheduleBackup(options: BackupScheduleOptions): void;
+    loadExtension(extensionPath: string): void;
+    onBeforeQuery(hook: BeforeQueryHook): void;
+    onAfterQuery(hook: AfterQueryHook): void;
+    addCloseListener(fn: () => void): void;
+    close(): void;
+    get closed(): boolean;
+    get readerCount(): number;
+    private ensureOpen;
+    private ensureCdc;
+    private ensureCdcPolling;
+    private stopCdcPollingLoop;
+    private fireBeforeQueryHooks;
+    private fireAfterQueryHooks;
+}
+
+declare class Sirannon {
+    readonly options?: SirannonOptions | undefined;
+    private readonly dbs;
+    private _shutdown;
+    private readonly hookRegistry;
+    private readonly metricsCollector;
+    private readonly lifecycleManager;
+    constructor(options?: SirannonOptions | undefined);
+    open(id: string, path: string, options?: DatabaseOptions): Database;
+    close(id: string): void;
+    get(id: string): Database | undefined;
+    has(id: string): boolean;
+    databases(): Map<string, Database>;
+    shutdown(): void;
+    onBeforeQuery(hook: BeforeQueryHook): void;
+    onAfterQuery(hook: AfterQueryHook): void;
+    onBeforeConnect(hook: BeforeConnectHook): void;
+    onDatabaseOpen(hook: DatabaseOpenHook): void;
+    onDatabaseClose(hook: DatabaseCloseHook): void;
+    private ensureRunning;
+}
+
+export { type AppliedMigration as A, Database as D, type HookDispose as H, type Migration as M, type RollbackResult as R, Sirannon as S, Transaction as T, type MigrationResult as a, type AppliedMigrationEntry as b, type HookEvent as c, type HookEventContextMap as d, type HookHandler as e, HookRegistry as f, MetricsCollector as g, type SubscribeHookContext as h };

package/dist/types-DArCObcu.d.ts

@@ -0,0 +1,186 @@
+/** Query parameter types: named (object) or positional (array). */
+type Params = Record<string, unknown> | unknown[];
+/** Result returned by mutation statements (INSERT, UPDATE, DELETE). */
+interface ExecuteResult {
+    changes: number;
+    lastInsertRowId: number | bigint;
+}
+/** CDC operation type. */
+type ChangeOperation = 'insert' | 'update' | 'delete';
+/** Event emitted when a watched table row changes. */
+interface ChangeEvent<T = Record<string, unknown>> {
+    type: ChangeOperation;
+    table: string;
+    row: T;
+    oldRow?: T;
+    seq: bigint;
+    timestamp: number;
+}
+/** Context passed to query hooks. */
+interface QueryHookContext {
+    databaseId: string;
+    sql: string;
+    params?: Params;
+    metadata?: Record<string, unknown>;
+}
+/** Hook invoked before a query is executed. Throw to deny. */
+type BeforeQueryHook = (ctx: QueryHookContext) => void | Promise<void>;
+/** Hook invoked after a query is executed. */
+type AfterQueryHook = (ctx: QueryHookContext & {
+    durationMs: number;
+}) => void | Promise<void>;
+/** Context passed to connection hooks. */
+interface ConnectionHookContext {
+    databaseId: string;
+    path: string;
+}
+/** Hook invoked before a database connection is established. */
+type BeforeConnectHook = (ctx: ConnectionHookContext) => void | Promise<void>;
+/** Hook invoked when a database is opened. */
+type DatabaseOpenHook = (ctx: ConnectionHookContext) => void | Promise<void>;
+/** Hook invoked when a database is closed. */
+type DatabaseCloseHook = (ctx: ConnectionHookContext) => void | Promise<void>;
+/** Hook invoked before a subscription is created. Throw to deny. */
+type BeforeSubscribeHook = (ctx: {
+    databaseId: string;
+    table: string;
+    filter?: Record<string, unknown>;
+}) => void | Promise<void>;
+/** Aggregated hook configuration. */
+interface HookConfig {
+    onBeforeQuery?: BeforeQueryHook | BeforeQueryHook[];
+    onAfterQuery?: AfterQueryHook | AfterQueryHook[];
+    onBeforeConnect?: BeforeConnectHook | BeforeConnectHook[];
+    onDatabaseOpen?: DatabaseOpenHook | DatabaseOpenHook[];
+    onDatabaseClose?: DatabaseCloseHook | DatabaseCloseHook[];
+    onBeforeSubscribe?: BeforeSubscribeHook | BeforeSubscribeHook[];
+}
+/** Metrics emitted after a query completes. */
+interface QueryMetrics {
+    databaseId: string;
+    sql: string;
+    durationMs: number;
+    rowsReturned?: number;
+    changes?: number;
+    error?: boolean;
+}
+/** Metrics emitted when a connection opens or closes. */
+interface ConnectionMetrics {
+    databaseId: string;
+    path: string;
+    readerCount: number;
+    event: 'open' | 'close';
+}
+/** Metrics emitted when a CDC event is dispatched. */
+interface CDCMetrics {
+    databaseId: string;
+    table: string;
+    operation: ChangeOperation;
+    subscriberCount: number;
+}
+/** Callbacks for metrics collection. */
+interface MetricsConfig {
+    onQueryComplete?: (metrics: QueryMetrics) => void;
+    onConnectionOpen?: (metrics: ConnectionMetrics) => void;
+    onConnectionClose?: (metrics: ConnectionMetrics) => void;
+    onCDCEvent?: (metrics: CDCMetrics) => void;
+}
+/** Configuration for automatic database lifecycle management. */
+interface LifecycleConfig {
+    autoOpen?: {
+        resolver: (id: string) => {
+            path: string;
+            options?: DatabaseOptions;
+        } | undefined;
+    };
+    /** Milliseconds before an idle database is closed. 0 = disabled. */
+    idleTimeout?: number;
+    /** Maximum number of concurrently open databases. 0 = unlimited. */
+    maxOpen?: number;
+}
+/** Options for opening a single database. */
+interface DatabaseOptions {
+    /** Open the database in read-only mode. */
+    readOnly?: boolean;
+    /** Number of read connections in the pool. Default: 4. */
+    readPoolSize?: number;
+    /** Enable WAL mode. Default: true. */
+    walMode?: boolean;
+    /** CDC polling interval in milliseconds. Default: 50. */
+    cdcPollInterval?: number;
+    /** CDC retention period in milliseconds. Default: 3_600_000 (1 hour). */
+    cdcRetention?: number;
+}
+/** Top-level options for the Sirannon database registry. */
+interface SirannonOptions {
+    hooks?: HookConfig;
+    metrics?: MetricsConfig;
+    lifecycle?: LifecycleConfig;
+}
+/** Options for scheduled backups. */
+interface BackupScheduleOptions {
+    /** Cron expression (e.g., '0 * * * *' for hourly). */
+    cron: string;
+    /** Directory to store backup files. */
+    destDir: string;
+    /** Maximum number of backup files to keep. Default: 5. */
+    maxFiles?: number;
+    /** Called when a scheduled backup fails. Without this, errors are silently discarded. */
+    onError?: (error: Error) => void;
+}
+/** Builder for creating CDC subscriptions with optional filters. */
+interface SubscriptionBuilder {
+    filter(conditions: Record<string, unknown>): SubscriptionBuilder;
+    subscribe(callback: (event: ChangeEvent) => void): Subscription;
+}
+/** Handle for an active subscription. */
+interface Subscription {
+    unsubscribe(): void;
+}
+/** Context passed to the onRequest middleware hook. */
+interface RequestContext {
+    headers: Record<string, string>;
+    method: string;
+    path: string;
+    databaseId?: string;
+    remoteAddress: string;
+}
+/** Return this from an onRequest hook to deny the request with a custom response. */
+interface RequestDenial {
+    status: number;
+    code: string;
+    message: string;
+}
+/** Middleware hook for auth, rate limiting, and request validation. */
+type OnRequestHook = (ctx: RequestContext) => undefined | RequestDenial | Promise<undefined | RequestDenial>;
+/** Options for the standalone HTTP + WS server. */
+interface ServerOptions {
+    host?: string;
+    port?: number;
+    cors?: boolean | CorsOptions;
+    onRequest?: OnRequestHook;
+}
+/** CORS configuration. */
+interface CorsOptions {
+    origin?: string | string[];
+    methods?: string[];
+    headers?: string[];
+}
+/** Options for the mountable WebSocket handler. */
+interface WSHandlerOptions {
+    /** Maximum message size in bytes. Default: 1_048_576 (1 MB). */
+    maxPayloadLength?: number;
+}
+/** Options for the client SDK. */
+interface ClientOptions {
+    /** Transport to use. Default: 'websocket'. */
+    transport?: 'websocket' | 'http';
+    /** Custom headers for HTTP requests. */
+    headers?: Record<string, string>;
+    /** Reconnect on WebSocket disconnect. Default: true. */
+    autoReconnect?: boolean;
+    /** Reconnect interval in ms. Default: 1000. */
+    reconnectInterval?: number;
+}
+
+export type { AfterQueryHook as A, BackupScheduleOptions as B, CDCMetrics as C, DatabaseOptions as D, ExecuteResult as E, HookConfig as H, LifecycleConfig as L, MetricsConfig as M, OnRequestHook as O, Params as P, QueryHookContext as Q, RequestContext as R, ServerOptions as S, WSHandlerOptions as W, BeforeConnectHook as a, BeforeQueryHook as b, BeforeSubscribeHook as c, ChangeEvent as d, ChangeOperation as e, ClientOptions as f, ConnectionHookContext as g, ConnectionMetrics as h, CorsOptions as i, DatabaseCloseHook as j, DatabaseOpenHook as k, QueryMetrics as l, RequestDenial as m, SirannonOptions as n, Subscription as o, SubscriptionBuilder as p };

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@delali/sirannon-db",
+  "type": "module",
+  "version": "0.1.1",
+  "description": "A production-grade library that turns SQLite databases into a networked data layer with real-time subscriptions.",
+  "author": "Delali (https://sondelali.com)",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/assetcorp/sirannon-db",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/assetcorp/sirannon-db.git",
+    "directory": "packages/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/assetcorp/sirannon-db/issues"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "sqlite",
+    "database",
+    "realtime",
+    "subscriptions",
+    "websocket",
+    "embedded",
+    "better-sqlite3"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "bench": "node --expose-gc --import tsx benchmarks/run-all.ts",
+    "bench:micro": "node --expose-gc --import tsx benchmarks/micro/point-select.ts",
+    "bench:ycsb": "node --expose-gc --import tsx benchmarks/ycsb/workload-a.ts",
+    "bench:oltp": "node --expose-gc --import tsx benchmarks/oltp/tpc-c-lite.ts",
+    "bench:scaling": "node --expose-gc --import tsx benchmarks/scaling/concurrency.ts",
+    "bench:cdc": "node --expose-gc --import tsx benchmarks/sirannon/cdc-latency.ts",
+    "bench:docker": "node --import tsx benchmarks/run-docker.ts",
+    "bench:docker:e2e": "node --import tsx benchmarks/run-e2e.ts",
+    "bench:docker:engine": "node --expose-gc --import tsx benchmarks/run-engine.ts",
+    "bench:statistical": "node --expose-gc --import tsx benchmarks/run-statistical.ts",
+    "bench:charts": "python3 benchmarks/scripts/generate-charts.py benchmarks/results/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.mjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "better-sqlite3": "12.6.2",
+    "croner": "10.0.1",
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.58.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
+    "@types/node": "25.3.3",
+    "@types/pg": "8.11.10",
+    "@vitest/coverage-v8": "4.0.18",
+    "pg": "8.19.0",
+    "simple-statistics": "7.8.7",
+    "tinybench": "6.0.0",
+    "tsup": "8.5.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  }
+}