@periodic/titanium 1.0.0

package/dist/adapters/express.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rateLimit = rateLimit;
+exports.createRateLimiter = createRateLimiter;
+const limiter_1 = require("../core/limiter");
+const ip_1 = require("../utils/ip");
+/**
+ * Express rate limiting middleware factory
+ *
+ * Features:
+ * - Framework-agnostic core with Express adapter
+ * - Configurable identifier extraction (user ID, API key, IP, etc.)
+ * - Fail-open or fail-closed strategies
+ * - Standard HTTP rate limit headers
+ * - Skip function for conditional rate limiting
+ *
+ * @param options - Express rate limit configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import { rateLimit } from '@periodic/titanium';
+ *
+ * const redis = createClient();
+ * await redis.connect();
+ *
+ * // Basic usage with IP-based rate limiting
+ * app.use(rateLimit({
+ *   redis,
+ *   limit: 100,
+ *   window: 60,
+ *   keyPrefix: 'api'
+ * }));
+ *
+ * // User-based rate limiting with JWT
+ * app.post('/api/resource',
+ *   authMiddleware,
+ *   rateLimit({
+ *     redis,
+ *     limit: 10,
+ *     window: 60,
+ *     keyPrefix: 'create-resource',
+ *     identifier: (req) => req.user?.id?.toString() || null
+ *   }),
+ *   handler
+ * );
+ * ```
+ */
+function rateLimit(options) {
+    // Validate required options
+    if (!options.redis) {
+        throw new Error("Redis client is required");
+    }
+    if (!options.limit || options.limit <= 0) {
+        throw new Error("Limit must be a positive number");
+    }
+    if (!options.window || options.window <= 0) {
+        throw new Error("Window must be a positive number");
+    }
+    if (!options.keyPrefix || options.keyPrefix.trim() === "") {
+        throw new Error("Key prefix is required");
+    }
+    // Extract options with defaults
+    const { redis, limit, window, keyPrefix, algorithm = "fixed-window", identifier, message = "Too many requests. Please try again later.", skip, failStrategy = "open", standardHeaders = true, logger, } = options;
+    // Create logger instance
+    const log = {
+        info: logger?.info || console.log,
+        warn: logger?.warn || console.warn,
+        error: logger?.error || console.error,
+    };
+    // Create core rate limiter
+    const limiter = new limiter_1.RateLimiter({
+        redis,
+        limit,
+        window,
+        keyPrefix,
+        algorithm,
+        logger: log,
+    });
+    // Return Express middleware
+    return async (req, res, next) => {
+        try {
+            // Check if rate limiting should be skipped
+            if (skip && skip(req)) {
+                return next();
+            }
+            // Extract identifier
+            let clientIdentifier;
+            if (identifier) {
+                const customId = identifier(req);
+                clientIdentifier = customId || (0, ip_1.getDefaultIdentifier)(req);
+            }
+            else {
+                clientIdentifier = (0, ip_1.getDefaultIdentifier)(req);
+            }
+            // Attempt rate limiting
+            let result;
+            try {
+                result = await limiter.limit(clientIdentifier);
+            }
+            catch (error) {
+                // Redis error - apply fail strategy
+                log.error?.("Rate limiter error:", error);
+                if (failStrategy === "closed") {
+                    log.warn?.("Redis unavailable with fail-closed strategy - blocking request");
+                    res.status(503).json({
+                        error: "Service temporarily unavailable. Please try again later.",
+                    });
+                    return;
+                }
+                // Fail-open strategy
+                log.warn?.("Redis unavailable with fail-open strategy - allowing request");
+                return next();
+            }
+            // Set standard headers if enabled
+            if (standardHeaders) {
+                setRateLimitHeaders(res, {
+                    limit: result.limit,
+                    remaining: result.remaining,
+                    reset: result.reset,
+                    retryAfter: result.allowed ? undefined : result.ttl,
+                });
+            }
+            // Check if request is allowed
+            if (!result.allowed) {
+                log.warn?.(`Rate limit exceeded for identifier: ${clientIdentifier} (${keyPrefix})`);
+                res.status(429).json({
+                    error: message,
+                    retryAfter: result.ttl,
+                    limit: result.limit,
+                    remaining: result.remaining,
+                    reset: result.reset,
+                });
+                return;
+            }
+            // Log warning when approaching limit (80% threshold)
+            if (result.remaining < result.limit * 0.2) {
+                log.info?.(`Rate limit warning for identifier: ${clientIdentifier} (${keyPrefix}) - ${result.remaining} remaining`);
+            }
+            next();
+        }
+        catch (error) {
+            // Unexpected error - apply fail strategy
+            log.error?.("Unexpected rate limit middleware error:", error);
+            if (failStrategy === "closed") {
+                res.status(503).json({
+                    error: "Service temporarily unavailable. Please try again later.",
+                });
+                return;
+            }
+            // Fail-open
+            log.warn?.("Allowing request due to unexpected error (fail-open mode)");
+            next();
+        }
+    };
+}
+/**
+ * Set standard rate limit headers on response
+ */
+function setRateLimitHeaders(res, info) {
+    res.setHeader("X-RateLimit-Limit", info.limit.toString());
+    res.setHeader("X-RateLimit-Remaining", info.remaining.toString());
+    res.setHeader("X-RateLimit-Reset", info.reset.toString());
+    if (info.retryAfter !== undefined) {
+        res.setHeader("Retry-After", info.retryAfter.toString());
+    }
+}
+/**
+ * Create a rate limiter instance for manual control
+ * Useful for custom implementations or non-Express frameworks
+ *
+ * @param options - Rate limiter configuration
+ * @returns RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({
+ *   redis,
+ *   limit: 100,
+ *   window: 60,
+ *   keyPrefix: 'api'
+ * });
+ *
+ * const result = await limiter.limit('user-123');
+ * if (!result.allowed) {
+ *   // Handle rate limit exceeded
+ * }
+ * ```
+ */
+function createRateLimiter(options) {
+    return new limiter_1.RateLimiter(options);
+}
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":";;AAgDA,8BAkJC;AAqCD,8CAOC;AA7OD,6CAA8C;AAE9C,oCAAmD;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,SAAgB,SAAS,CAAC,OAAgC;IACxD,4BAA4B;IAC5B,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,gCAAgC;IAChC,MAAM,EACJ,KAAK,EACL,KAAK,EACL,MAAM,EACN,SAAS,EACT,SAAS,GAAG,cAAc,EAC1B,UAAU,EACV,OAAO,GAAG,4CAA4C,EACtD,IAAI,EACJ,YAAY,GAAG,MAAM,EACrB,eAAe,GAAG,IAAI,EACtB,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,yBAAyB;IACzB,MAAM,GAAG,GAAW;QAClB,IAAI,EAAE,MAAM,EAAE,IAAI,IAAI,OAAO,CAAC,GAAG;QACjC,IAAI,EAAE,MAAM,EAAE,IAAI,IAAI,OAAO,CAAC,IAAI;QAClC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,OAAO,CAAC,KAAK;KACtC,CAAC;IAEF,2BAA2B;IAC3B,MAAM,OAAO,GAAG,IAAI,qBAAW,CAAC;QAC9B,KAAK;QACL,KAAK;QACL,MAAM;QACN,SAAS;QACT,SAAS;QACT,MAAM,EAAE,GAAG;KACZ,CAAC,CAAC;IAEH,4BAA4B;IAC5B,OAAO,KAAK,EACV,GAAY,EACZ,GAAa,EACb,IAAkB,EACH,EAAE;QACjB,IAAI,CAAC;YACH,2CAA2C;YAC3C,IAAI,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YAED,qBAAqB;YACrB,IAAI,gBAAwB,CAAC;YAC7B,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;gBACjC,gBAAgB,GAAG,QAAQ,IAAI,IAAA,yBAAoB,EAAC,GAAG,CAAC,CAAC;YAC3D,CAAC;iBAAM,CAAC;gBACN,gBAAgB,GAAG,IAAA,yBAAoB,EAAC,GAAG,CAAC,CAAC;YAC/C,CAAC;YAED,wBAAwB;YACxB,IAAI,MAAM,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,oCAAoC;gBACpC,GAAG,CAAC,KAAK,EAAE,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC;gBAE1C,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;oBAC9B,GAAG,CAAC,IAAI,EAAE,CACR,gEAAgE,CACjE,CAAC;oBACF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACnB,KAAK,EAAE,0DAA0D;qBAClE,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBAED,qBAAqB;gBACrB,GAAG,CAAC,IAAI,EAAE,CACR,8DAA8D,CAC/D,CAAC;gBACF,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YAED,kCAAkC;YAClC,IAAI,eAAe,EAAE,CAAC;gBACpB,mBAAmB,CAAC,GAAG,EAAE;oBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG;iBACpD,CAAC,CAAC;YACL,CAAC;YAED,8BAA8B;YAC9B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,GAAG,CAAC,IAAI,EAAE,CACR,uCAAuC,gBAAgB,KAAK,SAAS,GAAG,CACzE,CAAC;gBAEF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACnB,KAAK,EAAE,OAAO;oBACd,UAAU,EAAE,MAAM,CAAC,GAAG;oBACtB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,qDAAqD;YACrD,IAAI,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC;gBAC1C,GAAG,CAAC,IAAI,EAAE,CACR,sCAAsC,gBAAgB,KAAK,SAAS,OAAO,MAAM,CAAC,SAAS,YAAY,CACxG,CAAC;YACJ,CAAC;YAED,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,yCAAyC;YACzC,GAAG,CAAC,KAAK,EAAE,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;YAE9D,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;gBAC9B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBACnB,KAAK,EAAE,0DAA0D;iBAClE,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,YAAY;YACZ,GAAG,CAAC,IAAI,EAAE,CAAC,2DAA2D,CAAC,CAAC;YACxE,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,GAAa,EAAE,IAAmB;IAC7D,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1D,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClE,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE1D,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,iBAAiB,CAC/B,OAGC;IAED,OAAO,IAAI,qBAAW,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/dist/core/limiter.d.ts

@@ -0,0 +1,64 @@
+import { RateLimiterConfig, RateLimitResult } from "./types";
+/**
+ * Core rate limiter implementation
+ * Framework-agnostic, pure Redis-based rate limiting
+ */
+export declare class RateLimiter {
+    private redis;
+    private requestLimit;
+    private window;
+    private keyPrefix;
+    private algorithm;
+    private logger;
+    constructor(config: RateLimiterConfig);
+    /**
+     * Validate configuration options
+     */
+    private validateConfig;
+    /**
+     * Create logger with fallback to console
+     */
+    private createLogger;
+    /**
+     * Build Redis key for the identifier
+     */
+    private buildKey;
+    /**
+     * Check if Redis client is available
+     */
+    private isRedisAvailable;
+    /**
+     * Attempt to consume a request for the given identifier
+     * Returns rate limit information
+     *
+     * @param identifier - Unique identifier for the client (user ID, IP, API key, etc.)
+     * @returns Promise resolving to rate limit result
+     *
+     * @throws Error if Redis operations fail (caller should handle)
+     */
+    limit(identifier: string): Promise<RateLimitResult>;
+    /**
+     * Fixed window rate limiting implementation
+     * Uses true fixed window semantics with SET NX EX
+     */
+    private fixedWindowLimit;
+    /**
+     * Reset rate limit for a specific identifier
+     * Useful for testing or manual intervention
+     *
+     * @param identifier - Unique identifier to reset
+     * @returns Promise resolving to true if key was deleted, false otherwise
+     */
+    reset(identifier: string): Promise<boolean>;
+    /**
+     * Get current rate limit status for an identifier
+     *
+     * @param identifier - Unique identifier to check
+     * @returns Promise resolving to current count and TTL, or null if no limit exists
+     */
+    getStatus(identifier: string): Promise<{
+        current: number;
+        ttl: number;
+    } | null>;
+}
+//# sourceMappingURL=limiter.d.ts.map

package/dist/core/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/core/limiter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAqB,MAAM,SAAS,CAAC;AAEhF;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,iBAAiB;IAWrC;;OAEG;IACH,OAAO,CAAC,cAAc;IAkBtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;;;;;OAQG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAkBzD;;;OAGG;YACW,gBAAgB;IAkC9B;;;;;;OAMG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBjD;;;;;OAKG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA6BpD"}

package/dist/core/limiter.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+/**
+ * Core rate limiter implementation
+ * Framework-agnostic, pure Redis-based rate limiting
+ */
+class RateLimiter {
+    constructor(config) {
+        this.validateConfig(config);
+        this.redis = config.redis;
+        this.requestLimit = config.limit;
+        this.window = config.window;
+        this.keyPrefix = config.keyPrefix;
+        this.algorithm = config.algorithm || "fixed-window";
+        this.logger = this.createLogger(config.logger);
+    }
+    /**
+     * Validate configuration options
+     */
+    validateConfig(config) {
+        if (!config.redis) {
+            throw new Error("Redis client is required");
+        }
+        if (!config.limit || config.limit <= 0) {
+            throw new Error("Limit must be a positive number");
+        }
+        if (!config.window || config.window <= 0) {
+            throw new Error("Window must be a positive number (in seconds)");
+        }
+        if (!config.keyPrefix || config.keyPrefix.trim() === "") {
+            throw new Error("Key prefix is required");
+        }
+    }
+    /**
+     * Create logger with fallback to console
+     */
+    createLogger(customLogger) {
+        return {
+            info: customLogger?.info || console.log,
+            warn: customLogger?.warn || console.warn,
+            error: customLogger?.error || console.error,
+        };
+    }
+    /**
+     * Build Redis key for the identifier
+     */
+    buildKey(identifier) {
+        return `ratelimit:${this.keyPrefix}:${identifier}`;
+    }
+    /**
+     * Check if Redis client is available
+     */
+    isRedisAvailable() {
+        return this.redis.isOpen && this.redis.isReady;
+    }
+    /**
+     * Attempt to consume a request for the given identifier
+     * Returns rate limit information
+     *
+     * @param identifier - Unique identifier for the client (user ID, IP, API key, etc.)
+     * @returns Promise resolving to rate limit result
+     *
+     * @throws Error if Redis operations fail (caller should handle)
+     */
+    async limit(identifier) {
+        if (!identifier || identifier.trim() === "") {
+            throw new Error("Identifier cannot be empty");
+        }
+        if (!this.isRedisAvailable()) {
+            throw new Error("Redis client is not available");
+        }
+        const key = this.buildKey(identifier);
+        if (this.algorithm === "fixed-window") {
+            return this.fixedWindowLimit(key);
+        }
+        throw new Error(`Unsupported algorithm: ${this.algorithm}`);
+    }
+    /**
+     * Fixed window rate limiting implementation
+     * Uses true fixed window semantics with SET NX EX
+     */
+    async fixedWindowLimit(key) {
+        const now = Date.now();
+        // Try to initialize the window if it doesn't exist
+        // SET key 0 EX window NX - Only set if key doesn't exist
+        const initialized = await this.redis.set(key, "0", {
+            EX: this.window,
+            NX: true,
+        });
+        // Atomically increment the counter
+        const currentCount = await this.redis.incr(key);
+        // Get TTL to calculate reset time
+        const ttl = await this.redis.ttl(key);
+        // Calculate reset timestamp
+        const resetTime = ttl > 0 ? now + ttl * 1000 : now + this.window * 1000;
+        const remaining = Math.max(0, this.requestLimit - currentCount);
+        const allowed = currentCount <= this.requestLimit;
+        this.logger.info?.(`Rate limit check: identifier=${key}, count=${currentCount}/${this.requestLimit}, allowed=${allowed}`);
+        return {
+            allowed,
+            limit: this.requestLimit,
+            remaining,
+            reset: Math.ceil(resetTime / 1000),
+            ttl: ttl > 0 ? ttl : this.window,
+        };
+    }
+    /**
+     * Reset rate limit for a specific identifier
+     * Useful for testing or manual intervention
+     *
+     * @param identifier - Unique identifier to reset
+     * @returns Promise resolving to true if key was deleted, false otherwise
+     */
+    async reset(identifier) {
+        if (!identifier || identifier.trim() === "") {
+            throw new Error("Identifier cannot be empty");
+        }
+        if (!this.isRedisAvailable()) {
+            throw new Error("Redis client is not available");
+        }
+        const key = this.buildKey(identifier);
+        const result = await this.redis.del(key);
+        this.logger.info?.(`Rate limit reset for: ${key}`);
+        return result > 0;
+    }
+    /**
+     * Get current rate limit status for an identifier
+     *
+     * @param identifier - Unique identifier to check
+     * @returns Promise resolving to current count and TTL, or null if no limit exists
+     */
+    async getStatus(identifier) {
+        if (!identifier || identifier.trim() === "") {
+            throw new Error("Identifier cannot be empty");
+        }
+        if (!this.isRedisAvailable()) {
+            throw new Error("Redis client is not available");
+        }
+        const key = this.buildKey(identifier);
+        // Use pipeline for atomic read
+        const pipeline = this.redis.multi();
+        pipeline.get(key);
+        pipeline.ttl(key);
+        const results = await pipeline.exec();
+        const currentValue = results?.[0];
+        const ttl = results?.[1] || -1;
+        if (!currentValue || ttl < 0) {
+            return null;
+        }
+        const current = parseInt(currentValue, 10);
+        return { current, ttl };
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=limiter.js.map

package/dist/core/limiter.js.map

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

package/dist/core/types.d.ts

@@ -0,0 +1,145 @@
+import { RedisClientType } from "redis";
+import { Request } from "express";
+/**
+ * Rate limiting algorithm types
+ * Currently only fixed-window is implemented
+ */
+export type Algorithm = "fixed-window";
+/**
+ * Strategy for handling failures when Redis is unavailable
+ * - 'open': Allow requests through (recommended for availability)
+ * - 'closed': Block all requests (recommended for strict security)
+ */
+export type FailStrategy = "open" | "closed";
+/**
+ * Logger interface for optional logging
+ * If not provided, console will be used as fallback
+ */
+export interface Logger {
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+}
+/**
+ * Result returned by the core rate limiter
+ */
+export interface RateLimitResult {
+    /**
+     * Whether the request should be allowed
+     */
+    allowed: boolean;
+    /**
+     * Maximum number of requests allowed in the window
+     */
+    limit: number;
+    /**
+     * Number of requests remaining in current window
+     */
+    remaining: number;
+    /**
+     * Timestamp (in seconds) when the rate limit resets
+     */
+    reset: number;
+    /**
+     * Time to live in seconds for the current window
+     */
+    ttl: number;
+}
+/**
+ * Core rate limiter configuration
+ */
+export interface RateLimiterConfig {
+    /**
+     * Redis client instance (must be connected)
+     */
+    redis: RedisClientType;
+    /**
+     * Maximum number of requests allowed in the time window
+     */
+    limit: number;
+    /**
+     * Time window in seconds
+     */
+    window: number;
+    /**
+     * Prefix for Redis keys (useful for different route groups)
+     */
+    keyPrefix: string;
+    /**
+     * Rate limiting algorithm
+     * @default 'fixed-window'
+     */
+    algorithm?: Algorithm;
+    /**
+     * Optional logger instance
+     * If not provided, falls back to console
+     */
+    logger?: Logger;
+}
+/**
+ * Express middleware configuration
+ */
+export interface ExpressRateLimitOptions extends RateLimiterConfig {
+    /**
+     * Custom function to extract identifier from request
+     * If not provided, uses IP address from request
+     *
+     * @param req - Express request object
+     * @returns Unique identifier for the client, or null to use IP
+     *
+     * @example
+     * // Use user ID from JWT token
+     * identifier: (req) => req.user?.id?.toString() || null
+     *
+     * @example
+     * // Use API key from headers
+     * identifier: (req) => req.headers['x-api-key'] as string || null
+     */
+    identifier?: (req: Request) => string | null;
+    /**
+     * Custom error message when rate limit is exceeded
+     * @default 'Too many requests. Please try again later.'
+     */
+    message?: string;
+    /**
+     * Function to skip rate limiting for certain requests
+     *
+     * @param req - Express request object
+     * @returns true to skip rate limiting, false to apply it
+     *
+     * @example
+     * // Skip rate limiting for admin users
+     * skip: (req) => req.user?.isAdmin === true
+     *
+     * @example
+     * // Skip rate limiting for internal IPs
+     * skip: (req) => req.ip?.startsWith('192.168.')
+     */
+    skip?: (req: Request) => boolean;
+    /**
+     * Strategy for handling Redis failures
+     * - 'open': Allow requests when Redis is down (recommended)
+     * - 'closed': Block requests when Redis is down
+     * @default 'open'
+     */
+    failStrategy?: FailStrategy;
+    /**
+     * Whether to include standard rate limit headers in responses
+     * - X-RateLimit-Limit
+     * - X-RateLimit-Remaining
+     * - X-RateLimit-Reset
+     * - Retry-After (when limit exceeded)
+     * @default true
+     */
+    standardHeaders?: boolean;
+}
+/**
+ * Internal rate limit information for header setting
+ */
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+    retryAfter?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;IAEvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAEjC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/core/types.js

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

package/dist/core/types.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @periodic/titanium
+ *
+ * Production-ready Redis-backed rate limiting middleware for Express
+ * with TypeScript support, fail-safe design, and flexible configuration.
+ *
+ * @packageDocumentation
+ */
+export { rateLimit, createRateLimiter } from "./adapters/express";
+export { RateLimiter } from "./core/limiter";
+export type { Algorithm, FailStrategy, Logger, RateLimitResult, RateLimiterConfig, ExpressRateLimitOptions, RateLimitInfo, } from "./core/types";
+export { extractClientIp, normalizeIp, getDefaultIdentifier } from "./utils/ip";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGlE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,YAAY,EACV,SAAS,EACT,YAAY,EACZ,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * @periodic/titanium
+ *
+ * Production-ready Redis-backed rate limiting middleware for Express
+ * with TypeScript support, fail-safe design, and flexible configuration.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultIdentifier = exports.normalizeIp = exports.extractClientIp = exports.RateLimiter = exports.createRateLimiter = exports.rateLimit = void 0;
+// Export Express middleware
+var express_1 = require("./adapters/express");
+Object.defineProperty(exports, "rateLimit", { enumerable: true, get: function () { return express_1.rateLimit; } });
+Object.defineProperty(exports, "createRateLimiter", { enumerable: true, get: function () { return express_1.createRateLimiter; } });
+// Export core components for advanced usage
+var limiter_1 = require("./core/limiter");
+Object.defineProperty(exports, "RateLimiter", { enumerable: true, get: function () { return limiter_1.RateLimiter; } });
+// Export utilities
+var ip_1 = require("./utils/ip");
+Object.defineProperty(exports, "extractClientIp", { enumerable: true, get: function () { return ip_1.extractClientIp; } });
+Object.defineProperty(exports, "normalizeIp", { enumerable: true, get: function () { return ip_1.normalizeIp; } });
+Object.defineProperty(exports, "getDefaultIdentifier", { enumerable: true, get: function () { return ip_1.getDefaultIdentifier; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,4BAA4B;AAC5B,8CAAkE;AAAzD,oGAAA,SAAS,OAAA;AAAE,4GAAA,iBAAiB,OAAA;AAErC,4CAA4C;AAC5C,0CAA6C;AAApC,sGAAA,WAAW,OAAA;AAapB,mBAAmB;AACnB,iCAAgF;AAAvE,qGAAA,eAAe,OAAA;AAAE,iGAAA,WAAW,OAAA;AAAE,0GAAA,oBAAoB,OAAA"}

package/dist/utils/ip.d.ts

@@ -0,0 +1,31 @@
+import { Request } from "express";
+/**
+ * Extract client IP address from Express request
+ * Handles various proxy and load balancer scenarios
+ *
+ * Priority:
+ * 1. X-Forwarded-For header (first IP if multiple)
+ * 2. X-Real-IP header
+ * 3. Socket remote address
+ * 4. 'unknown' as fallback
+ *
+ * @param req - Express request object
+ * @returns IP address string
+ */
+export declare function extractClientIp(req: Request): string;
+/**
+ * Normalize IP address for consistent key generation
+ * Handles IPv6 to IPv4 mapping
+ *
+ * @param ip - IP address string
+ * @returns Normalized IP address
+ */
+export declare function normalizeIp(ip: string): string;
+/**
+ * Extract and normalize client identifier from request
+ *
+ * @param req - Express request object
+ * @returns Normalized IP address
+ */
+export declare function getDefaultIdentifier(req: Request): string;
+//# sourceMappingURL=ip.d.ts.map

package/dist/utils/ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip.d.ts","sourceRoot":"","sources":["../../src/utils/ip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CA0BpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAGzD"}