⚡ FlashGuard

Stop the "Thundering Herd". Protect your distributed systems from traffic spikes.

FlashGuard is a high-performance request coalescing library for Node.js. It prevents Cache Stampedes by ensuring that only one request hits your database during a traffic spike, while thousands of other users wait for the result.

✨ Features

• Request Coalescing: Single-flight execution to save your database.
• Stale-While-Revalidate: Background updates for non-blocking freshness.
• Distributed Locking: Safe execution across multiple fleet instances.
• TypeScript Support: First-class typing included.

📦 Installation

npm install @asad-ahmed-saiyed/flashguard ioredis

(Note: ioredis is a required peer dependency).

🚀 Quick Start

Here is how to wrap your expensive database calls (like SQL queries or API requests) with FlashGuard.

import { FlashGuard, RedisDriver } from "@asad-ahmed-saiyed/flashguard";
import Redis from "ioredis";

// 1. Setup Redis Connection
const redis = new Redis(process.env.REDIS_URL);
const driver = new RedisDriver(redis);

// 2. Initialize FlashGuard
const guard = new FlashGuard(driver);

// 3. The Function You Want to Protect
async function getProductProfile(productId) {
  const cacheKey = `product:${productId}`;

  return await guard.fetch(
    cacheKey,
    async () => {
      // 🟢 THE "LEADER" WORK
      // This code runs ONLY ONCE, even if 1,000 users hit it at the same time.
      console.log("Fetching from Database...");
      // Assume 'db' is your database client
      return await db.query("SELECT * FROM products WHERE id = ?", [productId]);
    },
    {
      ttl: 60, // Cache data for 60 seconds
    }
  );
}

📊 Performance Benchmarks

Tests conducted under high-concurrency load (100 concurrent users) on resource-constrained hardware.

| Metric | ❌ Standard Redis | ✅ FlashGuard | Impact | | --- | --- | --- | --- | | Response Time (p95) | 1.31 s | 1.06 s | 19% Faster ⚡ | | Throughput | 104 req/sec | 132 req/sec | 27% More Capacity 📈 | | Database Load | 100 Calls | 1 Call | 99% Load Reduction 🛡️ |

⚙️ Configuration Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | ttl | number | 60 | Time-To-Live: How long (in seconds) the data stays fresh in Redis. | | swr | number | 300 | Stale-While-Revalidate: Extra time (in seconds) to serve old data while fetching new data in the background. | | timeout | number | 10000 | Lock Timeout: Max time (ms) a "follower" waits for the "leader" to finish. |

🛡️ "Fail-Open" Design

If Redis crashes, FlashGuard automatically bypasses the cache and executes your function directly. This ensures your application never goes down just because the cache is offline.

📄 License

MIT