noormme 1.0.0

package/dist/esm/dialect/sqlite/sqlite-auto-optimizer.js

@@ -0,0 +1,370 @@
+/// <reference types="./sqlite-auto-optimizer.d.ts" />
+import { sql } from '../../raw-builder/sql.js';
+/**
+ * SQLite Auto-Optimizer that automatically applies performance optimizations
+ * and provides intelligent recommendations for SQLite databases
+ */
+export class SQLiteAutoOptimizer {
+    logger;
+    static instance;
+    optimizationHistory = new Map();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    static getInstance(logger) {
+        if (!SQLiteAutoOptimizer.instance) {
+            SQLiteAutoOptimizer.instance = new SQLiteAutoOptimizer(logger);
+        }
+        return SQLiteAutoOptimizer.instance;
+    }
+    /**
+     * Get default optimization configuration
+     */
+    getDefaultConfig() {
+        return {
+            enableAutoPragma: true,
+            enableAutoIndexing: true,
+            enablePerformanceTuning: true,
+            enableBackupRecommendations: true,
+            slowQueryThreshold: 1000,
+            autoVacuumMode: 'INCREMENTAL',
+            journalMode: 'WAL',
+            synchronous: 'NORMAL',
+            cacheSize: -64000, // 64MB cache
+            tempStore: 'MEMORY'
+        };
+    }
+    /**
+     * Analyze current SQLite configuration and performance
+     */
+    async analyzeDatabase(db) {
+        try {
+            const [pageCount, pageSize, freelistCount, schemaVersion, userVersion, applicationId, cacheSize, synchronous, journalMode, autoVacuum, tempStore, foreignKeys] = await Promise.all([
+                this.getPragmaValue(db, 'page_count'),
+                this.getPragmaValue(db, 'page_size'),
+                this.getPragmaValue(db, 'freelist_count'),
+                this.getPragmaValue(db, 'schema_version'),
+                this.getPragmaValue(db, 'user_version'),
+                this.getPragmaValue(db, 'application_id'),
+                this.getPragmaValue(db, 'cache_size'),
+                this.getPragmaValue(db, 'synchronous'),
+                this.getPragmaValue(db, 'journal_mode'),
+                this.getPragmaValue(db, 'auto_vacuum'),
+                this.getPragmaValue(db, 'temp_store'),
+                this.getPragmaValue(db, 'foreign_keys')
+            ]);
+            // Run integrity check
+            const integrityResult = await sql `PRAGMA integrity_check`.execute(db);
+            const integrityCheck = integrityResult.rows.length === 1 &&
+                integrityResult.rows[0].integrity_check === 'ok';
+            return {
+                pageCount: Number(pageCount),
+                pageSize: Number(pageSize),
+                freelistCount: Number(freelistCount),
+                schemaVersion: Number(schemaVersion),
+                userVersion: Number(userVersion),
+                applicationId: Number(applicationId),
+                cacheSize: Number(cacheSize),
+                synchronous: Number(synchronous),
+                journalMode: String(journalMode),
+                autoVacuum: Number(autoVacuum),
+                tempStore: Number(tempStore),
+                foreignKeys: Number(foreignKeys),
+                integrityCheck
+            };
+        }
+        catch (error) {
+            this.logger.warn('Failed to analyze SQLite database:', error);
+            throw error;
+        }
+    }
+    /**
+     * Apply automatic optimizations based on configuration
+     */
+    async optimizeDatabase(db, config = this.getDefaultConfig()) {
+        const result = {
+            appliedOptimizations: [],
+            recommendations: [],
+            performanceImpact: 'low',
+            warnings: []
+        };
+        try {
+            // Analyze current state
+            const metrics = await this.analyzeDatabase(db);
+            // Apply pragma optimizations
+            if (config.enableAutoPragma) {
+                await this.applyPragmaOptimizations(db, config, metrics, result);
+            }
+            // Apply performance tuning
+            if (config.enablePerformanceTuning) {
+                await this.applyPerformanceTuning(db, config, metrics, result);
+            }
+            // Generate recommendations
+            await this.generateRecommendations(db, metrics, result);
+            // Store optimization history
+            const dbId = await this.getDatabaseId(db);
+            this.optimizationHistory.set(dbId, result);
+            this.logger.info(`Applied ${result.appliedOptimizations.length} SQLite optimizations`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error('Failed to optimize SQLite database:', error);
+            result.warnings.push(`Optimization failed: ${error}`);
+            return result;
+        }
+    }
+    /**
+     * Apply pragma-based optimizations
+     */
+    async applyPragmaOptimizations(db, config, metrics, result) {
+        const optimizations = [];
+        // Enable WAL mode for better concurrency
+        if (metrics.journalMode !== 'wal' && config.journalMode === 'WAL') {
+            try {
+                await sql `PRAGMA journal_mode = WAL`.execute(db);
+                optimizations.push('Enabled WAL mode for better concurrency');
+                result.performanceImpact = 'high';
+            }
+            catch (error) {
+                result.warnings.push('Failed to enable WAL mode');
+            }
+        }
+        // Set cache size
+        if (Math.abs(metrics.cacheSize) < Math.abs(config.cacheSize)) {
+            try {
+                await sql `PRAGMA cache_size = ${sql.lit(config.cacheSize)}`.execute(db);
+                optimizations.push(`Set cache size to ${config.cacheSize}`);
+                result.performanceImpact = 'medium';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set cache size');
+            }
+        }
+        // Enable foreign keys
+        if (metrics.foreignKeys === 0) {
+            try {
+                await sql `PRAGMA foreign_keys = ON`.execute(db);
+                optimizations.push('Enabled foreign key constraints');
+                result.performanceImpact = 'low';
+            }
+            catch (error) {
+                result.warnings.push('Failed to enable foreign keys');
+            }
+        }
+        // Set synchronous mode
+        const syncModes = ['OFF', 'NORMAL', 'FULL', 'EXTRA'];
+        const targetSync = syncModes.indexOf(config.synchronous);
+        if (metrics.synchronous !== targetSync) {
+            try {
+                await sql `PRAGMA synchronous = ${sql.lit(config.synchronous)}`.execute(db);
+                optimizations.push(`Set synchronous mode to ${config.synchronous}`);
+                result.performanceImpact = 'medium';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set synchronous mode');
+            }
+        }
+        // Set temp store
+        const tempStores = ['DEFAULT', 'FILE', 'MEMORY'];
+        const targetTemp = tempStores.indexOf(config.tempStore);
+        if (metrics.tempStore !== targetTemp) {
+            try {
+                await sql `PRAGMA temp_store = ${sql.lit(config.tempStore)}`.execute(db);
+                optimizations.push(`Set temp store to ${config.tempStore}`);
+                result.performanceImpact = 'low';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set temp store');
+            }
+        }
+        result.appliedOptimizations.push(...optimizations);
+    }
+    /**
+     * Apply performance tuning optimizations
+     */
+    async applyPerformanceTuning(db, config, metrics, result) {
+        const optimizations = [];
+        // Run ANALYZE for query optimization
+        try {
+            await sql `ANALYZE`.execute(db);
+            optimizations.push('Ran ANALYZE for query optimization');
+            result.performanceImpact = 'medium';
+        }
+        catch (error) {
+            result.warnings.push('Failed to run ANALYZE');
+        }
+        // Optimize database (SQLite 3.18+)
+        try {
+            await sql `PRAGMA optimize`.execute(db);
+            optimizations.push('Ran PRAGMA optimize for automatic tuning');
+            result.performanceImpact = 'low';
+        }
+        catch (error) {
+            // PRAGMA optimize is not available in older SQLite versions
+            this.logger.debug('PRAGMA optimize not available in this SQLite version');
+        }
+        // Set auto vacuum mode
+        const vacuumModes = ['NONE', 'FULL', 'INCREMENTAL'];
+        const targetVacuum = vacuumModes.indexOf(config.autoVacuumMode);
+        if (metrics.autoVacuum !== targetVacuum) {
+            try {
+                await sql `PRAGMA auto_vacuum = ${sql.lit(config.autoVacuumMode)}`.execute(db);
+                optimizations.push(`Set auto vacuum to ${config.autoVacuumMode}`);
+                result.performanceImpact = 'medium';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set auto vacuum mode');
+            }
+        }
+        result.appliedOptimizations.push(...optimizations);
+    }
+    /**
+     * Generate intelligent recommendations
+     */
+    async generateRecommendations(db, metrics, result) {
+        const recommendations = [];
+        // Check for large freelist (fragmentation)
+        if (metrics.freelistCount > 100) {
+            recommendations.push(`High fragmentation detected (${metrics.freelistCount} free pages). Consider running VACUUM to reclaim space.`);
+        }
+        // Check for integrity issues
+        if (!metrics.integrityCheck) {
+            recommendations.push('Database integrity check failed. Run PRAGMA integrity_check for details.');
+        }
+        // Check for missing indexes (simplified)
+        const tables = await this.getTableList(db);
+        for (const table of tables) {
+            const indexes = await this.getTableIndexes(db, table);
+            if (indexes.length === 0) {
+                recommendations.push(`Table '${table}' has no indexes. Consider adding indexes for frequently queried columns.`);
+            }
+        }
+        // Check cache efficiency
+        if (Math.abs(metrics.cacheSize) < 32000) {
+            recommendations.push('Consider increasing cache_size for better performance with larger databases.');
+        }
+        // Check for WAL mode benefits
+        if (metrics.journalMode !== 'wal') {
+            recommendations.push('Consider enabling WAL mode for better concurrent read performance.');
+        }
+        result.recommendations.push(...recommendations);
+    }
+    /**
+     * Get pragma value
+     */
+    async getPragmaValue(db, pragma) {
+        try {
+            const result = await sql `PRAGMA ${sql.id(pragma)}`.execute(db);
+            return result.rows[0]?.[pragma] ?? null;
+        }
+        catch (error) {
+            this.logger.debug(`Failed to get PRAGMA ${pragma}:`, error);
+            return null;
+        }
+    }
+    /**
+     * Get database identifier for history tracking
+     */
+    async getDatabaseId(db) {
+        try {
+            const result = await sql `PRAGMA database_list`.execute(db);
+            const mainDb = result.rows.find((db) => db.seq === 0);
+            return mainDb?.file || 'unknown';
+        }
+        catch (error) {
+            return 'unknown';
+        }
+    }
+    /**
+     * Get list of tables
+     */
+    async getTableList(db) {
+        try {
+            const result = await db
+                .selectFrom('sqlite_master')
+                .select('name')
+                .where('type', '=', 'table')
+                .where('name', 'not like', 'sqlite_%')
+                .execute();
+            return result.map(row => row.name);
+        }
+        catch (error) {
+            this.logger.debug('Failed to get table list:', error);
+            return [];
+        }
+    }
+    /**
+     * Get indexes for a table
+     */
+    async getTableIndexes(db, tableName) {
+        try {
+            const result = await sql `PRAGMA index_list(${sql.lit(tableName)})`.execute(db);
+            return result.rows || [];
+        }
+        catch (error) {
+            this.logger.debug(`Failed to get indexes for table ${tableName}:`, error);
+            return [];
+        }
+    }
+    /**
+     * Get optimization history for a database
+     */
+    getOptimizationHistory(dbId) {
+        if (!dbId)
+            return null;
+        return this.optimizationHistory.get(dbId) || null;
+    }
+    /**
+     * Clear optimization history
+     */
+    clearHistory() {
+        this.optimizationHistory.clear();
+    }
+    /**
+     * Get backup recommendations
+     */
+    async getBackupRecommendations(db) {
+        const recommendations = [];
+        const metrics = await this.analyzeDatabase(db);
+        // Check for WAL files
+        if (metrics.journalMode === 'wal') {
+            recommendations.push('When using WAL mode, ensure to backup both the main database file and WAL file for consistency.');
+        }
+        // Check database size
+        const dbSize = metrics.pageCount * metrics.pageSize;
+        if (dbSize > 100 * 1024 * 1024) { // 100MB
+            recommendations.push('For large databases, consider using SQLite backup API or .backup command for efficient backups.');
+        }
+        // Check for active transactions
+        recommendations.push('Perform backups during low-activity periods to minimize lock contention.');
+        return recommendations;
+    }
+    /**
+     * Suggest index optimizations based on query patterns
+     */
+    async suggestIndexOptimizations(db, queryPatterns) {
+        const suggestions = [];
+        // Analyze common WHERE clauses
+        const whereColumns = new Map();
+        for (const query of queryPatterns) {
+            const whereMatch = query.match(/WHERE\s+([^ORDER\s]+)/i);
+            if (whereMatch) {
+                const whereClause = whereMatch[1];
+                const columnMatches = whereClause.match(/(\w+)\s*[=<>]/g);
+                if (columnMatches) {
+                    for (const match of columnMatches) {
+                        const column = match.replace(/\s*[=<>].*/, '').trim();
+                        whereColumns.set(column, (whereColumns.get(column) || 0) + 1);
+                    }
+                }
+            }
+        }
+        // Suggest indexes for frequently queried columns
+        for (const [column, count] of whereColumns.entries()) {
+            if (count >= 3) {
+                suggestions.push(`Consider adding an index on '${column}' (used in ${count} queries)`);
+            }
+        }
+        return suggestions;
+    }
+}

package/dist/esm/dialect/sqlite/sqlite-dialect-config.d.ts

@@ -0,0 +1,41 @@
+import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * Config for the SQLite dialect.
+ */
+export interface SqliteDialectConfig {
+    /**
+     * An sqlite Database instance or a function that returns one.
+     *
+     * If a function is provided, it's called once when the first query is executed.
+     *
+     * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
+     */
+    database: SqliteDatabase | (() => Promise<SqliteDatabase>);
+    /**
+     * Called once when the first query is executed.
+     *
+     * This is a Kysely specific feature and does not come from the `better-sqlite3` module.
+     */
+    onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+}
+/**
+ * This interface is the subset of better-sqlite3 driver's `Database` class that
+ * kysely needs.
+ *
+ * We don't use the type from `better-sqlite3` here to not have a dependency to it.
+ *
+ * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
+ */
+export interface SqliteDatabase {
+    close(): void;
+    prepare(sql: string): SqliteStatement;
+}
+export interface SqliteStatement {
+    readonly reader: boolean;
+    all(parameters: ReadonlyArray<unknown>): unknown[];
+    run(parameters: ReadonlyArray<unknown>): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(parameters: ReadonlyArray<unknown>): IterableIterator<unknown>;
+}

package/dist/esm/dialect/sqlite/sqlite-dialect-config.js

@@ -0,0 +1,2 @@
+/// <reference types="./sqlite-dialect-config.d.ts" />
+export {};

package/dist/esm/dialect/sqlite/sqlite-dialect.d.ts

@@ -0,0 +1,55 @@
+import { Driver } from '../../driver/driver.js';
+import { Kysely } from '../../kysely.js';
+import { QueryCompiler } from '../../query-compiler/query-compiler.js';
+import { Dialect } from '../dialect.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
+import { DialectAdapter } from '../dialect-adapter.js';
+import { SqliteDialectConfig } from './sqlite-dialect-config.js';
+/**
+ * SQLite dialect that uses the [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3) library.
+ *
+ * The constructor takes an instance of {@link SqliteDialectConfig}.
+ *
+ * ```ts
+ * import Database from 'better-sqlite3'
+ *
+ * new SqliteDialect({
+ *   database: new Database('db.sqlite')
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `database`
+ * can be a function:
+ *
+ * ```ts
+ * import Database from 'better-sqlite3'
+ *
+ * new SqliteDialect({
+ *   database: async () => new Database('db.sqlite')
+ * })
+ * ```
+ */
+export declare class SqliteDialect implements Dialect {
+    #private;
+    constructor(config: SqliteDialectConfig);
+    /**
+     * Creates a driver for the dialect.
+     */
+    createDriver(): Driver;
+    /**
+     * Creates a query compiler for the dialect.
+     */
+    createQueryCompiler(): QueryCompiler;
+    /**
+     * Creates an adapter for the dialect.
+     */
+    createAdapter(): DialectAdapter;
+    /**
+     * Creates a database introspector that can be used to get database metadata
+     * such as the table names and column names of those tables.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}

package/dist/esm/dialect/sqlite/sqlite-dialect.js

@@ -0,0 +1,48 @@
+/// <reference types="./sqlite-dialect.d.ts" />
+import { SqliteDriver } from './sqlite-driver.js';
+import { SqliteQueryCompiler } from './sqlite-query-compiler.js';
+import { SqliteIntrospector } from './sqlite-introspector.js';
+import { SqliteAdapter } from './sqlite-adapter.js';
+import { freeze } from '../../util/object-utils.js';
+/**
+ * SQLite dialect that uses the [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3) library.
+ *
+ * The constructor takes an instance of {@link SqliteDialectConfig}.
+ *
+ * ```ts
+ * import Database from 'better-sqlite3'
+ *
+ * new SqliteDialect({
+ *   database: new Database('db.sqlite')
+ * })
+ * ```
+ *
+ * If you want the pool to only be created once it's first used, `database`
+ * can be a function:
+ *
+ * ```ts
+ * import Database from 'better-sqlite3'
+ *
+ * new SqliteDialect({
+ *   database: async () => new Database('db.sqlite')
+ * })
+ * ```
+ */
+export class SqliteDialect {
+    #config;
+    constructor(config) {
+        this.#config = freeze({ ...config });
+    }
+    createDriver() {
+        return new SqliteDriver(this.#config);
+    }
+    createQueryCompiler() {
+        return new SqliteQueryCompiler();
+    }
+    createAdapter() {
+        return new SqliteAdapter();
+    }
+    createIntrospector(db) {
+        return new SqliteIntrospector(db);
+    }
+}

package/dist/esm/dialect/sqlite/sqlite-driver.d.ts

@@ -0,0 +1,42 @@
+import { DatabaseConnection } from '../../driver/database-connection.js';
+import { Driver } from '../../driver/driver.js';
+import { QueryCompiler } from '../../query-compiler/query-compiler.js';
+import { SqliteDialectConfig } from './sqlite-dialect-config.js';
+export declare class SqliteDriver implements Driver {
+    #private;
+    constructor(config: SqliteDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     */
+    init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
+    acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
+    beginTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
+    commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
+    rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    savepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
+    rollbackToSavepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
+    releaseSavepoint(connection: DatabaseConnection, savepointName: string, compileQuery: QueryCompiler['compileQuery']): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
+    releaseConnection(): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
+    destroy(): Promise<void>;
+}