noormme 1.0.0

package/dist/esm/performance/query-analyzer.js

@@ -0,0 +1,260 @@
+/// <reference types="./query-analyzer.d.ts" />
+/**
+ * Analyzes query performance and provides warnings for optimization
+ */
+export class QueryAnalyzer {
+    db;
+    logger;
+    schemaInfo;
+    options;
+    queryHistory = [];
+    recentQueries = new Map();
+    maxHistorySize = 1000;
+    constructor(db, logger, schemaInfo, options = {}) {
+        this.db = db;
+        this.logger = logger;
+        this.schemaInfo = schemaInfo;
+        this.options = options;
+        this.options = {
+            enabled: process.env.NODE_ENV === 'development',
+            slowQueryThreshold: 1000, // 1 second
+            nPlusOneDetection: true,
+            missingIndexDetection: true,
+            largeResultSetThreshold: 1000,
+            ...options
+        };
+    }
+    /**
+     * Record a query execution for analysis
+     */
+    recordQuery(query, executionTime, resultCount, table) {
+        if (!this.options.enabled)
+            return;
+        const metrics = {
+            query: this.normalizeQuery(query),
+            executionTime,
+            timestamp: new Date(),
+            table,
+            operation: this.extractOperation(query)
+        };
+        this.queryHistory.push(metrics);
+        // Keep history size under control
+        if (this.queryHistory.length > this.maxHistorySize) {
+            this.queryHistory = this.queryHistory.slice(-this.maxHistorySize);
+        }
+        // Track recent queries for N+1 detection
+        const normalizedQuery = metrics.query;
+        if (!this.recentQueries.has(normalizedQuery)) {
+            this.recentQueries.set(normalizedQuery, []);
+        }
+        this.recentQueries.get(normalizedQuery).push(metrics);
+        // Clean up old recent queries (keep last 10 seconds)
+        const cutoff = new Date(Date.now() - 10000);
+        for (const [query, queries] of this.recentQueries.entries()) {
+            const recent = queries.filter(q => q.timestamp >= cutoff);
+            if (recent.length === 0) {
+                this.recentQueries.delete(query);
+            }
+            else {
+                this.recentQueries.set(query, recent);
+            }
+        }
+        // Analyze the query
+        this.analyzeQuery(metrics, resultCount);
+    }
+    /**
+     * Analyze a query for performance issues
+     */
+    analyzeQuery(metrics, resultCount) {
+        const warnings = [];
+        // Check for slow queries
+        if (this.options.slowQueryThreshold && metrics.executionTime > this.options.slowQueryThreshold) {
+            warnings.push({
+                type: 'slow_query',
+                message: `Slow query detected: ${metrics.executionTime}ms`,
+                suggestion: 'Consider adding indexes or optimizing the query',
+                query: metrics.query,
+                table: metrics.table,
+                severity: metrics.executionTime > this.options.slowQueryThreshold * 3 ? 'high' : 'medium'
+            });
+        }
+        // Check for N+1 queries
+        if (this.options.nPlusOneDetection) {
+            const nPlusOneWarning = this.detectNPlusOne(metrics);
+            if (nPlusOneWarning) {
+                warnings.push(nPlusOneWarning);
+            }
+        }
+        // Check for missing indexes
+        if (this.options.missingIndexDetection && metrics.table) {
+            const missingIndexWarning = this.checkForMissingIndexes(metrics);
+            if (missingIndexWarning) {
+                warnings.push(missingIndexWarning);
+            }
+        }
+        // Check for large result sets
+        if (resultCount && this.options.largeResultSetThreshold && resultCount > this.options.largeResultSetThreshold) {
+            warnings.push({
+                type: 'large_result_set',
+                message: `Large result set: ${resultCount} rows returned`,
+                suggestion: 'Consider using pagination or filtering to reduce result size',
+                query: metrics.query,
+                table: metrics.table,
+                severity: resultCount > this.options.largeResultSetThreshold * 5 ? 'high' : 'medium'
+            });
+        }
+        // Log warnings
+        for (const warning of warnings) {
+            this.logWarning(warning);
+        }
+    }
+    /**
+     * Detect N+1 query patterns
+     */
+    detectNPlusOne(metrics) {
+        const recentQueries = this.recentQueries.get(metrics.query) || [];
+        // Look for the same query executed multiple times in quick succession
+        if (recentQueries.length >= 5) {
+            const timeWindow = 5000; // 5 seconds
+            const recentInWindow = recentQueries.filter(q => Date.now() - q.timestamp.getTime() < timeWindow);
+            if (recentInWindow.length >= 5) {
+                return {
+                    type: 'n_plus_one',
+                    message: `Potential N+1 query detected: same query executed ${recentInWindow.length} times`,
+                    suggestion: 'Consider using joins or batch loading to reduce query count',
+                    query: metrics.query,
+                    table: metrics.table,
+                    severity: 'high'
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Check for missing indexes based on WHERE clauses
+     */
+    checkForMissingIndexes(metrics) {
+        if (!metrics.table || !metrics.query.includes('WHERE')) {
+            return null;
+        }
+        const table = this.schemaInfo.tables.find(t => t.name === metrics.table);
+        if (!table)
+            return null;
+        // Extract WHERE conditions (simplified parsing)
+        const whereMatch = metrics.query.match(/WHERE\s+([^ORDER\s]+)/i);
+        if (!whereMatch)
+            return null;
+        const whereClause = whereMatch[1];
+        const columnMatches = whereClause.match(/(\w+)\s*[=<>]/g);
+        if (!columnMatches)
+            return null;
+        // Check if columns used in WHERE have indexes
+        for (const match of columnMatches) {
+            const column = match.replace(/\s*[=<>].*/, '').trim();
+            // Skip if it's the primary key (automatically indexed)
+            if (table.primaryKey?.includes(column))
+                continue;
+            // Check if there's an index on this column
+            const hasIndex = table.indexes.some(index => index.columns.includes(column) || index.columns[0] === column);
+            if (!hasIndex) {
+                return {
+                    type: 'missing_index',
+                    message: `Column '${column}' used in WHERE clause may benefit from an index`,
+                    suggestion: `Consider adding an index on ${metrics.table}.${column}`,
+                    query: metrics.query,
+                    table: metrics.table,
+                    severity: 'medium'
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Normalize query for comparison (remove dynamic values)
+     */
+    normalizeQuery(query) {
+        return query
+            .replace(/\$\d+/g, '?') // Replace PostgreSQL parameters
+            .replace(/'[^']*'/g, '?') // Replace string literals
+            .replace(/\b\d+\b/g, '?') // Replace numbers
+            .replace(/\s+/g, ' ') // Normalize whitespace
+            .trim();
+    }
+    /**
+     * Extract operation type from query
+     */
+    extractOperation(query) {
+        const normalized = query.trim().toUpperCase();
+        if (normalized.startsWith('SELECT'))
+            return 'SELECT';
+        if (normalized.startsWith('INSERT'))
+            return 'INSERT';
+        if (normalized.startsWith('UPDATE'))
+            return 'UPDATE';
+        if (normalized.startsWith('DELETE'))
+            return 'DELETE';
+        return 'OTHER';
+    }
+    /**
+     * Log performance warning
+     */
+    logWarning(warning) {
+        const emoji = this.getWarningEmoji(warning.type);
+        const message = `${emoji} Performance Warning [${warning.severity.toUpperCase()}]: ${warning.message}`;
+        switch (warning.severity) {
+            case 'high':
+                this.logger.warn(message);
+                break;
+            case 'medium':
+                this.logger.info(message);
+                break;
+            case 'low':
+                this.logger.debug(message);
+                break;
+        }
+        this.logger.debug(`  Suggestion: ${warning.suggestion}`);
+        if (warning.query) {
+            this.logger.debug(`  Query: ${warning.query}`);
+        }
+    }
+    /**
+     * Get emoji for warning type
+     */
+    getWarningEmoji(type) {
+        const emojis = {
+            'n_plus_one': '🔄',
+            'missing_index': '📇',
+            'slow_query': '🐌',
+            'full_table_scan': '🔍',
+            'large_result_set': '📊'
+        };
+        return emojis[type] || '⚠️';
+    }
+    /**
+     * Get performance statistics
+     */
+    getPerformanceStats() {
+        const slowQueries = this.queryHistory.filter(q => q.executionTime > (this.options.slowQueryThreshold || 1000)).length;
+        const totalTime = this.queryHistory.reduce((sum, q) => sum + q.executionTime, 0);
+        const averageExecutionTime = this.queryHistory.length > 0 ? totalTime / this.queryHistory.length : 0;
+        return {
+            totalQueries: this.queryHistory.length,
+            averageExecutionTime,
+            slowQueries,
+            warningCount: {} // Would be populated by tracking warnings
+        };
+    }
+    /**
+     * Clear query history
+     */
+    clearHistory() {
+        this.queryHistory = [];
+        this.recentQueries.clear();
+    }
+    /**
+     * Update schema info for index checking
+     */
+    updateSchema(schemaInfo) {
+        this.schemaInfo = schemaInfo;
+    }
+}

package/dist/esm/plugin/camel-case/camel-case-plugin.d.ts

@@ -0,0 +1,170 @@
+import { QueryResult } from '../../driver/database-connection.js';
+import { RootOperationNode } from '../../query-compiler/query-compiler.js';
+import { UnknownRow } from '../../util/type-utils.js';
+import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+export interface CamelCasePluginOptions {
+    /**
+     * If true, camelCase is transformed into upper case SNAKE_CASE.
+     * For example `fooBar => FOO_BAR` and `FOO_BAR => fooBar`
+     *
+     * Defaults to false.
+     */
+    upperCase?: boolean;
+    /**
+     * If true, an underscore is added before each digit when converting
+     * camelCase to snake_case. For example `foo12Bar => foo_12_bar` and
+     * `foo_12_bar => foo12Bar`
+     *
+     * Defaults to false.
+     */
+    underscoreBeforeDigits?: boolean;
+    /**
+     * If true, an underscore is added between consecutive upper case
+     * letters when converting from camelCase to snake_case. For example
+     * `fooBAR => foo_b_a_r` and `foo_b_a_r => fooBAR`.
+     *
+     * Defaults to false.
+     */
+    underscoreBetweenUppercaseLetters?: boolean;
+    /**
+     * If true, nested object's keys will not be converted to camel case.
+     *
+     * Defaults to false.
+     */
+    maintainNestedObjectKeys?: boolean;
+}
+/**
+ * A plugin that converts snake_case identifiers in the database into
+ * camelCase in the JavaScript side.
+ *
+ * For example let's assume we have a table called `person_table`
+ * with columns `first_name` and `last_name` in the database. When
+ * using `CamelCasePlugin` we would setup Kysely like this:
+ *
+ * ```ts
+ * import * as Sqlite from 'better-sqlite3'
+ * import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
+ *
+ * interface CamelCasedDatabase {
+ *   userMetadata: {
+ *     firstName: string
+ *     lastName: string
+ *   }
+ * }
+ *
+ * const db = new Kysely<CamelCasedDatabase>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [new CamelCasePlugin()],
+ * })
+ *
+ * const person = await db.selectFrom('userMetadata')
+ *   .where('firstName', '=', 'Arnold')
+ *   .select(['firstName', 'lastName'])
+ *   .executeTakeFirst()
+ *
+ * if (person) {
+ *   console.log(person.firstName)
+ * }
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "first_name", "last_name" from "user_metadata" where "first_name" = ?
+ * ```
+ *
+ * As you can see from the example, __everything__ needs to be defined
+ * in camelCase in the TypeScript code: table names, columns, schemas,
+ * __everything__. When using the `CamelCasePlugin` Kysely works as if
+ * the database was defined in camelCase.
+ *
+ * There are various options you can give to the plugin to modify
+ * the way identifiers are converted. See {@link CamelCasePluginOptions}.
+ * If those options are not enough, you can override this plugin's
+ * `snakeCase` and `camelCase` methods to make the conversion exactly
+ * the way you like:
+ *
+ * ```ts
+ * class MyCamelCasePlugin extends CamelCasePlugin {
+ *   protected override snakeCase(str: string): string {
+ *     // ...
+ *
+ *     return str
+ *   }
+ *
+ *   protected override camelCase(str: string): string {
+ *     // ...
+ *
+ *     return str
+ *   }
+ * }
+ * ```
+ */
+export declare class CamelCasePlugin implements KyselyPlugin {
+    #private;
+    readonly opt: CamelCasePluginOptions;
+    constructor(opt?: CamelCasePluginOptions);
+    /**
+     * This is called for each query before it is executed. You can modify the query by
+     * transforming its {@link OperationNode} tree provided in {@link PluginTransformQueryArgs.node | args.node}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * import type {
+     *   KyselyPlugin,
+     *   QueryResult,
+     *   RootOperationNode,
+     *   UnknownRow
+     * } from 'kysely'
+     *
+     * interface MyData {
+     *   // ...
+     * }
+     * const data = new WeakMap<any, MyData>()
+     *
+     * const plugin = {
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     const something: MyData = {}
+     *
+     *     // ...
+     *
+     *     data.set(args.queryId, something)
+     *
+     *     // ...
+     *
+     *     return args.node
+     *   },
+     *
+     *   async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+     *     // ...
+     *
+     *     const something = data.get(args.queryId)
+     *
+     *     // ...
+     *
+     *     return args.result
+     *   }
+     * } satisfies KyselyPlugin
+     * ```
+     *
+     * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+    protected mapRow(row: UnknownRow): UnknownRow;
+    protected snakeCase(str: string): string;
+    protected camelCase(str: string): string;
+}

package/dist/esm/plugin/camel-case/camel-case-plugin.js

@@ -0,0 +1,119 @@
+/// <reference types="./camel-case-plugin.d.ts" />
+import { isPlainObject } from '../../util/object-utils.js';
+import { SnakeCaseTransformer } from './camel-case-transformer.js';
+import { createCamelCaseMapper, createSnakeCaseMapper, } from './camel-case.js';
+/**
+ * A plugin that converts snake_case identifiers in the database into
+ * camelCase in the JavaScript side.
+ *
+ * For example let's assume we have a table called `person_table`
+ * with columns `first_name` and `last_name` in the database. When
+ * using `CamelCasePlugin` we would setup Kysely like this:
+ *
+ * ```ts
+ * import * as Sqlite from 'better-sqlite3'
+ * import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
+ *
+ * interface CamelCasedDatabase {
+ *   userMetadata: {
+ *     firstName: string
+ *     lastName: string
+ *   }
+ * }
+ *
+ * const db = new Kysely<CamelCasedDatabase>({
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
+ *   }),
+ *   plugins: [new CamelCasePlugin()],
+ * })
+ *
+ * const person = await db.selectFrom('userMetadata')
+ *   .where('firstName', '=', 'Arnold')
+ *   .select(['firstName', 'lastName'])
+ *   .executeTakeFirst()
+ *
+ * if (person) {
+ *   console.log(person.firstName)
+ * }
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "first_name", "last_name" from "user_metadata" where "first_name" = ?
+ * ```
+ *
+ * As you can see from the example, __everything__ needs to be defined
+ * in camelCase in the TypeScript code: table names, columns, schemas,
+ * __everything__. When using the `CamelCasePlugin` Kysely works as if
+ * the database was defined in camelCase.
+ *
+ * There are various options you can give to the plugin to modify
+ * the way identifiers are converted. See {@link CamelCasePluginOptions}.
+ * If those options are not enough, you can override this plugin's
+ * `snakeCase` and `camelCase` methods to make the conversion exactly
+ * the way you like:
+ *
+ * ```ts
+ * class MyCamelCasePlugin extends CamelCasePlugin {
+ *   protected override snakeCase(str: string): string {
+ *     // ...
+ *
+ *     return str
+ *   }
+ *
+ *   protected override camelCase(str: string): string {
+ *     // ...
+ *
+ *     return str
+ *   }
+ * }
+ * ```
+ */
+export class CamelCasePlugin {
+    opt;
+    #camelCase;
+    #snakeCase;
+    #snakeCaseTransformer;
+    constructor(opt = {}) {
+        this.opt = opt;
+        this.#camelCase = createCamelCaseMapper(opt);
+        this.#snakeCase = createSnakeCaseMapper(opt);
+        this.#snakeCaseTransformer = new SnakeCaseTransformer(this.snakeCase.bind(this));
+    }
+    transformQuery(args) {
+        return this.#snakeCaseTransformer.transformNode(args.node, args.queryId);
+    }
+    async transformResult(args) {
+        if (args.result.rows && Array.isArray(args.result.rows)) {
+            return {
+                ...args.result,
+                rows: args.result.rows.map((row) => this.mapRow(row)),
+            };
+        }
+        return args.result;
+    }
+    mapRow(row) {
+        return Object.keys(row).reduce((obj, key) => {
+            let value = row[key];
+            if (Array.isArray(value)) {
+                value = value.map((it) => (canMap(it, this.opt) ? this.mapRow(it) : it));
+            }
+            else if (canMap(value, this.opt)) {
+                value = this.mapRow(value);
+            }
+            obj[this.camelCase(key)] = value;
+            return obj;
+        }, {});
+    }
+    snakeCase(str) {
+        return this.#snakeCase(str);
+    }
+    camelCase(str) {
+        return this.#camelCase(str);
+    }
+}
+function canMap(obj, opt) {
+    return isPlainObject(obj) && !opt?.maintainNestedObjectKeys;
+}

package/dist/esm/plugin/camel-case/camel-case-transformer.d.ts

@@ -0,0 +1,9 @@
+import { IdentifierNode } from '../../operation-node/identifier-node.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { QueryId } from '../../util/query-id.js';
+import { StringMapper } from './camel-case.js';
+export declare class SnakeCaseTransformer extends OperationNodeTransformer {
+    #private;
+    constructor(snakeCase: StringMapper);
+    protected transformIdentifier(node: IdentifierNode, queryId: QueryId): IdentifierNode;
+}

package/dist/esm/plugin/camel-case/camel-case-transformer.js

@@ -0,0 +1,16 @@
+/// <reference types="./camel-case-transformer.d.ts" />
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+export class SnakeCaseTransformer extends OperationNodeTransformer {
+    #snakeCase;
+    constructor(snakeCase) {
+        super();
+        this.#snakeCase = snakeCase;
+    }
+    transformIdentifier(node, queryId) {
+        node = super.transformIdentifier(node, queryId);
+        return {
+            ...node,
+            name: this.#snakeCase(node.name),
+        };
+    }
+}

package/dist/esm/plugin/camel-case/camel-case.d.ts

@@ -0,0 +1,15 @@
+export type StringMapper = (str: string) => string;
+/**
+ * Creates a function that transforms camel case strings to snake case.
+ */
+export declare function createSnakeCaseMapper({ upperCase, underscoreBeforeDigits, underscoreBetweenUppercaseLetters, }?: {
+    upperCase?: boolean | undefined;
+    underscoreBeforeDigits?: boolean | undefined;
+    underscoreBetweenUppercaseLetters?: boolean | undefined;
+}): StringMapper;
+/**
+ * Creates a function that transforms snake case strings to camel case.
+ */
+export declare function createCamelCaseMapper({ upperCase, }?: {
+    upperCase?: boolean | undefined;
+}): StringMapper;