remult-sqlite-github 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,487 @@
+import { SqlImplementation, SqlCommand, EntityMetadata, FieldMetadata, SqlDatabase } from 'remult';
+import Database from 'better-sqlite3';
+
+/**
+ * Database type from better-sqlite3
+ */
+type DatabaseType = Database.Database;
+/**
+ * SQLite configuration options
+ */
+interface SqliteOptions {
+    /**
+     * Enable foreign key constraints
+     * @default true
+     */
+    foreignKeys?: boolean;
+    /**
+     * SQLite busy timeout in milliseconds
+     * @default 5000
+     */
+    busyTimeout?: number;
+    /**
+     * Additional PRAGMA statements to execute on connection
+     */
+    pragmas?: Record<string, string | number | boolean>;
+}
+/**
+ * GitHub authentication configuration
+ */
+interface GitHubAuthConfig {
+    /**
+     * Personal Access Token for authentication
+     * Use either token OR appId/privateKey/installationId
+     */
+    token?: string;
+    /**
+     * GitHub App ID for app-based authentication
+     */
+    appId?: number;
+    /**
+     * GitHub App private key (PEM format)
+     */
+    privateKey?: string;
+    /**
+     * GitHub App installation ID
+     */
+    installationId?: number;
+}
+/**
+ * GitHub repository configuration
+ */
+interface GitHubRepoConfig extends GitHubAuthConfig {
+    /**
+     * Repository owner (username or organization)
+     */
+    owner: string;
+    /**
+     * Repository name
+     */
+    repo: string;
+    /**
+     * Branch to use for storage
+     * @default "main"
+     */
+    branch?: string;
+    /**
+     * Path prefix in repository
+     * @default ""
+     */
+    path?: string;
+}
+/**
+ * Sync configuration options
+ */
+interface SyncConfig {
+    /**
+     * Interval between automatic snapshots in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    snapshotInterval?: number;
+    /**
+     * Only create snapshot if there are changes
+     * @default true
+     */
+    snapshotOnChange?: boolean;
+    /**
+     * Enable WAL mode segmentation for incremental uploads
+     * @default false
+     */
+    enableWal?: boolean;
+    /**
+     * WAL file size threshold before creating new segment (bytes)
+     * Only applies when enableWal is true
+     * @default 1048576 (1MB)
+     */
+    walThreshold?: number;
+    /**
+     * Maximum retry attempts for failed operations
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Enable gzip compression for uploads
+     * @default false
+     */
+    compression?: boolean;
+}
+/**
+ * Main configuration options for the GitHub data provider
+ */
+interface BetterSqlite3GitHubOptions {
+    /**
+     * Local SQLite database file path
+     */
+    file: string;
+    /**
+     * SQLite configuration options
+     */
+    sqliteOptions?: SqliteOptions;
+    /**
+     * GitHub repository configuration
+     */
+    github: GitHubRepoConfig;
+    /**
+     * Sync configuration options
+     */
+    sync?: SyncConfig;
+    /**
+     * Event callback for sync events
+     */
+    onEvent?: (event: GitHubSyncEvent) => void;
+    /**
+     * Enable verbose logging
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Events emitted during sync operations
+ */
+type GitHubSyncEvent = {
+    type: "snapshot_uploaded";
+    sha: string;
+    size: number;
+    compressed: boolean;
+} | {
+    type: "wal_uploaded";
+    index: number;
+    size: number;
+} | {
+    type: "recovery_started";
+    branch: string;
+} | {
+    type: "recovery_completed";
+    sha: string;
+} | {
+    type: "commit_created";
+    sha: string;
+    message: string;
+} | {
+    type: "sync_error";
+    error: Error;
+    context: string;
+    willRetry: boolean;
+} | {
+    type: "rate_limit_hit";
+    resetAt: Date;
+    remaining: number;
+} | {
+    type: "initialized";
+    recovered: boolean;
+};
+/**
+ * Internal configuration for GitHubOperations
+ */
+interface GitHubConfig {
+    owner: string;
+    repo: string;
+    branch: string;
+    path: string;
+    token?: string;
+    appId?: number;
+    privateKey?: string;
+    installationId?: number;
+}
+/**
+ * Result of a file retrieval operation
+ */
+interface GitHubFileResult {
+    content: Buffer;
+    sha: string;
+    size: number;
+}
+/**
+ * File listing entry
+ */
+interface GitHubFileEntry {
+    name: string;
+    path: string;
+    sha: string;
+    size: number;
+    type: "file" | "dir";
+}
+/**
+ * Rate limit information
+ */
+interface RateLimitInfo {
+    remaining: number;
+    resetAt: Date;
+    limit: number;
+}
+/**
+ * Result of a recovery operation
+ */
+interface RecoveryResult {
+    recovered: boolean;
+    sha?: string;
+    size?: number;
+    compressed?: boolean;
+}
+/**
+ * Snapshot metadata stored alongside the database file
+ */
+interface SnapshotMetadata {
+    timestamp: string;
+    size: number;
+    checksum: string;
+    compressed: boolean;
+    walIndex?: number;
+}
+/**
+ * Internal sync manager options
+ */
+interface GitHubSyncManagerOptions {
+    dbPath: string;
+    github: GitHubConfig;
+    sqliteOptions?: SqliteOptions;
+    sync: Required<SyncConfig>;
+    onEvent?: (event: GitHubSyncEvent) => void;
+    verbose: boolean;
+}
+
+/**
+ * Orchestrates database sync operations with GitHub
+ */
+declare class GitHubSyncManager {
+    private options;
+    private github;
+    private recovery;
+    private db;
+    private hasChanges;
+    private currentSha;
+    private snapshotTimer;
+    private isInitialized;
+    private isClosed;
+    constructor(options: GitHubSyncManagerOptions);
+    /**
+     * Initialize the sync manager: recover from GitHub if needed, open database
+     */
+    initialize(): Promise<DatabaseType>;
+    /**
+     * Open the SQLite database with configured options
+     */
+    private openDatabase;
+    /**
+     * Called after database writes to track changes
+     */
+    onWrite(): Promise<void>;
+    /**
+     * Create a snapshot and upload to GitHub
+     */
+    snapshot(): Promise<void>;
+    /**
+     * Upload file with automatic conflict resolution
+     */
+    private uploadWithConflictRetry;
+    /**
+     * Force an immediate sync (alias for snapshot)
+     */
+    forceSync(): Promise<void>;
+    /**
+     * Close the sync manager and perform final sync
+     */
+    close(): Promise<void>;
+    /**
+     * Start the automatic snapshot timer
+     */
+    private startSnapshotTimer;
+    /**
+     * Get the raw database instance
+     */
+    get database(): DatabaseType | null;
+    /**
+     * Check if there are pending changes
+     */
+    get hasPendingChanges(): boolean;
+    /**
+     * Check if the manager is initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Emit an event if handler is registered
+     */
+    private emitEvent;
+    /**
+     * Log a message if verbose mode is enabled
+     */
+    private log;
+}
+
+/**
+ * GitHub REST API operations wrapper with retry logic and rate limit handling
+ */
+declare class GitHubOperations {
+    private config;
+    private maxRetries;
+    private cachedToken;
+    private tokenExpiry;
+    private onEvent?;
+    private verbose;
+    constructor(config: GitHubConfig, maxRetries?: number, onEvent?: (event: GitHubSyncEvent) => void, verbose?: boolean);
+    /**
+     * Get a file from the repository
+     */
+    getFile(path: string): Promise<GitHubFileResult | null>;
+    /**
+     * Get a large file using the blob API
+     */
+    private getBlob;
+    /**
+     * Create or update a file in the repository
+     * Returns the new commit SHA
+     */
+    putFile(path: string, content: Buffer, message: string, sha?: string): Promise<string>;
+    /**
+     * Delete a file from the repository
+     */
+    deleteFile(path: string, sha: string, message: string): Promise<void>;
+    /**
+     * List files in a directory
+     */
+    listFiles(path: string): Promise<GitHubFileEntry[]>;
+    /**
+     * Check current rate limit status
+     */
+    checkRateLimit(): Promise<RateLimitInfo>;
+    /**
+     * Ensure the branch exists, create if it doesn't
+     * For empty repos, we skip branch creation since files can be pushed directly
+     */
+    ensureBranch(): Promise<void>;
+    /**
+     * Get the full path including configured prefix
+     */
+    private getFullPath;
+    /**
+     * Make an authenticated fetch request
+     */
+    private fetch;
+    /**
+     * Get authentication token (PAT or GitHub App installation token)
+     */
+    private getAuthToken;
+    /**
+     * Generate a JWT for GitHub App authentication
+     */
+    private generateJWT;
+    /**
+     * Base64 URL encode a string
+     */
+    private base64UrlEncode;
+    /**
+     * Execute a function with retry logic and exponential backoff
+     */
+    private withRetry;
+    /**
+     * Handle rate limit headers from response
+     */
+    private handleRateLimitHeaders;
+    /**
+     * Sleep for the specified duration
+     */
+    private sleep;
+    /**
+     * Emit an event if handler is registered
+     */
+    private emitEvent;
+    /**
+     * Log a message if verbose mode is enabled
+     */
+    private log;
+}
+/**
+ * Custom error for conflict (SHA mismatch) situations
+ */
+declare class ConflictError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * A Remult data provider that syncs SQLite to GitHub
+ */
+declare class BetterSqlite3GitHubDataProvider implements SqlImplementation {
+    private syncManager;
+    private _isInitialized;
+    private initPromise;
+    private innerProvider;
+    constructor(options: BetterSqlite3GitHubOptions);
+    /**
+     * Initialize the data provider
+     * This must be called before using the provider
+     */
+    init(): Promise<void>;
+    private doInit;
+    /**
+     * Ensure the provider is initialized
+     */
+    private ensureInitialized;
+    private getProvider;
+    getLimitSqlSyntax(limit: number, offset: number): string;
+    createCommand(): SqlCommand;
+    transaction(action: (sql: SqlImplementation) => Promise<void>): Promise<void>;
+    entityIsUsedForTheFirstTime(entity: EntityMetadata): Promise<void>;
+    end(): Promise<void>;
+    get orderByNullsFirst(): boolean | undefined;
+    get afterMutation(): VoidFunction | undefined;
+    get supportsJsonColumnType(): boolean | undefined;
+    get doesNotSupportReturningSyntax(): boolean;
+    ensureSchema(entities: EntityMetadata<any>[]): Promise<void>;
+    wrapIdentifier(name: string): string;
+    addColumnSqlSyntax(x: FieldMetadata, dbName: string, isAlterTable: boolean): string;
+    /**
+     * Check if a SQL statement is a write operation
+     */
+    private isWriteOperation;
+    /**
+     * Force an immediate sync to GitHub
+     */
+    forceSync(): Promise<void>;
+    /**
+     * Create a snapshot and upload to GitHub
+     */
+    snapshot(): Promise<void>;
+    /**
+     * Close the provider and perform final sync
+     */
+    close(): Promise<void>;
+    /**
+     * Get the raw better-sqlite3 database instance
+     */
+    get rawDatabase(): DatabaseType | null;
+    /**
+     * Get the sync manager instance
+     */
+    get sync(): GitHubSyncManager;
+    /**
+     * Check if the provider is initialized
+     */
+    get isInitialized(): boolean;
+}
+
+/**
+ * Create a GitHub-synced SQLite data provider for Remult
+ *
+ * @param options - Configuration options for the provider
+ * @returns A factory function that creates an initialized SqlDatabase
+ *
+ * @example
+ * ```typescript
+ * import { createGitHubDataProvider } from "remult-sqlite-github";
+ *
+ * const api = remultApi({
+ *   dataProvider: createGitHubDataProvider({
+ *     file: "./mydb.sqlite",
+ *     github: {
+ *       owner: "your-username",
+ *       repo: "your-database-repo",
+ *       token: process.env.GITHUB_TOKEN,
+ *     },
+ *   }),
+ *   entities: [Task],
+ * });
+ * ```
+ */
+declare function createGitHubDataProvider(options: BetterSqlite3GitHubOptions): () => Promise<SqlDatabase>;
+
+export { BetterSqlite3GitHubDataProvider, type BetterSqlite3GitHubOptions, ConflictError, type DatabaseType, type GitHubAuthConfig, GitHubOperations, type GitHubRepoConfig, type GitHubSyncEvent, GitHubSyncManager, type RateLimitInfo, type RecoveryResult, type SnapshotMetadata, type SqliteOptions, type SyncConfig, createGitHubDataProvider };