@resq-sw/rate-limiting 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @resq-sw/rate-limiting
+
+> Rate limiting algorithms, throttle/debounce utilities, and distributed rate limit stores.
+
+## Installation
+
+```bash
+bun add @resq-sw/rate-limiting effect
+```
+
+Optional peer dependencies for Redis-backed limiting:
+
+```bash
+bun add @upstash/ratelimit @upstash/redis
+```
+
+## Quick Start
+
+```ts
+import { throttle, debounce, TokenBucketLimiter } from "@resq-sw/rate-limiting";
+
+const save = throttle(() => persist(data), 1000);
+const search = debounce((q: string) => fetchResults(q), 300);
+
+const limiter = new TokenBucketLimiter(5, 60000); // 5 per minute
+await limiter.acquire();
+```
+
+## API Reference
+
+### `throttle(func, wait, options?)`
+
+Limits function execution to at most once per `wait` milliseconds.
+
+- **func** (`T extends (...args) => unknown`) -- function to throttle.
+- **wait** (`number`) -- interval in ms.
+- **options** (`ThrottleOptions`) -- see below.
+- Returns the throttled function with a `.cancel()` method.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `leading` | `boolean` | `true` | Call on leading edge |
+| `trailing` | `boolean` | `true` | Call on trailing edge |
+
+```ts
+const fn = throttle(handleScroll, 200, { trailing: false });
+fn(); // executes immediately
+fn(); // ignored
+fn.cancel(); // cancel pending trailing call
+```
+
+### `debounce(func, wait, options?)`
+
+Delays function execution until `wait` ms after the last call.
+
+- **func** (`T extends (...args) => unknown`) -- function to debounce.
+- **wait** (`number`) -- delay in ms.
+- **options** (`DebounceOptions`) -- see below.
+- Returns the debounced function with `.cancel()` and `.flush()` methods.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `leading` | `boolean` | `false` | Call on leading edge |
+| `maxWait` | `number` | -- | Maximum time before forced execution |
+
+```ts
+const search = debounce(fetchResults, 300, { maxWait: 1000 });
+search("a"); search("ab"); search("abc");
+// Executes after 300ms idle, or forced after 1000ms
+search.flush(); // execute immediately
+search.cancel(); // cancel pending
+```
+
+### `KeyedThrottle<T>`
+
+Per-key throttle manager. Each key gets its own independent throttle.
+
+```ts
+const perUser = new KeyedThrottle(handleRequest, 1000);
+perUser.execute("user:123", requestData);  // throttled per user
+perUser.cancel("user:123");                // cancel specific key
+perUser.cancelAll();                       // cancel all keys
+perUser.getStats();                        // { activeKeys: number, keys: string[] }
+```
+
+### `KeyedDebounce<T>`
+
+Per-key debounce manager. Each key gets its own independent debounce.
+
+```ts
+const perField = new KeyedDebounce(validate, 300);
+perField.execute("email", value);   // debounced per field
+perField.flush("email");            // execute immediately
+perField.cancel("email");           // cancel specific key
+perField.cancelAll();               // cancel all keys
+perField.getStats();                // { activeKeys, keys }
+```
+
+### `TokenBucketLimiter`
+
+Token bucket algorithm -- tokens refill over time.
+
+```ts
+const limiter = new TokenBucketLimiter(capacity, windowMs);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `capacity` | `number` | Max tokens (burst size) |
+| `windowMs` | `number` | Refill window in ms |
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `acquire()` | `Promise<void>` | Wait for a token (blocks if empty) |
+| `tryAcquire()` | `boolean` | Try to get a token without waiting |
+| `getStats()` | `RateLimiterStats` | `{ availableTokens, queueSize, capacity }` |
+| `reset()` | `void` | Reset to full capacity |
+
+```ts
+const limiter = new TokenBucketLimiter(10, 60000); // 10 req/min
+if (limiter.tryAcquire()) {
+  await handleRequest();
+} else {
+  return new Response("Too Many Requests", { status: 429 });
+}
+```
+
+### `LeakyBucketLimiter`
+
+Leaky bucket algorithm -- requests drain at a constant rate for smoother limiting.
+
+```ts
+const limiter = new LeakyBucketLimiter(capacity, requestsPerSecond);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `capacity` | `number` | Max queue size |
+| `requestsPerSecond` | `number` | Drain rate |
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `acquire()` | `Promise<void>` | Queue a request (throws if queue full) |
+| `tryAcquire()` | `boolean` | Check if immediate processing is possible |
+| `getStats()` | `RateLimiterStats` | `{ availableTokens, queueSize, capacity }` |
+| `reset()` | `void` | Clear the queue |
+
+```ts
+const limiter = new LeakyBucketLimiter(100, 10); // 100 queue, 10 req/sec
+try {
+  await limiter.acquire();
+  await processRequest();
+} catch (e) {
+  // "Rate limit exceeded: queue full"
+}
+```
+
+### `SlidingWindowCounter`
+
+Sliding window counter for accurate per-key rate limiting.
+
+```ts
+const counter = new SlidingWindowCounter(windowMs, maxRequests);
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `check(key)` | `{ allowed, remaining, resetAt }` | Check and increment counter |
+| `reset(key)` | `void` | Reset counter for a key |
+| `getStats()` | `KeyedStats` | `{ activeKeys, keys }` |
+
+```ts
+const counter = new SlidingWindowCounter(60000, 100); // 100 per minute
+const { allowed, remaining, resetAt } = counter.check("user:123");
+if (!allowed) {
+  return new Response("Rate limited", {
+    status: 429,
+    headers: { "X-RateLimit-Remaining": String(remaining), "X-RateLimit-Reset": String(resetAt) },
+  });
+}
+```
+
+### Rate Limit Stores
+
+#### `MemoryRateLimitStore`
+
+In-memory store implementing `IRateLimitStore`. Suitable for single-process applications.
+
+```ts
+const store = new MemoryRateLimitStore();
+const result = await store.check("key", windowMs, maxRequests);
+// { limited, remaining, resetTime, total }
+```
+
+#### `RedisRateLimitStore`
+
+Redis-backed store using `@upstash/ratelimit` with sliding window algorithm.
+
+```ts
+import { Redis } from "@upstash/redis";
+const store = new RedisRateLimitStore(new Redis({ url: "...", token: "..." }));
+const result = await store.check("key", 60000, 100);
+```
+
+### Presets
+
+```ts
+import { RATE_LIMIT_PRESETS } from "@resq-sw/rate-limiting";
+```
+
+| Preset | Window | Max Requests |
+|--------|--------|-------------|
+| `auth` | 15 min | 5 |
+| `api` | 1 min | 100 |
+| `read` | 1 min | 200 |
+| `upload` | 1 hour | 20 |
+
+### Effect Schemas
+
+Exported for runtime validation: `ThrottleOptionsSchema`, `DebounceOptionsSchema`, `RateLimiterStatsSchema`, `KeyedStatsSchema`, `RateLimitConfigSchema`, `RateLimitCheckResultSchema`.
+
+## License
+
+Apache-2.0

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import { DebounceOptions, DebounceOptionsSchema, KeyedDebounce, KeyedStats, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, RateLimiterStats, RateLimiterStatsSchema, SlidingWindowCounter, ThrottleOptions, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle } from "./throttle.js";
+import { IRateLimitStore, MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResult, RateLimitCheckResultSchema, RateLimitConfig, RateLimitConfigSchema, RedisRateLimitStore } from "./rate-limit.js";
+export { DebounceOptions, DebounceOptionsSchema, IRateLimitStore, KeyedDebounce, KeyedStats, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResult, RateLimitCheckResultSchema, RateLimitConfig, RateLimitConfigSchema, RateLimiterStats, RateLimiterStatsSchema, RedisRateLimitStore, SlidingWindowCounter, ThrottleOptions, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle };

package/lib/index.js

@@ -0,0 +1,3 @@
+import { DebounceOptionsSchema, KeyedDebounce, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, RateLimiterStatsSchema, SlidingWindowCounter, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle } from "./throttle.js";
+import { MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResultSchema, RateLimitConfigSchema, RedisRateLimitStore } from "./rate-limit.js";
+export { DebounceOptionsSchema, KeyedDebounce, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResultSchema, RateLimitConfigSchema, RateLimiterStatsSchema, RedisRateLimitStore, SlidingWindowCounter, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle };

package/lib/rate-limit.d.ts

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+import { Redis } from "@upstash/redis";
+
+//#region src/rate-limit.d.ts
+declare const RateLimitConfigSchema: Schema.Struct<{
+  readonly windowMs: Schema.Number;
+  readonly maxRequests: Schema.Number;
+  readonly headers: Schema.optional<Schema.Boolean>;
+}>;
+type RateLimitConfig = typeof RateLimitConfigSchema.Type;
+declare const RateLimitCheckResultSchema: Schema.Struct<{
+  readonly limited: Schema.Boolean;
+  readonly remaining: Schema.Number;
+  readonly resetTime: Schema.Number;
+  readonly total: Schema.Number;
+}>;
+type RateLimitCheckResult = typeof RateLimitCheckResultSchema.Type;
+interface IRateLimitStore {
+  check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult>;
+  reset(key: string): Promise<void>;
+}
+/**
+ * Redis-backed rate limit store using @upstash/ratelimit
+ */
+declare class RedisRateLimitStore implements IRateLimitStore {
+  private readonly limiters;
+  private readonly redis;
+  constructor(redisClient: Redis);
+  private getLimiter;
+  check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult>;
+  reset(key: string): Promise<void>;
+}
+/**
+ * In-memory rate limit store for local development or simple services
+ */
+declare class MemoryRateLimitStore implements IRateLimitStore {
+  private readonly store;
+  check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult>;
+  reset(key: string): Promise<void>;
+}
+declare const RATE_LIMIT_PRESETS: {
+  readonly auth: {
+    readonly windowMs: number;
+    readonly maxRequests: 5;
+  };
+  readonly api: {
+    readonly windowMs: number;
+    readonly maxRequests: 100;
+  };
+  readonly read: {
+    readonly windowMs: number;
+    readonly maxRequests: 200;
+  };
+  readonly upload: {
+    readonly windowMs: number;
+    readonly maxRequests: 20;
+  };
+};
+//#endregion
+export { IRateLimitStore, MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResult, RateLimitCheckResultSchema, RateLimitConfig, RateLimitConfigSchema, RedisRateLimitStore };
+//# sourceMappingURL=rate-limit.d.ts.map

package/lib/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","names":[],"sources":["../src/rate-limit.ts"],"mappings":";;;;cA6Ba,qBAAA,EAAqB,MAAA,CAAA,MAAA;EAAA;;;;KAMtB,eAAA,UAAyB,qBAAA,CAAsB,IAAA;AAAA,cAE9C,0BAAA,EAA0B,MAAA,CAAA,MAAA;EAAA;;;;;KAO3B,oBAAA,UAA8B,0BAAA,CAA2B,IAAA;AAAA,UAMpD,eAAA;EACf,KAAA,CAAM,GAAA,UAAa,QAAA,UAAkB,WAAA,WAAsB,OAAA,CAAQ,oBAAA;EACnE,KAAA,CAAM,GAAA,WAAc,OAAA;AAAA;AAftB;;;AAAA,cAqBa,mBAAA,YAA+B,eAAA;EAAA,iBACzB,QAAA;EAAA,iBACA,KAAA;cAEL,WAAA,EAAa,KAAA;EAAA,QAIjB,UAAA;EAcF,KAAA,CAAM,GAAA,UAAa,QAAA,UAAkB,WAAA,WAAsB,OAAA,CAAQ,oBAAA;EAYnE,KAAA,CAAM,GAAA,WAAc,OAAA;AAAA;;;;cASf,oBAAA,YAAgC,eAAA;EAAA,iBAC1B,KAAA;EAEX,KAAA,CAAM,GAAA,UAAa,QAAA,UAAkB,WAAA,WAAsB,OAAA,CAAQ,oBAAA;EAyBnE,KAAA,CAAM,GAAA,WAAc,OAAA;AAAA;AAAA,cASf,kBAAA;EAAA"}

package/lib/rate-limit.js

@@ -0,0 +1,121 @@
+import { Schema } from "effect";
+import { Ratelimit } from "@upstash/ratelimit";
+//#region src/rate-limit.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @file Rate Limiting Utilities
+* @module @resq/typescript/utils/middleware/rate-limit
+*/
+const RateLimitConfigSchema = Schema.Struct({
+	windowMs: Schema.Number,
+	maxRequests: Schema.Number,
+	headers: Schema.optional(Schema.Boolean)
+});
+const RateLimitCheckResultSchema = Schema.Struct({
+	limited: Schema.Boolean,
+	remaining: Schema.Number,
+	resetTime: Schema.Number,
+	total: Schema.Number
+});
+/**
+* Redis-backed rate limit store using @upstash/ratelimit
+*/
+var RedisRateLimitStore = class {
+	limiters = /* @__PURE__ */ new Map();
+	redis;
+	constructor(redisClient) {
+		this.redis = redisClient;
+	}
+	getLimiter(windowMs, maxRequests) {
+		const key = `${windowMs}:${maxRequests}`;
+		let limiter = this.limiters.get(key);
+		if (!limiter) {
+			limiter = new Ratelimit({
+				redis: this.redis,
+				limiter: Ratelimit.slidingWindow(maxRequests, `${windowMs} ms`),
+				prefix: "@resq/ratelimit"
+			});
+			this.limiters.set(key, limiter);
+		}
+		return limiter;
+	}
+	async check(key, windowMs, maxRequests) {
+		const result = await this.getLimiter(windowMs, maxRequests).limit(key);
+		return {
+			limited: !result.success,
+			remaining: result.remaining,
+			resetTime: result.reset,
+			total: result.limit
+		};
+	}
+	async reset(key) {}
+};
+/**
+* In-memory rate limit store for local development or simple services
+*/
+var MemoryRateLimitStore = class {
+	store = /* @__PURE__ */ new Map();
+	async check(key, windowMs, maxRequests) {
+		const now = Date.now();
+		const state = this.store.get(key);
+		if (!state || state.resetTime <= now) {
+			const newState = {
+				count: 1,
+				resetTime: now + windowMs
+			};
+			this.store.set(key, newState);
+			return {
+				limited: false,
+				remaining: maxRequests - 1,
+				resetTime: newState.resetTime,
+				total: maxRequests
+			};
+		}
+		state.count++;
+		return {
+			limited: state.count > maxRequests,
+			remaining: Math.max(0, maxRequests - state.count),
+			resetTime: state.resetTime,
+			total: maxRequests
+		};
+	}
+	async reset(key) {
+		this.store.delete(key);
+	}
+};
+const RATE_LIMIT_PRESETS = {
+	auth: {
+		windowMs: 900 * 1e3,
+		maxRequests: 5
+	},
+	api: {
+		windowMs: 60 * 1e3,
+		maxRequests: 100
+	},
+	read: {
+		windowMs: 60 * 1e3,
+		maxRequests: 200
+	},
+	upload: {
+		windowMs: 3600 * 1e3,
+		maxRequests: 20
+	}
+};
+//#endregion
+export { MemoryRateLimitStore, RATE_LIMIT_PRESETS, RateLimitCheckResultSchema, RateLimitConfigSchema, RedisRateLimitStore };
+
+//# sourceMappingURL=rate-limit.js.map

package/lib/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","names":["S"],"sources":["../src/rate-limit.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @file Rate Limiting Utilities\n * @module @resq/typescript/utils/middleware/rate-limit\n */\n\nimport { Ratelimit } from '@upstash/ratelimit';\nimport type { Redis } from '@upstash/redis';\nimport { Schema as S } from 'effect';\n\n// ============================================\n// Effect Schema Definitions\n// ============================================\n\nexport const RateLimitConfigSchema = S.Struct({\n  windowMs: S.Number,\n  maxRequests: S.Number,\n  headers: S.optional(S.Boolean),\n});\n\nexport type RateLimitConfig = typeof RateLimitConfigSchema.Type;\n\nexport const RateLimitCheckResultSchema = S.Struct({\n  limited: S.Boolean,\n  remaining: S.Number,\n  resetTime: S.Number,\n  total: S.Number,\n});\n\nexport type RateLimitCheckResult = typeof RateLimitCheckResultSchema.Type;\n\n// ============================================\n// Rate Limit Store Interfaces\n// ============================================\n\nexport interface IRateLimitStore {\n  check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult>;\n  reset(key: string): Promise<void>;\n}\n\n/**\n * Redis-backed rate limit store using @upstash/ratelimit\n */\nexport class RedisRateLimitStore implements IRateLimitStore {\n  private readonly limiters = new Map<string, Ratelimit>();\n  private readonly redis: Redis;\n\n  constructor(redisClient: Redis) {\n    this.redis = redisClient;\n  }\n\n  private getLimiter(windowMs: number, maxRequests: number): Ratelimit {\n    const key = `${windowMs}:${maxRequests}`;\n    let limiter = this.limiters.get(key);\n    if (!limiter) {\n      limiter = new Ratelimit({\n        redis: this.redis,\n        limiter: Ratelimit.slidingWindow(maxRequests, `${windowMs} ms`),\n        prefix: '@resq/ratelimit',\n      });\n      this.limiters.set(key, limiter);\n    }\n    return limiter;\n  }\n\n  async check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult> {\n    const limiter = this.getLimiter(windowMs, maxRequests);\n    const result = await limiter.limit(key);\n\n    return {\n      limited: !result.success,\n      remaining: result.remaining,\n      resetTime: result.reset,\n      total: result.limit,\n    };\n  }\n\n  async reset(key: string): Promise<void> {\n    // Note: @upstash/ratelimit reset is complex as it uses multiple keys.\n    // For now, we clear the main key if possible.\n  }\n}\n\n/**\n * In-memory rate limit store for local development or simple services\n */\nexport class MemoryRateLimitStore implements IRateLimitStore {\n  private readonly store = new Map<string, { count: number; resetTime: number }>();\n\n  async check(key: string, windowMs: number, maxRequests: number): Promise<RateLimitCheckResult> {\n    const now = Date.now();\n    const state = this.store.get(key);\n\n    if (!state || state.resetTime <= now) {\n      const newState = { count: 1, resetTime: now + windowMs };\n      this.store.set(key, newState);\n      return {\n        limited: false,\n        remaining: maxRequests - 1,\n        resetTime: newState.resetTime,\n        total: maxRequests,\n      };\n    }\n\n    state.count++;\n    const limited = state.count > maxRequests;\n    return {\n      limited,\n      remaining: Math.max(0, maxRequests - state.count),\n      resetTime: state.resetTime,\n      total: maxRequests,\n    };\n  }\n\n  async reset(key: string): Promise<void> {\n    this.store.delete(key);\n  }\n}\n\n// ============================================\n// Rate Limit Presets\n// ============================================\n\nexport const RATE_LIMIT_PRESETS = {\n  auth: {\n    windowMs: 15 * 60 * 1000,\n    maxRequests: 5,\n  },\n  api: {\n    windowMs: 60 * 1000,\n    maxRequests: 100,\n  },\n  read: {\n    windowMs: 60 * 1000,\n    maxRequests: 200,\n  },\n  upload: {\n    windowMs: 60 * 60 * 1000,\n    maxRequests: 20,\n  },\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,wBAAwBA,OAAE,OAAO;CAC5C,UAAUA,OAAE;CACZ,aAAaA,OAAE;CACf,SAASA,OAAE,SAASA,OAAE,QAAQ;CAC/B,CAAC;AAIF,MAAa,6BAA6BA,OAAE,OAAO;CACjD,SAASA,OAAE;CACX,WAAWA,OAAE;CACb,WAAWA,OAAE;CACb,OAAOA,OAAE;CACV,CAAC;;;;AAgBF,IAAa,sBAAb,MAA4D;CAC1D,2BAA4B,IAAI,KAAwB;CACxD;CAEA,YAAY,aAAoB;AAC9B,OAAK,QAAQ;;CAGf,WAAmB,UAAkB,aAAgC;EACnE,MAAM,MAAM,GAAG,SAAS,GAAG;EAC3B,IAAI,UAAU,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,CAAC,SAAS;AACZ,aAAU,IAAI,UAAU;IACtB,OAAO,KAAK;IACZ,SAAS,UAAU,cAAc,aAAa,GAAG,SAAS,KAAK;IAC/D,QAAQ;IACT,CAAC;AACF,QAAK,SAAS,IAAI,KAAK,QAAQ;;AAEjC,SAAO;;CAGT,MAAM,MAAM,KAAa,UAAkB,aAAoD;EAE7F,MAAM,SAAS,MADC,KAAK,WAAW,UAAU,YAAY,CACzB,MAAM,IAAI;AAEvC,SAAO;GACL,SAAS,CAAC,OAAO;GACjB,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,OAAO,OAAO;GACf;;CAGH,MAAM,MAAM,KAA4B;;;;;AAS1C,IAAa,uBAAb,MAA6D;CAC3D,wBAAyB,IAAI,KAAmD;CAEhF,MAAM,MAAM,KAAa,UAAkB,aAAoD;EAC7F,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;AAEjC,MAAI,CAAC,SAAS,MAAM,aAAa,KAAK;GACpC,MAAM,WAAW;IAAE,OAAO;IAAG,WAAW,MAAM;IAAU;AACxD,QAAK,MAAM,IAAI,KAAK,SAAS;AAC7B,UAAO;IACL,SAAS;IACT,WAAW,cAAc;IACzB,WAAW,SAAS;IACpB,OAAO;IACR;;AAGH,QAAM;AAEN,SAAO;GACL,SAFc,MAAM,QAAQ;GAG5B,WAAW,KAAK,IAAI,GAAG,cAAc,MAAM,MAAM;GACjD,WAAW,MAAM;GACjB,OAAO;GACR;;CAGH,MAAM,MAAM,KAA4B;AACtC,OAAK,MAAM,OAAO,IAAI;;;AAQ1B,MAAa,qBAAqB;CAChC,MAAM;EACJ,UAAU,MAAU;EACpB,aAAa;EACd;CACD,KAAK;EACH,UAAU,KAAK;EACf,aAAa;EACd;CACD,MAAM;EACJ,UAAU,KAAK;EACf,aAAa;EACd;CACD,QAAQ;EACN,UAAU,OAAU;EACpB,aAAa;EACd;CACF"}

package/lib/throttle.d.ts

@@ -0,0 +1,253 @@
+import { Schema } from "effect";
+
+//#region src/throttle.d.ts
+/**
+ * Throttle Options Schema
+ */
+declare const ThrottleOptionsSchema: Schema.Struct<{
+  /** Whether to call the function on the leading edge */readonly leading: Schema.optional<Schema.Boolean>; /** Whether to call the function on the trailing edge */
+  readonly trailing: Schema.optional<Schema.Boolean>;
+}>;
+type ThrottleOptions = typeof ThrottleOptionsSchema.Type;
+/**
+ * Debounce Options Schema
+ */
+declare const DebounceOptionsSchema: Schema.Struct<{
+  /** Whether to call the function on the leading edge */readonly leading: Schema.optional<Schema.Boolean>; /** Maximum time to wait before forcing execution */
+  readonly maxWait: Schema.optional<Schema.Number>;
+}>;
+type DebounceOptions = typeof DebounceOptionsSchema.Type;
+/**
+ * Rate Limiter Stats Schema
+ */
+declare const RateLimiterStatsSchema: Schema.Struct<{
+  readonly availableTokens: Schema.Number;
+  readonly queueSize: Schema.Number;
+  readonly capacity: Schema.Number;
+}>;
+type RateLimiterStats = typeof RateLimiterStatsSchema.Type;
+/**
+ * Keyed Stats Schema
+ */
+declare const KeyedStatsSchema: Schema.Struct<{
+  readonly activeKeys: Schema.Number;
+  readonly keys: Schema.$Array<Schema.String>;
+}>;
+type KeyedStats = typeof KeyedStatsSchema.Type;
+/** Generic callable function type */
+type AnyFunction = (...args: never[]) => unknown;
+/**
+ * Throttle a function to only execute once per specified interval
+ *
+ * @param func Function to throttle
+ * @param wait Wait time in milliseconds
+ * @param options Throttle options
+ * @returns Throttled function
+ *
+ * @example
+ * ```ts
+ * const fetchData = throttle(() => fetch('/api/data'), 1000);
+ * fetchData(); // Executes immediately
+ * fetchData(); // Ignored
+ * fetchData(); // Ignored
+ * // After 1000ms, next call will execute
+ * ```
+ */
+declare function throttle<T extends AnyFunction>(func: T, wait: number, options?: ThrottleOptions): ((...args: Parameters<T>) => ReturnType<T> | undefined) & {
+  cancel: () => void;
+};
+/**
+ * Debounce a function to only execute after it stops being called for specified time
+ *
+ * @param func Function to debounce
+ * @param wait Wait time in milliseconds
+ * @param options Debounce options
+ * @returns Debounced function
+ *
+ * @example
+ * ```ts
+ * const search = debounce((query) => fetchSearchResults(query), 300);
+ * search('a'); // Waiting...
+ * search('ab'); // Waiting...
+ * search('abc'); // Executes after 300ms of no calls
+ * ```
+ */
+declare function debounce<T extends AnyFunction>(func: T, wait: number, options?: DebounceOptions): ((...args: Parameters<T>) => void) & {
+  cancel: () => void;
+  flush: () => void;
+};
+/**
+ * Per-key throttle manager for throttling by specific keys
+ * Useful for throttling per-endpoint or per-user
+ */
+declare class KeyedThrottle<T extends AnyFunction> {
+  private throttles;
+  private readonly func;
+  private readonly wait;
+  private readonly options;
+  constructor(func: T, wait: number, options?: ThrottleOptions);
+  /**
+   * Execute function with throttling per key
+   */
+  execute(key: string, ...args: Parameters<T>): ReturnType<T> | undefined;
+  /**
+   * Cancel throttle for specific key
+   */
+  cancel(key: string): void;
+  /**
+   * Cancel all throttles
+   */
+  cancelAll(): void;
+  /**
+   * Get stats
+   */
+  getStats(): KeyedStats;
+}
+/**
+ * Per-key debounce manager for debouncing by specific keys
+ * Useful for debouncing per-endpoint or per-user
+ */
+declare class KeyedDebounce<T extends AnyFunction> {
+  private debounces;
+  private readonly func;
+  private readonly wait;
+  private readonly options;
+  constructor(func: T, wait: number, options?: DebounceOptions);
+  /**
+   * Execute function with debouncing per key
+   */
+  execute(key: string, ...args: Parameters<T>): void;
+  /**
+   * Cancel debounce for specific key
+   */
+  cancel(key: string): void;
+  /**
+   * Flush debounce for specific key (execute immediately)
+   */
+  flush(key: string): void;
+  /**
+   * Cancel all debounces
+   */
+  cancelAll(): void;
+  /**
+   * Get stats
+   */
+  getStats(): KeyedStats;
+}
+/**
+ * Rate limiter using token bucket algorithm
+ *
+ * @example
+ * ```ts
+ * const limiter = new TokenBucketLimiter(5, 60000); // 5 requests per minute
+ *
+ * async function fetchData() {
+ *   await limiter.acquire();
+ *   return fetch('/api/data');
+ * }
+ * ```
+ */
+declare class TokenBucketLimiter {
+  private tokens;
+  private lastRefill;
+  private readonly capacity;
+  private readonly refillRate;
+  private readonly refillInterval;
+  private queue;
+  /**
+   * @param capacity Maximum number of tokens (requests)
+   * @param windowMs Time window in milliseconds
+   */
+  constructor(capacity: number, windowMs: number);
+  /**
+   * Refill tokens based on elapsed time
+   */
+  private refill;
+  /**
+   * Acquire a token (wait if none available)
+   */
+  acquire(): Promise<void>;
+  /**
+   * Try to acquire a token without waiting
+   */
+  tryAcquire(): boolean;
+  /**
+   * Schedule next token release
+   */
+  private scheduleNextRelease;
+  /**
+   * Get rate limiter stats
+   */
+  getStats(): RateLimiterStats;
+  /**
+   * Reset the rate limiter
+   */
+  reset(): void;
+}
+/**
+ * Leaky bucket algorithm - requests "leak" out at a constant rate
+ * Provides smoother rate limiting than token bucket
+ */
+declare class LeakyBucketLimiter {
+  private queue;
+  private readonly capacity;
+  private readonly leakRate;
+  private processing;
+  /**
+   * @param capacity Maximum queue size
+   * @param requestsPerSecond How many requests to process per second
+   */
+  constructor(capacity: number, requestsPerSecond: number);
+  /**
+   * Add a request to the bucket
+   */
+  acquire(): Promise<void>;
+  /**
+   * Try to acquire without blocking
+   */
+  tryAcquire(): boolean;
+  /**
+   * Process the queue at the leak rate
+   */
+  private processQueue;
+  /**
+   * Get stats
+   */
+  getStats(): RateLimiterStats;
+  /**
+   * Clear the queue
+   */
+  reset(): void;
+}
+/**
+ * Sliding window counter for accurate rate limiting
+ */
+declare class SlidingWindowCounter {
+  private counters;
+  private readonly windowMs;
+  private readonly maxRequests;
+  constructor(windowMs: number, maxRequests: number);
+  /**
+   * Check and increment counter for a key
+   */
+  check(key: string): {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+  };
+  /**
+   * Reset counter for a key
+   */
+  reset(key: string): void;
+  /**
+   * Cleanup old entries
+   */
+  private cleanup;
+  /**
+   * Get stats
+   */
+  getStats(): KeyedStats;
+}
+//#endregion
+export { DebounceOptions, DebounceOptionsSchema, KeyedDebounce, KeyedStats, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, RateLimiterStats, RateLimiterStatsSchema, SlidingWindowCounter, ThrottleOptions, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle };
+//# sourceMappingURL=throttle.d.ts.map

package/lib/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","names":[],"sources":["../src/throttle.ts"],"mappings":"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"}

package/lib/throttle.js

@@ -0,0 +1,521 @@
+import { Schema } from "effect";
+//#region src/throttle.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @file Throttle and Debounce Utilities
+* @module utils/throttle
+* @author ResQ
+* @description Provides functions to limit the rate at which functions can be called.
+*              Useful for preventing excessive API calls and managing request frequency.
+*              Includes throttle, debounce, rate limiter, and queue utilities.
+* @compliance NIST 800-53 SC-5 (Denial of Service Protection)
+*/
+/**
+* Throttle Options Schema
+*/
+const ThrottleOptionsSchema = Schema.Struct({
+	leading: Schema.optional(Schema.Boolean),
+	trailing: Schema.optional(Schema.Boolean)
+});
+/**
+* Debounce Options Schema
+*/
+const DebounceOptionsSchema = Schema.Struct({
+	leading: Schema.optional(Schema.Boolean),
+	maxWait: Schema.optional(Schema.Number)
+});
+/**
+* Rate Limiter Stats Schema
+*/
+const RateLimiterStatsSchema = Schema.Struct({
+	availableTokens: Schema.Number,
+	queueSize: Schema.Number,
+	capacity: Schema.Number
+});
+/**
+* Keyed Stats Schema
+*/
+const KeyedStatsSchema = Schema.Struct({
+	activeKeys: Schema.Number,
+	keys: Schema.Array(Schema.String)
+});
+/**
+* Throttle a function to only execute once per specified interval
+*
+* @param func Function to throttle
+* @param wait Wait time in milliseconds
+* @param options Throttle options
+* @returns Throttled function
+*
+* @example
+* ```ts
+* const fetchData = throttle(() => fetch('/api/data'), 1000);
+* fetchData(); // Executes immediately
+* fetchData(); // Ignored
+* fetchData(); // Ignored
+* // After 1000ms, next call will execute
+* ```
+*/
+function throttle(func, wait, options = {}) {
+	let timeout = null;
+	let previous = 0;
+	let result;
+	const { leading = true, trailing = true } = options;
+	const later = (context, args) => {
+		previous = leading === false ? 0 : Date.now();
+		timeout = null;
+		result = func.apply(context, args);
+	};
+	const throttled = function(...args) {
+		const now = Date.now();
+		if (!previous && leading === false) previous = now;
+		const remaining = wait - (now - previous);
+		if (remaining <= 0 || remaining > wait) {
+			if (timeout) {
+				clearTimeout(timeout);
+				timeout = null;
+			}
+			previous = now;
+			result = func.apply(this, args);
+		} else if (!timeout && trailing) timeout = setTimeout(() => later(this, args), remaining);
+		return result;
+	};
+	throttled.cancel = () => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = null;
+		}
+		previous = 0;
+	};
+	return throttled;
+}
+/**
+* Debounce a function to only execute after it stops being called for specified time
+*
+* @param func Function to debounce
+* @param wait Wait time in milliseconds
+* @param options Debounce options
+* @returns Debounced function
+*
+* @example
+* ```ts
+* const search = debounce((query) => fetchSearchResults(query), 300);
+* search('a'); // Waiting...
+* search('ab'); // Waiting...
+* search('abc'); // Executes after 300ms of no calls
+* ```
+*/
+function debounce(func, wait, options = {}) {
+	let timeout = null;
+	let lastCallTime = 0;
+	let lastInvokeTime = 0;
+	const { leading = false, maxWait } = options;
+	const invokeFunc = (context, args) => {
+		lastInvokeTime = Date.now();
+		func.apply(context, args);
+	};
+	const shouldInvoke = (time) => {
+		const timeSinceLastCall = time - lastCallTime;
+		const timeSinceLastInvoke = time - lastInvokeTime;
+		return lastCallTime === 0 || timeSinceLastCall >= wait || timeSinceLastCall < 0 || maxWait !== void 0 && timeSinceLastInvoke >= maxWait;
+	};
+	const timerExpired = function(args) {
+		timeout = null;
+		invokeFunc(this, args);
+	};
+	const debounced = function(...args) {
+		const time = Date.now();
+		const isInvoking = shouldInvoke(time);
+		lastCallTime = time;
+		if (isInvoking && timeout === null && leading) {
+			invokeFunc(this, args);
+			timeout = setTimeout(() => timerExpired.call(this, args), wait);
+			return;
+		}
+		if (timeout) clearTimeout(timeout);
+		timeout = setTimeout(() => timerExpired.call(this, args), wait);
+	};
+	debounced.cancel = () => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = null;
+		}
+		lastCallTime = 0;
+		lastInvokeTime = 0;
+	};
+	debounced.flush = () => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = null;
+		}
+	};
+	return debounced;
+}
+/**
+* Per-key throttle manager for throttling by specific keys
+* Useful for throttling per-endpoint or per-user
+*/
+var KeyedThrottle = class {
+	throttles = /* @__PURE__ */ new Map();
+	func;
+	wait;
+	options;
+	constructor(func, wait, options = {}) {
+		this.func = func;
+		this.wait = wait;
+		this.options = options;
+	}
+	/**
+	* Execute function with throttling per key
+	*/
+	execute(key, ...args) {
+		let throttled = this.throttles.get(key);
+		if (!throttled) {
+			throttled = throttle(this.func, this.wait, this.options);
+			this.throttles.set(key, throttled);
+		}
+		return throttled(...args);
+	}
+	/**
+	* Cancel throttle for specific key
+	*/
+	cancel(key) {
+		const throttled = this.throttles.get(key);
+		if (throttled) throttled.cancel();
+		this.throttles.delete(key);
+	}
+	/**
+	* Cancel all throttles
+	*/
+	cancelAll() {
+		for (const throttled of this.throttles.values()) throttled.cancel();
+		this.throttles.clear();
+	}
+	/**
+	* Get stats
+	*/
+	getStats() {
+		return {
+			activeKeys: this.throttles.size,
+			keys: Array.from(this.throttles.keys())
+		};
+	}
+};
+/**
+* Per-key debounce manager for debouncing by specific keys
+* Useful for debouncing per-endpoint or per-user
+*/
+var KeyedDebounce = class {
+	debounces = /* @__PURE__ */ new Map();
+	func;
+	wait;
+	options;
+	constructor(func, wait, options = {}) {
+		this.func = func;
+		this.wait = wait;
+		this.options = options;
+	}
+	/**
+	* Execute function with debouncing per key
+	*/
+	execute(key, ...args) {
+		let debounced = this.debounces.get(key);
+		if (!debounced) {
+			debounced = debounce(this.func, this.wait, this.options);
+			this.debounces.set(key, debounced);
+		}
+		debounced(...args);
+	}
+	/**
+	* Cancel debounce for specific key
+	*/
+	cancel(key) {
+		const debounced = this.debounces.get(key);
+		if (debounced) debounced.cancel();
+		this.debounces.delete(key);
+	}
+	/**
+	* Flush debounce for specific key (execute immediately)
+	*/
+	flush(key) {
+		const debounced = this.debounces.get(key);
+		if (debounced) debounced.flush();
+	}
+	/**
+	* Cancel all debounces
+	*/
+	cancelAll() {
+		for (const debounced of this.debounces.values()) debounced.cancel();
+		this.debounces.clear();
+	}
+	/**
+	* Get stats
+	*/
+	getStats() {
+		return {
+			activeKeys: this.debounces.size,
+			keys: Array.from(this.debounces.keys())
+		};
+	}
+};
+/**
+* Rate limiter using token bucket algorithm
+*
+* @example
+* ```ts
+* const limiter = new TokenBucketLimiter(5, 60000); // 5 requests per minute
+*
+* async function fetchData() {
+*   await limiter.acquire();
+*   return fetch('/api/data');
+* }
+* ```
+*/
+var TokenBucketLimiter = class {
+	tokens;
+	lastRefill;
+	capacity;
+	refillRate;
+	refillInterval;
+	queue = [];
+	/**
+	* @param capacity Maximum number of tokens (requests)
+	* @param windowMs Time window in milliseconds
+	*/
+	constructor(capacity, windowMs) {
+		this.capacity = capacity;
+		this.tokens = capacity;
+		this.lastRefill = Date.now();
+		this.refillRate = capacity;
+		this.refillInterval = windowMs;
+	}
+	/**
+	* Refill tokens based on elapsed time
+	*/
+	refill() {
+		const now = Date.now();
+		const tokensToAdd = (now - this.lastRefill) / this.refillInterval * this.refillRate;
+		if (tokensToAdd > 0) {
+			this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
+			this.lastRefill = now;
+		}
+	}
+	/**
+	* Acquire a token (wait if none available)
+	*/
+	async acquire() {
+		this.refill();
+		if (this.tokens >= 1) {
+			this.tokens -= 1;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			this.queue.push(resolve);
+			this.scheduleNextRelease();
+		});
+	}
+	/**
+	* Try to acquire a token without waiting
+	*/
+	tryAcquire() {
+		this.refill();
+		if (this.tokens >= 1) {
+			this.tokens -= 1;
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Schedule next token release
+	*/
+	scheduleNextRelease() {
+		if (this.queue.length === 0) return;
+		const waitTime = this.refillInterval / this.refillRate;
+		setTimeout(() => {
+			this.refill();
+			const resolve = this.queue.shift();
+			if (resolve && this.tokens >= 1) {
+				this.tokens -= 1;
+				resolve();
+			}
+			this.scheduleNextRelease();
+		}, waitTime);
+	}
+	/**
+	* Get rate limiter stats
+	*/
+	getStats() {
+		this.refill();
+		return {
+			availableTokens: Math.floor(this.tokens),
+			queueSize: this.queue.length,
+			capacity: this.capacity
+		};
+	}
+	/**
+	* Reset the rate limiter
+	*/
+	reset() {
+		this.tokens = this.capacity;
+		this.lastRefill = Date.now();
+		this.queue = [];
+	}
+};
+/**
+* Leaky bucket algorithm - requests "leak" out at a constant rate
+* Provides smoother rate limiting than token bucket
+*/
+var LeakyBucketLimiter = class {
+	queue = [];
+	capacity;
+	leakRate;
+	processing = false;
+	/**
+	* @param capacity Maximum queue size
+	* @param requestsPerSecond How many requests to process per second
+	*/
+	constructor(capacity, requestsPerSecond) {
+		this.capacity = capacity;
+		this.leakRate = 1e3 / requestsPerSecond;
+	}
+	/**
+	* Add a request to the bucket
+	*/
+	async acquire() {
+		if (this.queue.length >= this.capacity) throw new Error("Rate limit exceeded: queue full");
+		return new Promise((resolve) => {
+			this.queue.push({
+				resolve,
+				timestamp: Date.now()
+			});
+			this.processQueue();
+		});
+	}
+	/**
+	* Try to acquire without blocking
+	*/
+	tryAcquire() {
+		if (this.queue.length >= this.capacity) return false;
+		if (!this.processing && this.queue.length === 0) return true;
+		return false;
+	}
+	/**
+	* Process the queue at the leak rate
+	*/
+	processQueue() {
+		if (this.processing || this.queue.length === 0) return;
+		this.processing = true;
+		const processNext = () => {
+			const item = this.queue.shift();
+			if (item) item.resolve();
+			if (this.queue.length > 0) setTimeout(processNext, this.leakRate);
+			else this.processing = false;
+		};
+		processNext();
+	}
+	/**
+	* Get stats
+	*/
+	getStats() {
+		return {
+			availableTokens: this.capacity - this.queue.length,
+			queueSize: this.queue.length,
+			capacity: this.capacity
+		};
+	}
+	/**
+	* Clear the queue
+	*/
+	reset() {
+		this.queue = [];
+		this.processing = false;
+	}
+};
+/**
+* Sliding window counter for accurate rate limiting
+*/
+var SlidingWindowCounter = class {
+	counters = /* @__PURE__ */ new Map();
+	windowMs;
+	maxRequests;
+	constructor(windowMs, maxRequests) {
+		this.windowMs = windowMs;
+		this.maxRequests = maxRequests;
+		setInterval(() => this.cleanup(), windowMs);
+	}
+	/**
+	* Check and increment counter for a key
+	*/
+	check(key) {
+		const now = Date.now();
+		const windowStart = Math.floor(now / this.windowMs) * this.windowMs;
+		const previousWindowStart = windowStart - this.windowMs;
+		let counter = this.counters.get(key);
+		if (!counter) {
+			counter = {
+				current: 0,
+				previous: 0,
+				windowStart
+			};
+			this.counters.set(key, counter);
+		}
+		if (counter.windowStart < previousWindowStart) {
+			counter.previous = 0;
+			counter.current = 0;
+			counter.windowStart = windowStart;
+		} else if (counter.windowStart < windowStart) {
+			counter.previous = counter.current;
+			counter.current = 0;
+			counter.windowStart = windowStart;
+		}
+		const windowPosition = (now - windowStart) / this.windowMs;
+		const weightedCount = counter.previous * (1 - windowPosition) + counter.current;
+		const allowed = weightedCount < this.maxRequests;
+		if (allowed) counter.current++;
+		return {
+			allowed,
+			remaining: Math.max(0, Math.floor(this.maxRequests - weightedCount - (allowed ? 1 : 0))),
+			resetAt: windowStart + this.windowMs
+		};
+	}
+	/**
+	* Reset counter for a key
+	*/
+	reset(key) {
+		this.counters.delete(key);
+	}
+	/**
+	* Cleanup old entries
+	*/
+	cleanup() {
+		const cutoff = Date.now() - this.windowMs * 2;
+		for (const [key, counter] of this.counters.entries()) if (counter.windowStart < cutoff) this.counters.delete(key);
+	}
+	/**
+	* Get stats
+	*/
+	getStats() {
+		return {
+			activeKeys: this.counters.size,
+			keys: Array.from(this.counters.keys())
+		};
+	}
+};
+//#endregion
+export { DebounceOptionsSchema, KeyedDebounce, KeyedStatsSchema, KeyedThrottle, LeakyBucketLimiter, RateLimiterStatsSchema, SlidingWindowCounter, ThrottleOptionsSchema, TokenBucketLimiter, debounce, throttle };
+
+//# sourceMappingURL=throttle.js.map

package/lib/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","names":["S"],"sources":["../src/throttle.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @file Throttle and Debounce Utilities\n * @module utils/throttle\n * @author ResQ\n * @description Provides functions to limit the rate at which functions can be called.\n *              Useful for preventing excessive API calls and managing request frequency.\n *              Includes throttle, debounce, rate limiter, and queue utilities.\n * @compliance NIST 800-53 SC-5 (Denial of Service Protection)\n */\n\nimport { Schema as S } from 'effect';\n\n// ============================================\n// Effect Schema Definitions\n// ============================================\n\n/**\n * Throttle Options Schema\n */\nconst ThrottleOptionsSchema = S.Struct({\n  /** Whether to call the function on the leading edge */\n  leading: S.optional(S.Boolean),\n  /** Whether to call the function on the trailing edge */\n  trailing: S.optional(S.Boolean),\n});\n\nexport type ThrottleOptions = typeof ThrottleOptionsSchema.Type;\n\n/**\n * Debounce Options Schema\n */\nconst DebounceOptionsSchema = S.Struct({\n  /** Whether to call the function on the leading edge */\n  leading: S.optional(S.Boolean),\n  /** Maximum time to wait before forcing execution */\n  maxWait: S.optional(S.Number),\n});\n\nexport type DebounceOptions = typeof DebounceOptionsSchema.Type;\n\n/**\n * Rate Limiter Stats Schema\n */\nconst RateLimiterStatsSchema = S.Struct({\n  availableTokens: S.Number,\n  queueSize: S.Number,\n  capacity: S.Number,\n});\n\nexport type RateLimiterStats = typeof RateLimiterStatsSchema.Type;\n\n/**\n * Keyed Stats Schema\n */\nconst KeyedStatsSchema = S.Struct({\n  activeKeys: S.Number,\n  keys: S.Array(S.String),\n});\n\nexport type KeyedStats = typeof KeyedStatsSchema.Type;\n\n// ============================================\n// Generic Function Type\n// ============================================\n\n/** Generic callable function type */\ntype AnyFunction = (...args: never[]) => unknown;\n\n// ============================================\n// Throttle Function\n// ============================================\n\n/**\n * Throttle a function to only execute once per specified interval\n *\n * @param func Function to throttle\n * @param wait Wait time in milliseconds\n * @param options Throttle options\n * @returns Throttled function\n *\n * @example\n * ```ts\n * const fetchData = throttle(() => fetch('/api/data'), 1000);\n * fetchData(); // Executes immediately\n * fetchData(); // Ignored\n * fetchData(); // Ignored\n * // After 1000ms, next call will execute\n * ```\n */\nexport function throttle<T extends AnyFunction>(\n  func: T,\n  wait: number,\n  options: ThrottleOptions = {},\n): ((...args: Parameters<T>) => ReturnType<T> | undefined) & { cancel: () => void } {\n  let timeout: ReturnType<typeof setTimeout> | null = null;\n  let previous = 0;\n  let result: ReturnType<T> | undefined;\n\n  const { leading = true, trailing = true } = options;\n\n  const later = (context: unknown, args: Parameters<T>) => {\n    previous = leading === false ? 0 : Date.now();\n    timeout = null;\n    result = func.apply(context, args) as ReturnType<T>;\n  };\n\n  const throttled = function (this: unknown, ...args: Parameters<T>): ReturnType<T> | undefined {\n    const now = Date.now();\n\n    if (!previous && leading === false) {\n      previous = now;\n    }\n\n    const remaining = wait - (now - previous);\n\n    if (remaining <= 0 || remaining > wait) {\n      if (timeout) {\n        clearTimeout(timeout);\n        timeout = null;\n      }\n      previous = now;\n      result = func.apply(this, args) as ReturnType<T>;\n    } else if (!timeout && trailing) {\n      timeout = setTimeout(() => later(this, args), remaining);\n    }\n\n    return result;\n  } as ((...args: Parameters<T>) => ReturnType<T> | undefined) & { cancel: () => void };\n\n  throttled.cancel = () => {\n    if (timeout) {\n      clearTimeout(timeout);\n      timeout = null;\n    }\n    previous = 0;\n  };\n\n  return throttled;\n}\n\n// ============================================\n// Debounce Function\n// ============================================\n\n/**\n * Debounce a function to only execute after it stops being called for specified time\n *\n * @param func Function to debounce\n * @param wait Wait time in milliseconds\n * @param options Debounce options\n * @returns Debounced function\n *\n * @example\n * ```ts\n * const search = debounce((query) => fetchSearchResults(query), 300);\n * search('a'); // Waiting...\n * search('ab'); // Waiting...\n * search('abc'); // Executes after 300ms of no calls\n * ```\n */\nexport function debounce<T extends AnyFunction>(\n  func: T,\n  wait: number,\n  options: DebounceOptions = {},\n): ((...args: Parameters<T>) => void) & { cancel: () => void; flush: () => void } {\n  let timeout: ReturnType<typeof setTimeout> | null = null;\n  let lastCallTime = 0;\n  let lastInvokeTime = 0;\n\n  const { leading = false, maxWait } = options;\n\n  const invokeFunc = (context: unknown, args: Parameters<T>) => {\n    lastInvokeTime = Date.now();\n    func.apply(context, args);\n  };\n\n  const shouldInvoke = (time: number) => {\n    const timeSinceLastCall = time - lastCallTime;\n    const timeSinceLastInvoke = time - lastInvokeTime;\n\n    return (\n      lastCallTime === 0 ||\n      timeSinceLastCall >= wait ||\n      timeSinceLastCall < 0 ||\n      (maxWait !== undefined && timeSinceLastInvoke >= maxWait)\n    );\n  };\n\n  const timerExpired = function (this: unknown, args: Parameters<T>) {\n    timeout = null;\n    invokeFunc(this, args);\n  };\n\n  const debounced = function (this: unknown, ...args: Parameters<T>): void {\n    const time = Date.now();\n    const isInvoking = shouldInvoke(time);\n\n    lastCallTime = time;\n\n    if (isInvoking && timeout === null && leading) {\n      invokeFunc(this, args);\n      timeout = setTimeout(() => timerExpired.call(this, args), wait);\n      return;\n    }\n\n    if (timeout) {\n      clearTimeout(timeout);\n    }\n\n    timeout = setTimeout(() => timerExpired.call(this, args), wait);\n  } as ((...args: Parameters<T>) => void) & { cancel: () => void; flush: () => void };\n\n  debounced.cancel = () => {\n    if (timeout) {\n      clearTimeout(timeout);\n      timeout = null;\n    }\n    lastCallTime = 0;\n    lastInvokeTime = 0;\n  };\n\n  debounced.flush = () => {\n    if (timeout) {\n      clearTimeout(timeout);\n      timeout = null;\n    }\n  };\n\n  return debounced;\n}\n\n// ============================================\n// Keyed Throttle Manager\n// ============================================\n\n/**\n * Per-key throttle manager for throttling by specific keys\n * Useful for throttling per-endpoint or per-user\n */\nexport class KeyedThrottle<T extends AnyFunction> {\n  private throttles = new Map<\n    string,\n    ((...args: Parameters<T>) => ReturnType<T> | undefined) & { cancel: () => void }\n  >();\n  private readonly func: T;\n  private readonly wait: number;\n  private readonly options: ThrottleOptions;\n\n  constructor(func: T, wait: number, options: ThrottleOptions = {}) {\n    this.func = func;\n    this.wait = wait;\n    this.options = options;\n  }\n\n  /**\n   * Execute function with throttling per key\n   */\n  public execute(key: string, ...args: Parameters<T>): ReturnType<T> | undefined {\n    let throttled = this.throttles.get(key);\n\n    if (!throttled) {\n      throttled = throttle(this.func, this.wait, this.options);\n      this.throttles.set(key, throttled);\n    }\n\n    return throttled(...args);\n  }\n\n  /**\n   * Cancel throttle for specific key\n   */\n  public cancel(key: string): void {\n    const throttled = this.throttles.get(key);\n    if (throttled) {\n      throttled.cancel();\n    }\n    this.throttles.delete(key);\n  }\n\n  /**\n   * Cancel all throttles\n   */\n  public cancelAll(): void {\n    for (const throttled of this.throttles.values()) {\n      throttled.cancel();\n    }\n    this.throttles.clear();\n  }\n\n  /**\n   * Get stats\n   */\n  public getStats(): KeyedStats {\n    return {\n      activeKeys: this.throttles.size,\n      keys: Array.from(this.throttles.keys()),\n    };\n  }\n}\n\n// ============================================\n// Keyed Debounce Manager\n// ============================================\n\n/**\n * Per-key debounce manager for debouncing by specific keys\n * Useful for debouncing per-endpoint or per-user\n */\nexport class KeyedDebounce<T extends AnyFunction> {\n  private debounces = new Map<\n    string,\n    ((...args: Parameters<T>) => void) & { cancel: () => void; flush: () => void }\n  >();\n  private readonly func: T;\n  private readonly wait: number;\n  private readonly options: DebounceOptions;\n\n  constructor(func: T, wait: number, options: DebounceOptions = {}) {\n    this.func = func;\n    this.wait = wait;\n    this.options = options;\n  }\n\n  /**\n   * Execute function with debouncing per key\n   */\n  public execute(key: string, ...args: Parameters<T>): void {\n    let debounced = this.debounces.get(key);\n\n    if (!debounced) {\n      debounced = debounce(this.func, this.wait, this.options);\n      this.debounces.set(key, debounced);\n    }\n\n    debounced(...args);\n  }\n\n  /**\n   * Cancel debounce for specific key\n   */\n  public cancel(key: string): void {\n    const debounced = this.debounces.get(key);\n    if (debounced) {\n      debounced.cancel();\n    }\n    this.debounces.delete(key);\n  }\n\n  /**\n   * Flush debounce for specific key (execute immediately)\n   */\n  public flush(key: string): void {\n    const debounced = this.debounces.get(key);\n    if (debounced) {\n      debounced.flush();\n    }\n  }\n\n  /**\n   * Cancel all debounces\n   */\n  public cancelAll(): void {\n    for (const debounced of this.debounces.values()) {\n      debounced.cancel();\n    }\n    this.debounces.clear();\n  }\n\n  /**\n   * Get stats\n   */\n  public getStats(): KeyedStats {\n    return {\n      activeKeys: this.debounces.size,\n      keys: Array.from(this.debounces.keys()),\n    };\n  }\n}\n\n// ============================================\n// Token Bucket Rate Limiter\n// ============================================\n\n/**\n * Rate limiter using token bucket algorithm\n *\n * @example\n * ```ts\n * const limiter = new TokenBucketLimiter(5, 60000); // 5 requests per minute\n *\n * async function fetchData() {\n *   await limiter.acquire();\n *   return fetch('/api/data');\n * }\n * ```\n */\nexport class TokenBucketLimiter {\n  private tokens: number;\n  private lastRefill: number;\n  private readonly capacity: number;\n  private readonly refillRate: number;\n  private readonly refillInterval: number;\n  private queue: Array<() => void> = [];\n\n  /**\n   * @param capacity Maximum number of tokens (requests)\n   * @param windowMs Time window in milliseconds\n   */\n  constructor(capacity: number, windowMs: number) {\n    this.capacity = capacity;\n    this.tokens = capacity;\n    this.lastRefill = Date.now();\n    this.refillRate = capacity;\n    this.refillInterval = windowMs;\n  }\n\n  /**\n   * Refill tokens based on elapsed time\n   */\n  private refill(): void {\n    const now = Date.now();\n    const elapsed = now - this.lastRefill;\n    const tokensToAdd = (elapsed / this.refillInterval) * this.refillRate;\n\n    if (tokensToAdd > 0) {\n      this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);\n      this.lastRefill = now;\n    }\n  }\n\n  /**\n   * Acquire a token (wait if none available)\n   */\n  public async acquire(): Promise<void> {\n    this.refill();\n\n    if (this.tokens >= 1) {\n      this.tokens -= 1;\n      return Promise.resolve();\n    }\n\n    // Wait for token to become available\n    return new Promise<void>((resolve) => {\n      this.queue.push(resolve);\n      this.scheduleNextRelease();\n    });\n  }\n\n  /**\n   * Try to acquire a token without waiting\n   */\n  public tryAcquire(): boolean {\n    this.refill();\n\n    if (this.tokens >= 1) {\n      this.tokens -= 1;\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Schedule next token release\n   */\n  private scheduleNextRelease(): void {\n    if (this.queue.length === 0) return;\n\n    const waitTime = this.refillInterval / this.refillRate;\n\n    setTimeout(() => {\n      this.refill();\n      const resolve = this.queue.shift();\n      if (resolve && this.tokens >= 1) {\n        this.tokens -= 1;\n        resolve();\n      }\n      this.scheduleNextRelease();\n    }, waitTime);\n  }\n\n  /**\n   * Get rate limiter stats\n   */\n  public getStats(): RateLimiterStats {\n    this.refill();\n    return {\n      availableTokens: Math.floor(this.tokens),\n      queueSize: this.queue.length,\n      capacity: this.capacity,\n    };\n  }\n\n  /**\n   * Reset the rate limiter\n   */\n  public reset(): void {\n    this.tokens = this.capacity;\n    this.lastRefill = Date.now();\n    this.queue = [];\n  }\n}\n\n// ============================================\n// Leaky Bucket Rate Limiter\n// ============================================\n\n/**\n * Leaky bucket algorithm - requests \"leak\" out at a constant rate\n * Provides smoother rate limiting than token bucket\n */\nexport class LeakyBucketLimiter {\n  private queue: Array<{ resolve: () => void; timestamp: number }> = [];\n  private readonly capacity: number;\n  private readonly leakRate: number; // requests per second\n  private processing = false;\n\n  /**\n   * @param capacity Maximum queue size\n   * @param requestsPerSecond How many requests to process per second\n   */\n  constructor(capacity: number, requestsPerSecond: number) {\n    this.capacity = capacity;\n    this.leakRate = 1000 / requestsPerSecond; // ms between requests\n  }\n\n  /**\n   * Add a request to the bucket\n   */\n  public async acquire(): Promise<void> {\n    if (this.queue.length >= this.capacity) {\n      throw new Error('Rate limit exceeded: queue full');\n    }\n\n    return new Promise<void>((resolve) => {\n      this.queue.push({ resolve, timestamp: Date.now() });\n      this.processQueue();\n    });\n  }\n\n  /**\n   * Try to acquire without blocking\n   */\n  public tryAcquire(): boolean {\n    if (this.queue.length >= this.capacity) {\n      return false;\n    }\n\n    // Check if we can process immediately\n    if (!this.processing && this.queue.length === 0) {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Process the queue at the leak rate\n   */\n  private processQueue(): void {\n    if (this.processing || this.queue.length === 0) return;\n\n    this.processing = true;\n\n    const processNext = () => {\n      const item = this.queue.shift();\n      if (item) {\n        item.resolve();\n      }\n\n      if (this.queue.length > 0) {\n        setTimeout(processNext, this.leakRate);\n      } else {\n        this.processing = false;\n      }\n    };\n\n    processNext();\n  }\n\n  /**\n   * Get stats\n   */\n  public getStats(): RateLimiterStats {\n    return {\n      availableTokens: this.capacity - this.queue.length,\n      queueSize: this.queue.length,\n      capacity: this.capacity,\n    };\n  }\n\n  /**\n   * Clear the queue\n   */\n  public reset(): void {\n    this.queue = [];\n    this.processing = false;\n  }\n}\n\n// ============================================\n// Sliding Window Counter\n// ============================================\n\n/**\n * Sliding window counter for accurate rate limiting\n */\nexport class SlidingWindowCounter {\n  private counters = new Map<string, { current: number; previous: number; windowStart: number }>();\n  private readonly windowMs: number;\n  private readonly maxRequests: number;\n\n  constructor(windowMs: number, maxRequests: number) {\n    this.windowMs = windowMs;\n    this.maxRequests = maxRequests;\n\n    // Cleanup old entries periodically\n    setInterval(() => this.cleanup(), windowMs);\n  }\n\n  /**\n   * Check and increment counter for a key\n   */\n  public check(key: string): { allowed: boolean; remaining: number; resetAt: number } {\n    const now = Date.now();\n    const windowStart = Math.floor(now / this.windowMs) * this.windowMs;\n    const previousWindowStart = windowStart - this.windowMs;\n\n    let counter = this.counters.get(key);\n\n    if (!counter) {\n      counter = { current: 0, previous: 0, windowStart };\n      this.counters.set(key, counter);\n    }\n\n    // Roll over to new window if needed\n    if (counter.windowStart < previousWindowStart) {\n      counter.previous = 0;\n      counter.current = 0;\n      counter.windowStart = windowStart;\n    } else if (counter.windowStart < windowStart) {\n      counter.previous = counter.current;\n      counter.current = 0;\n      counter.windowStart = windowStart;\n    }\n\n    // Calculate weighted count\n    const windowPosition = (now - windowStart) / this.windowMs;\n    const weightedCount = counter.previous * (1 - windowPosition) + counter.current;\n\n    const allowed = weightedCount < this.maxRequests;\n\n    if (allowed) {\n      counter.current++;\n    }\n\n    return {\n      allowed,\n      remaining: Math.max(0, Math.floor(this.maxRequests - weightedCount - (allowed ? 1 : 0))),\n      resetAt: windowStart + this.windowMs,\n    };\n  }\n\n  /**\n   * Reset counter for a key\n   */\n  public reset(key: string): void {\n    this.counters.delete(key);\n  }\n\n  /**\n   * Cleanup old entries\n   */\n  private cleanup(): void {\n    const cutoff = Date.now() - this.windowMs * 2;\n    for (const [key, counter] of this.counters.entries()) {\n      if (counter.windowStart < cutoff) {\n        this.counters.delete(key);\n      }\n    }\n  }\n\n  /**\n   * Get stats\n   */\n  public getStats(): KeyedStats {\n    return {\n      activeKeys: this.counters.size,\n      keys: Array.from(this.counters.keys()),\n    };\n  }\n}\n\n// ============================================\n// Exports\n// ============================================\n\nexport { DebounceOptionsSchema, KeyedStatsSchema, RateLimiterStatsSchema, ThrottleOptionsSchema };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAM,wBAAwBA,OAAE,OAAO;CAErC,SAASA,OAAE,SAASA,OAAE,QAAQ;CAE9B,UAAUA,OAAE,SAASA,OAAE,QAAQ;CAChC,CAAC;;;;AAOF,MAAM,wBAAwBA,OAAE,OAAO;CAErC,SAASA,OAAE,SAASA,OAAE,QAAQ;CAE9B,SAASA,OAAE,SAASA,OAAE,OAAO;CAC9B,CAAC;;;;AAOF,MAAM,yBAAyBA,OAAE,OAAO;CACtC,iBAAiBA,OAAE;CACnB,WAAWA,OAAE;CACb,UAAUA,OAAE;CACb,CAAC;;;;AAOF,MAAM,mBAAmBA,OAAE,OAAO;CAChC,YAAYA,OAAE;CACd,MAAMA,OAAE,MAAMA,OAAE,OAAO;CACxB,CAAC;;;;;;;;;;;;;;;;;;AAgCF,SAAgB,SACd,MACA,MACA,UAA2B,EAAE,EACqD;CAClF,IAAI,UAAgD;CACpD,IAAI,WAAW;CACf,IAAI;CAEJ,MAAM,EAAE,UAAU,MAAM,WAAW,SAAS;CAE5C,MAAM,SAAS,SAAkB,SAAwB;AACvD,aAAW,YAAY,QAAQ,IAAI,KAAK,KAAK;AAC7C,YAAU;AACV,WAAS,KAAK,MAAM,SAAS,KAAK;;CAGpC,MAAM,YAAY,SAAyB,GAAG,MAAgD;EAC5F,MAAM,MAAM,KAAK,KAAK;AAEtB,MAAI,CAAC,YAAY,YAAY,MAC3B,YAAW;EAGb,MAAM,YAAY,QAAQ,MAAM;AAEhC,MAAI,aAAa,KAAK,YAAY,MAAM;AACtC,OAAI,SAAS;AACX,iBAAa,QAAQ;AACrB,cAAU;;AAEZ,cAAW;AACX,YAAS,KAAK,MAAM,MAAM,KAAK;aACtB,CAAC,WAAW,SACrB,WAAU,iBAAiB,MAAM,MAAM,KAAK,EAAE,UAAU;AAG1D,SAAO;;AAGT,WAAU,eAAe;AACvB,MAAI,SAAS;AACX,gBAAa,QAAQ;AACrB,aAAU;;AAEZ,aAAW;;AAGb,QAAO;;;;;;;;;;;;;;;;;;AAuBT,SAAgB,SACd,MACA,MACA,UAA2B,EAAE,EACmD;CAChF,IAAI,UAAgD;CACpD,IAAI,eAAe;CACnB,IAAI,iBAAiB;CAErB,MAAM,EAAE,UAAU,OAAO,YAAY;CAErC,MAAM,cAAc,SAAkB,SAAwB;AAC5D,mBAAiB,KAAK,KAAK;AAC3B,OAAK,MAAM,SAAS,KAAK;;CAG3B,MAAM,gBAAgB,SAAiB;EACrC,MAAM,oBAAoB,OAAO;EACjC,MAAM,sBAAsB,OAAO;AAEnC,SACE,iBAAiB,KACjB,qBAAqB,QACrB,oBAAoB,KACnB,YAAY,KAAA,KAAa,uBAAuB;;CAIrD,MAAM,eAAe,SAAyB,MAAqB;AACjE,YAAU;AACV,aAAW,MAAM,KAAK;;CAGxB,MAAM,YAAY,SAAyB,GAAG,MAA2B;EACvE,MAAM,OAAO,KAAK,KAAK;EACvB,MAAM,aAAa,aAAa,KAAK;AAErC,iBAAe;AAEf,MAAI,cAAc,YAAY,QAAQ,SAAS;AAC7C,cAAW,MAAM,KAAK;AACtB,aAAU,iBAAiB,aAAa,KAAK,MAAM,KAAK,EAAE,KAAK;AAC/D;;AAGF,MAAI,QACF,cAAa,QAAQ;AAGvB,YAAU,iBAAiB,aAAa,KAAK,MAAM,KAAK,EAAE,KAAK;;AAGjE,WAAU,eAAe;AACvB,MAAI,SAAS;AACX,gBAAa,QAAQ;AACrB,aAAU;;AAEZ,iBAAe;AACf,mBAAiB;;AAGnB,WAAU,cAAc;AACtB,MAAI,SAAS;AACX,gBAAa,QAAQ;AACrB,aAAU;;;AAId,QAAO;;;;;;AAWT,IAAa,gBAAb,MAAkD;CAChD,4BAAoB,IAAI,KAGrB;CACH;CACA;CACA;CAEA,YAAY,MAAS,MAAc,UAA2B,EAAE,EAAE;AAChE,OAAK,OAAO;AACZ,OAAK,OAAO;AACZ,OAAK,UAAU;;;;;CAMjB,QAAe,KAAa,GAAG,MAAgD;EAC7E,IAAI,YAAY,KAAK,UAAU,IAAI,IAAI;AAEvC,MAAI,CAAC,WAAW;AACd,eAAY,SAAS,KAAK,MAAM,KAAK,MAAM,KAAK,QAAQ;AACxD,QAAK,UAAU,IAAI,KAAK,UAAU;;AAGpC,SAAO,UAAU,GAAG,KAAK;;;;;CAM3B,OAAc,KAAmB;EAC/B,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI;AACzC,MAAI,UACF,WAAU,QAAQ;AAEpB,OAAK,UAAU,OAAO,IAAI;;;;;CAM5B,YAAyB;AACvB,OAAK,MAAM,aAAa,KAAK,UAAU,QAAQ,CAC7C,WAAU,QAAQ;AAEpB,OAAK,UAAU,OAAO;;;;;CAMxB,WAA8B;AAC5B,SAAO;GACL,YAAY,KAAK,UAAU;GAC3B,MAAM,MAAM,KAAK,KAAK,UAAU,MAAM,CAAC;GACxC;;;;;;;AAYL,IAAa,gBAAb,MAAkD;CAChD,4BAAoB,IAAI,KAGrB;CACH;CACA;CACA;CAEA,YAAY,MAAS,MAAc,UAA2B,EAAE,EAAE;AAChE,OAAK,OAAO;AACZ,OAAK,OAAO;AACZ,OAAK,UAAU;;;;;CAMjB,QAAe,KAAa,GAAG,MAA2B;EACxD,IAAI,YAAY,KAAK,UAAU,IAAI,IAAI;AAEvC,MAAI,CAAC,WAAW;AACd,eAAY,SAAS,KAAK,MAAM,KAAK,MAAM,KAAK,QAAQ;AACxD,QAAK,UAAU,IAAI,KAAK,UAAU;;AAGpC,YAAU,GAAG,KAAK;;;;;CAMpB,OAAc,KAAmB;EAC/B,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI;AACzC,MAAI,UACF,WAAU,QAAQ;AAEpB,OAAK,UAAU,OAAO,IAAI;;;;;CAM5B,MAAa,KAAmB;EAC9B,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI;AACzC,MAAI,UACF,WAAU,OAAO;;;;;CAOrB,YAAyB;AACvB,OAAK,MAAM,aAAa,KAAK,UAAU,QAAQ,CAC7C,WAAU,QAAQ;AAEpB,OAAK,UAAU,OAAO;;;;;CAMxB,WAA8B;AAC5B,SAAO;GACL,YAAY,KAAK,UAAU;GAC3B,MAAM,MAAM,KAAK,KAAK,UAAU,MAAM,CAAC;GACxC;;;;;;;;;;;;;;;;AAqBL,IAAa,qBAAb,MAAgC;CAC9B;CACA;CACA;CACA;CACA;CACA,QAAmC,EAAE;;;;;CAMrC,YAAY,UAAkB,UAAkB;AAC9C,OAAK,WAAW;AAChB,OAAK,SAAS;AACd,OAAK,aAAa,KAAK,KAAK;AAC5B,OAAK,aAAa;AAClB,OAAK,iBAAiB;;;;;CAMxB,SAAuB;EACrB,MAAM,MAAM,KAAK,KAAK;EAEtB,MAAM,eADU,MAAM,KAAK,cACI,KAAK,iBAAkB,KAAK;AAE3D,MAAI,cAAc,GAAG;AACnB,QAAK,SAAS,KAAK,IAAI,KAAK,UAAU,KAAK,SAAS,YAAY;AAChE,QAAK,aAAa;;;;;;CAOtB,MAAa,UAAyB;AACpC,OAAK,QAAQ;AAEb,MAAI,KAAK,UAAU,GAAG;AACpB,QAAK,UAAU;AACf,UAAO,QAAQ,SAAS;;AAI1B,SAAO,IAAI,SAAe,YAAY;AACpC,QAAK,MAAM,KAAK,QAAQ;AACxB,QAAK,qBAAqB;IAC1B;;;;;CAMJ,aAA6B;AAC3B,OAAK,QAAQ;AAEb,MAAI,KAAK,UAAU,GAAG;AACpB,QAAK,UAAU;AACf,UAAO;;AAGT,SAAO;;;;;CAMT,sBAAoC;AAClC,MAAI,KAAK,MAAM,WAAW,EAAG;EAE7B,MAAM,WAAW,KAAK,iBAAiB,KAAK;AAE5C,mBAAiB;AACf,QAAK,QAAQ;GACb,MAAM,UAAU,KAAK,MAAM,OAAO;AAClC,OAAI,WAAW,KAAK,UAAU,GAAG;AAC/B,SAAK,UAAU;AACf,aAAS;;AAEX,QAAK,qBAAqB;KACzB,SAAS;;;;;CAMd,WAAoC;AAClC,OAAK,QAAQ;AACb,SAAO;GACL,iBAAiB,KAAK,MAAM,KAAK,OAAO;GACxC,WAAW,KAAK,MAAM;GACtB,UAAU,KAAK;GAChB;;;;;CAMH,QAAqB;AACnB,OAAK,SAAS,KAAK;AACnB,OAAK,aAAa,KAAK,KAAK;AAC5B,OAAK,QAAQ,EAAE;;;;;;;AAYnB,IAAa,qBAAb,MAAgC;CAC9B,QAAmE,EAAE;CACrE;CACA;CACA,aAAqB;;;;;CAMrB,YAAY,UAAkB,mBAA2B;AACvD,OAAK,WAAW;AAChB,OAAK,WAAW,MAAO;;;;;CAMzB,MAAa,UAAyB;AACpC,MAAI,KAAK,MAAM,UAAU,KAAK,SAC5B,OAAM,IAAI,MAAM,kCAAkC;AAGpD,SAAO,IAAI,SAAe,YAAY;AACpC,QAAK,MAAM,KAAK;IAAE;IAAS,WAAW,KAAK,KAAK;IAAE,CAAC;AACnD,QAAK,cAAc;IACnB;;;;;CAMJ,aAA6B;AAC3B,MAAI,KAAK,MAAM,UAAU,KAAK,SAC5B,QAAO;AAIT,MAAI,CAAC,KAAK,cAAc,KAAK,MAAM,WAAW,EAC5C,QAAO;AAGT,SAAO;;;;;CAMT,eAA6B;AAC3B,MAAI,KAAK,cAAc,KAAK,MAAM,WAAW,EAAG;AAEhD,OAAK,aAAa;EAElB,MAAM,oBAAoB;GACxB,MAAM,OAAO,KAAK,MAAM,OAAO;AAC/B,OAAI,KACF,MAAK,SAAS;AAGhB,OAAI,KAAK,MAAM,SAAS,EACtB,YAAW,aAAa,KAAK,SAAS;OAEtC,MAAK,aAAa;;AAItB,eAAa;;;;;CAMf,WAAoC;AAClC,SAAO;GACL,iBAAiB,KAAK,WAAW,KAAK,MAAM;GAC5C,WAAW,KAAK,MAAM;GACtB,UAAU,KAAK;GAChB;;;;;CAMH,QAAqB;AACnB,OAAK,QAAQ,EAAE;AACf,OAAK,aAAa;;;;;;AAWtB,IAAa,uBAAb,MAAkC;CAChC,2BAAmB,IAAI,KAAyE;CAChG;CACA;CAEA,YAAY,UAAkB,aAAqB;AACjD,OAAK,WAAW;AAChB,OAAK,cAAc;AAGnB,oBAAkB,KAAK,SAAS,EAAE,SAAS;;;;;CAM7C,MAAa,KAAuE;EAClF,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,cAAc,KAAK,MAAM,MAAM,KAAK,SAAS,GAAG,KAAK;EAC3D,MAAM,sBAAsB,cAAc,KAAK;EAE/C,IAAI,UAAU,KAAK,SAAS,IAAI,IAAI;AAEpC,MAAI,CAAC,SAAS;AACZ,aAAU;IAAE,SAAS;IAAG,UAAU;IAAG;IAAa;AAClD,QAAK,SAAS,IAAI,KAAK,QAAQ;;AAIjC,MAAI,QAAQ,cAAc,qBAAqB;AAC7C,WAAQ,WAAW;AACnB,WAAQ,UAAU;AAClB,WAAQ,cAAc;aACb,QAAQ,cAAc,aAAa;AAC5C,WAAQ,WAAW,QAAQ;AAC3B,WAAQ,UAAU;AAClB,WAAQ,cAAc;;EAIxB,MAAM,kBAAkB,MAAM,eAAe,KAAK;EAClD,MAAM,gBAAgB,QAAQ,YAAY,IAAI,kBAAkB,QAAQ;EAExE,MAAM,UAAU,gBAAgB,KAAK;AAErC,MAAI,QACF,SAAQ;AAGV,SAAO;GACL;GACA,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,cAAc,iBAAiB,UAAU,IAAI,GAAG,CAAC;GACxF,SAAS,cAAc,KAAK;GAC7B;;;;;CAMH,MAAa,KAAmB;AAC9B,OAAK,SAAS,OAAO,IAAI;;;;;CAM3B,UAAwB;EACtB,MAAM,SAAS,KAAK,KAAK,GAAG,KAAK,WAAW;AAC5C,OAAK,MAAM,CAAC,KAAK,YAAY,KAAK,SAAS,SAAS,CAClD,KAAI,QAAQ,cAAc,OACxB,MAAK,SAAS,OAAO,IAAI;;;;;CAQ/B,WAA8B;AAC5B,SAAO;GACL,YAAY,KAAK,SAAS;GAC1B,MAAM,MAAM,KAAK,KAAK,SAAS,MAAM,CAAC;GACvC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@resq-sw/rate-limiting",
+  "version": "0.1.0",
+  "description": "Rate limiting algorithms, throttle/debounce utilities, and HTTP middleware",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": ["lib", "README.md"],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "effect": ">=3.0.0",
+    "@upstash/redis": ">=1.0.0",
+    "@upstash/ratelimit": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    },
+    "@upstash/redis": {
+      "optional": true
+    },
+    "@upstash/ratelimit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@upstash/ratelimit": "^2.0.5",
+    "@upstash/redis": "^1.36.3",
+    "effect": "4.0.0-beta.43",
+    "tsdown": "^0.21.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resq-software/npm.git",
+    "directory": "packages/rate-limiting"
+  },
+  "keywords": ["rate-limiting", "throttle", "debounce", "sliding-window", "token-bucket", "leaky-bucket", "middleware"],
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}