remult-sqlite-s3 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+import { SqlDatabase } from 'remult';
+import { Options, Database } from 'better-sqlite3';
+import { SqliteCoreDataProvider } from 'remult/remult-sqlite-core-js';
+
+/**
+ * Public types for BetterSqlite3S3DataProvider
+ */
+interface BetterSqlite3S3Options {
+    /** Path to SQLite database file */
+    file: string;
+    /** better-sqlite3 options (optional) */
+    sqliteOptions?: {
+        readonly?: boolean;
+        fileMustExist?: boolean;
+        timeout?: number;
+        verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
+        nativeBinding?: string;
+    };
+    s3: {
+        /** S3 bucket name */
+        bucket: string;
+        /**
+         * Unique database name (required)
+         * Used to namespace all S3 keys for this database.
+         * Must be unique per database to prevent data conflicts.
+         * Example: "myapp-users", "myapp-orders", "prod-main"
+         */
+        databaseName: string;
+        /** Optional key prefix prepended to all S3 keys (e.g., "databases/") */
+        keyPrefix?: string;
+        /** AWS region (default: "us-east-1") */
+        region?: string;
+        /** Custom endpoint for S3-compatible storage (MinIO, R2, Backblaze, etc.) */
+        endpoint?: string;
+        /** Explicit credentials (optional - uses AWS SDK default chain if not provided) */
+        credentials?: {
+            accessKeyId: string;
+            secretAccessKey: string;
+        };
+        /** Force path style for S3-compatible storage like MinIO */
+        forcePathStyle?: boolean;
+    };
+    sync?: {
+        /**
+         * Sync mode:
+         * - 'async': Fast writes, eventual durability (default)
+         * - 'sync': Wait for S3 confirmation on every write
+         */
+        mode?: 'async' | 'sync';
+        /** Sync WAL to S3 when it reaches this size in bytes (default: 1MB) */
+        walThreshold?: number;
+        /** Create full snapshot every N milliseconds (default: 5 minutes) */
+        snapshotInterval?: number;
+        /** S3 operation retry count (default: 3) */
+        maxRetries?: number;
+        /** Lock TTL in milliseconds (default: 60000) */
+        lockTtl?: number;
+        /** Lock refresh interval in milliseconds (default: 30000) */
+        lockRefresh?: number;
+        /** Force acquire lock even if another process holds it (use only in development) */
+        forceLock?: boolean;
+    };
+    /** Called on sync events (uploads, recoveries, errors) */
+    onEvent?: (event: S3SyncEvent) => void;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+type S3SyncEvent = {
+    type: 'wal_uploaded';
+    generation: string;
+    index: number;
+    size: number;
+} | {
+    type: 'snapshot_uploaded';
+    generation: string;
+    size: number;
+} | {
+    type: 'recovery_started';
+    generation: string;
+} | {
+    type: 'recovery_completed';
+    generation: string;
+    segments: number;
+} | {
+    type: 'lock_acquired';
+    lockId: string;
+} | {
+    type: 'lock_lost';
+    reason: string;
+} | {
+    type: 'sync_error';
+    error: Error;
+    context: string;
+    willRetry: boolean;
+} | {
+    type: 'initialized';
+    generation: string;
+    recovered: boolean;
+};
+interface S3Config {
+    bucket: string;
+    databaseName: string;
+    keyPrefix: string;
+    region: string;
+    endpoint?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    forcePathStyle?: boolean;
+}
+interface SyncConfig {
+    mode: 'async' | 'sync';
+    walThreshold: number;
+    snapshotInterval: number;
+    maxRetries: number;
+    lockTtl: number;
+    lockRefresh: number;
+    forceLock: boolean;
+}
+
+/**
+ * S3 Sync Manager
+ * Coordinates lock, WAL, and snapshot operations
+ */
+
+interface S3SyncManagerOptions {
+    dbPath: string;
+    sqliteOptions?: Options;
+    s3: S3Config;
+    sync: SyncConfig;
+    onEvent: (event: S3SyncEvent) => void;
+    verbose: boolean;
+}
+declare class S3SyncManager {
+    private s3;
+    private lock;
+    private walManager;
+    private recoveryManager;
+    private db;
+    private dbPath;
+    private sqliteOptions?;
+    private syncConfig;
+    private onEvent;
+    private verbose;
+    private generation;
+    private snapshotTimer;
+    private closed;
+    constructor(options: S3SyncManagerOptions);
+    /**
+     * Initialize the sync manager
+     * - Acquire lock
+     * - Recover from S3 if needed
+     * - Open database
+     * - Start sync timers
+     */
+    initialize(): Promise<Database>;
+    /**
+     * Called after write operations
+     */
+    onWrite(): Promise<void>;
+    /**
+     * Force sync WAL to S3
+     */
+    syncWal(): Promise<void>;
+    /**
+     * Force full sync (WAL + check for snapshot)
+     */
+    sync(): Promise<void>;
+    /**
+     * Create a full snapshot
+     */
+    snapshot(): Promise<void>;
+    /**
+     * Close the sync manager
+     */
+    close(): Promise<void>;
+    /**
+     * Get the current generation
+     */
+    getGeneration(): string;
+    private createGenerationInfo;
+    private updateGenerationInfo;
+    private startSnapshotTimer;
+    private stopSnapshotTimer;
+    private log;
+}
+
+/**
+ * BetterSqlite3S3DataProvider
+ * A Remult data provider that wraps better-sqlite3 with automatic S3 synchronization
+ */
+
+/**
+ * BetterSqlite3S3DataProvider
+ *
+ * A drop-in replacement for BetterSqlite3DataProvider with automatic S3 synchronization.
+ *
+ * Usage:
+ * ```typescript
+ * const provider = new BetterSqlite3S3DataProvider({
+ *   file: './mydb.sqlite',
+ *   s3: {
+ *     bucket: 'my-bucket',
+ *     databaseName: 'myapp-main',  // Required: unique name for this database
+ *     keyPrefix: 'databases/',     // Optional: prefix for all keys
+ *   },
+ * });
+ * await provider.init();
+ * const dataProvider = new SqlDatabase(provider);
+ * ```
+ */
+declare class BetterSqlite3S3DataProvider extends SqliteCoreDataProvider {
+    private db;
+    private syncManager;
+    private options;
+    private initialized;
+    private initPromise;
+    constructor(options: BetterSqlite3S3Options);
+    /**
+     * Async initialization - must be called before use
+     */
+    init(): Promise<void>;
+    private doInit;
+    /**
+     * Get the underlying database (for advanced use cases)
+     */
+    get rawDatabase(): Database;
+    /**
+     * Get the sync manager (for manual sync control)
+     */
+    get sync(): S3SyncManager;
+    /**
+     * Force sync to S3
+     */
+    forceSync(): Promise<void>;
+    /**
+     * Force a full snapshot
+     */
+    snapshot(): Promise<void>;
+    /**
+     * Close the database and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the provider is initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get the current generation ID
+     */
+    get generation(): string;
+    private ensureInitialized;
+    private applyDefaults;
+}
+
+/**
+ * remult-sqlite-s3
+ * A Remult data provider that syncs SQLite to S3 for serverless deployments
+ */
+
+/**
+ * Creates an S3-synced SQLite data provider for Remult.
+ * Handles initialization and graceful shutdown automatically.
+ *
+ * @example
+ * ```typescript
+ * import { remultApi } from 'remult/remult-express'
+ * import { createS3DataProvider } from 'remult-sqlite-s3'
+ *
+ * export const api = remultApi({
+ *   dataProvider: createS3DataProvider({
+ *     file: './mydb.sqlite',
+ *     s3: {
+ *       bucket: 'my-bucket',
+ *       databaseName: 'my-database',
+ *     },
+ *   }),
+ *   entities: [Task],
+ * })
+ * ```
+ */
+declare function createS3DataProvider(options: BetterSqlite3S3Options): () => Promise<SqlDatabase>;
+
+export { BetterSqlite3S3DataProvider, type BetterSqlite3S3Options, type S3Config, type S3SyncEvent, S3SyncManager, type SyncConfig, createS3DataProvider };