wizinsight

A TypeScript-based client-side performance & monitoring library for hyperwiz.

Features

✅ Request Metrics Tracking - Monitor HTTP request performance, timing, and metadata
🔄 Non-intrusive Interception - Works with existing hyperwiz clients without breaking changes
📊 Flexible Callbacks - Custom hooks for request start, end, and error events
📦 Zero Dependencies - Lightweight with hyperwiz as peer dependency only

Installation

npm install wizinsight

Note: This library requires hyperwiz as a peer dependency. Make sure you have it installed:

npm install hyperwiz

Quick Start

import { createClient } from 'hyperwiz'
import { initMetricsInterceptor } from 'wizinsight'

// Create your hyperwiz client
const client = createClient('https://api.example.com')

// Initialize metrics interceptor
initMetricsInterceptor(client)

// Now all requests will be tracked automatically
const response = await client.get('/users')

API Reference

`initMetricsInterceptor(client, options?)`

Initializes metrics interception for a hyperwiz client.

Parameters

client - The hyperwiz client instance
options - Optional configuration object

Options

interface MetricsInterceptorOptions {
  onRequestStart?: (metrics: RequestMetrics) => void
  onRequestEnd?: (metrics: RequestMetrics) => void
  onRequestError?: (metrics: RequestMetrics) => void
  collectRequestSize?: boolean
  collectResponseSize?: boolean
  collectNetworkInfo?: boolean
}

`RequestMetrics`

interface RequestMetrics {
  url: string
  method: string
  startTime: number
  endTime?: number
  duration?: number
  status?: number
  statusText?: string
  error?: Error
  requestSize?: number
  responseSize?: number
  timestamp: number
  networkInfo?: NetworkInfo
}

`NetworkInfo`

interface NetworkInfo {
  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g' | '5g'
  downlink?: number
  rtt?: number
  saveData?: boolean
  connectionType?: string
}

Usage Examples

Basic Usage

import { createClient } from 'hyperwiz'
import { initMetricsInterceptor } from 'wizinsight'

const client = createClient('https://api.example.com')
initMetricsInterceptor(client)

// All requests are now tracked
await client.get('/users')
await client.post('/users', { name: 'John' })

Advanced Usage with Callbacks

import { createClient } from 'hyperwiz'
import { initMetricsInterceptor } from 'wizinsight'

const client = createClient('https://api.example.com')

initMetricsInterceptor(client, {
  onRequestStart: (metrics) => {
    console.log(`🚀 Request started: ${metrics.method} ${metrics.url}`)
  },
  
  onRequestEnd: (metrics) => {
    console.log(`✅ Request completed: ${metrics.method} ${metrics.url}`)
    console.log(`⏱️  Duration: ${metrics.duration?.toFixed(2)}ms`)
    console.log(`📊 Status: ${metrics.status}`)
    
    // Network information
    if (metrics.networkInfo) {
      console.log(`🌐 Network: ${metrics.networkInfo.effectiveType}`)
      console.log(`📡 Speed: ${metrics.networkInfo.downlink} Mbps`)
      console.log(`⏱️  RTT: ${metrics.networkInfo.rtt}ms`)
      console.log(`💾 Save Data: ${metrics.networkInfo.saveData ? 'Yes' : 'No'}`)
    }
  },
  
  onRequestError: (metrics) => {
    console.error(`❌ Request failed: ${metrics.method} ${metrics.url}`)
    console.error(`💥 Error:`, metrics.error)
  },
  
  collectRequestSize: true,
  collectResponseSize: true,
  collectNetworkInfo: true
})

Custom Metrics Collection

const metrics: RequestMetrics[] = []

initMetricsInterceptor(client, {
  onRequestEnd: (metric) => {
    metrics.push(metric)
    
    // Calculate average response time
    const avgDuration = metrics.reduce((sum, m) => sum + (m.duration || 0), 0) / metrics.length
    console.log(`Average response time: ${avgDuration.toFixed(2)}ms`)
  }
})

Performance Monitoring

initMetricsInterceptor(client, {
  onRequestEnd: (metrics) => {
    // Alert on slow requests
    if (metrics.duration && metrics.duration > 1000) {
      console.warn(`Slow request detected: ${metrics.method} ${metrics.url} took ${metrics.duration}ms`)
    }
    
    // Track error rates
    if (metrics.status && metrics.status >= 400) {
      console.error(`Request failed with status ${metrics.status}: ${metrics.url}`)
    }
  }
})

Network-Aware Optimization

initMetricsInterceptor(client, {
  onRequestStart: (metrics) => {
    if (metrics.networkInfo) {
      // Optimize for slow connections
      if (metrics.networkInfo.effectiveType === '2g' || metrics.networkInfo.effectiveType === 'slow-2g') {
        console.log('🔄 Using lightweight mode for slow connection')
        // Load minimal content, disable animations, etc.
      } else if (metrics.networkInfo.effectiveType === '5g') {
        console.log('🚀 Using ultra-fast mode for 5G connection')
        // Load high-quality content, enable advanced features, etc.
      }
      
      // Respect data saving preferences
      if (metrics.networkInfo.saveData) {
        console.log('💾 Data saver mode enabled')
        // Disable autoplay, load compressed images, etc.
      }
    }
  },
  
  onRequestEnd: (metrics) => {
    if (metrics.networkInfo) {
      // Log network performance
      console.log(`🌐 Network: ${metrics.networkInfo.effectiveType}`)
      console.log(`📡 Speed: ${metrics.networkInfo.downlink} Mbps`)
      console.log(`⏱️  RTT: ${metrics.networkInfo.rtt}ms`)
    }
  },
  
  collectNetworkInfo: true
})

Development

Building

npm run build

Development Mode

npm run dev

Type Checking

npm run type-check

License

MIT