@kysera/debug 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+import { Kysely } from 'kysely';
+import { KyseraLogger } from '@kysera/core';
+
+/**
+ * Debug plugin for Kysely.
+ *
+ * @module @kysera/debug
+ */
+
+/**
+ * Query metrics data.
+ */
+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.
+ */
+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;
+}
+/**
+ * Database with debug capabilities.
+ */
+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`);
+ *   },
+ * });
+ * ```
+ */
+declare function withDebug<DB>(db: Kysely<DB>, options?: DebugOptions): DebugDatabase<DB>;
+
+/**
+ * Query profiler for performance analysis.
+ *
+ * @module @kysera/debug
+ */
+
+/**
+ * Query profiler summary.
+ */
+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.
+ */
+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();
+ * ```
+ */
+declare class QueryProfiler {
+    private queries;
+    private readonly maxQueries;
+    /**
+     * Create a new query profiler.
+     *
+     * @param options - Profiler options
+     */
+    constructor(options?: ProfilerOptions);
+    /**
+     * Record a query metric.
+     *
+     * @param metric - Query metrics to record
+     */
+    record(metric: QueryMetrics): void;
+    /**
+     * Get profiling summary.
+     *
+     * @returns Summary of all recorded queries
+     */
+    getSummary(): ProfilerSummary;
+    /**
+     * Get the slowest N queries.
+     *
+     * @param count - Number of queries to return
+     * @returns Array of slowest queries
+     */
+    getSlowestQueries(count: number): QueryMetrics[];
+    /**
+     * Get queries slower than a threshold.
+     *
+     * @param thresholdMs - Duration threshold in milliseconds
+     * @returns Array of slow queries
+     */
+    getSlowQueries(thresholdMs: number): QueryMetrics[];
+    /**
+     * Clear all recorded queries.
+     */
+    clear(): void;
+    /**
+     * Get the number of recorded queries.
+     */
+    get count(): number;
+}
+
+/**
+ * SQL formatting utilities.
+ *
+ * @module @kysera/debug
+ */
+/**
+ * Format SQL for better readability.
+ *
+ * Adds newlines before major SQL keywords to make
+ * complex queries easier to read.
+ *
+ * @param sql - SQL string to format
+ * @returns Formatted SQL string
+ *
+ * @example
+ * ```typescript
+ * import { formatSQL } from '@kysera/debug';
+ *
+ * const sql = 'SELECT id, name FROM users WHERE active = true ORDER BY name';
+ * console.log(formatSQL(sql));
+ * // SELECT id, name
+ * // FROM users
+ * // WHERE active = true
+ * // ORDER BY name
+ * ```
+ */
+declare function formatSQL(sql: string): string;
+/**
+ * Format SQL with indentation for nested queries.
+ *
+ * More advanced formatting with proper indentation
+ * for subqueries and nested structures.
+ *
+ * @param sql - SQL string to format
+ * @param indentSize - Number of spaces for indentation
+ * @returns Formatted SQL string
+ *
+ * @example
+ * ```typescript
+ * import { formatSQLPretty } from '@kysera/debug';
+ *
+ * const sql = 'SELECT * FROM users WHERE id IN (SELECT user_id FROM orders)';
+ * console.log(formatSQLPretty(sql));
+ * ```
+ */
+declare function formatSQLPretty(sql: string, indentSize?: number): string;
+/**
+ * Minify SQL by removing unnecessary whitespace.
+ *
+ * @param sql - SQL string to minify
+ * @returns Minified SQL string
+ *
+ * @example
+ * ```typescript
+ * import { minifySQL } from '@kysera/debug';
+ *
+ * const sql = `
+ *   SELECT id, name
+ *   FROM users
+ *   WHERE active = true
+ * `;
+ * console.log(minifySQL(sql));
+ * // SELECT id, name FROM users WHERE active = true
+ * ```
+ */
+declare function minifySQL(sql: string): string;
+/**
+ * Highlight SQL keywords in a query.
+ *
+ * Returns SQL with ANSI color codes for terminal output.
+ *
+ * @param sql - SQL string to highlight
+ * @returns SQL with ANSI color codes
+ *
+ * @example
+ * ```typescript
+ * import { highlightSQL } from '@kysera/debug';
+ *
+ * console.log(highlightSQL('SELECT * FROM users'));
+ * // Keywords will be highlighted in blue
+ * ```
+ */
+declare function highlightSQL(sql: string): string;
+
+export { type DebugDatabase, type DebugOptions, type ProfilerOptions, type ProfilerSummary, type QueryMetrics, QueryProfiler, formatSQL, formatSQLPretty, highlightSQL, minifySQL, withDebug };

package/dist/index.js

@@ -0,0 +1,7 @@
+import {DefaultQueryCompiler}from'kysely';import {consoleLogger}from'@kysera/core';var n=class{metrics=[];queryData=new WeakMap;maxMetrics;logger;options;onSlowQuery;constructor(e={}){this.logger=e.logger??consoleLogger,this.maxMetrics=e.maxMetrics??1e3,this.onSlowQuery=e.onSlowQuery,this.options={logQuery:e.logQuery??true,logParams:e.logParams??false,slowQueryThreshold:e.slowQueryThreshold??100};}transformQuery(e){let r=performance.now(),s=new DefaultQueryCompiler().compileQuery(e.node,e.queryId);return this.queryData.set(e.queryId,{startTime:r,sql:s.sql,params:s.parameters}),e.node}transformResult(e){let r=this.queryData.get(e.queryId);if(r){let s=performance.now()-r.startTime;this.queryData.delete(e.queryId);let o={sql:r.sql,params:[...r.params],duration:s,timestamp:Date.now()};if(this.metrics.push(o),this.metrics.length>this.maxMetrics&&this.metrics.shift(),this.options.logQuery){let m=this.options.logParams?`[SQL] ${r.sql}
+[Params] ${JSON.stringify(r.params)}`:`[SQL] ${r.sql}`;this.logger.debug(m),this.logger.debug(`[Duration] ${s.toFixed(2)}ms`);}s>this.options.slowQueryThreshold&&(this.onSlowQuery?this.onSlowQuery(r.sql,s):this.logger.warn(`[SLOW QUERY] ${s.toFixed(2)}ms: ${r.sql}`));}return Promise.resolve(e.result)}getMetrics(){return [...this.metrics]}clearMetrics(){this.metrics=[];}};function p(i,e={}){let r=new n(e),t=i.withPlugin(r);return t.getMetrics=()=>r.getMetrics(),t.clearMetrics=()=>{r.clearMetrics();},t}var u=class{queries=[];maxQueries;constructor(e={}){this.maxQueries=e.maxQueries??1e3;}record(e){this.queries.push(e),this.queries.length>this.maxQueries&&this.queries.shift();}getSummary(){if(this.queries.length===0)return {totalQueries:0,totalDuration:0,averageDuration:0,slowestQuery:null,fastestQuery:null,queries:[]};let e=this.queries.reduce((t,s)=>t+s.duration,0),r=[...this.queries].sort((t,s)=>s.duration-t.duration);return {totalQueries:this.queries.length,totalDuration:e,averageDuration:e/this.queries.length,slowestQuery:r[0]??null,fastestQuery:r[r.length-1]??null,queries:[...this.queries]}}getSlowestQueries(e){return [...this.queries].sort((r,t)=>t.duration-r.duration).slice(0,e)}getSlowQueries(e){return this.queries.filter(r=>r.duration>e)}clear(){this.queries=[];}get count(){return this.queries.length}};function a(i){return i.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}var l=["SELECT","FROM","WHERE","JOIN","LEFT JOIN","RIGHT JOIN","INNER JOIN","OUTER JOIN","CROSS JOIN","ORDER BY","GROUP BY","HAVING","LIMIT","OFFSET","INSERT INTO","VALUES","UPDATE","SET","DELETE FROM","UNION","EXCEPT","INTERSECT","ON","AND","OR","RETURNING"];function g(i){let e=i;for(let r of l){let t=new RegExp(`(\\s+)(${a(r)})\\s+`,"gi");e=e.replace(t,`
+$2 `);}return e.trim()}function h(i,e=2){let r=g(i),t=" ".repeat(e),s=0;return r=r.replace(/\(/g,()=>(s++,`(
+`+t.repeat(s))),r=r.replace(/\)/g,()=>(s=Math.max(0,s-1),`
+`+t.repeat(s)+")")),r=r.replace(/\n\s*\n/g,`
+`),r.trim()}function Q(i){return i.replace(/\s+/g," ").replace(/\s*,\s*/g,", ").replace(/\s*\(\s*/g," (").replace(/\s*\)\s*/g,") ").trim()}function f(i){let e="\x1B[34m",r="\x1B[0m",t=i;for(let s of l){let o=new RegExp(`\\b(${a(s)})\\b`,"gi");t=t.replace(o,`${e}$1${r}`);}return t}export{u as QueryProfiler,g as formatSQL,h as formatSQLPretty,f as highlightSQL,Q as minifySQL,p as withDebug};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts","../src/profiler.ts","../src/format.ts"],"names":["DebugPlugin","options","consoleLogger","args","startTime","compiled","DefaultQueryCompiler","data","duration","metric","message","withDebug","db","plugin","debugDb","QueryProfiler","totalDuration","sum","q","sorted","a","b","count","thresholdMs","escapeRegex","str","SQL_KEYWORDS","formatSQL","sql","formatted","keyword","regex","formatSQLPretty","indentSize","indent","level","minifySQL","highlightSQL","BLUE","RESET","highlighted"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Debug plugin for Kysely.\n *\n * @module @kysera/debug\n */\n\nimport type {\n  Kysely,\n  PluginTransformQueryArgs,\n  PluginTransformResultArgs,\n  QueryResult,\n  UnknownRow,\n  KyselyPlugin,\n  RootOperationNode,\n} from 'kysely';\nimport { DefaultQueryCompiler } from 'kysely';\nimport { consoleLogger, type KyseraLogger } from '@kysera/core';\n\n/**\n * Query metrics data.\n */\nexport interface QueryMetrics {\n  /** SQL query string */\n  sql: string;\n  /** Query parameters */\n  params?: unknown[];\n  /** Query execution duration in milliseconds */\n  duration: number;\n  /** Timestamp when query was executed */\n  timestamp: number;\n}\n\n/**\n * Options for debug plugin.\n */\nexport interface DebugOptions {\n  /**\n   * Log query SQL.\n   * @default true\n   */\n  logQuery?: boolean;\n\n  /**\n   * Log query parameters.\n   * @default false\n   */\n  logParams?: boolean;\n\n  /**\n   * Duration threshold (ms) to consider a query slow.\n   * @default 100\n   */\n  slowQueryThreshold?: number;\n\n  /**\n   * Callback for slow queries.\n   */\n  onSlowQuery?: (sql: string, duration: number) => void;\n\n  /**\n   * Logger for debug messages.\n   * @default consoleLogger\n   */\n  logger?: KyseraLogger;\n\n  /**\n   * Maximum number of metrics to keep in memory.\n   * When limit is reached, oldest metrics are removed (circular buffer).\n   * @default 1000\n   */\n  maxMetrics?: number;\n}\n\n/**\n * Internal query data for tracking execution.\n * @internal\n */\ninterface QueryData {\n  startTime: number;\n  sql: string;\n  params: readonly unknown[];\n}\n\n/**\n * Debug plugin implementation.\n * @internal\n */\nclass DebugPlugin implements KyselyPlugin {\n  private metrics: QueryMetrics[] = [];\n  private queryData = new WeakMap<object, QueryData>();\n  private readonly maxMetrics: number;\n  private readonly logger: KyseraLogger;\n  private readonly options: Required<Pick<DebugOptions, 'logQuery' | 'logParams' | 'slowQueryThreshold'>>;\n  private readonly onSlowQuery: ((sql: string, duration: number) => void) | undefined;\n\n  constructor(options: DebugOptions = {}) {\n    this.logger = options.logger ?? consoleLogger;\n    this.maxMetrics = options.maxMetrics ?? 1000;\n    this.onSlowQuery = options.onSlowQuery;\n    this.options = {\n      logQuery: options.logQuery ?? true,\n      logParams: options.logParams ?? false,\n      slowQueryThreshold: options.slowQueryThreshold ?? 100,\n    };\n  }\n\n  transformQuery(args: PluginTransformQueryArgs): RootOperationNode {\n    const startTime = performance.now();\n\n    // Compile the query to get SQL and parameters\n    const compiler = new DefaultQueryCompiler();\n    const compiled = compiler.compileQuery(args.node, args.queryId);\n\n    // Store query data for later use in transformResult\n    this.queryData.set(args.queryId, {\n      startTime,\n      sql: compiled.sql,\n      params: compiled.parameters,\n    });\n\n    return args.node;\n  }\n\n  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {\n    const data = this.queryData.get(args.queryId);\n\n    if (data) {\n      const endTime = performance.now();\n      const duration = endTime - data.startTime;\n      this.queryData.delete(args.queryId);\n\n      const metric: QueryMetrics = {\n        sql: data.sql,\n        params: [...data.params],\n        duration,\n        timestamp: Date.now(),\n      };\n\n      // Circular buffer: keep only last N metrics\n      this.metrics.push(metric);\n      if (this.metrics.length > this.maxMetrics) {\n        this.metrics.shift();\n      }\n\n      if (this.options.logQuery) {\n        const message = this.options.logParams\n          ? `[SQL] ${data.sql}\\n[Params] ${JSON.stringify(data.params)}`\n          : `[SQL] ${data.sql}`;\n        this.logger.debug(message);\n        this.logger.debug(`[Duration] ${duration.toFixed(2)}ms`);\n      }\n\n      // Check for slow query\n      if (duration > this.options.slowQueryThreshold) {\n        if (this.onSlowQuery) {\n          this.onSlowQuery(data.sql, duration);\n        } else {\n          this.logger.warn(`[SLOW QUERY] ${duration.toFixed(2)}ms: ${data.sql}`);\n        }\n      }\n    }\n\n    return Promise.resolve(args.result);\n  }\n\n  getMetrics(): QueryMetrics[] {\n    return [...this.metrics];\n  }\n\n  clearMetrics(): void {\n    this.metrics = [];\n  }\n}\n\n/**\n * Database with debug capabilities.\n */\nexport interface DebugDatabase<DB> extends Kysely<DB> {\n  /** Get all collected query metrics */\n  getMetrics(): QueryMetrics[];\n  /** Clear all collected metrics */\n  clearMetrics(): void;\n}\n\n/**\n * Wrap a Kysely database with debug capabilities.\n *\n * Adds query logging, metrics collection, and slow query detection.\n *\n * @param db - Kysely database instance\n * @param options - Debug options\n * @returns Database with debug capabilities\n *\n * @example Basic usage\n * ```typescript\n * import { withDebug } from '@kysera/debug';\n *\n * const debugDb = withDebug(db);\n *\n * // Queries are now logged and timed\n * await debugDb.selectFrom('users').selectAll().execute();\n *\n * // Get collected metrics\n * const metrics = debugDb.getMetrics();\n * console.log(`Total queries: ${metrics.length}`);\n * ```\n *\n * @example With custom options\n * ```typescript\n * import { withDebug } from '@kysera/debug';\n *\n * const debugDb = withDebug(db, {\n *   logQuery: true,\n *   logParams: true,\n *   slowQueryThreshold: 50,\n *   maxMetrics: 500,\n *   onSlowQuery: (sql, duration) => {\n *     alertService.notify(`Slow query: ${duration}ms`);\n *   },\n * });\n * ```\n */\nexport function withDebug<DB>(\n  db: Kysely<DB>,\n  options: DebugOptions = {}\n): DebugDatabase<DB> {\n  const plugin = new DebugPlugin(options);\n  const debugDb = db.withPlugin(plugin) as DebugDatabase<DB>;\n\n  // Attach metrics methods\n  debugDb.getMetrics = (): QueryMetrics[] => plugin.getMetrics();\n  debugDb.clearMetrics = (): void => {\n    plugin.clearMetrics();\n  };\n\n  return debugDb;\n}\n","/**\n * Query profiler for performance analysis.\n *\n * @module @kysera/debug\n */\n\nimport type { QueryMetrics } from './plugin.js';\n\n/**\n * Query profiler summary.\n */\nexport interface ProfilerSummary {\n  /** Total number of recorded queries */\n  totalQueries: number;\n  /** Sum of all query durations */\n  totalDuration: number;\n  /** Average query duration */\n  averageDuration: number;\n  /** Slowest recorded query */\n  slowestQuery: QueryMetrics | null;\n  /** Fastest recorded query */\n  fastestQuery: QueryMetrics | null;\n  /** All recorded queries */\n  queries: QueryMetrics[];\n}\n\n/**\n * Options for QueryProfiler.\n */\nexport interface ProfilerOptions {\n  /**\n   * Maximum number of queries to keep in memory.\n   * @default 1000\n   */\n  maxQueries?: number;\n}\n\n/**\n * Query profiler for collecting and analyzing query performance.\n *\n * Provides detailed statistics about query execution times\n * including average, min, max, and query counts.\n *\n * @example\n * ```typescript\n * import { QueryProfiler } from '@kysera/debug';\n *\n * const profiler = new QueryProfiler({ maxQueries: 500 });\n *\n * // Record queries manually\n * profiler.record({\n *   sql: 'SELECT * FROM users',\n *   duration: 10,\n *   timestamp: Date.now(),\n * });\n *\n * // Get summary\n * const summary = profiler.getSummary();\n * console.log(`Total queries: ${summary.totalQueries}`);\n * console.log(`Average duration: ${summary.averageDuration.toFixed(2)}ms`);\n *\n * // Clear recorded queries\n * profiler.clear();\n * ```\n */\nexport class QueryProfiler {\n  private queries: QueryMetrics[] = [];\n  private readonly maxQueries: number;\n\n  /**\n   * Create a new query profiler.\n   *\n   * @param options - Profiler options\n   */\n  constructor(options: ProfilerOptions = {}) {\n    this.maxQueries = options.maxQueries ?? 1000;\n  }\n\n  /**\n   * Record a query metric.\n   *\n   * @param metric - Query metrics to record\n   */\n  record(metric: QueryMetrics): void {\n    this.queries.push(metric);\n    // Circular buffer: keep only last N queries\n    if (this.queries.length > this.maxQueries) {\n      this.queries.shift();\n    }\n  }\n\n  /**\n   * Get profiling summary.\n   *\n   * @returns Summary of all recorded queries\n   */\n  getSummary(): ProfilerSummary {\n    if (this.queries.length === 0) {\n      return {\n        totalQueries: 0,\n        totalDuration: 0,\n        averageDuration: 0,\n        slowestQuery: null,\n        fastestQuery: null,\n        queries: [],\n      };\n    }\n\n    const totalDuration = this.queries.reduce((sum, q) => sum + q.duration, 0);\n    const sorted = [...this.queries].sort((a, b) => b.duration - a.duration);\n\n    return {\n      totalQueries: this.queries.length,\n      totalDuration,\n      averageDuration: totalDuration / this.queries.length,\n      slowestQuery: sorted[0] ?? null,\n      fastestQuery: sorted[sorted.length - 1] ?? null,\n      queries: [...this.queries],\n    };\n  }\n\n  /**\n   * Get the slowest N queries.\n   *\n   * @param count - Number of queries to return\n   * @returns Array of slowest queries\n   */\n  getSlowestQueries(count: number): QueryMetrics[] {\n    return [...this.queries]\n      .sort((a, b) => b.duration - a.duration)\n      .slice(0, count);\n  }\n\n  /**\n   * Get queries slower than a threshold.\n   *\n   * @param thresholdMs - Duration threshold in milliseconds\n   * @returns Array of slow queries\n   */\n  getSlowQueries(thresholdMs: number): QueryMetrics[] {\n    return this.queries.filter((q) => q.duration > thresholdMs);\n  }\n\n  /**\n   * Clear all recorded queries.\n   */\n  clear(): void {\n    this.queries = [];\n  }\n\n  /**\n   * Get the number of recorded queries.\n   */\n  get count(): number {\n    return this.queries.length;\n  }\n}\n","/**\n * SQL formatting utilities.\n *\n * @module @kysera/debug\n */\n\n/**\n * Escape special regex characters in a string.\n * @internal\n */\nfunction escapeRegex(str: string): string {\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * SQL keywords that should start on a new line.\n */\nconst SQL_KEYWORDS = [\n  'SELECT',\n  'FROM',\n  'WHERE',\n  'JOIN',\n  'LEFT JOIN',\n  'RIGHT JOIN',\n  'INNER JOIN',\n  'OUTER JOIN',\n  'CROSS JOIN',\n  'ORDER BY',\n  'GROUP BY',\n  'HAVING',\n  'LIMIT',\n  'OFFSET',\n  'INSERT INTO',\n  'VALUES',\n  'UPDATE',\n  'SET',\n  'DELETE FROM',\n  'UNION',\n  'EXCEPT',\n  'INTERSECT',\n  'ON',\n  'AND',\n  'OR',\n  'RETURNING',\n];\n\n/**\n * Format SQL for better readability.\n *\n * Adds newlines before major SQL keywords to make\n * complex queries easier to read.\n *\n * @param sql - SQL string to format\n * @returns Formatted SQL string\n *\n * @example\n * ```typescript\n * import { formatSQL } from '@kysera/debug';\n *\n * const sql = 'SELECT id, name FROM users WHERE active = true ORDER BY name';\n * console.log(formatSQL(sql));\n * // SELECT id, name\n * // FROM users\n * // WHERE active = true\n * // ORDER BY name\n * ```\n */\nexport function formatSQL(sql: string): string {\n  let formatted = sql;\n\n  // Add newlines before SQL keywords\n  for (const keyword of SQL_KEYWORDS) {\n    const regex = new RegExp(`(\\\\s+)(${escapeRegex(keyword)})\\\\s+`, 'gi');\n    formatted = formatted.replace(regex, `\\n$2 `);\n  }\n\n  return formatted.trim();\n}\n\n/**\n * Format SQL with indentation for nested queries.\n *\n * More advanced formatting with proper indentation\n * for subqueries and nested structures.\n *\n * @param sql - SQL string to format\n * @param indentSize - Number of spaces for indentation\n * @returns Formatted SQL string\n *\n * @example\n * ```typescript\n * import { formatSQLPretty } from '@kysera/debug';\n *\n * const sql = 'SELECT * FROM users WHERE id IN (SELECT user_id FROM orders)';\n * console.log(formatSQLPretty(sql));\n * ```\n */\nexport function formatSQLPretty(sql: string, indentSize = 2): string {\n  let formatted = formatSQL(sql);\n  const indent = ' '.repeat(indentSize);\n  let level = 0;\n\n  // Handle parentheses for subqueries\n  formatted = formatted.replace(/\\(/g, () => {\n    level++;\n    return '(\\n' + indent.repeat(level);\n  });\n\n  formatted = formatted.replace(/\\)/g, () => {\n    level = Math.max(0, level - 1);\n    return '\\n' + indent.repeat(level) + ')';\n  });\n\n  // Clean up excessive newlines\n  formatted = formatted.replace(/\\n\\s*\\n/g, '\\n');\n\n  return formatted.trim();\n}\n\n/**\n * Minify SQL by removing unnecessary whitespace.\n *\n * @param sql - SQL string to minify\n * @returns Minified SQL string\n *\n * @example\n * ```typescript\n * import { minifySQL } from '@kysera/debug';\n *\n * const sql = `\n *   SELECT id, name\n *   FROM users\n *   WHERE active = true\n * `;\n * console.log(minifySQL(sql));\n * // SELECT id, name FROM users WHERE active = true\n * ```\n */\nexport function minifySQL(sql: string): string {\n  return sql\n    .replace(/\\s+/g, ' ') // Collapse whitespace\n    .replace(/\\s*,\\s*/g, ', ') // Normalize commas\n    .replace(/\\s*\\(\\s*/g, ' (') // Normalize opening parens\n    .replace(/\\s*\\)\\s*/g, ') ') // Normalize closing parens\n    .trim();\n}\n\n/**\n * Highlight SQL keywords in a query.\n *\n * Returns SQL with ANSI color codes for terminal output.\n *\n * @param sql - SQL string to highlight\n * @returns SQL with ANSI color codes\n *\n * @example\n * ```typescript\n * import { highlightSQL } from '@kysera/debug';\n *\n * console.log(highlightSQL('SELECT * FROM users'));\n * // Keywords will be highlighted in blue\n * ```\n */\nexport function highlightSQL(sql: string): string {\n  const BLUE = '\\x1b[34m';\n  const RESET = '\\x1b[0m';\n\n  let highlighted = sql;\n\n  for (const keyword of SQL_KEYWORDS) {\n    const regex = new RegExp(`\\\\b(${escapeRegex(keyword)})\\\\b`, 'gi');\n    highlighted = highlighted.replace(regex, `${BLUE}$1${RESET}`);\n  }\n\n  return highlighted;\n}\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@kysera/debug",
+  "version": "0.6.0",
+  "description": "Debug utilities for Kysera ORM - query logging, profiling, SQL formatting",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "kysely": ">=0.28.8"
+  },
+  "dependencies": {
+    "@kysera/core": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "kysely": "^0.28.8",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "keywords": [
+    "kysely",
+    "orm",
+    "database",
+    "debug",
+    "profiling",
+    "logging",
+    "sql"
+  ],
+  "author": "Kysera Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kysera-dev/kysera.git",
+    "directory": "packages/debug"
+  },
+  "bugs": {
+    "url": "https://github.com/kysera-dev/kysera/issues"
+  },
+  "homepage": "https://github.com/kysera-dev/kysera#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}

package/src/format.ts

@@ -0,0 +1,176 @@
+/**
+ * SQL formatting utilities.
+ *
+ * @module @kysera/debug
+ */
+
+/**
+ * Escape special regex characters in a string.
+ * @internal
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * SQL keywords that should start on a new line.
+ */
+const SQL_KEYWORDS = [
+  'SELECT',
+  'FROM',
+  'WHERE',
+  'JOIN',
+  'LEFT JOIN',
+  'RIGHT JOIN',
+  'INNER JOIN',
+  'OUTER JOIN',
+  'CROSS JOIN',
+  'ORDER BY',
+  'GROUP BY',
+  'HAVING',
+  'LIMIT',
+  'OFFSET',
+  'INSERT INTO',
+  'VALUES',
+  'UPDATE',
+  'SET',
+  'DELETE FROM',
+  'UNION',
+  'EXCEPT',
+  'INTERSECT',
+  'ON',
+  'AND',
+  'OR',
+  'RETURNING',
+];
+
+/**
+ * Format SQL for better readability.
+ *
+ * Adds newlines before major SQL keywords to make
+ * complex queries easier to read.
+ *
+ * @param sql - SQL string to format
+ * @returns Formatted SQL string
+ *
+ * @example
+ * ```typescript
+ * import { formatSQL } from '@kysera/debug';
+ *
+ * const sql = 'SELECT id, name FROM users WHERE active = true ORDER BY name';
+ * console.log(formatSQL(sql));
+ * // SELECT id, name
+ * // FROM users
+ * // WHERE active = true
+ * // ORDER BY name
+ * ```
+ */
+export function formatSQL(sql: string): string {
+  let formatted = sql;
+
+  // Add newlines before SQL keywords
+  for (const keyword of SQL_KEYWORDS) {
+    const regex = new RegExp(`(\\s+)(${escapeRegex(keyword)})\\s+`, 'gi');
+    formatted = formatted.replace(regex, `\n$2 `);
+  }
+
+  return formatted.trim();
+}
+
+/**
+ * Format SQL with indentation for nested queries.
+ *
+ * More advanced formatting with proper indentation
+ * for subqueries and nested structures.
+ *
+ * @param sql - SQL string to format
+ * @param indentSize - Number of spaces for indentation
+ * @returns Formatted SQL string
+ *
+ * @example
+ * ```typescript
+ * import { formatSQLPretty } from '@kysera/debug';
+ *
+ * const sql = 'SELECT * FROM users WHERE id IN (SELECT user_id FROM orders)';
+ * console.log(formatSQLPretty(sql));
+ * ```
+ */
+export function formatSQLPretty(sql: string, indentSize = 2): string {
+  let formatted = formatSQL(sql);
+  const indent = ' '.repeat(indentSize);
+  let level = 0;
+
+  // Handle parentheses for subqueries
+  formatted = formatted.replace(/\(/g, () => {
+    level++;
+    return '(\n' + indent.repeat(level);
+  });
+
+  formatted = formatted.replace(/\)/g, () => {
+    level = Math.max(0, level - 1);
+    return '\n' + indent.repeat(level) + ')';
+  });
+
+  // Clean up excessive newlines
+  formatted = formatted.replace(/\n\s*\n/g, '\n');
+
+  return formatted.trim();
+}
+
+/**
+ * Minify SQL by removing unnecessary whitespace.
+ *
+ * @param sql - SQL string to minify
+ * @returns Minified SQL string
+ *
+ * @example
+ * ```typescript
+ * import { minifySQL } from '@kysera/debug';
+ *
+ * const sql = `
+ *   SELECT id, name
+ *   FROM users
+ *   WHERE active = true
+ * `;
+ * console.log(minifySQL(sql));
+ * // SELECT id, name FROM users WHERE active = true
+ * ```
+ */
+export function minifySQL(sql: string): string {
+  return sql
+    .replace(/\s+/g, ' ') // Collapse whitespace
+    .replace(/\s*,\s*/g, ', ') // Normalize commas
+    .replace(/\s*\(\s*/g, ' (') // Normalize opening parens
+    .replace(/\s*\)\s*/g, ') ') // Normalize closing parens
+    .trim();
+}
+
+/**
+ * Highlight SQL keywords in a query.
+ *
+ * Returns SQL with ANSI color codes for terminal output.
+ *
+ * @param sql - SQL string to highlight
+ * @returns SQL with ANSI color codes
+ *
+ * @example
+ * ```typescript
+ * import { highlightSQL } from '@kysera/debug';
+ *
+ * console.log(highlightSQL('SELECT * FROM users'));
+ * // Keywords will be highlighted in blue
+ * ```
+ */
+export function highlightSQL(sql: string): string {
+  const BLUE = '\x1b[34m';
+  const RESET = '\x1b[0m';
+
+  let highlighted = sql;
+
+  for (const keyword of SQL_KEYWORDS) {
+    const regex = new RegExp(`\\b(${escapeRegex(keyword)})\\b`, 'gi');
+    highlighted = highlighted.replace(regex, `${BLUE}$1${RESET}`);
+  }
+
+  return highlighted;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @kysera/debug - Debug utilities for Kysera ORM
+ *
+ * Provides query logging, metrics collection, profiling,
+ * and SQL formatting utilities.
+ *
+ * @module @kysera/debug
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { withDebug, QueryProfiler, formatSQL } from '@kysera/debug';
+ *
+ * // Add debug capabilities to database
+ * const debugDb = withDebug(db, {
+ *   logQuery: true,
+ *   slowQueryThreshold: 100,
+ * });
+ *
+ * // Execute queries
+ * await debugDb.selectFrom('users').selectAll().execute();
+ *
+ * // Analyze metrics
+ * const metrics = debugDb.getMetrics();
+ * console.log(`Executed ${metrics.length} queries`);
+ *
+ * // Format SQL for display
+ * console.log(formatSQL(metrics[0].sql));
+ * ```
+ */
+
+// Plugin
+export {
+  type QueryMetrics,
+  type DebugOptions,
+  type DebugDatabase,
+  withDebug,
+} from './plugin.js';
+
+// Profiler
+export {
+  type ProfilerSummary,
+  type ProfilerOptions,
+  QueryProfiler,
+} from './profiler.js';
+
+// Formatting
+export {
+  formatSQL,
+  formatSQLPretty,
+  minifySQL,
+  highlightSQL,
+} from './format.js';