graphql-watchdog

graphql-watchdog

GraphQL performance toolkit -- N+1 detection, normalized caching, cost analysis, and CI regression testing.

Features

• N+1 Query Detection -- Automatically detects N+1 patterns in resolver execution and suggests DataLoader fixes
• Query Cost Analysis -- AST-based cost calculation with configurable field costs, list multipliers, and hard limits
• Query Optimization Suggestions -- Analyzes queries and suggests pagination, fragments, DataLoader usage, and more
• Dynamic Cost Tracking -- Automatically derives cost weights from actual resolver performance data
• Normalized Response Cache -- Entity-level caching with LRU eviction, TTL expiration, and type/entity-based invalidation
• Pluggable Cache Backends -- In-memory, Redis, and Cloudflare KV backends via the CacheBackend interface
• Performance Dashboard -- Self-contained HTML dashboard with score gauges, charts, and trend tracking
• Server Plugins -- Drop-in plugins for GraphQL Yoga and Apollo Server
• CLI Tooling -- Static analysis and benchmarking commands for CI/CD pipelines
• CI Regression Testing -- Benchmark operations against endpoints with p50/p95/p99 tracking and regression detection

Quick Start

npm install graphql-watchdog graphql

With GraphQL Yoga

import { createYoga, createSchema } from 'graphql-yoga';
import { useWatchdog } from 'graphql-watchdog';

const yoga = createYoga({
  schema: createSchema({ /* your schema */ }),
  plugins: [
    useWatchdog({
      enableDetector: true,
      enableCost: true,
      cost: {
        maxCost: 1000,
        defaultListMultiplier: 10,
      },
      enableCache: true,
      cache: {
        maxSize: 500,
        ttl: 60000,
      },
    }),
  ],
});

With Apollo Server

import { ApolloServer } from '@apollo/server';
import { watchdogApolloPlugin } from 'graphql-watchdog';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    watchdogApolloPlugin({
      enableDetector: true,
      onDetection: (detections) => {
        detections.forEach((d) => {
          console.warn(`N+1 detected: ${d.field} (${d.callCount} calls)`);
        });
      },
    }),
  ],
});

Requirements

• Node.js >= 18.0.0
• graphql >= 16.0.0 (peer dependency)
• graphql-yoga >= 5.0.0 (optional, for Yoga plugin)
• @apollo/server >= 4.0.0 (optional, for Apollo plugin)
• ioredis >= 5.0.0 (optional, for Redis cache backend)
• TypeScript >= 5.0 (optional, for type definitions)

Fully written in TypeScript with complete type exports for all public APIs.

Usage

N+1 Detection

The detector instruments resolver functions to track execution patterns and identify N+1 queries:

import { ResolverInstrumenter, analyzeForN1 } from 'graphql-watchdog';

const instrumenter = new ResolverInstrumenter();
const instrumented = instrumenter.instrumentResolvers(resolvers);

// ... execute GraphQL operations using instrumented resolvers ...

const detections = analyzeForN1(instrumenter.getCalls());
// [{ field: 'Post.author', callCount: 10, severity: 'critical', suggestion: '...' }]

Cost Analysis

Analyze query cost statically from the AST:

import { analyzeCost, costLimitRule } from 'graphql-watchdog';
import { parse, validate } from 'graphql';

const query = parse(`
  query {
    posts(first: 20) {
      title
      author { name }
      comments(first: 10) { text }
    }
  }
`);

const breakdown = analyzeCost(query, schema, {
  maxCost: 500,
  defaultListMultiplier: 10,
  costMap: {
    'Query.posts': 2,
    'Post.comments': 5,
  },
});

console.log(breakdown.totalCost);  // calculated cost
console.log(breakdown.exceeds);     // true if over maxCost

// Or use as a validation rule
const errors = validate(schema, query, [costLimitRule(schema, { maxCost: 500 })]);

Query Optimization Suggestions

Analyze queries and get actionable optimization suggestions:

import { analyzeCost, suggestOptimizations } from 'graphql-watchdog';
import { parse } from 'graphql';

const query = parse(`
  query {
    allUsers {
      name
      posts {
        title
        author { name }
        comments {
          text
          author { name }
        }
      }
    }
  }
`);

const breakdown = analyzeCost(query, schema);
const suggestions = suggestOptimizations(breakdown, query, schema);

for (const suggestion of suggestions) {
  console.log(`[${suggestion.severity}] ${suggestion.type}: ${suggestion.message}`);
  console.log(`  Estimated saving: ${suggestion.estimatedSaving}`);
}

Suggestion types:

• pagination -- Unbounded list fields missing first/limit arguments
• field-pruning -- Deeply nested fields contributing disproportionate cost
• depth-reduction -- Queries exceeding 5 levels of nesting
• fragment -- Repeated selection sets that could use fragments
• dataloader -- Object fields under list parents likely causing N+1 queries

Dynamic Cost Tracking

Derive cost weights automatically from actual resolver performance:

import { DynamicCostTracker, ResolverInstrumenter, analyzeCost } from 'graphql-watchdog';

// Create tracker and wire it to the instrumenter
const tracker = new DynamicCostTracker();
const instrumenter = new ResolverInstrumenter({ costTracker: tracker });
const instrumented = instrumenter.instrumentResolvers(resolvers);

// ... execute queries -- timing data is recorded automatically ...

// Generate cost config from observed performance
const costConfig = tracker.toCostConfig({
  baselineDuration: 10, // 10ms = cost 1
});

// Use dynamic costs for analysis
const breakdown = analyzeCost(query, schema, costConfig);

// Export timing data for persistence
const timingData = tracker.export();
saveToFile(timingData);

// Import on restart
const saved = loadFromFile();
tracker.import(saved);

// Get stats
const stats = tracker.getStats();
console.log(`Tracking ${stats.trackedFields} fields, ${stats.totalCalls} total calls`);
console.log('Slowest fields:', stats.slowestFields);

Response Cache

Normalized caching with automatic invalidation:

import { ResponseCache, normalizeResponse, getMutationTypes } from 'graphql-watchdog';

const cache = new ResponseCache({
  maxSize: 1000,
  ttl: 60000, // 1 minute
});

// Cache a response
const { entities, cacheKey } = normalizeResponse(data, 'GetPosts', variables);
cache.set(cacheKey, data, entities);

// Retrieve from cache
const cached = cache.get(cacheKey);

// Invalidate after mutations
const affectedTypes = getMutationTypes(mutationDocument, schema);
affectedTypes.forEach((type) => cache.invalidateByType(type));

// Check stats
const stats = cache.getStats();
// { hits: 50, misses: 10, hitRate: 0.833, entries: 25 }

Cache Backends

The cache supports pluggable backends via the CacheBackend interface. The default is in-memory, but you can use Redis or Cloudflare KV.

Redis Backend

npm install ioredis  # optional peer dependency

import { ResponseCache, RedisCacheBackend } from 'graphql-watchdog';

const redisBackend = new RedisCacheBackend({
  url: 'redis://localhost:6379',
  keyPrefix: 'gql-watchdog:',
});

await redisBackend.connect();

const cache = new ResponseCache({
  maxSize: 10000,
  ttl: 300000,
  backend: redisBackend,
});

// Use cache as normal -- data persists in Redis
cache.set(cacheKey, data, entities);

// For backend-backed caches, use getAsync:
const cached = await cache.getAsync(cacheKey);

// Disconnect when done
await redisBackend.disconnect();

Cloudflare KV Backend

No additional dependencies -- uses the Workers KV API available at runtime:

import { ResponseCache, CloudflareKVBackend } from 'graphql-watchdog';

// In a Cloudflare Worker:
export default {
  async fetch(request, env) {
    const kvBackend = new CloudflareKVBackend({
      namespace: env.GQL_CACHE, // KV namespace binding
      keyPrefix: 'cache:',
    });

    const cache = new ResponseCache({
      ttl: 300000,
      backend: kvBackend,
    });

    // Use normally
  },
};

Custom Backend

Implement the CacheBackend interface to create your own:

import type { CacheBackend } from 'graphql-watchdog';

class MyCustomBackend implements CacheBackend {
  async get(key: string): Promise<string | null> { /* ... */ }
  async set(key: string, value: string, ttlMs?: number): Promise<void> { /* ... */ }
  async del(key: string): Promise<void> { /* ... */ }
  async keys(pattern: string): Promise<string[]> { /* ... */ }
  async delMany(keys: string[]): Promise<number> { /* ... */ }
  async clear(): Promise<void> { /* ... */ }
}

Performance Dashboard

Generate a self-contained HTML performance dashboard:

import { generateReport, generateDashboard } from 'graphql-watchdog';

// Via generateReport
const html = generateReport(performanceReport, 'dashboard');

// Or directly
const html = generateDashboard(performanceReport);

// Write to file
import { writeFileSync } from 'fs';
writeFileSync('dashboard.html', html);

The dashboard includes:

• Performance score (0-100) based on N+1 count, cost, and cache hit rate
• N+1 hotspots table with field, call count, severity, and DataLoader suggestions
• Cost breakdown chart (inline SVG bar chart)
• Cache stats gauge with hit rate, entries, and miss count
• Operations table sorted by duration
• localStorage integration for tracking trends across runs
• Dark theme, fully self-contained (no external dependencies)

Reporting

Generate performance reports in terminal, JSON, or dashboard format:

import { generateReport } from 'graphql-watchdog';

const report = generateReport(performanceReport, 'terminal');   // colored terminal output
const json = generateReport(performanceReport, 'json');          // machine-readable JSON
const html = generateReport(performanceReport, 'dashboard');     // self-contained HTML dashboard

CLI

Analyze

Run static cost analysis on GraphQL operations:

graphql-watchdog analyze --schema schema.graphql --operations "queries/**/*.graphql" --max-cost 500

Options:

• --schema <path> -- Path to GraphQL schema SDL file (required)
• --operations <glob> -- Glob pattern for .graphql operation files (required)
• --max-cost <number> -- Maximum allowed query cost
• --default-list-multiplier <number> -- Default multiplier for list fields
• --format <terminal|json> -- Output format (default: terminal)

Benchmark

Benchmark GraphQL operations with regression detection:

# Run benchmarks
graphql-watchdog benchmark \
  --endpoint http://localhost:4000/graphql \
  --operations "queries/**/*.graphql" \
  --iterations 50 \
  --output baseline.json

# Compare against baseline (exits 1 on regression)
graphql-watchdog benchmark \
  --endpoint http://localhost:4000/graphql \
  --operations "queries/**/*.graphql" \
  --baseline baseline.json \
  --threshold 20

Options:

• --endpoint <url> -- GraphQL endpoint URL (required)
• --operations <glob> -- Glob pattern for .graphql files (required)
• --baseline <file> -- Baseline JSON for regression comparison
• --iterations <n> -- Iterations per operation (default: 10)
• --output <file> -- Save results to JSON file
• --threshold <percent> -- Regression threshold % (default: 20)

Comparison with Alternatives

graphql-watchdog combines several capabilities that would otherwise require multiple packages:

Feature	graphql-watchdog	graphql-query-complexity	graphql-depth-limit	apollo-server-plugin-response-cache
Cost analysis	Yes	Yes	No	No
N+1 detection	Yes	No	No	No
Normalized response cache	Yes	No	No	Yes
Dynamic cost tracking	Yes	No	No	No
Optimization suggestions	Yes	No	No	No
Pluggable cache backends (Redis, CF KV)	Yes	No	No	No
CI benchmark regression testing	Yes	No	No	No
Performance dashboard	Yes	No	No	No
Yoga + Apollo plugins	Yes	Partial	Partial	Apollo only

Choose graphql-watchdog if you want a unified performance toolkit. Choose individual packages if you only need one specific capability.

Configuration Reference

WatchdogConfig

Option	Type	Default	Description
enableDetector	boolean	true	Enable N+1 detection
enableCost	boolean	true	Enable cost analysis
enableCache	boolean	false	Enable response caching
cost	CostConfig	{}	Cost analysis configuration
cache	CacheConfig	{}	Cache configuration
dynamicCost	boolean	false	Enable dynamic cost tracking
dynamicCostBaseline	number	10	Milliseconds per cost unit for dynamic tracking

CostConfig

Option	Type	Default	Description
defaultFieldCost	number	1	Default cost per field
defaultListMultiplier	number	10	Default multiplier for list fields
costMap	Record<string, number>	{}	Custom costs by TypeName.fieldName
maxCost	number	Infinity	Maximum allowed query cost

CacheConfig

Option	Type	Default	Description
maxSize	number	1000	Maximum cache entries
ttl	number	60000	Time-to-live in milliseconds
invalidateOnMutation	boolean	true	Auto-invalidate on mutations
backend	CacheBackend	undefined	External cache backend (Redis, Cloudflare KV, custom)

API Reference

Detection

• ResolverInstrumenter -- Wraps resolvers to track execution
  • constructor(options?) -- Optional { costTracker: DynamicCostTracker } for automatic timing
  • .instrumentResolvers(resolvers) -- Returns instrumented resolver map
  • .getCalls() -- Returns recorded resolver calls
  • .reset() -- Clears recorded calls
• analyzeForN1(calls, threshold?) -- Analyzes calls for N+1 patterns

Cost

• analyzeCost(document, schema, config?, variables?) -- Returns cost breakdown
• costLimitRule(schema, config) -- GraphQL validation rule for cost limits
• suggestOptimizations(breakdown, document, schema, config?) -- Returns optimization suggestions
• DynamicCostTracker -- Tracks resolver performance and generates cost configs
  • .recordTiming(typeName, fieldName, durationMs) -- Record a resolver timing
  • .toCostConfig(options?) -- Generate CostConfig from observed data
  • .export() -- Export timing data for persistence
  • .import(data) -- Import previously saved timing data
  • .getStats() -- Get summary statistics

Cache

• ResponseCache -- LRU cache with TTL and entity normalization
  • .set(key, data, entities) -- Store response
  • .get(key) -- Retrieve response (null if expired/missing)
  • .getAsync(key) -- Async retrieve (required for backend-backed caches)
  • .invalidateByType(typename) -- Invalidate by type name
  • .invalidateByEntity(typename, id) -- Invalidate by specific entity
  • .getStats() -- Get hit/miss statistics
  • .clear() -- Clear all entries
• normalizeResponse(data, operationName, variables?) -- Normalize response data
• getMutationTypes(document, schema) -- Extract mutation return types

Cache Backends

• CacheBackend -- Interface for pluggable cache storage
• MemoryCacheBackend -- In-memory implementation with TTL support
• RedisCacheBackend -- Redis backend (requires ioredis peer dependency)
  • .connect() / .disconnect() -- Manage connection lifecycle
• CloudflareKVBackend -- Cloudflare Workers KV backend (no deps needed)

Plugins

• useWatchdog(config?) -- GraphQL Yoga plugin
• watchdogApolloPlugin(config?) -- Apollo Server plugin

Reporting

• generateReport(report, format?) -- Generate formatted report ('terminal', 'json', or 'dashboard')
• generateDashboard(report) -- Generate self-contained HTML dashboard
• calculatePerformanceScore(report) -- Calculate 0-100 performance score

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/my-feature)
• Run tests (npm test)
• Commit your changes (git commit -am 'Add my feature')
• Push to the branch (git push origin feature/my-feature)
• Open a Pull Request

License

MIT