feat: comprehensive performance monitoring middleware (#34)

[talkstream]

Summary

This PR adds a comprehensive performance monitoring system to wireframe, based on patterns from the kogotochki project. It provides platform-agnostic operation tracking, statistical analysis, and framework integration for monitoring application performance.

Features

Core Functionality

• PerformanceMonitor class with operation tracking and comprehensive statistics
• Timer API for granular performance measurement
• Slow operation detection with configurable thresholds and custom handlers
• Memory monitoring utilities for tracking heap and RSS usage
• Scoped monitoring for component isolation

Framework Integration

• Express/Connect middleware adapter
• Hono middleware for Cloudflare Workers
• Koa middleware support
• Fastify plugin implementation
• Ready-to-use stats endpoint handler

Advanced Features

• @TrackPerformance decorator for method-level tracking
• Performance budgets with violation detection
• Export functionality for external analytics
• Sampling support for high-traffic applications

Implementation Details

1. Type-safe Implementation

   • Full TypeScript strict mode compliance
   • Framework-agnostic design using 'any' types where necessary
   • Proper error handling and logging integration

2. Production Ready

   • Configurable metric retention limits
   • Memory-efficient circular buffer for metrics
   • Support for high-traffic sampling
   • Automatic cleanup strategies

3. Developer Experience

   • Comprehensive documentation with examples
   • Easy integration with existing codebases
   • Minimal configuration required
   • Intuitive API design

Usage Example

import { PerformanceMonitor } from '@/middleware/performance-monitor';
import { createHonoMiddleware } from '@/middleware/performance-http';

const monitor = new PerformanceMonitor({
  slowOperationThreshold: 1000,
  onSlowOperation: async (metrics) => {
    console.error('Slow operation detected', metrics);
  }
});

// Use with Hono
app.use('*', createHonoMiddleware(monitor));

// Track custom operations
const result = await monitor.trackOperation(
  'database.query',
  async () => await db.query('SELECT * FROM users'),
  { query: 'users' }
);

// Get statistics
const stats = monitor.getStats('database.query');
console.log(`Average query time: ${stats.avgDuration}ms`);

Tests

• Comprehensive test suite with 19 tests covering all functionality
• Timer accuracy validation
• Statistical calculations verification
• Framework integration testing
• Decorator functionality tests

Documentation

Added comprehensive documentation in docs/patterns/performance-monitoring.md covering:

• Basic and advanced usage
• Framework integration guides
• Production considerations
• Performance budgets
• Troubleshooting guide

Notes

• Enabled experimental decorators in tsconfig.json for @TrackPerformance support
• Framework middleware uses 'any' types for maximum compatibility
• All TypeScript and ESLint checks pass

This monitoring system has been battle-tested in the kogotochki production bot and provides essential insights for maintaining application performance.

Related to #17, #18 (performance optimization patterns from kogotochki)