@zeitar/throttle 1.0.0

package/LICENSE.md

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2025 Khaled Zeitar
+
+This library implements rate limiting algorithms with architecture inspired by
+Symfony's Rate Limiter component.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @zeitar/throttle
+
+A production-ready TypeScript rate limiting library with support for multiple algorithms.
+
+> Architecture inspired by [Symfony's Rate Limiter component](https://symfony.com/doc/current/rate_limiter.html), implemented natively in TypeScript with async/await patterns for Node.js.
+
+[![npm version](https://img.shields.io/npm/v/@zeitar/throttle.svg)](https://www.npmjs.com/package/@zeitar/throttle)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **Multiple Algorithms**: Token Bucket, Fixed Window, Sliding Window, and No-Limit policies
+- 📦 **TypeScript Native**: Full type safety with strict typing
+- 🔒 **Production Ready**: Thread-safe with optional distributed locking support
+- 🧩 **Composable**: Combine multiple limiters with CompoundLimiter
+- 💾 **Pluggable Storage**: In-memory storage included, easily extend for Redis, etc.
+- ⚡ **High Performance**: Efficient algorithms with minimal overhead (O(1) time complexity)
+- 🎯 **Zero Dependencies**: Core library has no external dependencies
+- 🔌 **Framework Agnostic**: Works with Express, Fastify, or any Node.js framework
+
+## Installation
+
+```bash
+npm install @zeitar/throttle
+```
+
+## Quick Start
+
+```typescript
+import { RateLimiterFactory, InMemoryStorage } from '@zeitar/throttle';
+
+// Create a rate limiter factory
+const factory = new RateLimiterFactory(
+  {
+    policy: 'token_bucket',
+    id: 'api',
+    limit: 100,              // Burst size
+    rate: {
+      interval: '1 hour',    // Refill interval
+      amount: 100            // Tokens per interval
+    }
+  },
+  new InMemoryStorage()
+);
+
+// Create a limiter for a specific user
+const limiter = factory.create('user-123');
+
+// Try to consume tokens
+const result = await limiter.consume(5);
+
+if (result.isAccepted()) {
+  console.log(`✓ Request accepted! ${result.getRemainingTokens()} tokens remaining`);
+} else {
+  console.log(`✗ Rate limited. Retry after ${result.getRetryAfter()} seconds`);
+}
+```
+
+## Express Middleware Example
+
+```typescript
+import { RateLimiterFactory, InMemoryStorage } from '@zeitar/throttle';
+import type { Request, Response, NextFunction } from 'express';
+
+const factory = new RateLimiterFactory(
+  {
+    policy: 'token_bucket',
+    id: 'api',
+    limit: 100,
+    rate: { interval: '1 minute', amount: 100 }
+  },
+  new InMemoryStorage()
+);
+
+app.use(async (req: Request, res: Response, next: NextFunction) => {
+  const limiter = factory.create(req.ip);
+  const result = await limiter.consume();
+
+  res.setHeader('X-RateLimit-Remaining', result.getRemainingTokens().toString());
+
+  if (!result.isAccepted()) {
+    res.setHeader('Retry-After', result.getRetryAfter().toString());
+    return res.status(429).json({
+      error: 'Too many requests',
+      retryAfter: result.getRetryAfter()
+    });
+  }
+
+  next();
+});
+```
+
+## Documentation
+
+### Getting Started
+- **[Getting Started Guide](./docs/getting-started.md)** - Installation, basic usage, and testing
+- **[Choosing an Algorithm](./docs/algorithms.md)** - Algorithm comparison and selection guide
+- **[Framework Integration](./docs/framework-integration.md)** - Express, Fastify, NestJS, Koa, Hono examples
+
+### Core Concepts
+- **[Common Patterns](./docs/common-patterns.md)** - User tiers, endpoint limits, global+per-user patterns
+- **[Advanced Usage](./docs/advanced-usage.md)** - Reservation pattern, compound limiters, dynamic creation
+- **[Custom Storage](./docs/custom-storage.md)** - Redis, PostgreSQL, DynamoDB implementations
+- **[API Reference](./docs/api-reference.md)** - Complete API documentation
+
+### Help & Troubleshooting
+- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
+
+## Algorithm Comparison
+
+| Algorithm | Best For | Allows Bursts? | Precision |
+|-----------|----------|----------------|-----------|
+| **Token Bucket** ⭐ | Most APIs, microservices | ✅ Yes | Medium |
+| **Fixed Window** | Daily quotas, analytics | ⚠️ At boundaries | Low |
+| **Sliding Window** | High-security APIs, payments | ❌ No | High |
+| **No Limit** | Testing, feature flags | ✅ Always | N/A |
+
+**Not sure which to choose?** See the [Algorithm Guide](./docs/algorithms.md).
+
+## Key Features
+
+### Multiple Rate Limits (Compound Limiter)
+
+```typescript
+import { CompoundRateLimiterFactory } from '@zeitar/throttle';
+
+// Enforce BOTH limits simultaneously
+const compound = new CompoundRateLimiterFactory([
+  perSecondFactory,  // 10/second
+  perMinuteFactory   // 100/minute
+]);
+
+const limiter = compound.create('user-123');
+```
+
+### Reservation Pattern
+
+```typescript
+// Reserve tokens and wait for availability
+const reservation = await limiter.reserve(10, 5); // Wait max 5 seconds
+await reservation.wait();
+// Tokens are now reserved, proceed with operation
+```
+
+### Distributed Systems
+
+```typescript
+// Use Redis for multi-server deployments
+import { RedisStorage, RedisLock } from './your-impl';
+
+const factory = new RateLimiterFactory(
+  config,
+  new RedisStorage(redisClient),
+  new RedisLock(redisClient)
+);
+```
+
+See [Custom Storage](./docs/custom-storage.md) for implementation.
+
+## Performance
+
+- **All algorithms**: O(1) time complexity
+- **Memory usage**: ~100 bytes per active limiter
+- **Throughput**: Designed for high-concurrency scenarios
+- **Storage**: Pluggable backend (in-memory, Redis, database)
+
+## Architecture
+
+This library uses several design patterns for flexibility and maintainability:
+
+- **Strategy Pattern**: Different algorithms implement `LimiterInterface`
+- **Factory Pattern**: `RateLimiterFactory` creates configured limiters
+- **Composite Pattern**: `CompoundLimiter` combines multiple limiters
+- **Dependency Injection**: Storage and locking are pluggable
+
+Inspired by [Symfony's Rate Limiter](https://github.com/symfony/rate-limiter) with full TypeScript support and async/await patterns.
+
+## Testing
+
+```typescript
+import { NoLimiter, InMemoryStorage } from '@zeitar/throttle';
+
+// Use NoLimiter for tests that shouldn't be rate limited
+const limiter = new NoLimiter();
+
+// Or clear InMemoryStorage between tests
+const storage = new InMemoryStorage();
+storage.clear();
+```
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## License
+
+MIT © 2025 Khaled Zeitar
+
+## Credits & Acknowledgments
+
+- **Implementation**: © 2025 Khaled Zeitar - Original TypeScript implementation
+- **Architectural inspiration**: [Symfony Rate Limiter](https://github.com/symfony/rate-limiter) by Fabien Potencier and contributors
+
+While the code is written from scratch in TypeScript, the design patterns, API structure, and architectural decisions are influenced by Symfony's proven approach to rate limiting.

package/dist/CompoundLimiter.d.ts

@@ -0,0 +1,33 @@
+import type { LimiterInterface } from './LimiterInterface';
+import type { RateLimit } from './RateLimit';
+import { Reservation } from './Reservation';
+/**
+ * Compound rate limiter that combines multiple limiters.
+ *
+ * Uses AND logic: all limiters must accept for the request to be accepted.
+ * Returns the most restrictive result (lowest available tokens, longest retry time).
+ *
+ * Note: Does NOT support the reserve() pattern due to complexity of coordinating
+ * multiple reservations.
+ */
+export declare class CompoundLimiter implements LimiterInterface {
+    private readonly limiters;
+    constructor(limiters: LimiterInterface[]);
+    /**
+     * Reserve is not supported by compound limiters.
+     *
+     * @throws {ReserveNotSupportedError} Always throws
+     */
+    reserve(_tokens?: number, _maxTime?: number | null): Promise<Reservation>;
+    /**
+     * Try to consume tokens from all limiters.
+     *
+     * Returns the most restrictive result if any limiter rejects.
+     */
+    consume(tokens?: number): Promise<RateLimit>;
+    /**
+     * Reset all limiters.
+     */
+    reset(): Promise<void>;
+}
+//# sourceMappingURL=CompoundLimiter.d.ts.map

package/dist/CompoundLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompoundLimiter.d.ts","sourceRoot":"","sources":["../src/CompoundLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,QAAQ,EAAE,gBAAgB,EAAE;IAOxC;;;;OAIG;IACG,OAAO,CAAC,OAAO,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAMxF;;;;OAIG;IACG,OAAO,CAAC,MAAM,GAAE,MAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IA4BrD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/CompoundLimiter.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompoundLimiter = void 0;
+const ReserveNotSupportedError_1 = require("./errors/ReserveNotSupportedError");
+/**
+ * Compound rate limiter that combines multiple limiters.
+ *
+ * Uses AND logic: all limiters must accept for the request to be accepted.
+ * Returns the most restrictive result (lowest available tokens, longest retry time).
+ *
+ * Note: Does NOT support the reserve() pattern due to complexity of coordinating
+ * multiple reservations.
+ */
+class CompoundLimiter {
+    constructor(limiters) {
+        if (limiters.length === 0) {
+            throw new Error('CompoundLimiter requires at least one limiter');
+        }
+        this.limiters = limiters;
+    }
+    /**
+     * Reserve is not supported by compound limiters.
+     *
+     * @throws {ReserveNotSupportedError} Always throws
+     */
+    async reserve(_tokens = 1, _maxTime = null) {
+        throw new ReserveNotSupportedError_1.ReserveNotSupportedError('CompoundLimiter does not support the reserve() method. Use consume() instead.');
+    }
+    /**
+     * Try to consume tokens from all limiters.
+     *
+     * Returns the most restrictive result if any limiter rejects.
+     */
+    async consume(tokens = 1) {
+        const results = await Promise.all(this.limiters.map(limiter => limiter.consume(tokens)));
+        // Find the most restrictive result
+        let mostRestrictive = results[0];
+        for (const result of results.slice(1)) {
+            // If current result is rejected and previous was accepted, or
+            // if both rejected but current has longer wait time, or
+            // if both accepted but current has fewer tokens
+            if ((!result.isAccepted() && mostRestrictive.isAccepted()) ||
+                (!result.isAccepted() &&
+                    !mostRestrictive.isAccepted() &&
+                    result.getRetryAfter() > mostRestrictive.getRetryAfter()) ||
+                (result.isAccepted() &&
+                    mostRestrictive.isAccepted() &&
+                    result.getRemainingTokens() < mostRestrictive.getRemainingTokens())) {
+                mostRestrictive = result;
+            }
+        }
+        return mostRestrictive;
+    }
+    /**
+     * Reset all limiters.
+     */
+    async reset() {
+        await Promise.all(this.limiters.map(limiter => limiter.reset()));
+    }
+}
+exports.CompoundLimiter = CompoundLimiter;
+//# sourceMappingURL=CompoundLimiter.js.map

package/dist/CompoundLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompoundLimiter.js","sourceRoot":"","sources":["../src/CompoundLimiter.ts"],"names":[],"mappings":";;;AAGA,gFAA6E;AAE7E;;;;;;;;GAQG;AACH,MAAa,eAAe;IAG1B,YAAY,QAA4B;QACtC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,UAAkB,CAAC,EAAE,WAA0B,IAAI;QAC/D,MAAM,IAAI,mDAAwB,CAChC,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CACtD,CAAC;QAEF,mCAAmC;QACnC,IAAI,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAEjC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACtC,8DAA8D;YAC9D,wDAAwD;YACxD,gDAAgD;YAChD,IACE,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,eAAe,CAAC,UAAU,EAAE,CAAC;gBACtD,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE;oBACnB,CAAC,eAAe,CAAC,UAAU,EAAE;oBAC7B,MAAM,CAAC,aAAa,EAAE,GAAG,eAAe,CAAC,aAAa,EAAE,CAAC;gBAC3D,CAAC,MAAM,CAAC,UAAU,EAAE;oBAClB,eAAe,CAAC,UAAU,EAAE;oBAC5B,MAAM,CAAC,kBAAkB,EAAE,GAAG,eAAe,CAAC,kBAAkB,EAAE,CAAC,EACrE,CAAC;gBACD,eAAe,GAAG,MAAM,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;CACF;AA5DD,0CA4DC"}

package/dist/CompoundRateLimiterFactory.d.ts

@@ -0,0 +1,19 @@
+import type { RateLimiterFactoryInterface } from './RateLimiterFactoryInterface';
+import type { LimiterInterface } from './LimiterInterface';
+/**
+ * Factory for creating compound rate limiters.
+ *
+ * Combines multiple factories to create a single limiter that enforces
+ * all policies simultaneously.
+ */
+export declare class CompoundRateLimiterFactory implements RateLimiterFactoryInterface {
+    private readonly factories;
+    constructor(factories: RateLimiterFactoryInterface[]);
+    /**
+     * Create a compound rate limiter.
+     *
+     * @param key - Optional key passed to all underlying factories
+     */
+    create(key?: string | null): LimiterInterface;
+}
+//# sourceMappingURL=CompoundRateLimiterFactory.d.ts.map

package/dist/CompoundRateLimiterFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompoundRateLimiterFactory.d.ts","sourceRoot":"","sources":["../src/CompoundRateLimiterFactory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,2BAA2B;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAE9C,SAAS,EAAE,2BAA2B,EAAE;IAOpD;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB;CAI9C"}

package/dist/CompoundRateLimiterFactory.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompoundRateLimiterFactory = void 0;
+const CompoundLimiter_1 = require("./CompoundLimiter");
+/**
+ * Factory for creating compound rate limiters.
+ *
+ * Combines multiple factories to create a single limiter that enforces
+ * all policies simultaneously.
+ */
+class CompoundRateLimiterFactory {
+    constructor(factories) {
+        if (factories.length === 0) {
+            throw new Error('CompoundRateLimiterFactory requires at least one factory');
+        }
+        this.factories = factories;
+    }
+    /**
+     * Create a compound rate limiter.
+     *
+     * @param key - Optional key passed to all underlying factories
+     */
+    create(key) {
+        const limiters = this.factories.map(factory => factory.create(key));
+        return new CompoundLimiter_1.CompoundLimiter(limiters);
+    }
+}
+exports.CompoundRateLimiterFactory = CompoundRateLimiterFactory;
+//# sourceMappingURL=CompoundRateLimiterFactory.js.map

package/dist/CompoundRateLimiterFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompoundRateLimiterFactory.js","sourceRoot":"","sources":["../src/CompoundRateLimiterFactory.ts"],"names":[],"mappings":";;;AAEA,uDAAoD;AAEpD;;;;;GAKG;AACH,MAAa,0BAA0B;IAGrC,YAAY,SAAwC;QAClD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAmB;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACpE,OAAO,IAAI,iCAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;CACF;AAnBD,gEAmBC"}

package/dist/LimiterInterface.d.ts

@@ -0,0 +1,32 @@
+import type { RateLimit } from './RateLimit';
+import type { Reservation } from './Reservation';
+/**
+ * Main contract for all rate limiters.
+ *
+ * Provides two patterns for rate limiting:
+ * - reserve(): Reserve tokens and wait if necessary
+ * - consume(): Immediately try to consume tokens
+ */
+export interface LimiterInterface {
+    /**
+     * Reserve tokens with optional maximum wait time.
+     *
+     * @param tokens - Number of tokens to reserve
+     * @param maxTime - Maximum time to wait (in seconds), or null for no limit
+     * @returns A Reservation object
+     * @throws {MaxWaitDurationExceededError} If wait time exceeds maxTime
+     */
+    reserve(tokens: number, maxTime?: number | null): Promise<Reservation>;
+    /**
+     * Try to consume tokens immediately.
+     *
+     * @param tokens - Number of tokens to consume
+     * @returns A RateLimit object indicating success or failure
+     */
+    consume(tokens: number): Promise<RateLimit>;
+    /**
+     * Reset the rate limiter state.
+     */
+    reset(): Promise<void>;
+}
+//# sourceMappingURL=LimiterInterface.d.ts.map

package/dist/LimiterInterface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimiterInterface.d.ts","sourceRoot":"","sources":["../src/LimiterInterface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE5C;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/LimiterInterface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=LimiterInterface.js.map

package/dist/LimiterInterface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimiterInterface.js","sourceRoot":"","sources":["../src/LimiterInterface.ts"],"names":[],"mappings":""}

package/dist/LimiterStateInterface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Interface for serializable rate limiter state objects.
+ *
+ * State objects must be JSON-serializable and provide their own expiration time.
+ */
+export interface LimiterStateInterface {
+    /**
+     * Get the unique identifier for this state object.
+     */
+    getId(): string;
+    /**
+     * Get the expiration time (in seconds since epoch) or null if no expiration.
+     */
+    getExpirationTime(): number | null;
+}
+//# sourceMappingURL=LimiterStateInterface.d.ts.map

package/dist/LimiterStateInterface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimiterStateInterface.d.ts","sourceRoot":"","sources":["../src/LimiterStateInterface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,KAAK,IAAI,MAAM,CAAC;IAEhB;;OAEG;IACH,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAAC;CACpC"}

package/dist/LimiterStateInterface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=LimiterStateInterface.js.map

package/dist/LimiterStateInterface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimiterStateInterface.js","sourceRoot":"","sources":["../src/LimiterStateInterface.ts"],"names":[],"mappings":""}

package/dist/RateLimit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Result object from a rate limiting operation.
+ *
+ * Contains information about whether the request was accepted, how many tokens
+ * are remaining, and when the client should retry if rejected.
+ */
+export declare class RateLimit {
+    private readonly availableTokens;
+    private readonly retryAfter;
+    private readonly accepted;
+    private readonly limit;
+    constructor(availableTokens: number, retryAfter: Date, accepted: boolean, limit: number);
+    /**
+     * Check if the request was accepted.
+     */
+    isAccepted(): boolean;
+    /**
+     * Ensure the request was accepted, throw an exception otherwise.
+     *
+     * @throws {RateLimitExceededError} If the request was not accepted
+     */
+    ensureAccepted(): this;
+    /**
+     * Get the date/time when the client should retry.
+     */
+    getRetryAfter(): Date;
+    /**
+     * Get the number of remaining tokens.
+     */
+    getRemainingTokens(): number;
+    /**
+     * Get the rate limit maximum.
+     */
+    getLimit(): number;
+    /**
+     * Wait until the retry time (blocking operation).
+     *
+     * Note: This uses a blocking setTimeout. Consider using async/await patterns
+     * in production code instead.
+     */
+    wait(): Promise<void>;
+}
+//# sourceMappingURL=RateLimit.d.ts.map

package/dist/RateLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimit.d.ts","sourceRoot":"","sources":["../src/RateLimit.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAO;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAG7B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,IAAI,EAChB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM;IAQf;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,cAAc,IAAI,IAAI;IAOtB;;OAEG;IACH,aAAa,IAAI,IAAI;IAIrB;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ5B"}

package/dist/RateLimit.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimit = void 0;
+const RateLimitExceededError_1 = require("./errors/RateLimitExceededError");
+/**
+ * Result object from a rate limiting operation.
+ *
+ * Contains information about whether the request was accepted, how many tokens
+ * are remaining, and when the client should retry if rejected.
+ */
+class RateLimit {
+    constructor(availableTokens, retryAfter, accepted, limit) {
+        this.availableTokens = availableTokens;
+        this.retryAfter = retryAfter;
+        this.accepted = accepted;
+        this.limit = limit;
+    }
+    /**
+     * Check if the request was accepted.
+     */
+    isAccepted() {
+        return this.accepted;
+    }
+    /**
+     * Ensure the request was accepted, throw an exception otherwise.
+     *
+     * @throws {RateLimitExceededError} If the request was not accepted
+     */
+    ensureAccepted() {
+        if (!this.accepted) {
+            throw new RateLimitExceededError_1.RateLimitExceededError('Rate limit exceeded', this);
+        }
+        return this;
+    }
+    /**
+     * Get the date/time when the client should retry.
+     */
+    getRetryAfter() {
+        return this.retryAfter;
+    }
+    /**
+     * Get the number of remaining tokens.
+     */
+    getRemainingTokens() {
+        return this.availableTokens;
+    }
+    /**
+     * Get the rate limit maximum.
+     */
+    getLimit() {
+        return this.limit;
+    }
+    /**
+     * Wait until the retry time (blocking operation).
+     *
+     * Note: This uses a blocking setTimeout. Consider using async/await patterns
+     * in production code instead.
+     */
+    async wait() {
+        const now = Date.now();
+        const waitMs = this.retryAfter.getTime() - now;
+        if (waitMs > 0) {
+            await new Promise(resolve => setTimeout(resolve, waitMs));
+        }
+    }
+}
+exports.RateLimit = RateLimit;
+//# sourceMappingURL=RateLimit.js.map

package/dist/RateLimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimit.js","sourceRoot":"","sources":["../src/RateLimit.ts"],"names":[],"mappings":";;;AAAA,4EAAyE;AAEzE;;;;;GAKG;AACH,MAAa,SAAS;IAMpB,YACE,eAAuB,EACvB,UAAgB,EAChB,QAAiB,EACjB,KAAa;QAEb,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,+CAAsB,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC;QAE/C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;CACF;AAxED,8BAwEC"}

package/dist/RateLimiterFactory.d.ts

@@ -0,0 +1,83 @@
+import type { RateLimiterFactoryInterface } from './RateLimiterFactoryInterface';
+import type { LimiterInterface } from './LimiterInterface';
+import type { StorageInterface } from './storage/StorageInterface';
+import type { LockInterface } from './storage/LockInterface';
+/**
+ * Configuration for token bucket policy.
+ */
+export interface TokenBucketConfig {
+    policy: 'token_bucket';
+    id: string;
+    limit: number;
+    rate: {
+        interval: string;
+        amount: number;
+    };
+}
+/**
+ * Configuration for fixed window policy.
+ */
+export interface FixedWindowConfig {
+    policy: 'fixed_window';
+    id: string;
+    limit: number;
+    interval: string;
+}
+/**
+ * Configuration for sliding window policy.
+ */
+export interface SlidingWindowConfig {
+    policy: 'sliding_window';
+    id: string;
+    limit: number;
+    interval: string;
+}
+/**
+ * Configuration for no-limit policy.
+ */
+export interface NoLimitConfig {
+    policy: 'no_limit';
+    id: string;
+}
+/**
+ * Union type of all possible rate limiter configurations.
+ */
+export type RateLimiterConfig = TokenBucketConfig | FixedWindowConfig | SlidingWindowConfig | NoLimitConfig;
+/**
+ * Factory for creating rate limiter instances based on configuration.
+ *
+ * Supports multiple rate limiting algorithms:
+ * - token_bucket: Token bucket with configurable burst and refill rate
+ * - fixed_window: Fixed time windows with hit counting
+ * - sliding_window: Sliding window with weighted previous window
+ * - no_limit: No rate limiting (always accepts)
+ */
+export declare class RateLimiterFactory implements RateLimiterFactoryInterface {
+    private readonly config;
+    private readonly storage;
+    private readonly lock?;
+    constructor(config: RateLimiterConfig, storage: StorageInterface, lock?: LockInterface);
+    /**
+     * Create a rate limiter instance.
+     *
+     * @param key - Optional key to distinguish between different limiters (e.g., user ID)
+     */
+    create(key?: string | null): LimiterInterface;
+    /**
+     * Validate and normalize configuration.
+     */
+    private validateConfig;
+    /**
+     * Create a token bucket limiter.
+     */
+    private createTokenBucketLimiter;
+    /**
+     * Create a fixed window limiter.
+     */
+    private createFixedWindowLimiter;
+    /**
+     * Create a sliding window limiter.
+     */
+    private createSlidingWindowLimiter;
+}
+//# sourceMappingURL=RateLimiterFactory.d.ts.map