io-ratelimiter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Devhuset
+
+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,292 @@
+# io-ratelimiter
+
+[![npm version](https://badge.fury.io/js/io-ratelimiter.svg)](https://badge.fury.io/js/io-ratelimiter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A flexible Redis-based rate limiting library supporting both fixed and sliding window algorithms. Works with **any Redis client** (ioredis, iovalkey, node-redis, Bun's native client, etc.).
+
+## Features
+
+- **Fixed window** rate limiting
+- **Sliding window** rate limiting with weighted scoring
+- Redis/Valkey-backed for distributed systems
+- Full TypeScript support
+- High performance Lua script execution (EVALSHA)
+- Protection against race conditions
+- **Client-agnostic** - bring your own Redis client
+- Zero runtime dependencies
+
+## Installation
+
+```bash
+bun add io-ratelimiter
+# or
+npm install io-ratelimiter
+# or
+yarn add io-ratelimiter
+# or
+pnpm add io-ratelimiter
+```
+
+You'll also need a Redis client:
+
+```bash
+# Choose one:
+npm install ioredis
+npm install iovalkey
+npm install redis  # node-redis
+```
+
+## Quick Start
+
+```typescript
+import { Ratelimit } from 'io-ratelimiter';
+import Redis from 'iovalkey'; // or 'ioredis' or 'redis'
+
+// Create any Redis client
+const client = new Redis('redis://localhost:6379');
+
+// Create rate limiter (10 requests per 60 seconds)
+const limiter = new Ratelimit(
+	client,
+	Ratelimit.slidingWindow({
+		limit: 10,
+		window: 60, // seconds
+		prefix: 'my-api', // optional
+	}),
+);
+
+// Check rate limit
+const result = await limiter.limit('user-123');
+if (result.success) {
+	// Process request
+	console.log(`${result.remaining} requests remaining`);
+} else {
+	// Rate limit exceeded
+	console.log(`Try again in ${result.retry_after}ms`);
+}
+```
+
+## Rate Limiting Algorithms
+
+### Fixed Window
+
+Divides time into fixed intervals (e.g., 60-second windows) and tracks requests within each window. Simple and fast.
+
+```typescript
+const limiter = new Ratelimit(
+	client,
+	Ratelimit.fixedWindow({
+		limit: 100,
+		window: 60,
+		prefix: 'api',
+	}),
+);
+```
+
+**Best for**: High-throughput scenarios where slight bursts are acceptable
+
+### Sliding Window
+
+Provides smoother rate limiting by considering both current and previous windows with weighted rates. More accurate but requires Lua script support.
+
+```typescript
+const limiter = new Ratelimit(
+	client,
+	Ratelimit.slidingWindow({
+		limit: 100,
+		window: 60,
+		prefix: 'api',
+	}),
+);
+```
+
+**Best for**: Preventing burst traffic, fair rate limiting
+
+**Note**: Requires `script()` and `evalsha()` support. Works with ioredis, iovalkey, and node-redis. Bun's native Redis client currently only supports fixed window.
+
+## Client Compatibility
+
+| Client                                            | Fixed Window | Sliding Window |
+| ------------------------------------------------- | ------------ | -------------- |
+| [ioredis](https://github.com/redis/ioredis)       | ✅           | ✅             |
+| [iovalkey](https://github.com/valkey-io/iovalkey) | ✅           | ✅             |
+| [node-redis](https://github.com/redis/node-redis) | ✅           | ✅             |
+| [Bun Redis](https://bun.sh/docs/runtime/redis)    | ✅           | ❌             |
+
+## API Reference
+
+### `Ratelimit` Class
+
+```typescript
+import { Ratelimit, type RedisClient, type RatelimitResponse } from 'io-ratelimiter';
+
+const limiter = new Ratelimit(client: RedisClient, options: RatelimitOptions);
+```
+
+### Configuration Options
+
+```typescript
+interface RatelimitOptionsWithoutType {
+	/** Maximum requests per window */
+	limit: number;
+	/** Window duration in seconds */
+	window: number;
+	/** Optional Redis key prefix */
+	prefix?: string;
+}
+
+// Factory methods
+Ratelimit.fixedWindow(options: RatelimitOptionsWithoutType)
+Ratelimit.slidingWindow(options: RatelimitOptionsWithoutType)
+```
+
+### Response Type
+
+```typescript
+interface RatelimitResponse {
+	/** Whether the request is allowed */
+	success: boolean;
+	/** Maximum number of requests allowed in the window */
+	limit: number;
+	/** Number of remaining requests in current window */
+	remaining: number;
+	/** Time in milliseconds until the next request will be allowed (0 if under limit) */
+	retry_after: number;
+	/** Time in milliseconds when the current window expires completely */
+	reset: number;
+}
+```
+
+### `limit()` Method
+
+```typescript
+await limiter.limit(identifier: string): Promise<RatelimitResponse>
+```
+
+The `identifier` is typically a user ID, IP address, or API key.
+
+## Framework Integration Examples
+
+### Next.js App Router
+
+```typescript
+import { Ratelimit } from 'io-ratelimiter';
+import { NextResponse } from 'next/server';
+import { headers } from 'next/headers';
+import Redis from 'iovalkey';
+
+const client = new Redis(process.env.REDIS_URL);
+const ratelimit = new Ratelimit(
+	client,
+	Ratelimit.slidingWindow({ limit: 10, window: 60 }),
+);
+
+export async function GET() {
+	const headersList = await headers();
+	const ip = headersList.get('x-forwarded-for') || '127.0.0.1';
+
+	const { success, remaining, reset, retry_after } =
+		await ratelimit.limit(ip);
+
+	if (!success) {
+		return NextResponse.json(
+			{ error: 'Too many requests' },
+			{
+				status: 429,
+				headers: {
+					'X-RateLimit-Limit': '10',
+					'X-RateLimit-Remaining': remaining.toString(),
+					'X-RateLimit-Reset': reset.toString(),
+					'Retry-After': Math.ceil(retry_after / 1000).toString(),
+				},
+			},
+		);
+	}
+
+	return NextResponse.json({ message: 'Success' });
+}
+```
+
+### Express Middleware
+
+```typescript
+import { Ratelimit } from 'io-ratelimiter';
+import express from 'express';
+import Redis from 'iovalkey';
+
+const app = express();
+const client = new Redis(process.env.REDIS_URL);
+const ratelimit = new Ratelimit(
+	client,
+	Ratelimit.slidingWindow({ limit: 100, window: 60 }),
+);
+
+app.use(async (req, res, next) => {
+	const { success, remaining, reset, retry_after } = await ratelimit.limit(
+		req.ip,
+	);
+
+	res.setHeader('X-RateLimit-Limit', '100');
+	res.setHeader('X-RateLimit-Remaining', remaining.toString());
+	res.setHeader('X-RateLimit-Reset', reset.toString());
+
+	if (!success) {
+		res.setHeader('Retry-After', Math.ceil(retry_after / 1000).toString());
+		return res.status(429).json({ error: 'Too many requests' });
+	}
+
+	next();
+});
+```
+
+### Hono
+
+```typescript
+import { Ratelimit } from 'io-ratelimiter';
+import { Hono } from 'hono';
+import Redis from 'iovalkey';
+
+const app = new Hono();
+const client = new Redis(process.env.REDIS_URL);
+const ratelimit = new Ratelimit(
+	client,
+	Ratelimit.fixedWindow({ limit: 50, window: 60 }),
+);
+
+app.use('*', async (c, next) => {
+	const ip = c.req.header('x-forwarded-for') || 'unknown';
+	const { success, remaining, reset, retry_after } =
+		await ratelimit.limit(ip);
+
+	c.header('X-RateLimit-Limit', '50');
+	c.header('X-RateLimit-Remaining', remaining.toString());
+
+	if (!success) {
+		return c.json({ error: 'Too many requests' }, 429);
+	}
+
+	await next();
+});
+```
+
+## Performance
+
+The sliding window algorithm uses `SCRIPT LOAD` + `EVALSHA` for optimal performance:
+
+- Script is loaded once on first use
+- Subsequent requests send only a 40-byte SHA hash instead of the full ~800-byte Lua script
+- Atomic operations prevent race conditions
+- Automatic retry on script loss (e.g., Redis restart)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
+
+## Credits
+
+Built by [Kasper](https://twitter.com/kasperaamodt)

package/dist/index.d.mts

@@ -0,0 +1,98 @@
+/**
+ * Thrown when rate limiter configuration is invalid
+ * @example
+ * ```ts
+ * throw new ConfigurationError('Limit must be greater than 0')
+ * ```
+ */
+declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when rate limit operations fail. Includes the original error if available
+ * @example
+ * ```ts
+ * throw new RatelimitError('Failed to check rate limit', originalError)
+ * ```
+ */
+declare class RatelimitError extends Error {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+
+/**
+ * Minimal Redis client interface required for rate limiting.
+ * Compatible with ioredis, iovalkey, node-redis, Bun's native Redis client, and other Redis clients.
+ *
+ * Note: For sliding window algorithm, `script` and `evalsha` are required.
+ * Bun's native Redis client currently doesn't support these, so use ioredis/iovalkey for sliding window.
+ */
+interface RedisClient {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    script?(...args: unknown[]): Promise<unknown>;
+    evalsha?(sha: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+    flushdb?(): Promise<unknown>;
+    close?(): void;
+    quit?(): Promise<unknown>;
+}
+
+/**
+ * Response from a rate limit check
+ */
+interface RatelimitResponse {
+    /** Whether the request should be allowed */
+    success: boolean;
+    /** Maximum number of requests allowed in the window */
+    limit: number;
+    /** Number of remaining requests in current window */
+    remaining: number;
+    /** Time in milliseconds until the next request will be allowed. 0 if under limit */
+    retry_after: number;
+    /** Time in milliseconds when the current window expires completely */
+    reset: number;
+}
+/**
+ * Base configuration options for both fixed and sliding window rate limiters
+ */
+interface RatelimitOptionsWithoutType {
+    /** Maximum number of requests allowed within the window */
+    limit: number;
+    /** Time window in seconds */
+    window: number;
+    /** Optional prefix for Valkey keys to prevent collisions */
+    prefix?: string;
+}
+/**
+ * Complete rate limiter configuration including window type
+ */
+interface RatelimitOptions extends RatelimitOptionsWithoutType {
+    /** Type of rate limiting window to use */
+    type: 'fixed' | 'sliding';
+}
+
+/**
+ * Redis-based rate limiter supporting both fixed and sliding window algorithms.
+ * Fixed window divides time into discrete chunks while sliding window
+ * provides smoother rate limiting using weighted scoring.
+ *
+ * Accepts any Redis-compatible client (ioredis, iovalkey, node-redis, etc.).
+ */
+declare class Ratelimit {
+    private readonly options;
+    private readonly time_provider;
+    private readonly client;
+    private scriptSha?;
+    constructor(client: RedisClient, options: RatelimitOptions, time_provider?: () => number);
+    static fixedWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
+    static slidingWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
+    limit(identifier: string): Promise<RatelimitResponse>;
+    private validateOptions;
+    private getKey;
+    private fixedWindowLimit;
+    private slidingWindowLimit;
+    private evalSlidingWindow;
+}
+
+export { ConfigurationError, Ratelimit, RatelimitError, type RatelimitOptions, type RatelimitOptionsWithoutType, type RatelimitResponse, type RedisClient };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Thrown when rate limiter configuration is invalid
+ * @example
+ * ```ts
+ * throw new ConfigurationError('Limit must be greater than 0')
+ * ```
+ */
+declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when rate limit operations fail. Includes the original error if available
+ * @example
+ * ```ts
+ * throw new RatelimitError('Failed to check rate limit', originalError)
+ * ```
+ */
+declare class RatelimitError extends Error {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+
+/**
+ * Minimal Redis client interface required for rate limiting.
+ * Compatible with ioredis, iovalkey, node-redis, Bun's native Redis client, and other Redis clients.
+ *
+ * Note: For sliding window algorithm, `script` and `evalsha` are required.
+ * Bun's native Redis client currently doesn't support these, so use ioredis/iovalkey for sliding window.
+ */
+interface RedisClient {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    script?(...args: unknown[]): Promise<unknown>;
+    evalsha?(sha: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+    flushdb?(): Promise<unknown>;
+    close?(): void;
+    quit?(): Promise<unknown>;
+}
+
+/**
+ * Response from a rate limit check
+ */
+interface RatelimitResponse {
+    /** Whether the request should be allowed */
+    success: boolean;
+    /** Maximum number of requests allowed in the window */
+    limit: number;
+    /** Number of remaining requests in current window */
+    remaining: number;
+    /** Time in milliseconds until the next request will be allowed. 0 if under limit */
+    retry_after: number;
+    /** Time in milliseconds when the current window expires completely */
+    reset: number;
+}
+/**
+ * Base configuration options for both fixed and sliding window rate limiters
+ */
+interface RatelimitOptionsWithoutType {
+    /** Maximum number of requests allowed within the window */
+    limit: number;
+    /** Time window in seconds */
+    window: number;
+    /** Optional prefix for Valkey keys to prevent collisions */
+    prefix?: string;
+}
+/**
+ * Complete rate limiter configuration including window type
+ */
+interface RatelimitOptions extends RatelimitOptionsWithoutType {
+    /** Type of rate limiting window to use */
+    type: 'fixed' | 'sliding';
+}
+
+/**
+ * Redis-based rate limiter supporting both fixed and sliding window algorithms.
+ * Fixed window divides time into discrete chunks while sliding window
+ * provides smoother rate limiting using weighted scoring.
+ *
+ * Accepts any Redis-compatible client (ioredis, iovalkey, node-redis, etc.).
+ */
+declare class Ratelimit {
+    private readonly options;
+    private readonly time_provider;
+    private readonly client;
+    private scriptSha?;
+    constructor(client: RedisClient, options: RatelimitOptions, time_provider?: () => number);
+    static fixedWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
+    static slidingWindow(params: RatelimitOptionsWithoutType): RatelimitOptions;
+    limit(identifier: string): Promise<RatelimitResponse>;
+    private validateOptions;
+    private getKey;
+    private fixedWindowLimit;
+    private slidingWindowLimit;
+    private evalSlidingWindow;
+}
+
+export { ConfigurationError, Ratelimit, RatelimitError, type RatelimitOptions, type RatelimitOptionsWithoutType, type RatelimitResponse, type RedisClient };

package/dist/index.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// src/errors.ts
+var ConfigurationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
+var RatelimitError = class extends Error {
+  constructor(message, originalError) {
+    super(message);
+    this.originalError = originalError;
+    this.name = "RatelimitError";
+    this.stack = new Error().stack;
+    this.message = message;
+    this.originalError = originalError;
+  }
+};
+
+// src/client.ts
+var SLIDING_WINDOW_SCRIPT = `
+local current_key = KEYS[1]
+local previous_key = KEYS[2]
+local tokens = tonumber(ARGV[1])
+local now = tonumber(ARGV[2])
+local window = tonumber(ARGV[3])
+local increment_by = tonumber(ARGV[4])
+
+local current_count = tonumber(redis.call("GET", current_key) or "0")
+local previous_count = tonumber(redis.call("GET", previous_key) or "0")
+
+local time_in_current = now % window
+local time_remaining_previous = window - time_in_current
+local weighted_previous = (previous_count * time_remaining_previous) / window
+local cumulative_count = math.floor(weighted_previous) + current_count + increment_by
+
+if cumulative_count > tokens then
+    local needed = cumulative_count - tokens + increment_by
+    local retry_after = window - time_in_current
+    
+    if previous_count > 0 then
+        local time_needed = (needed * window) / previous_count
+        retry_after = math.ceil(time_needed)
+        
+        if retry_after > time_remaining_previous then
+            retry_after = time_remaining_previous
+        end
+    end
+    
+    return { -1, retry_after }
+end
+
+current_count = current_count + increment_by
+redis.call("SET", current_key, current_count)
+redis.call("PEXPIRE", current_key, window * 2 + 1000)
+
+return { tokens - (math.floor(weighted_previous) + current_count), 0 }
+`;
+
+// src/ratelimit.ts
+var Ratelimit = class {
+  constructor(client, options, time_provider = Date.now) {
+    this.options = options;
+    this.time_provider = time_provider;
+    this.client = client;
+    this.validateOptions(options);
+  }
+  static fixedWindow(params) {
+    return { type: "fixed", ...params };
+  }
+  static slidingWindow(params) {
+    return { type: "sliding", ...params };
+  }
+  async limit(identifier) {
+    try {
+      return this.options.type === "fixed" ? await this.fixedWindowLimit(identifier) : await this.slidingWindowLimit(identifier);
+    } catch (error) {
+      if (error instanceof ConfigurationError) {
+        throw error;
+      }
+      throw new RatelimitError(
+        "Failed to check rate limit",
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  validateOptions(options) {
+    if (options.limit <= 0) {
+      throw new ConfigurationError("Limit must be greater than 0");
+    }
+    if (options.window <= 0) {
+      throw new ConfigurationError("Time window must be greater than 0");
+    }
+    if (options.type !== "fixed" && options.type !== "sliding") {
+      throw new ConfigurationError(
+        'Type must be either "fixed" or "sliding"'
+      );
+    }
+  }
+  getKey(identifier, suffix) {
+    const prefix = this.options.prefix || "ratelimit";
+    return `${prefix}:${identifier}:${suffix}`;
+  }
+  async fixedWindowLimit(identifier) {
+    const now = this.time_provider();
+    const window_size = this.options.window;
+    const current_window = Math.floor(now / (window_size * 1e3));
+    const window_key = this.getKey(identifier, current_window.toString());
+    const window_end = (current_window + 1) * (window_size * 1e3);
+    const count = await this.client.incr(window_key);
+    if (count === 1) {
+      await this.client.expire(window_key, window_size);
+    }
+    if (count > this.options.limit) {
+      const ttl = await this.client.ttl(window_key);
+      return {
+        success: false,
+        limit: this.options.limit,
+        remaining: 0,
+        retry_after: Math.max(ttl * 1e3, 0),
+        reset: window_end
+      };
+    }
+    return {
+      success: true,
+      limit: this.options.limit,
+      remaining: this.options.limit - count,
+      retry_after: 0,
+      reset: window_end
+    };
+  }
+  async slidingWindowLimit(identifier) {
+    const now = this.time_provider();
+    const window = this.options.window * 1e3;
+    const current_window = Math.floor(now / window);
+    const previous_window = current_window - 1;
+    const current_key = this.getKey(identifier, current_window.toString());
+    const previous_key = this.getKey(
+      identifier,
+      previous_window.toString()
+    );
+    const [remaining, retry_after] = await this.evalSlidingWindow(
+      current_key,
+      previous_key,
+      this.options.limit.toString(),
+      now.toString(),
+      window.toString(),
+      "1"
+    );
+    return {
+      success: remaining >= 0,
+      limit: this.options.limit,
+      remaining: Math.max(0, remaining),
+      retry_after,
+      reset: this.time_provider() + this.options.window * 2e3
+    };
+  }
+  async evalSlidingWindow(currentKey, previousKey, limit, now, window, increment) {
+    if (!this.client.script || !this.client.evalsha) {
+      throw new ConfigurationError(
+        "Sliding window algorithm requires a Redis client with script() and evalsha() support for Lua script execution. Please use a client like ioredis, iovalkey, or node-redis."
+      );
+    }
+    if (!this.scriptSha) {
+      this.scriptSha = await this.client.script(
+        "LOAD",
+        SLIDING_WINDOW_SCRIPT
+      );
+    }
+    try {
+      const result = await this.client.evalsha(
+        this.scriptSha,
+        2,
+        currentKey,
+        previousKey,
+        limit,
+        now,
+        window,
+        increment
+      );
+      return result;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("NOSCRIPT")) {
+        this.scriptSha = await this.client.script(
+          "LOAD",
+          SLIDING_WINDOW_SCRIPT
+        );
+        const result = await this.client.evalsha(
+          this.scriptSha,
+          2,
+          currentKey,
+          previousKey,
+          limit,
+          now,
+          window,
+          increment
+        );
+        return result;
+      }
+      throw error;
+    }
+  }
+};
+
+exports.ConfigurationError = ConfigurationError;
+exports.Ratelimit = Ratelimit;
+exports.RatelimitError = RatelimitError;

package/dist/index.mjs

@@ -0,0 +1,204 @@
+// src/errors.ts
+var ConfigurationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
+var RatelimitError = class extends Error {
+  constructor(message, originalError) {
+    super(message);
+    this.originalError = originalError;
+    this.name = "RatelimitError";
+    this.stack = new Error().stack;
+    this.message = message;
+    this.originalError = originalError;
+  }
+};
+
+// src/client.ts
+var SLIDING_WINDOW_SCRIPT = `
+local current_key = KEYS[1]
+local previous_key = KEYS[2]
+local tokens = tonumber(ARGV[1])
+local now = tonumber(ARGV[2])
+local window = tonumber(ARGV[3])
+local increment_by = tonumber(ARGV[4])
+
+local current_count = tonumber(redis.call("GET", current_key) or "0")
+local previous_count = tonumber(redis.call("GET", previous_key) or "0")
+
+local time_in_current = now % window
+local time_remaining_previous = window - time_in_current
+local weighted_previous = (previous_count * time_remaining_previous) / window
+local cumulative_count = math.floor(weighted_previous) + current_count + increment_by
+
+if cumulative_count > tokens then
+    local needed = cumulative_count - tokens + increment_by
+    local retry_after = window - time_in_current
+    
+    if previous_count > 0 then
+        local time_needed = (needed * window) / previous_count
+        retry_after = math.ceil(time_needed)
+        
+        if retry_after > time_remaining_previous then
+            retry_after = time_remaining_previous
+        end
+    end
+    
+    return { -1, retry_after }
+end
+
+current_count = current_count + increment_by
+redis.call("SET", current_key, current_count)
+redis.call("PEXPIRE", current_key, window * 2 + 1000)
+
+return { tokens - (math.floor(weighted_previous) + current_count), 0 }
+`;
+
+// src/ratelimit.ts
+var Ratelimit = class {
+  constructor(client, options, time_provider = Date.now) {
+    this.options = options;
+    this.time_provider = time_provider;
+    this.client = client;
+    this.validateOptions(options);
+  }
+  static fixedWindow(params) {
+    return { type: "fixed", ...params };
+  }
+  static slidingWindow(params) {
+    return { type: "sliding", ...params };
+  }
+  async limit(identifier) {
+    try {
+      return this.options.type === "fixed" ? await this.fixedWindowLimit(identifier) : await this.slidingWindowLimit(identifier);
+    } catch (error) {
+      if (error instanceof ConfigurationError) {
+        throw error;
+      }
+      throw new RatelimitError(
+        "Failed to check rate limit",
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  validateOptions(options) {
+    if (options.limit <= 0) {
+      throw new ConfigurationError("Limit must be greater than 0");
+    }
+    if (options.window <= 0) {
+      throw new ConfigurationError("Time window must be greater than 0");
+    }
+    if (options.type !== "fixed" && options.type !== "sliding") {
+      throw new ConfigurationError(
+        'Type must be either "fixed" or "sliding"'
+      );
+    }
+  }
+  getKey(identifier, suffix) {
+    const prefix = this.options.prefix || "ratelimit";
+    return `${prefix}:${identifier}:${suffix}`;
+  }
+  async fixedWindowLimit(identifier) {
+    const now = this.time_provider();
+    const window_size = this.options.window;
+    const current_window = Math.floor(now / (window_size * 1e3));
+    const window_key = this.getKey(identifier, current_window.toString());
+    const window_end = (current_window + 1) * (window_size * 1e3);
+    const count = await this.client.incr(window_key);
+    if (count === 1) {
+      await this.client.expire(window_key, window_size);
+    }
+    if (count > this.options.limit) {
+      const ttl = await this.client.ttl(window_key);
+      return {
+        success: false,
+        limit: this.options.limit,
+        remaining: 0,
+        retry_after: Math.max(ttl * 1e3, 0),
+        reset: window_end
+      };
+    }
+    return {
+      success: true,
+      limit: this.options.limit,
+      remaining: this.options.limit - count,
+      retry_after: 0,
+      reset: window_end
+    };
+  }
+  async slidingWindowLimit(identifier) {
+    const now = this.time_provider();
+    const window = this.options.window * 1e3;
+    const current_window = Math.floor(now / window);
+    const previous_window = current_window - 1;
+    const current_key = this.getKey(identifier, current_window.toString());
+    const previous_key = this.getKey(
+      identifier,
+      previous_window.toString()
+    );
+    const [remaining, retry_after] = await this.evalSlidingWindow(
+      current_key,
+      previous_key,
+      this.options.limit.toString(),
+      now.toString(),
+      window.toString(),
+      "1"
+    );
+    return {
+      success: remaining >= 0,
+      limit: this.options.limit,
+      remaining: Math.max(0, remaining),
+      retry_after,
+      reset: this.time_provider() + this.options.window * 2e3
+    };
+  }
+  async evalSlidingWindow(currentKey, previousKey, limit, now, window, increment) {
+    if (!this.client.script || !this.client.evalsha) {
+      throw new ConfigurationError(
+        "Sliding window algorithm requires a Redis client with script() and evalsha() support for Lua script execution. Please use a client like ioredis, iovalkey, or node-redis."
+      );
+    }
+    if (!this.scriptSha) {
+      this.scriptSha = await this.client.script(
+        "LOAD",
+        SLIDING_WINDOW_SCRIPT
+      );
+    }
+    try {
+      const result = await this.client.evalsha(
+        this.scriptSha,
+        2,
+        currentKey,
+        previousKey,
+        limit,
+        now,
+        window,
+        increment
+      );
+      return result;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("NOSCRIPT")) {
+        this.scriptSha = await this.client.script(
+          "LOAD",
+          SLIDING_WINDOW_SCRIPT
+        );
+        const result = await this.client.evalsha(
+          this.scriptSha,
+          2,
+          currentKey,
+          previousKey,
+          limit,
+          now,
+          window,
+          increment
+        );
+        return result;
+      }
+      throw error;
+    }
+  }
+};
+
+export { ConfigurationError, Ratelimit, RatelimitError };

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "io-ratelimiter",
+	"version": "1.0.0",
+	"author": "Devhuset",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kasperaamodt/io-ratelimiter.git"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"devDependencies": {
+		"@types/bun": "^1.3.5",
+		"@types/node": "^25.0.3",
+		"@typescript-eslint/eslint-plugin": "^8.50.1",
+		"@typescript-eslint/parser": "^8.50.1",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"iovalkey": "^0.3.1",
+		"prettier": "^3.7.4",
+		"tsup": "^8.5.1",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.50.1"
+	},
+	"peerDependencies": {},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.js",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"bugs": {
+		"url": "https://github.com/kasperaamodt/io-ratelimiter/issues"
+	},
+	"description": "A flexible rate limiting library with support for fixed and sliding windows using Redis/Valkey",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"homepage": "https://github.com/kasperaamodt/io-ratelimiter#readme",
+	"keywords": [
+		"rate-limit",
+		"valkey",
+		"redis",
+		"sliding-window",
+		"fixed-window",
+		"typescript",
+		"rate-limiting"
+	],
+	"license": "MIT",
+	"scripts": {
+		"build": "tsup",
+		"test": "bun test",
+		"lint": "eslint 'src/**/*.ts'",
+		"format": "prettier --write \"src/**/*.ts\""
+	},
+	"types": "./dist/index.d.ts"
+}