@kysera/debug 0.6.0

package/src/plugin.ts

@@ -0,0 +1,237 @@
+/**
+ * Debug plugin for Kysely.
+ *
+ * @module @kysera/debug
+ */
+
+import type {
+  Kysely,
+  PluginTransformQueryArgs,
+  PluginTransformResultArgs,
+  QueryResult,
+  UnknownRow,
+  KyselyPlugin,
+  RootOperationNode,
+} from 'kysely';
+import { DefaultQueryCompiler } from 'kysely';
+import { consoleLogger, type KyseraLogger } from '@kysera/core';
+
+/**
+ * Query metrics data.
+ */
+export interface QueryMetrics {
+  /** SQL query string */
+  sql: string;
+  /** Query parameters */
+  params?: unknown[];
+  /** Query execution duration in milliseconds */
+  duration: number;
+  /** Timestamp when query was executed */
+  timestamp: number;
+}
+
+/**
+ * Options for debug plugin.
+ */
+export interface DebugOptions {
+  /**
+   * Log query SQL.
+   * @default true
+   */
+  logQuery?: boolean;
+
+  /**
+   * Log query parameters.
+   * @default false
+   */
+  logParams?: boolean;
+
+  /**
+   * Duration threshold (ms) to consider a query slow.
+   * @default 100
+   */
+  slowQueryThreshold?: number;
+
+  /**
+   * Callback for slow queries.
+   */
+  onSlowQuery?: (sql: string, duration: number) => void;
+
+  /**
+   * Logger for debug messages.
+   * @default consoleLogger
+   */
+  logger?: KyseraLogger;
+
+  /**
+   * Maximum number of metrics to keep in memory.
+   * When limit is reached, oldest metrics are removed (circular buffer).
+   * @default 1000
+   */
+  maxMetrics?: number;
+}
+
+/**
+ * Internal query data for tracking execution.
+ * @internal
+ */
+interface QueryData {
+  startTime: number;
+  sql: string;
+  params: readonly unknown[];
+}
+
+/**
+ * Debug plugin implementation.
+ * @internal
+ */
+class DebugPlugin implements KyselyPlugin {
+  private metrics: QueryMetrics[] = [];
+  private queryData = new WeakMap<object, QueryData>();
+  private readonly maxMetrics: number;
+  private readonly logger: KyseraLogger;
+  private readonly options: Required<Pick<DebugOptions, 'logQuery' | 'logParams' | 'slowQueryThreshold'>>;
+  private readonly onSlowQuery: ((sql: string, duration: number) => void) | undefined;
+
+  constructor(options: DebugOptions = {}) {
+    this.logger = options.logger ?? consoleLogger;
+    this.maxMetrics = options.maxMetrics ?? 1000;
+    this.onSlowQuery = options.onSlowQuery;
+    this.options = {
+      logQuery: options.logQuery ?? true,
+      logParams: options.logParams ?? false,
+      slowQueryThreshold: options.slowQueryThreshold ?? 100,
+    };
+  }
+
+  transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+    const startTime = performance.now();
+
+    // Compile the query to get SQL and parameters
+    const compiler = new DefaultQueryCompiler();
+    const compiled = compiler.compileQuery(args.node, args.queryId);
+
+    // Store query data for later use in transformResult
+    this.queryData.set(args.queryId, {
+      startTime,
+      sql: compiled.sql,
+      params: compiled.parameters,
+    });
+
+    return args.node;
+  }
+
+  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    const data = this.queryData.get(args.queryId);
+
+    if (data) {
+      const endTime = performance.now();
+      const duration = endTime - data.startTime;
+      this.queryData.delete(args.queryId);
+
+      const metric: QueryMetrics = {
+        sql: data.sql,
+        params: [...data.params],
+        duration,
+        timestamp: Date.now(),
+      };
+
+      // Circular buffer: keep only last N metrics
+      this.metrics.push(metric);
+      if (this.metrics.length > this.maxMetrics) {
+        this.metrics.shift();
+      }
+
+      if (this.options.logQuery) {
+        const message = this.options.logParams
+          ? `[SQL] ${data.sql}\n[Params] ${JSON.stringify(data.params)}`
+          : `[SQL] ${data.sql}`;
+        this.logger.debug(message);
+        this.logger.debug(`[Duration] ${duration.toFixed(2)}ms`);
+      }
+
+      // Check for slow query
+      if (duration > this.options.slowQueryThreshold) {
+        if (this.onSlowQuery) {
+          this.onSlowQuery(data.sql, duration);
+        } else {
+          this.logger.warn(`[SLOW QUERY] ${duration.toFixed(2)}ms: ${data.sql}`);
+        }
+      }
+    }
+
+    return Promise.resolve(args.result);
+  }
+
+  getMetrics(): QueryMetrics[] {
+    return [...this.metrics];
+  }
+
+  clearMetrics(): void {
+    this.metrics = [];
+  }
+}
+
+/**
+ * Database with debug capabilities.
+ */
+export interface DebugDatabase<DB> extends Kysely<DB> {
+  /** Get all collected query metrics */
+  getMetrics(): QueryMetrics[];
+  /** Clear all collected metrics */
+  clearMetrics(): void;
+}
+
+/**
+ * Wrap a Kysely database with debug capabilities.
+ *
+ * Adds query logging, metrics collection, and slow query detection.
+ *
+ * @param db - Kysely database instance
+ * @param options - Debug options
+ * @returns Database with debug capabilities
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { withDebug } from '@kysera/debug';
+ *
+ * const debugDb = withDebug(db);
+ *
+ * // Queries are now logged and timed
+ * await debugDb.selectFrom('users').selectAll().execute();
+ *
+ * // Get collected metrics
+ * const metrics = debugDb.getMetrics();
+ * console.log(`Total queries: ${metrics.length}`);
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * import { withDebug } from '@kysera/debug';
+ *
+ * const debugDb = withDebug(db, {
+ *   logQuery: true,
+ *   logParams: true,
+ *   slowQueryThreshold: 50,
+ *   maxMetrics: 500,
+ *   onSlowQuery: (sql, duration) => {
+ *     alertService.notify(`Slow query: ${duration}ms`);
+ *   },
+ * });
+ * ```
+ */
+export function withDebug<DB>(
+  db: Kysely<DB>,
+  options: DebugOptions = {}
+): DebugDatabase<DB> {
+  const plugin = new DebugPlugin(options);
+  const debugDb = db.withPlugin(plugin) as DebugDatabase<DB>;
+
+  // Attach metrics methods
+  debugDb.getMetrics = (): QueryMetrics[] => plugin.getMetrics();
+  debugDb.clearMetrics = (): void => {
+    plugin.clearMetrics();
+  };
+
+  return debugDb;
+}

package/src/profiler.ts

@@ -0,0 +1,157 @@
+/**
+ * Query profiler for performance analysis.
+ *
+ * @module @kysera/debug
+ */
+
+import type { QueryMetrics } from './plugin.js';
+
+/**
+ * Query profiler summary.
+ */
+export interface ProfilerSummary {
+  /** Total number of recorded queries */
+  totalQueries: number;
+  /** Sum of all query durations */
+  totalDuration: number;
+  /** Average query duration */
+  averageDuration: number;
+  /** Slowest recorded query */
+  slowestQuery: QueryMetrics | null;
+  /** Fastest recorded query */
+  fastestQuery: QueryMetrics | null;
+  /** All recorded queries */
+  queries: QueryMetrics[];
+}
+
+/**
+ * Options for QueryProfiler.
+ */
+export interface ProfilerOptions {
+  /**
+   * Maximum number of queries to keep in memory.
+   * @default 1000
+   */
+  maxQueries?: number;
+}
+
+/**
+ * Query profiler for collecting and analyzing query performance.
+ *
+ * Provides detailed statistics about query execution times
+ * including average, min, max, and query counts.
+ *
+ * @example
+ * ```typescript
+ * import { QueryProfiler } from '@kysera/debug';
+ *
+ * const profiler = new QueryProfiler({ maxQueries: 500 });
+ *
+ * // Record queries manually
+ * profiler.record({
+ *   sql: 'SELECT * FROM users',
+ *   duration: 10,
+ *   timestamp: Date.now(),
+ * });
+ *
+ * // Get summary
+ * const summary = profiler.getSummary();
+ * console.log(`Total queries: ${summary.totalQueries}`);
+ * console.log(`Average duration: ${summary.averageDuration.toFixed(2)}ms`);
+ *
+ * // Clear recorded queries
+ * profiler.clear();
+ * ```
+ */
+export class QueryProfiler {
+  private queries: QueryMetrics[] = [];
+  private readonly maxQueries: number;
+
+  /**
+   * Create a new query profiler.
+   *
+   * @param options - Profiler options
+   */
+  constructor(options: ProfilerOptions = {}) {
+    this.maxQueries = options.maxQueries ?? 1000;
+  }
+
+  /**
+   * Record a query metric.
+   *
+   * @param metric - Query metrics to record
+   */
+  record(metric: QueryMetrics): void {
+    this.queries.push(metric);
+    // Circular buffer: keep only last N queries
+    if (this.queries.length > this.maxQueries) {
+      this.queries.shift();
+    }
+  }
+
+  /**
+   * Get profiling summary.
+   *
+   * @returns Summary of all recorded queries
+   */
+  getSummary(): ProfilerSummary {
+    if (this.queries.length === 0) {
+      return {
+        totalQueries: 0,
+        totalDuration: 0,
+        averageDuration: 0,
+        slowestQuery: null,
+        fastestQuery: null,
+        queries: [],
+      };
+    }
+
+    const totalDuration = this.queries.reduce((sum, q) => sum + q.duration, 0);
+    const sorted = [...this.queries].sort((a, b) => b.duration - a.duration);
+
+    return {
+      totalQueries: this.queries.length,
+      totalDuration,
+      averageDuration: totalDuration / this.queries.length,
+      slowestQuery: sorted[0] ?? null,
+      fastestQuery: sorted[sorted.length - 1] ?? null,
+      queries: [...this.queries],
+    };
+  }
+
+  /**
+   * Get the slowest N queries.
+   *
+   * @param count - Number of queries to return
+   * @returns Array of slowest queries
+   */
+  getSlowestQueries(count: number): QueryMetrics[] {
+    return [...this.queries]
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, count);
+  }
+
+  /**
+   * Get queries slower than a threshold.
+   *
+   * @param thresholdMs - Duration threshold in milliseconds
+   * @returns Array of slow queries
+   */
+  getSlowQueries(thresholdMs: number): QueryMetrics[] {
+    return this.queries.filter((q) => q.duration > thresholdMs);
+  }
+
+  /**
+   * Clear all recorded queries.
+   */
+  clear(): void {
+    this.queries = [];
+  }
+
+  /**
+   * Get the number of recorded queries.
+   */
+  get count(): number {
+    return this.queries.length;
+  }
+}