flow-guard

flow-guard is a lightweight, context-aware request flow control library for Node.js backends. It goes beyond traditional static rate limiting by introducing smart, adaptive rules that manage API request patterns based on user roles, request dependencies, and real-time server performance.

✨ Key Highlights

• Role-Based Limits – Different rate limits for guests, registered users, and premium tiers.
• Request Dependency Chains – Ensure certain API calls only run after prerequisite actions are completed.
• Adaptive Cooldowns – Dynamically slow down or speed up requests based on CPU/memory usage.
• Burst Mode – Temporarily allow higher throughput during peak demand, then auto-scale back.
• Framework Agnostic – Works with Express, Fastify, Koa, or raw Node.js HTTP servers.

🎯 Ideal Use Cases

• Preventing checkout before cart validation.
• Protecting expensive database queries during high load.
• Offering premium users more generous API access.

🚀 Goal

To make backend APIs more resilient, efficient, and developer-friendly by providing a plug-and-play solution for intelligent request flow management.

🧩 Quick Start (Express)

const express = require('express');
const { flowGuard, rules } = require('./index');

const app = express();

const guard = flowGuard([
  rules.roleBasedLimit({
    guest: 5,
    user: 20,
    premium: 100,
    default: 10
  }),
  rules.dependencyCheck(['acceptedTerms', 'verifiedEmail'])
]);

app.use(guard);

app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello from flow-guard protected route' });
});

app.listen(3000);

📦 What’s Included

• flowGuard(rules) – middleware builder that runs a series of rules and blocks requests that fail.
• rules – a set of example rule factories (role-based limits, dependency checks) you can extend or replace.

🔧 Extendability

Add your own rules to adapt to your app’s needs (e.g., server load, request patterns, custom user tiers).

const myRule = () => async (req) => {
  // ...check req, server state, etc.
  return { allowed: true };
};

const guard = flowGuard([myRule()]);