🛡️ mongo-collscan-guard

Zero-config MongoDB Index Enforcer — Catch missing indexes before they crash your production database

🚨 The Problem

Your MongoDB queries work perfectly in development with 100 records. Then in production with 10 million records:

� Database locks up
💥 CPU hits 100%
💥 Response time: 45 seconds
� Users can't access your app

Why? A missing index causes a COLLSCAN (full collection scan).

✨ The Solution

mongo-collscan-guard automatically detects missing indexes during development and testing:

const { guard } = require('mongo-collscan-guard');
guard();  // That's it! One line.

Now when you run a query without an index:

🚨 FATAL ERROR: Collection Scan Detected!
   Query: db.users.find({"status":"active","age":{"$gt":18}})
   
   ❌ No index found - database is scanning entire collection
   ✅ Add this index: db.users.createIndex({"status":1,"age":1})
   
   Test aborted. Fix this before deploying to production!

🎯 Key Features

�️ Automatic Protection

• Zero configuration — works out of the box
• Auto-detects COLLSCAN in all MongoDB operations
• Production-safe — automatically disabled in production

� Smart Index Suggestions

• Uses MongoDB's ESR rule (Equality → Sort → Range)
• Suggests optimal compound indexes
• Analyzes aggregation pipelines ($lookup, $graphLookup)

📊 Real-Time Monitoring

• Interactive terminal dashboard with blessed UI
• Live query tracking with color-coded status
• Performance scoring and statistics

🌍 Developer Friendly

• Multi-language support (English, Türkçe, Deutsch, 日本語)
• TypeScript declarations included
• Jest & Mocha integrations built-in
• Mongoose plugin for seamless integration

⚡ Performance Features

• Slow query detection with configurable thresholds
• In-memory sort detection
• Deep pipeline analysis for complex aggregations
• Allowlist system for intentional collection scans

� Installation

npm install mongo-collscan-guard --save-dev

Requirements:

• Node.js >= 16.0.0
• MongoDB driver >= 4.0.0

🚀 Quick Start

Basic Usage

// In your test setup file
const { guard } = require('mongo-collscan-guard');

guard();  // Activate protection

// Now run your MongoDB queries
// Any COLLSCAN will throw an error with index suggestion

With Configuration

guard({
  mode: 'throw',              // 'throw' | 'warn' | 'log'
  slowMs: 100,                // Flag queries slower than 100ms
  locale: 'en',               // 'en' | 'tr' | 'de' | 'ja'
  detectInMemorySort: true,   // Detect sorts without indexes
  deepPipelineAnalysis: true, // Analyze $lookup stages
});

🧪 Framework Integration

Jest

// jest.setup.js
const { guard } = require('mongo-collscan-guard');

beforeAll(() => {
  guard({ mode: 'throw' });
});

// jest.config.js
module.exports = {
  setupFilesAfterEnv: ['./jest.setup.js'],
};

Mocha

Option 1: Command line

mocha --require mongo-collscan-guard/integrations/mocha

Option 2: In test file

const { guard, disable } = require('mongo-collscan-guard');

before(() => guard());
after(() => disable());

Mongoose

const mongoose = require('mongoose');
const { mongoosePlugin } = require('mongo-collscan-guard');

// Apply globally to all schemas
mongoose.plugin(mongoosePlugin);

// Or per-schema
mySchema.plugin(mongoosePlugin, { mode: 'warn' });

📊 Watch Mode - Real-Time Dashboard

Monitor your MongoDB queries in real-time with an interactive terminal UI:

npx mongo-collscan-guard watch --uri mongodb://localhost:27017/mydb

Features:

• � Live statistics (total queries, COLLSCAN count, slow queries)
• � Color-coded status (green = OK, yellow = slow, red = COLLSCAN)
• ⌨️ Keyboard navigation (↑↓ to navigate, d for details, r to reset)
• 🔍 Query inspection with full filter and index suggestions
• 📊 Performance score calculation

⚙️ Configuration Options

guard({
  // Enable/disable guard
  enabled: true,                    // Auto-detects from NODE_ENV
  activeEnvs: ['development', 'test'],
  
  // Detection modes
  mode: 'throw',                    // 'throw' | 'warn' | 'log'
  detectInMemorySort: true,         // Detect sorts without indexes
  deepPipelineAnalysis: true,       // Analyze $lookup/$graphLookup
  
  // Performance monitoring
  slowMs: 100,                      // Slow query threshold (ms)
  slowQueryMode: 'warn',            // Mode for slow queries
  
  // Customization
  locale: 'en',                     // 'en' | 'tr' | 'de' | 'ja'
  ignoredCollections: [],           // Collections to skip
  operations: ['find', 'aggregate', ...],
  
  // Advanced
  explainMode: 'inline',            // 'inline' | 'parallel'
  maxReports: 0,                    // Max reports (0 = unlimited)
  suggestIndex: true,               // Enable index suggestions
  
  // Custom callbacks
  reporter: (report) => { },        // Custom error reporter
  okReporter: (info) => { },        // Report successful queries
});

🎓 How It Works

1. Monkey Patching

Guards MongoDB Collection prototype methods (find, aggregate, etc.)

2. Query Interception

Intercepts every query before execution

3. Explain Analysis

Runs .explain("executionStats") to analyze query plan

4. COLLSCAN Detection

Checks for COLLSCAN stage in execution plan

5. Index Suggestion

Uses ESR rule to suggest optimal compound index:

• Equality fields first (exact matches)
• Sort fields second
• Range fields last (>, <, >=, <=)

Example:

// Query
db.users.find({ 
  status: 'active',      // Equality
  age: { $gt: 18 }       // Range
}).sort({ createdAt: -1 }) // Sort

// Suggested Index (ESR order)
{ status: 1, createdAt: -1, age: 1 }

🔧 CLI Commands

# Interactive menu
npx mongo-collscan-guard

# Show help
npx mongo-collscan-guard help

# Real-time monitoring
npx mongo-collscan-guard watch --uri <mongodb-uri>

# Show configuration options
npx mongo-collscan-guard config

# Show code examples
npx mongo-collscan-guard examples

# Check environment
npx mongo-collscan-guard doctor

# Show available languages
npx mongo-collscan-guard locale

📚 API Reference

Core Functions

const {
  guard,              // Activate guard
  disable,            // Disable guard
  isPatched,          // Check if guard is active
  getReports,         // Get COLLSCAN reports
  clearReports,       // Clear reports
} = require('mongo-collscan-guard');

Allowlist (Whitelist)

const { allowCollScan } = require('mongo-collscan-guard');

// Allow entire collection
allowCollScan('logs');

// Allow specific filter
allowCollScan('events', { type: 'system' });

// Allow specific operation
allowCollScan('cache', null, 'find');

Index Suggestions

const { suggestIndex } = require('mongo-collscan-guard');

const filter = { status: 'active', age: { $gt: 18 } };
const sort = { createdAt: -1 };

const index = suggestIndex(filter, sort);
// Returns: { status: 1, createdAt: -1, age: 1 }

Deep Pipeline Analysis

const { extractSubQueries, suggestSubQueryIndexes } = require('mongo-collscan-guard');

const pipeline = [
  { $match: { status: 'active' } },
  { $lookup: { from: 'orders', localField: '_id', foreignField: 'userId' } }
];

const subQueries = extractSubQueries(pipeline);
const suggestions = suggestSubQueryIndexes(subQueries, suggestIndex);
// Suggests indexes for 'orders' collection

🌍 Multi-Language Support

Built-in support for 4 languages:

guard({ locale: 'tr' });  // Türkçe
guard({ locale: 'de' });  // Deutsch
guard({ locale: 'ja' });  // 日本語
guard({ locale: 'en' });  // English (default)

Or use environment variable:

COLLSCAN_GUARD_LOCALE=tr node app.js

Custom locales:

const { registerLocale } = require('mongo-collscan-guard');

registerLocale('fr', {
  'collscan.title': '🚨 ERREUR: Scan de collection détecté!',
  // ... more translations
});

📝 TypeScript Support

Full TypeScript declarations included:

import { guard, GuardOptions, CollScanReport } from 'mongo-collscan-guard';

const options: GuardOptions = {
  mode: 'throw',
  slowMs: 100,
};

const handle = guard(options);

// Later
handle.disable();
const reports: CollScanReport[] = handle.getReports();

🎯 Supported Operations

✅ Query Operations

• find() • findOne() • countDocuments() • distinct()

✅ Aggregation

• aggregate() with full pipeline analysis

✅ Write Operations

• updateOne() • updateMany() • deleteOne() • deleteMany()

✅ Advanced Features

• In-memory sort detection
• Deep pipeline analysis ($lookup, $graphLookup, $unionWith)
• Slow query detection
• Sharded cluster support

🤝 Contributing

Contributions are welcome! This is an open-source project.

� License

MIT © 2024

🙏 Credits

Made with ❤️ for MongoDB developers who care about performance.

Author: Görkem

🔗 Links

• GitHub Repository
• NPM Package
• Issue Tracker

⭐ If this package saved your production database, give it a star on GitHub!