@maestro-js/rate-limiting 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,201 @@
+# @maestro-js/rate-limiting
+
+Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login,
+API endpoints, or any action that needs throttling.
+
+## Quick Setup
+
+```ts
+import { RateLimiting } from '@maestro-js/rate-limiting'
+import { Cache } from '@maestro-js/cache'
+
+// Create using a cache service as the driver
+const cacheService = Cache.Provider.create({
+  driver: Cache.drivers.redis({ url: 'redis-host', port: 6379 })
+})
+
+const rateLimiter = RateLimiting.Provider.create(cacheService)
+RateLimiting.Provider.register('default', rateLimiter)
+
+// Check before allowing an action
+await RateLimiting.increment('login:user@example.com', 1, 300)
+
+if (await RateLimiting.tooManyAttempts('login:user@example.com', 5)) {
+  const retryAfter = await RateLimiting.availableIn('login:user@example.com')
+  throw new Error(`Too many attempts. Try again in ${retryAfter}`)
+}
+```
+
+## API Reference
+
+### increment
+
+```ts
+RateLimiting.increment(key: string, amount?: number, decaySeconds?: number): Promise<number>
+```
+
+Records one or more hits against the bucket. Creates the bucket with the given decay window
+(default 60 seconds) if it doesn't exist. Returns the new hit count.
+
+```ts
+const hits = await RateLimiting.increment('api:client-123')        // +1, 60s window
+const hits = await RateLimiting.increment('api:client-123', 5, 120) // +5, 120s window
+```
+
+### tooManyAttempts
+
+```ts
+RateLimiting.tooManyAttempts(key: string, maxAttempts: number): Promise<boolean>
+```
+
+Returns `true` if the bucket has reached or exceeded `maxAttempts` and the decay window is still
+active. If the timer has expired but the counter remains, the counter is cleaned up and `false`
+is returned.
+
+```ts
+if (await RateLimiting.tooManyAttempts('login:user@example.com', 5)) {
+  return res.status(429).json({ error: 'Too many login attempts' })
+}
+```
+
+### remaining
+
+```ts
+RateLimiting.remaining(key: string, maxAttempts: number): Promise<number>
+```
+
+Returns the number of attempts left before `maxAttempts` is reached. Never returns a negative
+number.
+
+```ts
+const left = await RateLimiting.remaining('api:client-123', 100)
+res.setHeader('X-RateLimit-Remaining', left)
+```
+
+### clear
+
+```ts
+RateLimiting.clear(key: string): Promise<void>
+```
+
+Removes both the hit counter and timer for the bucket, fully resetting it.
+
+```ts
+// Reset after a successful login
+await RateLimiting.clear('login:user@example.com')
+```
+
+### availableIn
+
+```ts
+RateLimiting.availableIn(key: string): Promise<Iso.Duration | null>
+```
+
+Returns the time remaining until the decay window expires as an `Iso.Duration`, or `null` if no
+active window exists. The duration is rounded down to the nearest second.
+
+```ts
+const retryAfter = await RateLimiting.availableIn('api:client-123')
+if (retryAfter) {
+  res.setHeader('Retry-After', retryAfter) // e.g. "PT45S"
+}
+```
+
+### attempt
+
+```ts
+RateLimiting.attempt<T>(
+  key: string,
+  maxAttemptsPerWindow: number,
+  callback: () => T,
+  decaySeconds?: number
+): Promise<T | boolean>
+```
+
+Guarded callback execution. If the bucket is under the limit, increments and executes
+`callback`, returning its result. If the limit is exceeded, returns `false` without executing
+the callback.
+
+```ts
+const result = await RateLimiting.attempt('send-email:user-1', 10, async () => {
+  await sendEmail(to, subject, body)
+  return { sent: true }
+}, 3600)
+
+if (result === false) {
+  throw new Error('Email rate limit exceeded')
+}
+```
+
+## Common Patterns
+
+### Login throttling
+
+```ts
+async function handleLogin(email: string, password: string) {
+  const key = `login:${email}`
+
+  if (await RateLimiting.tooManyAttempts(key, 5)) {
+    const retryAfter = await RateLimiting.availableIn(key)
+    return { error: `Too many attempts. Try again in ${retryAfter}` }
+  }
+
+  await RateLimiting.increment(key, 1, 300) // 5-minute window
+
+  const user = await authenticate(email, password)
+  if (user) {
+    await RateLimiting.clear(key)
+    return { success: true }
+  }
+
+  return { error: 'Invalid credentials' }
+}
+```
+
+### API rate limiting with Retry-After header
+
+```ts
+async function rateLimitMiddleware(req: Request, res: Response, next: () => void) {
+  const key = `api:${req.ip}`
+
+  if (await RateLimiting.tooManyAttempts(key, 100)) {
+    const retryAfter = await RateLimiting.availableIn(key)
+    if (retryAfter) {
+      res.setHeader('Retry-After', retryAfter)
+    }
+    return res.status(429).json({ error: 'Rate limit exceeded' })
+  }
+
+  await RateLimiting.increment(key, 1, 60)
+  res.setHeader('X-RateLimit-Remaining', await RateLimiting.remaining(key, 100))
+  next()
+}
+```
+
+### Guarded action with attempt()
+
+```ts
+const result = await RateLimiting.attempt('report:org-5', 3, async () => {
+  return await generateExpensiveReport()
+}, 3600) // 3 per hour
+
+if (result === false) {
+  return { error: 'Report generation rate limit exceeded' }
+}
+```
+
+## Warnings and Gotchas
+
+- **No built-in drivers** — `RateLimiting.Provider.create()` takes a cache driver directly
+  (anything satisfying `RateLimiting.Driver`). Pass a `@maestro-js/cache` service instance.
+- **`attempt()` returns `T | boolean`** — check `=== false` to distinguish a rate-limited call
+  from a callback that returns a falsy value.
+- **`availableIn()` rounds down** — the returned duration is floored to the nearest second.
+- **Two cache keys per bucket** — each rate-limit key uses `_rate_limit:{key}` (counter) and
+  `_rate_limit:{key}:timer` (expiry instant). Keep this in mind when inspecting cache contents.
+- **Default decay is 60 seconds** — if you omit `decaySeconds`, the window is one minute.
+
+## Key Source Files
+
+- `packages/rate-limiting/src/index.ts` — single source file with create factory, Provider
+  pattern, and namespace types

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { Iso } from 'iso-fns2';
+
+declare function create(cache: RateLimiting.Driver): {
+    increment: (key: string, amount?: number, decaySeconds?: number) => Promise<number>;
+    tooManyAttempts: (key: string, maxAttempts: number) => Promise<boolean>;
+    availableIn: (key: string) => Promise<Iso.Duration | null>;
+    remaining: (key: string, maxAttempts: number) => Promise<number>;
+    clear: (key: string) => Promise<void>;
+    attempt: <T>(key: string, maxAttemptsPerWindow: number, callback: () => T, decaySeconds?: number) => Promise<T | boolean>;
+};
+declare function provider(key: RateLimiting.Provider.Key): {
+    increment: (key: string, amount?: number, decaySeconds?: number) => Promise<number>;
+    tooManyAttempts: (key: string, maxAttempts: number) => Promise<boolean>;
+    availableIn: (key: string) => Promise<Iso.Duration | null>;
+    remaining: (key: string, maxAttempts: number) => Promise<number>;
+    clear: (key: string) => Promise<void>;
+    attempt: <T>(key: string, maxAttemptsPerWindow: number, callback: () => T, decaySeconds?: number) => Promise<T | boolean>;
+};
+type KeysWithFallback = keyof RateLimiting.Provider.Keys extends never ? {
+    default: unknown;
+} : RateLimiting.Provider.Keys;
+/**
+ * Per-key rate limiting with configurable decay windows.
+ * Call methods directly on the default instance, or use `RateLimiting.Provider.create()` for named instances.
+ */
+declare const RateLimiting: {
+    provider: typeof provider;
+    increment: (key: string, amount?: number, decaySeconds?: number) => Promise<number>;
+    tooManyAttempts: (key: string, maxAttempts: number) => Promise<boolean>;
+    availableIn: (key: string) => Promise<Iso.Duration | null>;
+    remaining: (key: string, maxAttempts: number) => Promise<number>;
+    clear: (key: string) => Promise<void>;
+    attempt: <T>(key: string, maxAttemptsPerWindow: number, callback: () => T, decaySeconds?: number) => Promise<T | boolean>;
+    Provider: {
+        create: typeof create;
+        register: (name: RateLimiting.Provider.Key, item: RateLimiting.RateLimitingService) => void;
+    };
+};
+/**
+ * Per-key rate limiting with configurable decay windows.
+ *
+ * Each bucket is identified by a string key and tracked with two cache entries:
+ * a hit counter and a timer storing the window expiry as an ISO 8601 instant.
+ * The decay window (default 60 seconds) controls how long the counter lives.
+ *
+ * Use {@link increment} to record hits, {@link tooManyAttempts} to check if a
+ * limit has been exceeded, and {@link availableIn} to report how long until
+ * the window expires. For a combined check-and-execute flow, use {@link attempt}.
+ *
+ * @example
+ * ```ts
+ * await RateLimiting.increment('login:user@example.com', 1, 300)
+ *
+ * if (await RateLimiting.tooManyAttempts('login:user@example.com', 5)) {
+ *   const retryAfter = await RateLimiting.availableIn('login:user@example.com')
+ *   throw new Error(`Too many attempts. Try again in ${retryAfter}`)
+ * }
+ * ```
+ */
+declare namespace RateLimiting {
+    /**
+     * Rate-limiting service with increment/check/clear workflow.
+     *
+     * Returned by `RateLimiting.Provider.create()` or resolved via
+     * `RateLimiting.provider()`. Each method operates on a named bucket
+     * identified by a string key.
+     *
+     * @example
+     * ```ts
+     * await RateLimiting.increment('api:client-123')
+     * const blocked = await RateLimiting.tooManyAttempts('api:client-123', 100)
+     * ```
+     */
+    interface RateLimitingService {
+        /** Records one or more hits against the bucket, creating it with the given decay window if new */
+        increment: (key: string, amount?: number, decaySeconds?: number) => Promise<number>;
+        /** Returns `true` if the bucket has reached or exceeded `maxAttempts` and the decay window is still active */
+        tooManyAttempts: (key: string, maxAttempts: number) => Promise<boolean>;
+        /** Returns the time remaining until the decay window expires, or `null` if no active window */
+        availableIn: (key: string) => Promise<Iso.Duration | null>;
+        /** Returns the number of attempts remaining before `maxAttempts` is reached */
+        remaining: (key: string, maxAttempts: number) => Promise<number>;
+        /** Removes both the hit counter and timer for the bucket */
+        clear: (key: string) => Promise<void>;
+        /** Increments and executes `callback` if under the limit, otherwise returns `false` without executing */
+        attempt: <T>(key: string, maxAttemptsPerWindow: number, callback: () => T, decaySeconds?: number) => Promise<T | boolean>;
+    }
+    /** Subset of the cache interface required by the rate limiter — typically satisfied by a `@maestro-js/cache` service instance */
+    interface Driver {
+        has(key: string): Promise<boolean>;
+        get<T = any>(key: string): Promise<T | null>;
+        add(key: string, value: any, ttlSeconds: number): Promise<boolean>;
+        set(key: string, value: any, ttlSeconds: number): Promise<void>;
+        increment(key: string, value: number): Promise<number>;
+        decrement(key: string, value: number): Promise<number>;
+        del(key: string): Promise<void>;
+    }
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { RateLimiting };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+import { instantFns } from "iso-fns2";
+function create(cache) {
+  const getRateLimitKey = (key) => `_rate_limit:${key}`;
+  const getRateLimitTimerKey = (key) => `_rate_limit:${key}:timer`;
+  async function increment(key, amount = 1, decaySeconds = 60) {
+    await cache.add(getRateLimitTimerKey(key), instantFns.add(instantFns.now(), { seconds: decaySeconds }), decaySeconds);
+    const added = await cache.add(getRateLimitKey(key), 0, decaySeconds);
+    const hits = await cache.increment(getRateLimitKey(key), amount);
+    if (!added && hits === 1) {
+      await cache.set(getRateLimitKey(key), 1, decaySeconds);
+    }
+    return hits;
+  }
+  async function tooManyAttempts(key, maxAttempts) {
+    const value = await cache.get(getRateLimitKey(key));
+    if ((value ?? 0) >= maxAttempts) {
+      const hasTimer = await cache.has(getRateLimitTimerKey(key));
+      if (hasTimer) {
+        return true;
+      } else {
+        await cache.del(getRateLimitKey(key));
+        return false;
+      }
+    } else {
+      return false;
+    }
+  }
+  async function remaining(key, maxAttempts) {
+    const value = await cache.get(getRateLimitKey(key));
+    return Math.max(maxAttempts - (value ?? 0), 0);
+  }
+  async function clear(key) {
+    await cache.del(getRateLimitKey(key));
+    await cache.del(getRateLimitTimerKey(key));
+  }
+  async function availableIn(key) {
+    const availableInInstant = await cache.get(getRateLimitTimerKey(key));
+    const now = instantFns.now();
+    if (availableInInstant && now < availableInInstant) {
+      return instantFns.until(now, availableInInstant, {
+        largestUnit: "second",
+        smallestUnit: "second",
+        roundingMode: "floor"
+      });
+    } else {
+      return null;
+    }
+  }
+  async function attempt(key, maxAttemptsPerWindow, callback, decaySeconds = 60) {
+    if (await tooManyAttempts(key, maxAttemptsPerWindow)) {
+      return false;
+    } else {
+      await increment(key, 1, decaySeconds);
+      const result = await callback();
+      return result || true;
+    }
+  }
+  return { increment, tooManyAttempts, availableIn, remaining, clear, attempt };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    increment: service.increment,
+    tooManyAttempts: service.tooManyAttempts,
+    availableIn: service.availableIn,
+    remaining: service.remaining,
+    clear: service.clear,
+    attempt: service.attempt
+  };
+}
+var RateLimiting = {
+  Provider,
+  ...provider("default"),
+  provider
+};
+export {
+  RateLimiting
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maestro-js/rate-limiting",
+  "description": "Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login, API endpoints, or any action that needs throttling. Provides increment/check/clear workflow, guarded callback execution via attempt(), and ISO 8601 duration reporting. Requires a cache driver (e.g. from @maestro-js/cache).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "@maestro-js/cache": "1.0.0-alpha.0"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}