gthinking 1.2.1 → 2.1.1

package/src/utils/logger.ts

@@ -0,0 +1,290 @@
+/**
+ * Logger Utility for gthinking v2.0.0
+ * Structured logging with Winston
+ */
+
+import winston from 'winston';
+
+/**
+ * Log levels
+ */
+export const LogLevel = {
+  ERROR: 'error',
+  WARN: 'warn',
+  INFO: 'info',
+  DEBUG: 'debug',
+} as const;
+
+export type LogLevelType = typeof LogLevel[keyof typeof LogLevel];
+
+/**
+ * Logger configuration interface
+ */
+export interface LoggerConfig {
+  level: LogLevelType;
+  enableConsole: boolean;
+  enableFile: boolean;
+  logDir?: string;
+  maxFiles?: number;
+  maxSize?: string;
+}
+
+/**
+ * Default logger configuration
+ */
+const defaultConfig: LoggerConfig = {
+  level: 'info',
+  enableConsole: true,
+  enableFile: false,
+};
+
+/**
+ * Create a Winston logger instance
+ * @param config - Logger configuration
+ * @returns Winston logger instance
+ */
+export function createLogger(config: Partial<LoggerConfig> = {}): winston.Logger {
+  const mergedConfig = { ...defaultConfig, ...config };
+  
+  const transports: winston.transport[] = [];
+  
+  if (mergedConfig.enableConsole) {
+    transports.push(new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+        winston.format.printf(({ level, message, timestamp, ...metadata }) => {
+          let msg = `${timestamp} [${level}]: ${message}`;
+          if (Object.keys(metadata).length > 0) {
+            msg += ` ${JSON.stringify(metadata)}`;
+          }
+          return msg;
+        })
+      ),
+    }));
+  }
+  
+  if (mergedConfig.enableFile && mergedConfig.logDir) {
+    transports.push(new winston.transports.File({
+      filename: `${mergedConfig.logDir}/error.log`,
+      level: 'error',
+      maxFiles: mergedConfig.maxFiles || 5,
+      maxsize: (mergedConfig.maxSize || '10m') as any,
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json()
+      ),
+    }));
+    
+    transports.push(new winston.transports.File({
+      filename: `${mergedConfig.logDir}/combined.log`,
+      maxFiles: mergedConfig.maxFiles || 5,
+      maxsize: (mergedConfig.maxSize || '10m') as any,
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json()
+      ),
+    }));
+  }
+  
+  return winston.createLogger({
+    level: mergedConfig.level,
+    defaultMeta: { service: 'gthinking' },
+    transports,
+    exitOnError: false,
+  });
+}
+
+// Create default logger instance
+let defaultLogger: winston.Logger = createLogger();
+
+/**
+ * Set the default logger
+ * @param logger - The logger to set as default
+ */
+export function setDefaultLogger(logger: winston.Logger): void {
+  defaultLogger = logger;
+}
+
+/**
+ * Get the default logger
+ * @returns The default logger instance
+ */
+export function getDefaultLogger(): winston.Logger {
+  return defaultLogger;
+}
+
+/**
+ * Log an error message
+ * @param message - The error message
+ * @param metadata - Additional metadata
+ */
+export function error(message: string, metadata: Record<string, unknown> = {}): void {
+  defaultLogger.error(message, metadata);
+}
+
+/**
+ * Log a warning message
+ * @param message - The warning message
+ * @param metadata - Additional metadata
+ */
+export function warn(message: string, metadata: Record<string, unknown> = {}): void {
+  defaultLogger.warn(message, metadata);
+}
+
+/**
+ * Log an info message
+ * @param message - The info message
+ * @param metadata - Additional metadata
+ */
+export function info(message: string, metadata: Record<string, unknown> = {}): void {
+  defaultLogger.info(message, metadata);
+}
+
+/**
+ * Log a debug message
+ * @param message - The debug message
+ * @param metadata - Additional metadata
+ */
+export function debug(message: string, metadata: Record<string, unknown> = {}): void {
+  defaultLogger.debug(message, metadata);
+}
+
+/**
+ * Create a child logger with default metadata
+ * @param defaultMetadata - Default metadata to include
+ * @returns Child logger
+ */
+export function createChildLogger(defaultMetadata: Record<string, unknown>): winston.Logger {
+  return defaultLogger.child(defaultMetadata);
+}
+
+/**
+ * Logger class for component-specific logging
+ */
+export class Logger {
+  private logger: winston.Logger;
+  private component: string;
+
+  constructor(component: string, config?: Partial<LoggerConfig>) {
+    this.component = component;
+    this.logger = createLogger(config);
+  }
+
+  /**
+   * Log an error message
+   */
+  public error(message: string, metadata: Record<string, unknown> = {}): void {
+    this.logger.error(message, { component: this.component, ...metadata });
+  }
+
+  /**
+   * Log a warning message
+   */
+  public warn(message: string, metadata: Record<string, unknown> = {}): void {
+    this.logger.warn(message, { component: this.component, ...metadata });
+  }
+
+  /**
+   * Log an info message
+   */
+  public info(message: string, metadata: Record<string, unknown> = {}): void {
+    this.logger.info(message, { component: this.component, ...metadata });
+  }
+
+  /**
+   * Log a debug message
+   */
+  public debug(message: string, metadata: Record<string, unknown> = {}): void {
+    this.logger.debug(message, { component: this.component, ...metadata });
+  }
+
+  /**
+   * Create a child logger
+   */
+  public child(metadata: Record<string, unknown>): winston.Logger {
+    return this.logger.child({ component: this.component, ...metadata });
+  }
+}
+
+/**
+ * Performance logger for tracking operation performance
+ */
+export class PerformanceLogger {
+  private logger: winston.Logger;
+  private timings: Map<string, number> = new Map();
+
+  constructor() {
+    this.logger = createLogger({ level: 'debug' });
+  }
+
+  /**
+   * Start timing an operation
+   * @param operation - The operation name
+   */
+  public start(operation: string): void {
+    this.timings.set(operation, Date.now());
+  }
+
+  /**
+   * End timing an operation and log the duration
+   * @param operation - The operation name
+   * @param metadata - Additional metadata
+   */
+  public end(operation: string, metadata: Record<string, unknown> = {}): number {
+    const startTime = this.timings.get(operation);
+    if (!startTime) {
+      this.logger.warn(`No start time found for operation: ${operation}`);
+      return 0;
+    }
+    
+    const duration = Date.now() - startTime;
+    this.timings.delete(operation);
+    
+    this.logger.debug(`Operation ${operation} completed`, {
+      operation,
+      duration,
+      ...metadata,
+    });
+    
+    return duration;
+  }
+
+  /**
+   * Log a performance metric
+   * @param metric - The metric name
+   * @param value - The metric value
+   * @param metadata - Additional metadata
+   */
+  public logMetric(metric: string, value: number, metadata: Record<string, unknown> = {}): void {
+    this.logger.debug(`Performance metric: ${metric}`, {
+      metric,
+      value,
+      ...metadata,
+    });
+  }
+
+  /**
+   * Clear all timings
+   */
+  public clear(): void {
+    this.timings.clear();
+  }
+}
+
+// Export a singleton performance logger
+export const performanceLogger = new PerformanceLogger();
+
+/**
+ * Default logger instance
+ */
+export const logger = defaultLogger;
+
+/**
+ * Create a component logger
+ * @param component - Component name
+ * @returns Logger instance
+ */
+export function createComponentLogger(component: string): Logger {
+  return new Logger(component);
+}

package/src/utils/metrics.ts

@@ -0,0 +1,380 @@
+/**
+ * Metrics Utility for gthinking v2.0.0
+ * Performance metrics and monitoring
+ */
+
+import { EventEmitter } from 'events';
+import { Logger } from './logger';
+
+const logger = new Logger('Metrics');
+
+/**
+ * Metric types
+ */
+export type MetricType = 'counter' | 'gauge' | 'histogram' | 'timer';
+
+/**
+ * Metric value type
+ */
+export type MetricValue = number | Record<string, number>;
+
+/**
+ * Metric interface
+ */
+export interface Metric {
+  name: string;
+  type: MetricType;
+  value: MetricValue;
+  labels: Record<string, string>;
+  timestamp: number;
+}
+
+/**
+ * Timer metric interface
+ */
+export interface TimerMetric {
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+}
+
+/**
+ * Histogram bucket interface
+ */
+export interface HistogramBucket {
+  upperBound: number;
+  count: number;
+}
+
+/**
+ * Metrics collector class
+ */
+export class MetricsCollector extends EventEmitter {
+  private metrics: Map<string, Metric> = new Map();
+  private timers: Map<string, TimerMetric> = new Map();
+  private histograms: Map<string, number[]> = new Map();
+  private enabled = true;
+
+  /**
+   * Enable or disable metrics collection
+   * @param enabled - Whether to enable metrics
+   */
+  public setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Record a counter metric
+   * @param name - Metric name
+   * @param value - Counter value (default: 1)
+   * @param labels - Metric labels
+   */
+  public counter(name: string, value = 1, labels: Record<string, string> = {}): void {
+    if (!this.enabled) return;
+
+    const key = this.getMetricKey(name, labels);
+    const existing = this.metrics.get(key);
+    
+    if (existing && existing.type === 'counter') {
+      existing.value = (existing.value as number) + value;
+      existing.timestamp = Date.now();
+    } else {
+      this.metrics.set(key, {
+        name,
+        type: 'counter',
+        value,
+        labels,
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  /**
+   * Record a gauge metric
+   * @param name - Metric name
+   * @param value - Gauge value
+   * @param labels - Metric labels
+   */
+  public gauge(name: string, value: number, labels: Record<string, string> = {}): void {
+    if (!this.enabled) return;
+
+    const key = this.getMetricKey(name, labels);
+    this.metrics.set(key, {
+      name,
+      type: 'gauge',
+      value,
+      labels,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Start a timer
+   * @param name - Timer name
+   * @param labels - Timer labels
+   */
+  public startTimer(name: string, labels: Record<string, string> = {}): string {
+    const key = this.getMetricKey(name, labels);
+    this.timers.set(key, { startTime: Date.now() });
+    return key;
+  }
+
+  /**
+   * End a timer and record the duration
+   * @param key - Timer key returned by startTimer
+   * @returns Duration in milliseconds
+   */
+  public endTimer(key: string): number {
+    const timer = this.timers.get(key);
+    if (!timer) {
+      logger.warn(`Timer not found: ${key}`);
+      return 0;
+    }
+
+    timer.endTime = Date.now();
+    timer.duration = timer.endTime - timer.startTime;
+    this.timers.delete(key);
+
+    // Record as histogram
+    this.histogram(key, timer.duration);
+
+    return timer.duration;
+  }
+
+  /**
+   * Record a histogram value
+   * @param name - Histogram name
+   * @param value - Value to record
+   * @param labels - Histogram labels
+   */
+  public histogram(name: string, value: number, labels: Record<string, string> = {}): void {
+    if (!this.enabled) return;
+
+    const key = this.getMetricKey(name, labels);
+    const existing = this.histograms.get(key);
+    
+    if (existing) {
+      existing.push(value);
+    } else {
+      this.histograms.set(key, [value]);
+    }
+  }
+
+  /**
+   * Get all metrics
+   * @returns Array of all metrics
+   */
+  public getMetrics(): Metric[] {
+    return Array.from(this.metrics.values());
+  }
+
+  /**
+   * Get metrics by name
+   * @param name - Metric name
+   * @returns Array of metrics with the given name
+   */
+  public getMetricsByName(name: string): Metric[] {
+    return this.getMetrics().filter(m => m.name === name);
+  }
+
+  /**
+   * Get histogram statistics
+   * @param name - Histogram name
+   * @param labels - Histogram labels
+   * @returns Histogram statistics
+   */
+  public getHistogramStats(name: string, labels: Record<string, string> = {}): {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    mean: number;
+    p50: number;
+    p95: number;
+    p99: number;
+  } | null {
+    const key = this.getMetricKey(name, labels);
+    const values = this.histograms.get(key);
+    
+    if (!values || values.length === 0) {
+      return null;
+    }
+
+    const sorted = [...values].sort((a, b) => a - b);
+    const count = sorted.length;
+    const sum = sorted.reduce((a, b) => a + b, 0);
+    const min = sorted[0];
+    const max = sorted[count - 1];
+    const mean = sum / count;
+
+    const percentile = (p: number): number => {
+      const index = Math.ceil((p / 100) * count) - 1;
+      return sorted[Math.max(0, index)];
+    };
+
+    return {
+      count,
+      sum,
+      min,
+      max,
+      mean,
+      p50: percentile(50),
+      p95: percentile(95),
+      p99: percentile(99),
+    };
+  }
+
+  /**
+   * Clear all metrics
+   */
+  public clear(): void {
+    this.metrics.clear();
+    this.timers.clear();
+    this.histograms.clear();
+  }
+
+  /**
+   * Export metrics in Prometheus format
+   * @returns Metrics in Prometheus format
+   */
+  public exportPrometheus(): string {
+    const lines: string[] = [];
+
+    for (const metric of this.metrics.values()) {
+      const labels = Object.entries(metric.labels)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+      
+      const labelStr = labels ? `{${labels}}` : '';
+      lines.push(`${metric.name}${labelStr} ${metric.value}`);
+    }
+
+    for (const [key, values] of this.histograms.entries()) {
+      const [name, ...labelParts] = key.split(':');
+      const labels = labelParts.join(':');
+      const stats = this.getHistogramStats(name, labels ? JSON.parse(labels) : {});
+      
+      if (stats) {
+        lines.push(`${name}_count${labels ? `{${labels}}` : ''} ${stats.count}`);
+        lines.push(`${name}_sum${labels ? `{${labels}}` : ''} ${stats.sum}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Export metrics as JSON
+   * @returns Metrics as JSON object
+   */
+  public exportJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {
+      counters: {},
+      gauges: {},
+      histograms: {},
+      timestamps: {},
+    };
+
+    for (const metric of this.metrics.values()) {
+      const key = this.getMetricKey(metric.name, metric.labels);
+      
+      if (metric.type === 'counter') {
+        (result.counters as Record<string, number>)[key] = metric.value as number;
+      } else if (metric.type === 'gauge') {
+        (result.gauges as Record<string, number>)[key] = metric.value as number;
+      }
+      
+      (result.timestamps as Record<string, number>)[key] = metric.timestamp;
+    }
+
+    for (const [key, values] of this.histograms.entries()) {
+      const [name, ...labelParts] = key.split(':');
+      const labels = labelParts.join(':');
+      const stats = this.getHistogramStats(name, labels ? JSON.parse(labels) : {});
+      
+      if (stats) {
+        (result.histograms as Record<string, unknown>)[key] = stats;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Generate a metric key from name and labels
+   * @param name - Metric name
+   * @param labels - Metric labels
+   * @returns Metric key
+   */
+  private getMetricKey(name: string, labels: Record<string, string>): string {
+    if (Object.keys(labels).length === 0) {
+      return name;
+    }
+    return `${name}:${JSON.stringify(labels)}`;
+  }
+}
+
+// Export a singleton instance
+export const metricsCollector = new MetricsCollector();
+
+/**
+ * Decorator for timing function execution
+ * @param metricName - The metric name to use
+ * @returns Method decorator
+ */
+export function timed(metricName?: string) {
+  return function (
+    target: unknown,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ): void {
+    const originalMethod = descriptor.value;
+    const name = metricName || `${target.constructor.name}_${propertyKey}`;
+
+    descriptor.value = function (...args: unknown[]) {
+      const timerKey = metricsCollector.startTimer(name);
+      
+      try {
+        const result = originalMethod.apply(this, args);
+        
+        if (result instanceof Promise) {
+          return result.finally(() => {
+            metricsCollector.endTimer(timerKey);
+          });
+        } else {
+          metricsCollector.endTimer(timerKey);
+          return result;
+        }
+      } catch (error) {
+        metricsCollector.endTimer(timerKey);
+        throw error;
+      }
+    };
+  };
+}
+
+/**
+ * Track operation metrics
+ * @param operation - Operation name
+ * @param stage - Operation stage
+ * @param fn - Function to track
+ * @returns Function result
+ */
+export async function trackOperation<T>(
+  operation: string,
+  stage: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  const timerKey = metricsCollector.startTimer(`operation_${operation}`, { stage });
+  
+  try {
+    const result = await fn();
+    metricsCollector.counter(`operation_${operation}_success`, 1, { stage });
+    return result;
+  } catch (error) {
+    metricsCollector.counter(`operation_${operation}_error`, 1, { stage });
+    throw error;
+  } finally {
+    metricsCollector.endTimer(timerKey);
+  }
+}

package/src/utils/timer.ts

@@ -0,0 +1,15 @@
+export class Timer {
+  private start: number;
+
+  constructor() {
+    this.start = Date.now();
+  }
+
+  public elapsed(): number {
+    return Date.now() - this.start;
+  }
+  
+  public reset(): void {
+    this.start = Date.now();
+  }
+}