@geenius/tools 0.1.0

package/packages/perf/react/src/components/PerformanceDashboard.tsx

@@ -0,0 +1,257 @@
+/**
+ * @geenius-tools/perf-react — components/PerformanceDashboard.tsx
+ *
+ * Rich performance dashboard with SSR cache hit rates, query performance,
+ * and error metrics. Uses @geenius-ui/react for UI primitives.
+ *
+ * Uses Tailwind CSS utility classes.
+ */
+
+import { type FC } from 'react'
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface CacheMetrics {
+    hitRate: number
+    totalRequests: number
+    hits: number
+    misses: number
+    avgHitTime: number
+    avgMissTime: number
+}
+
+export interface QueryMetric {
+    queryKey: string
+    executions: number
+    avgDuration: number
+    minDuration: number
+    maxDuration: number
+    errors: number
+    cached: boolean
+}
+
+export interface ErrorMetric {
+    type: string
+    message: string
+    count: number
+    firstSeen: number
+    lastSeen: number
+}
+
+export interface PerformanceMetricsData {
+    score: number
+    cache: CacheMetrics
+    queries: QueryMetric[]
+    errors: ErrorMetric[]
+}
+
+export interface PerformanceDashboardProps {
+    /** Metrics data to display */
+    metrics: PerformanceMetricsData | null
+    /** Whether metrics are currently loading */
+    isLoading: boolean
+    /** Error if loading failed */
+    error: Error | null
+    /** Callback to refresh metrics */
+    onRefresh: () => void
+    /** Callback to clear metrics */
+    onClear: () => void
+    /** Callback to export metrics as JSON string */
+    onExport: () => string
+}
+
+/**
+ * PerformanceDashboard — displays SSR cache hit rates, query performance,
+ * and error metrics in a rich dashboard layout.
+ *
+ * This component is headless regarding data — the caller must provide
+ * the metrics data and callbacks. Use with `usePerformanceMetrics` hook.
+ */
+export const PerformanceDashboard: FC<PerformanceDashboardProps> = ({
+    metrics,
+    isLoading,
+    error,
+    onRefresh,
+    onClear,
+    onExport,
+}) => {
+
+    if (isLoading && !metrics) {
+        return (
+            <div className="flex justify-center py-8">
+                <div className="animate-spin h-8 w-8 border-2 border-primary border-t-transparent rounded-full" />
+                <span className="ml-3 text-muted-foreground">Loading performance metrics…</span>
+            </div>
+        )
+    }
+
+    if (error) {
+        return (
+            <div className="rounded-xl border border-border bg-card p-6">
+                <div className="text-red-600">
+                    Error loading metrics: {error.message}
+                </div>
+            </div>
+        )
+    }
+
+    if (!metrics) return null
+
+    const downloadMetrics = () => {
+        const data = onExport()
+        const blob = new Blob([data], { type: 'application/json' })
+        const url = URL.createObjectURL(blob)
+        const a = document.createElement('a')
+        a.href = url
+        a.download = `performance-metrics-${Date.now()}.json`
+        a.click()
+        URL.revokeObjectURL(url)
+    }
+
+    const scoreBadge = (score: number) => {
+        if (score >= 90) return { emoji: '🟢', label: 'Excellent', color: 'bg-green-100 text-green-800' }
+        if (score >= 70) return { emoji: '🟡', label: 'Good', color: 'bg-yellow-100 text-yellow-800' }
+        return { emoji: '🔴', label: 'Needs Improvement', color: 'bg-red-100 text-red-800' }
+    }
+
+    const badge = scoreBadge(metrics.score)
+
+    return (
+        <div className="space-y-6">
+            {/* Header */}
+            <div className="flex items-center justify-between">
+                <div>
+                    <h1 className="text-2xl font-bold">Performance Monitoring</h1>
+                    <p className="text-muted-foreground mt-1">SSR Cache, Query Performance, and Error Tracking</p>
+                </div>
+                <div className="flex gap-2">
+                    <button type="button" onClick={onRefresh} className="px-4 py-2 rounded-lg border border-border text-sm font-medium hover:bg-bg-muted transition-colors">Refresh</button>
+                    <button type="button" onClick={downloadMetrics} className="px-4 py-2 rounded-lg border border-border text-sm font-medium hover:bg-bg-muted transition-colors">Export</button>
+                    <button type="button" onClick={onClear} className="px-4 py-2 rounded-lg border border-border text-sm font-medium hover:bg-bg-muted transition-colors">Clear</button>
+                </div>
+            </div>
+
+            {/* Overall Score */}
+            <div className="rounded-xl border border-border bg-card p-6">
+                <div className="flex items-center justify-between">
+                    <div>
+                        <div className="text-sm text-muted-foreground mb-1">Overall Performance Score</div>
+                        <div className="text-4xl font-bold text-foreground">{metrics.score}</div>
+                    </div>
+                    <div className="text-5xl">{badge.emoji}</div>
+                </div>
+                <div className="mt-4">
+                    <span className={`px-2 py-1 rounded-full text-xs font-medium ${badge.color}`}>{badge.label}</span>
+                </div>
+            </div>
+
+            {/* SSR Cache Metrics */}
+            <div>
+                <h2 className="text-xl font-semibold mb-4">SSR Cache Performance</h2>
+                <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
+                    <MetricCard label="Cache Hit Rate" value={`${metrics.cache.hitRate.toFixed(1)}%`} badge={metrics.cache.hitRate >= 80 ? 'Excellent' : metrics.cache.hitRate >= 50 ? 'Good' : 'Poor'} badgeColor={metrics.cache.hitRate >= 80 ? 'bg-green-100 text-green-800' : metrics.cache.hitRate >= 50 ? 'bg-yellow-100 text-yellow-800' : 'bg-red-100 text-red-800'} />
+                    <MetricCard label="Total Requests" value={metrics.cache.totalRequests.toLocaleString()} subtitle={`${metrics.cache.hits} hits / ${metrics.cache.misses} misses`} />
+                    <MetricCard label="Avg Hit Time" value={`${metrics.cache.avgHitTime.toFixed(0)}`} unit="ms" badge={metrics.cache.avgHitTime < 50 ? 'Fast' : 'Acceptable'} badgeColor={metrics.cache.avgHitTime < 50 ? 'bg-green-100 text-green-800' : 'bg-yellow-100 text-yellow-800'} />
+                    <MetricCard label="Avg Miss Time" value={`${metrics.cache.avgMissTime.toFixed(0)}`} unit="ms" subtitle={`Time saved: ${(metrics.cache.avgMissTime - metrics.cache.avgHitTime).toFixed(0)}ms`} />
+                </div>
+            </div>
+
+            {/* Top Queries */}
+            <div>
+                <h2 className="text-xl font-semibold mb-4">Top Queries by Executions</h2>
+                <div className="rounded-xl border border-border bg-card overflow-x-auto">
+                    <table className="w-full">
+                        <thead>
+                            <tr className="border-b border-border">
+                                {['Query', 'Executions', 'Avg Duration', 'Errors', 'Cached'].map((h) => (
+                                    <th key={h} className="text-left p-4 text-sm font-semibold text-muted-foreground">{h}</th>
+                                ))}
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {metrics.queries.slice(0, 10).map((query, idx) => (
+                                <tr key={idx} className="border-b border-border/50 hover:bg-surface">
+                                    <td className="p-4 text-sm font-mono text-foreground truncate max-w-xs">{query.queryKey}</td>
+                                    <td className="p-4 text-sm text-foreground">{query.executions}</td>
+                                    <td className="p-4 text-sm text-foreground">
+                                        {query.avgDuration.toFixed(0)}ms
+                                        <span className="text-xs text-muted-foreground ml-2">({query.minDuration.toFixed(0)}-{query.maxDuration.toFixed(0)}ms)</span>
+                                    </td>
+                                    <td className="p-4">
+                                        {query.errors > 0
+                                            ? <span className="px-2 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800">{query.errors}</span>
+                                            : <span className="text-sm text-muted-foreground/60">0</span>
+                                        }
+                                    </td>
+                                    <td className="p-4">
+                                        <span className={`px-2 py-0.5 rounded-full text-xs font-medium ${query.cached ? 'bg-green-100 text-green-800' : 'bg-gray-100 text-gray-600'}`}>
+                                            {query.cached ? 'Yes' : 'No'}
+                                        </span>
+                                    </td>
+                                </tr>
+                            ))}
+                            {metrics.queries.length === 0 && (
+                                <tr><td colSpan={5} className="p-8 text-center text-muted-foreground">No query data available</td></tr>
+                            )}
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            {/* Errors */}
+            {metrics.errors.length > 0 && (
+                <div>
+                    <h2 className="text-xl font-semibold mb-4">Recent Errors</h2>
+                    <div className="rounded-xl border border-border bg-card divide-y divide-border">
+                        {metrics.errors.slice(0, 5).map((err, idx) => (
+                            <div key={idx} className="p-4">
+                                <div className="flex items-start justify-between">
+                                    <div className="flex-1">
+                                        <div className="flex items-center gap-2 mb-1">
+                                            <span className="px-2 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800">{err.type}</span>
+                                            <span className="text-sm font-semibold text-foreground">{err.message}</span>
+                                        </div>
+                                        <div className="text-xs text-muted-foreground">
+                                            First seen: {new Date(err.firstSeen).toLocaleString()} | Last seen: {new Date(err.lastSeen).toLocaleString()}
+                                        </div>
+                                    </div>
+                                    <div className="text-right ml-4">
+                                        <div className="text-lg font-bold text-red-600">{err.count}</div>
+                                        <div className="text-xs text-muted-foreground">occurrences</div>
+                                    </div>
+                                </div>
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            )}
+        </div>
+    )
+}
+
+// ─── MetricCard helper ──────────────────────────────────────────────────────
+
+function MetricCard({ label, value, unit, subtitle, badge, badgeColor }: {
+    label: string
+    value: string
+    unit?: string
+    subtitle?: string
+    badge?: string
+    badgeColor?: string
+}) {
+    return (
+        <div className="rounded-xl border border-border bg-card p-6">
+            <div className="text-sm text-muted-foreground mb-1">{label}</div>
+            <div className="text-3xl font-bold text-foreground">
+                {value}
+                {unit && <span className="text-lg text-muted-foreground">{unit}</span>}
+            </div>
+            {badge && (
+                <div className="mt-2">
+                    <span className={`px-2 py-0.5 rounded-full text-xs font-medium ${badgeColor}`}>{badge}</span>
+                </div>
+            )}
+            {subtitle && <div className="mt-2 text-sm text-muted-foreground">{subtitle}</div>}
+        </div>
+    )
+}

package/packages/perf/react/src/hooks/useMonitoredQuery.ts

@@ -0,0 +1,89 @@
+// @geenius-tools/perf-react — src/hooks/useMonitoredQuery.ts
+// TanStack Query wrapper with automatic performance tracking
+
+import { useEffect, useRef } from 'react'
+import { PerformanceMonitor } from '../services/PerformanceMonitor'
+
+/**
+ * Type-safe wrapper types for TanStack Query
+ * We use generic types to avoid hard dependency on @tanstack/react-query
+ */
+interface MonitoredQueryResult {
+    isSuccess: boolean
+    isError: boolean
+    error: unknown
+    isFetched: boolean
+    isFetchedAfterMount: boolean
+}
+
+interface UseMonitoredQueryOptions {
+    queryKey: readonly unknown[]
+}
+
+/**
+ * Hook that adds performance monitoring to a TanStack Query result
+ *
+ * @example
+ * import { useQuery } from '@tanstack/react-query'
+ *
+ * const result = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+ * useQueryMonitor(result, { queryKey: ['users'] })
+ */
+export function useQueryMonitor(
+    result: MonitoredQueryResult,
+    options: UseMonitoredQueryOptions,
+): void {
+    const startTimeRef = useRef<number>(0)
+    const queryKey = JSON.stringify(options.queryKey)
+
+    // Start timing before query
+    useEffect(() => {
+        startTimeRef.current = performance.now()
+    }, [queryKey])
+
+    // Track query performance
+    useEffect(() => {
+        if (result.isSuccess || result.isError) {
+            const duration = performance.now() - startTimeRef.current
+
+            PerformanceMonitor.trackQuery(
+                queryKey,
+                duration,
+                result.error instanceof Error ? result.error : undefined,
+                result.isFetched && !result.isFetchedAfterMount,
+            )
+
+            // Track cache hit/miss
+            if (result.isFetched && !result.isFetchedAfterMount) {
+                PerformanceMonitor.trackCacheHit({
+                    queryKey,
+                    duration,
+                    timestamp: Date.now(),
+                    cacheType: 'client',
+                })
+            } else if (result.isFetchedAfterMount) {
+                PerformanceMonitor.trackCacheMiss({
+                    queryKey,
+                    duration: 0,
+                    timestamp: Date.now(),
+                    cacheType: 'client',
+                    fetchDuration: duration,
+                })
+            }
+        }
+    }, [
+        result.isSuccess,
+        result.isError,
+        queryKey,
+        result.error,
+        result.isFetched,
+        result.isFetchedAfterMount,
+    ])
+
+    // Track errors
+    useEffect(() => {
+        if (result.error instanceof Error) {
+            PerformanceMonitor.trackError(result.error, 'query')
+        }
+    }, [result.error])
+}

package/packages/perf/react/src/hooks/usePerformanceMetrics.ts

@@ -0,0 +1,78 @@
+// @geenius-tools/perf-react — src/hooks/usePerformanceMetrics.ts
+
+import { useState, useEffect, useCallback } from 'react'
+import { PerformanceMonitor } from '../services/PerformanceMonitor'
+import type { PerformanceMetrics } from '../types'
+
+export interface UsePerformanceMetricsOptions {
+    /** Time range for metrics in milliseconds (default: 24h) */
+    timeRange?: number
+    /** Polling interval in milliseconds (default: 5000) */
+    pollingInterval?: number
+    /** Enable auto-refresh (default: true) */
+    autoRefresh?: boolean
+}
+
+/**
+ * React hook for accessing performance metrics
+ *
+ * @example
+ * const { metrics, isLoading, refresh, clearMetrics } = usePerformanceMetrics({
+ *   timeRange: 60 * 60 * 1000, // 1 hour
+ *   pollingInterval: 3000,
+ * })
+ */
+export function usePerformanceMetrics(
+    options: UsePerformanceMetricsOptions = {},
+) {
+    const {
+        timeRange = 24 * 60 * 60 * 1000,
+        pollingInterval = 5000,
+        autoRefresh = true,
+    } = options
+
+    const [metrics, setMetrics] = useState<PerformanceMetrics | null>(null)
+    const [isLoading, setIsLoading] = useState(true)
+    const [error, setError] = useState<Error | null>(null)
+
+    const fetchMetrics = useCallback(() => {
+        try {
+            const end = Date.now()
+            const start = end - timeRange
+            const data = PerformanceMonitor.getMetrics({ start, end })
+            setMetrics(data)
+            setError(null)
+        } catch (err) {
+            setError(err instanceof Error ? err : new Error('Failed to fetch metrics'))
+        } finally {
+            setIsLoading(false)
+        }
+    }, [timeRange])
+
+    useEffect(() => {
+        fetchMetrics()
+
+        if (autoRefresh) {
+            const interval = setInterval(fetchMetrics, pollingInterval)
+            return () => clearInterval(interval)
+        }
+    }, [fetchMetrics, autoRefresh, pollingInterval])
+
+    const clearMetrics = useCallback(() => {
+        PerformanceMonitor.clear()
+        fetchMetrics()
+    }, [fetchMetrics])
+
+    const exportMetrics = useCallback(() => {
+        return PerformanceMonitor.exportMetrics()
+    }, [])
+
+    return {
+        metrics,
+        isLoading,
+        error,
+        refresh: fetchMetrics,
+        clearMetrics,
+        exportMetrics,
+    }
+}

package/packages/perf/react/src/index.ts

@@ -0,0 +1,33 @@
+// @geenius-tools/perf-react — src/index.ts
+
+// ===== Types =====
+export type {
+    CacheMetrics,
+    QueryMetrics,
+    PageLoadMetrics,
+    ErrorMetrics,
+    PerformanceMetrics,
+    PerformanceConfig,
+    CacheHitEvent,
+    CacheMissEvent,
+} from './types'
+
+// ===== Service =====
+export { PerformanceMonitor } from './services/PerformanceMonitor'
+
+// ===== Hooks =====
+export { usePerformanceMetrics } from './hooks/usePerformanceMetrics'
+export type { UsePerformanceMetricsOptions } from './hooks/usePerformanceMetrics'
+
+export { useQueryMonitor } from './hooks/useMonitoredQuery'
+
+// ===== Components =====
+export { PerformanceDashboard } from './components/PerformanceDashboard'
+export type {
+    PerformanceDashboardProps,
+    PerformanceMetricsData,
+    CacheMetrics as DashboardCacheMetrics,
+    QueryMetric,
+    ErrorMetric,
+} from './components/PerformanceDashboard'
+