{"_id":"@asad-ahmed-saiyed/flashguard","_rev":"2-e326874aa3475e01267e8f2fad5a78fd","name":"@asad-ahmed-saiyed/flashguard","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@asad-ahmed-saiyed/flashguard","version":"1.0.0","keywords":["cache","redis","distributed-lock","request-coalescing","thundering-herd","concurrency","backend","microservices","serverless","typescript"],"author":{"name":"Asad Ahmed Saiyed"},"license":"MIT","_id":"@asad-ahmed-saiyed/flashguard@1.0.0","maintainers":[{"name":"asad-ahmed-saiyed","email":"asadahmedsaiyed786@gmail.com"}],"homepage":"https://github.com/asad-saiyed/flashguard#readme","bugs":{"url":"https://github.com/asad-saiyed/flashguard/issues"},"dist":{"shasum":"b014d7df559a6e0a731778402fd463ad96dc6f81","tarball":"https://registry.npmjs.org/@asad-ahmed-saiyed/flashguard/-/flashguard-1.0.0.tgz","fileCount":6,"integrity":"sha512-Rot3vJPKaQxYjgZSurMNVpO4hHL0sV237wTBTHWTz68Wdz3ISD28SQdAom3kZ48CeCuQOPOG9TX2Dus/LqmBhQ==","signatures":[{"sig":"MEQCIBeAiSDNMJhXsiY/hNwh0Mr7lFSIuC5wfqEnBP9xo6WYAiBWKgDwfvwZuMm+rp/qdd0BCwmaLIG5GNNLrU9a1tIRPw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8562},"main":"index.js","type":"module","types":"index.d.ts","engines":{"node":">=14.0.0"},"exports":{".":"./index.js"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"asad-ahmed-saiyed","email":"asadahmedsaiyed786@gmail.com"},"repository":{"url":"git+https://github.com/asad-saiyed/flashguard.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance request coalescing and cache stampede protection for distributed systems.","directories":{},"_nodeVersion":"22.13.0","_hasShrinkwrap":false,"peerDependencies":{"ioredis":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/flashguard_1.0.0_1769184114916_0.1998608041108143","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@asad-ahmed-saiyed/flashguard","version":"1.0.1","description":"High-performance request coalescing and cache stampede protection for distributed systems.","main":"index.js","types":"index.d.ts","type":"module","exports":{".":"./index.js"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"git+https://github.com/AsadAhmedSaiyed/FlashGuard-Library.git"},"peerDependencies":{"ioredis":"^5.0.0"},"keywords":["cache","redis","distributed-lock","request-coalescing","thundering-herd","concurrency","backend","microservices","serverless","typescript"],"author":{"name":"Asad Ahmed Saiyed"},"license":"MIT","bugs":{"url":"https://github.com/AsadAhmedSaiyed/FlashGuard-Library/issues"},"homepage":"https://github.com/AsadAhmedSaiyed/FlashGuard-Library#readme","engines":{"node":">=14.0.0"},"gitHead":"10059e10d150b6bc20be827ec4231efc31a21946","_id":"@asad-ahmed-saiyed/flashguard@1.0.1","_nodeVersion":"22.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-3peUcjOxUCpLvyZkKjNuAMlEBjrba9eEYzLC4cfMITZZ3v5ZpZ0PD54hiywYMC7qVgtZbxT8JnQtftD4NAYqEg==","shasum":"310e952c9c25133e8a94984227a3c8f1db71ab77","tarball":"https://registry.npmjs.org/@asad-ahmed-saiyed/flashguard/-/flashguard-1.0.1.tgz","fileCount":6,"unpackedSize":12048,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDhWg7BkeYFbFjmomIvCYLL1GKUgD0X4QxqXVgkCGynbAiAG+5qHx+2YeQtyPPSUtQGANFRO/7SnCAPLjtMCH+a5lQ=="}]},"_npmUser":{"name":"asad-ahmed-saiyed","email":"asadahmedsaiyed786@gmail.com"},"directories":{},"maintainers":[{"name":"asad-ahmed-saiyed","email":"asadahmedsaiyed786@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/flashguard_1.0.1_1769186212647_0.30483914171151216"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-23T16:01:54.785Z","modified":"2026-01-23T16:36:52.901Z","1.0.0":"2026-01-23T16:01:55.070Z","1.0.1":"2026-01-23T16:36:52.786Z"},"bugs":{"url":"https://github.com/AsadAhmedSaiyed/FlashGuard-Library/issues"},"author":{"name":"Asad Ahmed Saiyed"},"license":"MIT","homepage":"https://github.com/AsadAhmedSaiyed/FlashGuard-Library#readme","keywords":["cache","redis","distributed-lock","request-coalescing","thundering-herd","concurrency","backend","microservices","serverless","typescript"],"repository":{"type":"git","url":"git+https://github.com/AsadAhmedSaiyed/FlashGuard-Library.git"},"description":"High-performance request coalescing and cache stampede protection for distributed systems.","maintainers":[{"name":"asad-ahmed-saiyed","email":"asadahmedsaiyed786@gmail.com"}],"readme":"# ⚡ FlashGuard\r\n\r\n**Stop the \"Thundering Herd\". Protect your distributed systems from traffic spikes.**\r\n\r\nFlashGuard 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.\r\n\r\n[![NPM Version](https://img.shields.io/npm/v/@asad-ahmed-saiyed/flashguard?style=flat-square)](https://www.npmjs.com/package/@asad-ahmed-saiyed/flashguard)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\r\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074C1.svg?style=flat-square)](http://www.typescriptlang.org/)\r\n\r\n## ✨ Features\r\n\r\n- **Request Coalescing:** Single-flight execution to save your database.\r\n- **Stale-While-Revalidate:** Background updates for non-blocking freshness.\r\n- **Distributed Locking:** Safe execution across multiple fleet instances.\r\n- **TypeScript Support:** First-class typing included.\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @asad-ahmed-saiyed/flashguard ioredis\r\n```\r\n\r\n*(Note: `ioredis` is a required peer dependency).*\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\nHere is how to wrap your expensive database calls (like SQL queries or API requests) with FlashGuard.\r\n\r\n```javascript\r\nimport { FlashGuard, RedisDriver } from \"@asad-ahmed-saiyed/flashguard\";\r\nimport Redis from \"ioredis\";\r\n\r\n// 1. Setup Redis Connection\r\nconst redis = new Redis(process.env.REDIS_URL);\r\nconst driver = new RedisDriver(redis);\r\n\r\n// 2. Initialize FlashGuard\r\nconst guard = new FlashGuard(driver);\r\n\r\n// 3. The Function You Want to Protect\r\nasync function getProductProfile(productId) {\r\n  const cacheKey = `product:${productId}`;\r\n\r\n  return await guard.fetch(\r\n    cacheKey,\r\n    async () => {\r\n      // 🟢 THE \"LEADER\" WORK\r\n      // This code runs ONLY ONCE, even if 1,000 users hit it at the same time.\r\n      console.log(\"Fetching from Database...\");\r\n      // Assume 'db' is your database client\r\n      return await db.query(\"SELECT * FROM products WHERE id = ?\", [productId]);\r\n    },\r\n    {\r\n      ttl: 60, // Cache data for 60 seconds\r\n    }\r\n  );\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📊 Performance Benchmarks\r\n\r\nTests conducted under high-concurrency load (100 concurrent users) on resource-constrained hardware.\r\n\r\n| Metric | ❌ Standard Redis | ✅ FlashGuard | Impact |\r\n| --- | --- | --- | --- |\r\n| **Response Time (p95)** | 1.31 s | **1.06 s** | **19% Faster** ⚡ |\r\n| **Throughput** | 104 req/sec | **132 req/sec** | **27% More Capacity** 📈 |\r\n| **Database Load** | 100 Calls | **1 Call** | **99% Load Reduction** 🛡️ |\r\n\r\n---\r\n\r\n## ⚙️ Configuration Options\r\n\r\n| Option | Type | Default | Description |\r\n| --- | --- | --- | --- |\r\n| `ttl` | `number` | `60` | **Time-To-Live:** How long (in seconds) the data stays fresh in Redis. |\r\n| `swr` | `number` | `300` | **Stale-While-Revalidate:** Extra time (in seconds) to serve old data while fetching new data in the background. |\r\n| `timeout` | `number` | `10000` | **Lock Timeout:** Max time (ms) a \"follower\" waits for the \"leader\" to finish. |\r\n\r\n---\r\n\r\n## 🛡️ \"Fail-Open\" Design\r\n\r\nIf 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.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}