@kysera/debug 0.7.2 → 0.7.4

package/README.md

@@ -24,26 +24,28 @@ bun add @kysera/debug
 - **Performance Metrics** - Collect and analyze query performance data
 - **Slow Query Detection** - Identify and alert on slow database queries
 - **SQL Formatting** - Format and highlight SQL for better readability
-- **Query Profiling** - Detailed performance analysis with statistics
-- **Circular Buffer** - Memory-efficient metrics storage with automatic cleanup
+- **Query Profiling** - Detailed performance analysis with statistics using O(1) index-based metrics
+- **Circular Buffer** - O(1) memory-efficient metrics storage with automatic cleanup (ring buffer implementation)
 - **Zero Dependencies** - Only depends on `@kysera/core` and peer-depends on `kysely`
 
 ## Quick Start
 
 ```typescript
-import { Kysely } from 'kysely';
-import { withDebug } from '@kysera/debug';
+import { Kysely } from 'kysely'
+import { withDebug } from '@kysera/debug'
 
 // Wrap your database with debug capabilities
-const db = new Kysely<Database>({ /* config */ });
-const debugDb = withDebug(db);
+const db = new Kysely<Database>({
+  /* config */
+})
+const debugDb = withDebug(db)
 
 // Execute queries - they're automatically logged and timed
-await debugDb.selectFrom('users').selectAll().execute();
+await debugDb.selectFrom('users').selectAll().execute()
 
 // Get collected metrics
-const metrics = debugDb.getMetrics();
-console.log(`Executed ${metrics.length} queries`);
+const metrics = debugDb.getMetrics()
+console.log(`Executed ${metrics.length} queries`)
 ```
 
 ## API Documentation
@@ -53,10 +55,7 @@ console.log(`Executed ${metrics.length} queries`);
 Wraps a Kysely database instance with debug capabilities, adding query logging, metrics collection, and slow query detection.
 
 ```typescript
-function withDebug<DB>(
-  db: Kysely<DB>,
-  options?: DebugOptions
-): DebugDatabase<DB>
+function withDebug<DB>(db: Kysely<DB>, options?: DebugOptions): DebugDatabase<DB>
 ```
 
 #### Parameters
@@ -71,7 +70,7 @@ function withDebug<DB>(
 #### Example
 
 ```typescript
-import { withDebug } from '@kysera/debug';
+import { withDebug } from '@kysera/debug'
 
 const debugDb = withDebug(db, {
   logQuery: true,
@@ -79,9 +78,9 @@ const debugDb = withDebug(db, {
   slowQueryThreshold: 100,
   maxMetrics: 1000,
   onSlowQuery: (sql, duration) => {
-    console.warn(`Slow query detected: ${duration}ms`);
-  },
-});
+    console.warn(`Slow query detected: ${duration}ms`)
+  }
+})
 ```
 
 ### DebugOptions
@@ -94,37 +93,37 @@ 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
 }
 ```
 
@@ -135,10 +134,10 @@ Extended database interface with debug capabilities.
 ```typescript
 interface DebugDatabase<DB> extends Kysely<DB> {
   /** Get all collected query metrics */
-  getMetrics(): QueryMetrics[];
+  getMetrics(): QueryMetrics[]
 
   /** Clear all collected metrics */
-  clearMetrics(): void;
+  clearMetrics(): void
 }
 ```
 
@@ -149,9 +148,11 @@ interface DebugDatabase<DB> extends Kysely<DB> {
 Returns all collected query metrics.
 
 ```typescript
-const metrics = debugDb.getMetrics();
-console.log(`Total queries: ${metrics.length}`);
-console.log(`Average duration: ${metrics.reduce((sum, m) => sum + m.duration, 0) / metrics.length}ms`);
+const metrics = debugDb.getMetrics()
+console.log(`Total queries: ${metrics.length}`)
+console.log(
+  `Average duration: ${metrics.reduce((sum, m) => sum + m.duration, 0) / metrics.length}ms`
+)
 ```
 
 ##### clearMetrics()
@@ -159,7 +160,7 @@ console.log(`Average duration: ${metrics.reduce((sum, m) => sum + m.duration, 0)
 Clears all collected metrics from memory.
 
 ```typescript
-debugDb.clearMetrics();
+debugDb.clearMetrics()
 ```
 
 ### QueryMetrics
@@ -169,16 +170,16 @@ Query performance metrics data.
 ```typescript
 interface QueryMetrics {
   /** SQL query string */
-  sql: string;
+  sql: string
 
   /** Query parameters */
-  params?: unknown[];
+  params?: unknown[]
 
   /** Query execution duration in milliseconds */
-  duration: number;
+  duration: number
 
   /** Timestamp when query was executed */
-  timestamp: number;
+  timestamp: number
 }
 ```
 
@@ -186,57 +187,59 @@ interface QueryMetrics {
 
 Advanced query profiler for collecting and analyzing query performance with detailed statistics.
 
+**Implementation:** Uses O(1) index-based circular buffer for efficient metrics tracking with minimal memory overhead.
+
 ```typescript
 class QueryProfiler {
-  constructor(options?: ProfilerOptions);
+  constructor(options?: ProfilerOptions)
 
   /** Record a query metric */
-  record(metric: QueryMetrics): void;
+  record(metric: QueryMetrics): void
 
-  /** Get profiling summary */
-  getSummary(): ProfilerSummary;
+  /** Get profiling summary (O(1) using index-based metrics) */
+  getSummary(): ProfilerSummary
 
   /** Get the slowest N queries */
-  getSlowestQueries(count: number): QueryMetrics[];
+  getSlowestQueries(count: number): QueryMetrics[]
 
   /** Get queries slower than a threshold */
-  getSlowQueries(thresholdMs: number): QueryMetrics[];
+  getSlowQueries(thresholdMs: number): QueryMetrics[]
 
   /** Clear all recorded queries */
-  clear(): void;
+  clear(): void
 
   /** Get the number of recorded queries */
-  get count(): number;
+  get count(): number
 }
 ```
 
 #### Example
 
 ```typescript
-import { QueryProfiler } from '@kysera/debug';
+import { QueryProfiler } from '@kysera/debug'
 
-const profiler = new QueryProfiler({ maxQueries: 500 });
+const profiler = new QueryProfiler({ maxQueries: 500 })
 
 // Record queries manually
 profiler.record({
   sql: 'SELECT * FROM users WHERE id = $1',
   params: [123],
   duration: 10.5,
-  timestamp: Date.now(),
-});
+  timestamp: Date.now()
+})
 
 // Get summary
-const summary = profiler.getSummary();
-console.log(`Total queries: ${summary.totalQueries}`);
-console.log(`Average duration: ${summary.averageDuration.toFixed(2)}ms`);
-console.log(`Slowest query: ${summary.slowestQuery?.duration.toFixed(2)}ms`);
+const summary = profiler.getSummary()
+console.log(`Total queries: ${summary.totalQueries}`)
+console.log(`Average duration: ${summary.averageDuration.toFixed(2)}ms`)
+console.log(`Slowest query: ${summary.slowestQuery?.duration.toFixed(2)}ms`)
 
 // Get slow queries
-const slowQueries = profiler.getSlowQueries(50);
-console.log(`Queries slower than 50ms: ${slowQueries.length}`);
+const slowQueries = profiler.getSlowQueries(50)
+console.log(`Queries slower than 50ms: ${slowQueries.length}`)
 
 // Get top 10 slowest
-const top10 = profiler.getSlowestQueries(10);
+const top10 = profiler.getSlowestQueries(10)
 ```
 
 ### ProfilerOptions
@@ -249,7 +252,7 @@ interface ProfilerOptions {
    * Maximum number of queries to keep in memory.
    * @default 1000
    */
-  maxQueries?: number;
+  maxQueries?: number
 }
 ```
 
@@ -260,22 +263,22 @@ Summary statistics from the query profiler.
 ```typescript
 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[]
 }
 ```
 
@@ -292,10 +295,10 @@ function formatSQL(sql: string): string
 **Example:**
 
 ```typescript
-import { formatSQL } from '@kysera/debug';
+import { formatSQL } from '@kysera/debug'
 
-const sql = 'SELECT id, name FROM users WHERE active = true ORDER BY name';
-console.log(formatSQL(sql));
+const sql = 'SELECT id, name FROM users WHERE active = true ORDER BY name'
+console.log(formatSQL(sql))
 // Output:
 // SELECT id, name
 // FROM users
@@ -312,16 +315,17 @@ function formatSQLPretty(sql: string, indentSize?: number): string
 ```
 
 **Parameters:**
+
 - `sql` - SQL string to format
 - `indentSize` - Number of spaces for indentation (default: 2)
 
 **Example:**
 
 ```typescript
-import { formatSQLPretty } from '@kysera/debug';
+import { formatSQLPretty } from '@kysera/debug'
 
-const sql = 'SELECT * FROM users WHERE id IN (SELECT user_id FROM orders WHERE total > 100)';
-console.log(formatSQLPretty(sql));
+const sql = 'SELECT * FROM users WHERE id IN (SELECT user_id FROM orders WHERE total > 100)'
+console.log(formatSQLPretty(sql))
 // Output with proper indentation for subqueries
 ```
 
@@ -336,14 +340,14 @@ function minifySQL(sql: string): string
 **Example:**
 
 ```typescript
-import { minifySQL } from '@kysera/debug';
+import { minifySQL } from '@kysera/debug'
 
 const sql = `
   SELECT id, name
   FROM users
   WHERE active = true
-`;
-console.log(minifySQL(sql));
+`
+console.log(minifySQL(sql))
 // Output: SELECT id, name FROM users WHERE active = true
 ```
 
@@ -358,9 +362,9 @@ function highlightSQL(sql: string): string
 **Example:**
 
 ```typescript
-import { highlightSQL } from '@kysera/debug';
+import { highlightSQL } from '@kysera/debug'
 
-console.log(highlightSQL('SELECT * FROM users WHERE active = true'));
+console.log(highlightSQL('SELECT * FROM users WHERE active = true'))
 // Keywords will be highlighted in blue in terminal
 ```
 
@@ -369,21 +373,19 @@ console.log(highlightSQL('SELECT * FROM users WHERE active = true'));
 ### Basic Query Logging
 
 ```typescript
-import { Kysely } from 'kysely';
-import { withDebug } from '@kysera/debug';
+import { Kysely } from 'kysely'
+import { withDebug } from '@kysera/debug'
 
-const db = new Kysely<Database>({ /* config */ });
+const db = new Kysely<Database>({
+  /* config */
+})
 const debugDb = withDebug(db, {
   logQuery: true,
-  logParams: false,
-});
+  logParams: false
+})
 
 // Queries are automatically logged
-await debugDb
-  .selectFrom('users')
-  .where('active', '=', true)
-  .selectAll()
-  .execute();
+await debugDb.selectFrom('users').where('active', '=', true).selectAll().execute()
 // Console output:
 // [SQL] SELECT * FROM "users" WHERE "active" = $1
 // [Duration] 12.34ms
@@ -392,129 +394,127 @@ await debugDb
 ### Detecting Slow Queries
 
 ```typescript
-import { withDebug } from '@kysera/debug';
+import { withDebug } from '@kysera/debug'
 
 const debugDb = withDebug(db, {
   slowQueryThreshold: 50, // 50ms threshold
   onSlowQuery: (sql, duration) => {
     // Send to monitoring service
-    monitoring.recordSlowQuery({ sql, duration });
+    monitoring.recordSlowQuery({ sql, duration })
 
     // Log to error tracking
-    logger.warn(`Slow query detected: ${duration.toFixed(2)}ms`, { sql });
-  },
-});
+    logger.warn(`Slow query detected: ${duration.toFixed(2)}ms`, { sql })
+  }
+})
 
 // If query takes > 50ms, callback is triggered
-await debugDb.selectFrom('users').selectAll().execute();
+await debugDb.selectFrom('users').selectAll().execute()
 ```
 
 ### Collecting and Analyzing Metrics
 
 ```typescript
-import { withDebug, formatSQL } from '@kysera/debug';
+import { withDebug, formatSQL } from '@kysera/debug'
 
 const debugDb = withDebug(db, {
-  maxMetrics: 500, // Keep last 500 queries
-});
+  maxMetrics: 500 // Keep last 500 queries
+})
 
 // Execute some queries
-await debugDb.selectFrom('users').selectAll().execute();
-await debugDb.selectFrom('posts').selectAll().execute();
+await debugDb.selectFrom('users').selectAll().execute()
+await debugDb.selectFrom('posts').selectAll().execute()
 
 // Analyze metrics
-const metrics = debugDb.getMetrics();
-const totalDuration = metrics.reduce((sum, m) => sum + m.duration, 0);
-const avgDuration = totalDuration / metrics.length;
+const metrics = debugDb.getMetrics()
+const totalDuration = metrics.reduce((sum, m) => sum + m.duration, 0)
+const avgDuration = totalDuration / metrics.length
 
-console.log(`Total queries: ${metrics.length}`);
-console.log(`Average duration: ${avgDuration.toFixed(2)}ms`);
+console.log(`Total queries: ${metrics.length}`)
+console.log(`Average duration: ${avgDuration.toFixed(2)}ms`)
 
 // Find slowest query
-const slowest = metrics.reduce((max, m) =>
-  m.duration > max.duration ? m : max
-);
-console.log('Slowest query:');
-console.log(formatSQL(slowest.sql));
-console.log(`Duration: ${slowest.duration.toFixed(2)}ms`);
+const slowest = metrics.reduce((max, m) => (m.duration > max.duration ? m : max))
+console.log('Slowest query:')
+console.log(formatSQL(slowest.sql))
+console.log(`Duration: ${slowest.duration.toFixed(2)}ms`)
 ```
 
 ### Advanced Profiling
 
 ```typescript
-import { QueryProfiler } from '@kysera/debug';
+import { QueryProfiler } from '@kysera/debug'
 
-const profiler = new QueryProfiler({ maxQueries: 1000 });
+const profiler = new QueryProfiler({ maxQueries: 1000 })
 
 // Record queries from debug database
-const debugDb = withDebug(db);
+const debugDb = withDebug(db)
 // ... execute queries ...
 
-const metrics = debugDb.getMetrics();
-metrics.forEach(m => profiler.record(m));
+const metrics = debugDb.getMetrics()
+metrics.forEach(m => profiler.record(m))
 
 // Get comprehensive summary
-const summary = profiler.getSummary();
-console.log('Query Performance Summary:');
-console.log(`  Total Queries: ${summary.totalQueries}`);
-console.log(`  Total Time: ${summary.totalDuration.toFixed(2)}ms`);
-console.log(`  Average: ${summary.averageDuration.toFixed(2)}ms`);
-console.log(`  Slowest: ${summary.slowestQuery?.duration.toFixed(2)}ms`);
-console.log(`  Fastest: ${summary.fastestQuery?.duration.toFixed(2)}ms`);
+const summary = profiler.getSummary()
+console.log('Query Performance Summary:')
+console.log(`  Total Queries: ${summary.totalQueries}`)
+console.log(`  Total Time: ${summary.totalDuration.toFixed(2)}ms`)
+console.log(`  Average: ${summary.averageDuration.toFixed(2)}ms`)
+console.log(`  Slowest: ${summary.slowestQuery?.duration.toFixed(2)}ms`)
+console.log(`  Fastest: ${summary.fastestQuery?.duration.toFixed(2)}ms`)
 
 // Analyze slow queries
-const slowQueries = profiler.getSlowQueries(100);
+const slowQueries = profiler.getSlowQueries(100)
 if (slowQueries.length > 0) {
-  console.log(`\nFound ${slowQueries.length} queries slower than 100ms:`);
+  console.log(`\nFound ${slowQueries.length} queries slower than 100ms:`)
   slowQueries.forEach(q => {
-    console.log(`  ${q.duration.toFixed(2)}ms: ${q.sql.substring(0, 80)}...`);
-  });
+    console.log(`  ${q.duration.toFixed(2)}ms: ${q.sql.substring(0, 80)}...`)
+  })
 }
 
 // Get top 5 slowest
-const top5 = profiler.getSlowestQueries(5);
-console.log('\nTop 5 Slowest Queries:');
+const top5 = profiler.getSlowestQueries(5)
+console.log('\nTop 5 Slowest Queries:')
 top5.forEach((q, i) => {
-  console.log(`${i + 1}. ${q.duration.toFixed(2)}ms`);
-  console.log(formatSQL(q.sql));
-  console.log('');
-});
+  console.log(`${i + 1}. ${q.duration.toFixed(2)}ms`)
+  console.log(formatSQL(q.sql))
+  console.log('')
+})
 ```
 
 ### Custom Logger Integration
 
 ```typescript
-import { withDebug } from '@kysera/debug';
-import type { KyseraLogger } from '@kysera/core';
+import { withDebug } from '@kysera/debug'
+import type { KyseraLogger } from '@kysera/core'
 
 // Custom logger implementation
 const customLogger: KyseraLogger = {
   debug: (message: string) => {
     // Send to logging service
-    loggingService.debug('db-query', message);
+    loggingService.debug('db-query', message)
   },
   info: (message: string) => {
-    loggingService.info('db-query', message);
+    loggingService.info('db-query', message)
   },
   warn: (message: string) => {
-    loggingService.warn('db-query', message);
+    loggingService.warn('db-query', message)
   },
   error: (message: string) => {
-    loggingService.error('db-query', message);
-  },
-};
+    loggingService.error('db-query', message)
+  }
+}
 
 const debugDb = withDebug(db, {
   logger: customLogger,
   logQuery: true,
-  logParams: true,
-});
+  logParams: true
+})
 ```
 
 ### Production Monitoring
 
 ```typescript
-import { withDebug } from '@kysera/debug';
+import { withDebug } from '@kysera/debug'
 
 const debugDb = withDebug(db, {
   logQuery: false, // Don't log in production
@@ -525,51 +525,52 @@ const debugDb = withDebug(db, {
     apm.recordTransaction({
       type: 'db.query',
       duration,
-      metadata: { sql },
-    });
+      metadata: { sql }
+    })
 
     // Alert if extremely slow
     if (duration > 1000) {
       alerting.critical('Database query exceeded 1 second', {
         sql,
-        duration,
-      });
+        duration
+      })
     }
-  },
-});
+  }
+})
 
 // Periodic metrics reporting
 setInterval(() => {
-  const metrics = debugDb.getMetrics();
+  const metrics = debugDb.getMetrics()
   if (metrics.length > 0) {
-    const avgDuration = metrics.reduce((sum, m) => sum + m.duration, 0) / metrics.length;
+    const avgDuration = metrics.reduce((sum, m) => sum + m.duration, 0) / metrics.length
 
-    monitoring.gauge('db.query.avg_duration', avgDuration);
-    monitoring.gauge('db.query.count', metrics.length);
+    monitoring.gauge('db.query.avg_duration', avgDuration)
+    monitoring.gauge('db.query.count', metrics.length)
 
-    debugDb.clearMetrics(); // Reset for next interval
+    debugDb.clearMetrics() // Reset for next interval
   }
-}, 60000); // Every minute
+}, 60000) // Every minute
 ```
 
 ### Formatting SQL for Display
 
 ```typescript
-import { formatSQL, formatSQLPretty, highlightSQL } from '@kysera/debug';
+import { formatSQL, formatSQLPretty, highlightSQL } from '@kysera/debug'
 
-const sql = 'SELECT u.id, u.name, COUNT(p.id) as post_count FROM users u LEFT JOIN posts p ON u.id = p.user_id WHERE u.active = true GROUP BY u.id, u.name ORDER BY post_count DESC';
+const sql =
+  'SELECT u.id, u.name, COUNT(p.id) as post_count FROM users u LEFT JOIN posts p ON u.id = p.user_id WHERE u.active = true GROUP BY u.id, u.name ORDER BY post_count DESC'
 
 // Basic formatting
-console.log('Basic Format:');
-console.log(formatSQL(sql));
+console.log('Basic Format:')
+console.log(formatSQL(sql))
 
 // Pretty formatting with indentation
-console.log('\nPretty Format:');
-console.log(formatSQLPretty(sql));
+console.log('\nPretty Format:')
+console.log(formatSQLPretty(sql))
 
 // Highlighted for terminal
-console.log('\nHighlighted:');
-console.log(highlightSQL(formatSQL(sql)));
+console.log('\nHighlighted:')
+console.log(highlightSQL(formatSQL(sql)))
 ```
 
 ## TypeScript Support
@@ -582,40 +583,41 @@ import type {
   DebugOptions,
   DebugDatabase,
   ProfilerSummary,
-  ProfilerOptions,
-} from '@kysera/debug';
+  ProfilerOptions
+} from '@kysera/debug'
 
 // Type-safe debug options
 const options: DebugOptions = {
   logQuery: true,
   slowQueryThreshold: 100,
   onSlowQuery: (sql: string, duration: number) => {
-    console.warn(`Slow: ${sql} (${duration}ms)`);
-  },
-};
+    console.warn(`Slow: ${sql} (${duration}ms)`)
+  }
+}
 
 // Type-safe database
 interface Database {
-  users: { id: number; name: string };
+  users: { id: number; name: string }
 }
 
-const debugDb: DebugDatabase<Database> = withDebug(db, options);
+const debugDb: DebugDatabase<Database> = withDebug(db, options)
 ```
 
 ## Performance Considerations
 
 ### Memory Management
 
-The debug plugin uses a circular buffer to manage memory efficiently:
+The debug plugin uses an O(1) circular buffer (ring buffer) to manage memory efficiently:
 
 - Default limit: 1000 metrics
-- Oldest metrics automatically removed when limit reached
+- Oldest metrics automatically removed when limit reached (O(1) operation)
 - Configure via `maxMetrics` option
+- Index-based metrics tracking for constant-time summary calculations
 
 ```typescript
 const debugDb = withDebug(db, {
-  maxMetrics: 500, // Keep only last 500 queries
-});
+  maxMetrics: 500 // Keep only last 500 queries
+})
 ```
 
 ### Production Usage
@@ -623,29 +625,31 @@ const debugDb = withDebug(db, {
 For production environments:
 
 1. **Disable verbose logging:**
+
    ```typescript
    const debugDb = withDebug(db, {
      logQuery: false,
-     logParams: false,
-   });
+     logParams: false
+   })
    ```
 
 2. **Use slow query detection only:**
+
    ```typescript
    const debugDb = withDebug(db, {
      logQuery: false,
      slowQueryThreshold: 500,
      onSlowQuery: (sql, duration) => {
-       monitoring.recordSlowQuery({ sql, duration });
-     },
-   });
+       monitoring.recordSlowQuery({ sql, duration })
+     }
+   })
    ```
 
 3. **Limit metrics collection:**
    ```typescript
    const debugDb = withDebug(db, {
-     maxMetrics: 100, // Smaller buffer for production
-   });
+     maxMetrics: 100 // Smaller buffer for production
+   })
    ```
 
 ## Runtime Compatibility