@kysera/debug 0.7.2 → 0.7.4

package/src/plugin.ts

@@ -11,24 +11,14 @@ import type {
   QueryResult,
   UnknownRow,
   KyselyPlugin,
-  RootOperationNode,
-} from 'kysely';
-import { DefaultQueryCompiler } from 'kysely';
-import { consoleLogger, type KyseraLogger } from '@kysera/core';
+  RootOperationNode
+} from 'kysely'
+import { DefaultQueryCompiler } from 'kysely'
+import { consoleLogger, type KyseraLogger, type QueryMetrics } from '@kysera/core'
+import { CircularBuffer } from './circular-buffer.js'
 
-/**
- * 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;
-}
+// Re-export QueryMetrics for backwards compatibility
+export type { QueryMetrics }
 
 /**
  * Options for debug plugin.
@@ -38,37 +28,37 @@ export interface DebugOptions {
    * Log query SQL.
    * @default true
    */
-  logQuery?: boolean;
+  logQuery?: boolean
 
   /**
    * Log query parameters.
    * @default false
    */
-  logParams?: boolean;
+  logParams?: boolean
 
   /**
    * Duration threshold (ms) to consider a query slow.
    * @default 100
    */
-  slowQueryThreshold?: number;
+  slowQueryThreshold?: number
 
   /**
    * Callback for slow queries.
    */
-  onSlowQuery?: (sql: string, duration: number) => void;
+  onSlowQuery?: (sql: string, duration: number) => void
 
   /**
    * Logger for debug messages.
    * @default consoleLogger
    */
-  logger?: KyseraLogger;
+  logger?: KyseraLogger
 
   /**
    * Maximum number of metrics to keep in memory.
    * When limit is reached, oldest metrics are removed (circular buffer).
    * @default 1000
    */
-  maxMetrics?: number;
+  maxMetrics?: number
 }
 
 /**
@@ -76,9 +66,9 @@ export interface DebugOptions {
  * @internal
  */
 interface QueryData {
-  startTime: number;
-  sql: string;
-  params: readonly unknown[];
+  startTime: number
+  sql: string
+  params: readonly unknown[]
 }
 
 /**
@@ -86,89 +76,87 @@ interface QueryData {
  * @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;
+  private readonly metricsBuffer: CircularBuffer<QueryMetrics>
+  private queryData = new WeakMap<object, QueryData>()
+  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.logger = options.logger ?? consoleLogger
+    this.metricsBuffer = new CircularBuffer<QueryMetrics>(options.maxMetrics ?? 1000)
+    this.onSlowQuery = options.onSlowQuery
     this.options = {
       logQuery: options.logQuery ?? true,
       logParams: options.logParams ?? false,
-      slowQueryThreshold: options.slowQueryThreshold ?? 100,
-    };
+      slowQueryThreshold: options.slowQueryThreshold ?? 100
+    }
   }
 
   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
-    const startTime = performance.now();
+    const startTime = performance.now()
 
     // Compile the query to get SQL and parameters
-    const compiler = new DefaultQueryCompiler();
-    const compiled = compiler.compileQuery(args.node, args.queryId);
+    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,
-    });
+      params: compiled.parameters
+    })
 
-    return args.node;
+    return args.node
   }
 
   transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
-    const data = this.queryData.get(args.queryId);
+    const data = this.queryData.get(args.queryId)
 
     if (data) {
-      const endTime = performance.now();
-      const duration = endTime - data.startTime;
-      this.queryData.delete(args.queryId);
+      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();
+        timestamp: Date.now()
       }
 
+      // Add to circular buffer (O(1) operation)
+      this.metricsBuffer.add(metric)
+
       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`);
+          ? '[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);
+          this.onSlowQuery(data.sql, duration)
         } else {
-          this.logger.warn(`[SLOW QUERY] ${duration.toFixed(2)}ms: ${data.sql}`);
+          this.logger.warn('[SLOW QUERY] ' + duration.toFixed(2) + 'ms: ' + data.sql)
         }
       }
     }
 
-    return Promise.resolve(args.result);
+    return Promise.resolve(args.result)
   }
 
   getMetrics(): QueryMetrics[] {
-    return [...this.metrics];
+    return this.metricsBuffer.getOrdered()
   }
 
   clearMetrics(): void {
-    this.metrics = [];
+    this.metricsBuffer.clear()
   }
 }
 
@@ -177,9 +165,9 @@ class DebugPlugin implements KyselyPlugin {
  */
 export interface DebugDatabase<DB> extends Kysely<DB> {
   /** Get all collected query metrics */
-  getMetrics(): QueryMetrics[];
+  getMetrics(): QueryMetrics[]
   /** Clear all collected metrics */
-  clearMetrics(): void;
+  clearMetrics(): void
 }
 
 /**
@@ -202,7 +190,7 @@ export interface DebugDatabase<DB> extends Kysely<DB> {
  *
  * // Get collected metrics
  * const metrics = debugDb.getMetrics();
- * console.log(`Total queries: ${metrics.length}`);
+ * console.log('Total queries: ' + metrics.length);
  * ```
  *
  * @example With custom options
@@ -215,23 +203,20 @@ export interface DebugDatabase<DB> extends Kysely<DB> {
  *   slowQueryThreshold: 50,
  *   maxMetrics: 500,
  *   onSlowQuery: (sql, duration) => {
- *     alertService.notify(`Slow query: ${duration}ms`);
+ *     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>;
+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.getMetrics = (): QueryMetrics[] => plugin.getMetrics()
   debugDb.clearMetrics = (): void => {
-    plugin.clearMetrics();
-  };
+    plugin.clearMetrics()
+  }
 
-  return debugDb;
+  return debugDb
 }

package/src/profiler.ts

@@ -4,24 +4,25 @@
  * @module @kysera/debug
  */
 
-import type { QueryMetrics } from './plugin.js';
+import type { QueryMetrics } from '@kysera/core'
+import { CircularBuffer } from './circular-buffer.js'
 
 /**
  * Query profiler summary.
  */
 export interface ProfilerSummary {
   /** Total number of recorded queries */
-  totalQueries: number;
+  totalQueries: number
   /** Sum of all query durations */
-  totalDuration: number;
+  totalDuration: number
   /** Average query duration */
-  averageDuration: number;
+  averageDuration: number
   /** Slowest recorded query */
-  slowestQuery: QueryMetrics | null;
+  slowestQuery: QueryMetrics | null
   /** Fastest recorded query */
-  fastestQuery: QueryMetrics | null;
+  fastestQuery: QueryMetrics | null
   /** All recorded queries */
-  queries: QueryMetrics[];
+  queries: QueryMetrics[]
 }
 
 /**
@@ -32,7 +33,7 @@ export interface ProfilerOptions {
    * Maximum number of queries to keep in memory.
    * @default 1000
    */
-  maxQueries?: number;
+  maxQueries?: number
 }
 
 /**
@@ -56,16 +57,15 @@ export interface ProfilerOptions {
  *
  * // Get summary
  * const summary = profiler.getSummary();
- * console.log(`Total queries: ${summary.totalQueries}`);
- * console.log(`Average duration: ${summary.averageDuration.toFixed(2)}ms`);
+ * 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;
+  private readonly queriesBuffer: CircularBuffer<QueryMetrics>
 
   /**
    * Create a new query profiler.
@@ -73,20 +73,19 @@ export class QueryProfiler {
    * @param options - Profiler options
    */
   constructor(options: ProfilerOptions = {}) {
-    this.maxQueries = options.maxQueries ?? 1000;
+    this.queriesBuffer = new CircularBuffer<QueryMetrics>(options.maxQueries ?? 1000)
   }
 
   /**
    * Record a query metric.
    *
+   * Uses O(1) circular buffer to maintain bounded memory usage.
+   * When the buffer is full, oldest entries are overwritten.
+   *
    * @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();
-    }
+    this.queriesBuffer.add(metric)
   }
 
   /**
@@ -95,28 +94,30 @@ export class QueryProfiler {
    * @returns Summary of all recorded queries
    */
   getSummary(): ProfilerSummary {
-    if (this.queries.length === 0) {
+    const orderedQueries = this.getOrderedQueries()
+
+    if (orderedQueries.length === 0) {
       return {
         totalQueries: 0,
         totalDuration: 0,
         averageDuration: 0,
         slowestQuery: null,
         fastestQuery: null,
-        queries: [],
-      };
+        queries: []
+      }
     }
 
-    const totalDuration = this.queries.reduce((sum, q) => sum + q.duration, 0);
-    const sorted = [...this.queries].sort((a, b) => b.duration - a.duration);
+    const totalDuration = orderedQueries.reduce((sum, q) => sum + q.duration, 0)
+    const sorted = [...orderedQueries].sort((a, b) => b.duration - a.duration)
 
     return {
-      totalQueries: this.queries.length,
+      totalQueries: orderedQueries.length,
       totalDuration,
-      averageDuration: totalDuration / this.queries.length,
+      averageDuration: totalDuration / orderedQueries.length,
       slowestQuery: sorted[0] ?? null,
       fastestQuery: sorted[sorted.length - 1] ?? null,
-      queries: [...this.queries],
-    };
+      queries: orderedQueries
+    }
   }
 
   /**
@@ -126,9 +127,7 @@ export class QueryProfiler {
    * @returns Array of slowest queries
    */
   getSlowestQueries(count: number): QueryMetrics[] {
-    return [...this.queries]
-      .sort((a, b) => b.duration - a.duration)
-      .slice(0, count);
+    return [...this.getOrderedQueries()].sort((a, b) => b.duration - a.duration).slice(0, count)
   }
 
   /**
@@ -138,20 +137,30 @@ export class QueryProfiler {
    * @returns Array of slow queries
    */
   getSlowQueries(thresholdMs: number): QueryMetrics[] {
-    return this.queries.filter((q) => q.duration > thresholdMs);
+    return this.getOrderedQueries().filter(q => q.duration > thresholdMs)
   }
 
   /**
    * Clear all recorded queries.
    */
   clear(): void {
-    this.queries = [];
+    this.queriesBuffer.clear()
   }
 
   /**
    * Get the number of recorded queries.
    */
   get count(): number {
-    return this.queries.length;
+    return this.queriesBuffer.size
+  }
+
+  /**
+   * Get queries in chronological order.
+   * Handles circular buffer wrap-around correctly.
+   *
+   * @returns Array of queries in chronological order
+   */
+  private getOrderedQueries(): QueryMetrics[] {
+    return this.queriesBuffer.getOrdered()
   }
 }