docs(RateLimiter): add JSDoc to RateLimiter class and rateLimit function

Author: rudra3007-pro

lib/rate-limit.ts

@@ -1,28 +1,48 @@
 import { TTLCache } from './cache';
 
-// In-memory rate limiter to prevent basic DoS/spam (Denial of Wallet).
-// Note: In a serverless environment, this resets per cold-start/instance,
-// but it is highly effective at stopping aggressive single-instance spikes.
-// For multi-instance strict syncing, a Redis store (Vercel KV/Upstash) should be used.
+/**
+ * In-memory rate limiter to prevent basic DoS/spam (Denial of Wallet).
+ *
+ * Note: In a serverless environment, this resets per cold-start/instance,
+ * but it is highly effective at stopping aggressive single-instance spikes.
+ * For multi-instance strict syncing, a Redis store (Vercel KV/Upstash) should be used.
+ */
 export class RateLimiter {
   private cache: TTLCache<number>;
   private limit: number;
   private windowMs: number;
 
+  /**
+   * Creates a new RateLimiter instance.
+   *
+   * @param limit - Maximum number of requests allowed per window. Defaults to 5.
+   * @param windowMs - Time window in milliseconds. Defaults to 60000 (1 minute).
+   */
   constructor(limit = 5, windowMs = 60000) {
     this.limit = limit;
     this.windowMs = windowMs;
-    // Set max capacity to 10000 IPs to prevent memory leaks from the rate limiter itself
     this.cache = new TTLCache<number>(10000, windowMs);
   }
 
-  // Returns true if allowed, false if rate limited
+  /**
+   * Checks whether a request from the given IP is allowed.
+   *
+   * Increments the request count for the IP and resets the TTL on each call,
+   * behaving similarly to a sliding window timeout.
+   *
+   * @param ip - The IP address to check.
+   * @returns `true` if the request is allowed, `false` if rate limited.
+   *
+   * @example
+   * if (!rateLimiter.check(ip)) {
+   *   return new Response("Too Many Requests", { status: 429 });
+   * }
+   */
   check(ip: string): boolean {
     const current = this.cache.get(ip) || 0;
     if (current >= this.limit) {
       return false;
     }
-    // We increment the count and reset the TTL, behaving similarly to a sliding window timeout.
     this.cache.set(ip, current + 1, this.windowMs);
     return true;
   }
@@ -47,6 +67,20 @@ interface RateLimitResult {
 
 const trackers = new TTLCache<{ count: number }>(2000, 60000);
 
+/**
+ * Checks if a request from a given IP should be rate limited.
+ *
+ * @param ip - The IP address to track.
+ * @param limit - Maximum number of requests allowed in the window. Defaults to 60.
+ * @param windowMs - Time window in milliseconds. Defaults to 60000 (1 minute).
+ * @returns A {@link RateLimitResult} containing success status, limit, remaining count, and reset time.
+ *
+ * @example
+ * const result = rateLimit(ip);
+ * if (!result.success) {
+ *   return new Response("Too Many Requests", { status: 429 });
+ * }
+ */
 export function rateLimit(
   ip: string,
   limit: number = 60,