@diia-inhouse/redis 3.1.55 → 3.1.59

package/dist/interfaces/store.d.ts

@@ -18,11 +18,35 @@ interface SetValueOptions {
   */
   tags?: string[];
 }
+/**
+* Parsed reply of the `CL.THROTTLE` command.
+*
+* @see {@link https://www.dragonflydb.io/docs/command-reference/strings/cl.throttle | Dragonfly CL.THROTTLE}
+*/
 interface ThrottleResult {
+  /**
+  * Whether the action must be limited, i.e. the bucket had no room for the requested quantity.
+  */
   limited: boolean;
+  /**
+  * Total limit of the key, equals `maxBurst + 1`.
+  * Maps to the `X-RateLimit-Limit` header.
+  */
   totalLimit: number;
+  /**
+  * Remaining limit of the key.
+  * Maps to the `X-RateLimit-Remaining` header.
+  */
   remaining: number;
+  /**
+  * Number of seconds to wait before retrying if the action was limited, otherwise `-1`.
+  * Maps to the `Retry-After` header.
+  */
   retryAfterSec: number;
+  /**
+  * Number of seconds until the limit is fully restored.
+  * Maps to the `X-RateLimit-Reset` header.
+  */
   resetAfterSec: number;
 }
 type StoreStatusResult = {

package/dist/services/store.d.ts

@@ -38,6 +38,33 @@ declare class StoreService implements OnHealthCheck, OnDestroy {
   hdel(key: string, ...fields: string[]): Promise<number>;
   expire(key: string, seconds: number): Promise<number>;
   bumpTags(tags: string[]): Promise<"OK" | null>;
+  /**
+  * Applies a leaky bucket rate limit to the given key via the `CL.THROTTLE` command.
+  *
+  * The call is atomic: it consumes `quantity` tokens and reports the resulting bucket state in one round trip.
+  * Tokens are refilled continuously at `rate / periodSec`, so bursts are smoothed out
+  * and there are no edge cases at fixed-window boundaries.
+  *
+  * @param key - Identifier to rate limit against, e.g. a user id or an IP address.
+  * @param maxBurst - Extra tokens allowed on top of the steady rate, i.e. how large a burst may be.
+  * The bucket therefore holds `maxBurst + 1` tokens.
+  * @param rate - Number of tokens refilled per `periodSec`.
+  * @param periodSec - Length of the refill period in seconds.
+  * @param quantity - Number of tokens the call consumes.
+  * @returns Whether the action is limited plus the rate limit headers state.
+  *
+  * @example
+  * ```ts
+  * // 10 requests per minute, tolerating a burst of 5 extra requests
+  * const { limited, retryAfterSec } = await store.throttle(`login:${userId}`, 5, 10, 60)
+  * if (limited) {
+  *     res.setHeader('Retry-After', String(retryAfterSec))
+  *     res.writeHead(HttpStatusCode.TOO_MANY_REQUESTS)
+  * }
+  * ```
+  *
+  * @see {@link https://www.dragonflydb.io/docs/command-reference/strings/cl.throttle | Dragonfly CL.THROTTLE}
+  */
   throttle(key: string, maxBurst: number, rate: number, periodSec: number, quantity?: number): Promise<ThrottleResult>;
   flushDb(): Promise<"OK">;
   private validate;

package/dist/services/store.js

@@ -138,6 +138,33 @@ var StoreService = class {
 		for (const tagKey of tags) tagsConfig[tagKey] = timestamp;
 		return await this.clientRW.set(this.tagsKey, JSON.stringify(tagsConfig));
 	}
+	/**
+	* Applies a leaky bucket rate limit to the given key via the `CL.THROTTLE` command.
+	*
+	* The call is atomic: it consumes `quantity` tokens and reports the resulting bucket state in one round trip.
+	* Tokens are refilled continuously at `rate / periodSec`, so bursts are smoothed out
+	* and there are no edge cases at fixed-window boundaries.
+	*
+	* @param key - Identifier to rate limit against, e.g. a user id or an IP address.
+	* @param maxBurst - Extra tokens allowed on top of the steady rate, i.e. how large a burst may be.
+	* The bucket therefore holds `maxBurst + 1` tokens.
+	* @param rate - Number of tokens refilled per `periodSec`.
+	* @param periodSec - Length of the refill period in seconds.
+	* @param quantity - Number of tokens the call consumes.
+	* @returns Whether the action is limited plus the rate limit headers state.
+	*
+	* @example
+	* ```ts
+	* // 10 requests per minute, tolerating a burst of 5 extra requests
+	* const { limited, retryAfterSec } = await store.throttle(`login:${userId}`, 5, 10, 60)
+	* if (limited) {
+	*     res.setHeader('Retry-After', String(retryAfterSec))
+	*     res.writeHead(HttpStatusCode.TOO_MANY_REQUESTS)
+	* }
+	* ```
+	*
+	* @see {@link https://www.dragonflydb.io/docs/command-reference/strings/cl.throttle | Dragonfly CL.THROTTLE}
+	*/
 	async throttle(key, maxBurst, rate, periodSec, quantity = 1) {
 		const result = await this.clientRW.call("CL.THROTTLE", key, maxBurst, rate, periodSec, quantity);
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@diia-inhouse/redis",
-    "version": "3.1.55",
+    "version": "3.1.59",
     "type": "module",
     "description": "Redis services - redlock, pubsub, cache and store",
     "main": "dist/index.js",
@@ -47,14 +47,14 @@
         "@diia-inhouse/validators": ">=2.0.0"
     },
     "devDependencies": {
-        "@diia-inhouse/configs": "7.0.1",
-        "@diia-inhouse/diia-logger": "4.4.41",
-        "@diia-inhouse/env": "3.3.44",
-        "@diia-inhouse/errors": "2.2.16",
-        "@diia-inhouse/oxc-config": "2.1.1",
-        "@diia-inhouse/test": "8.3.2",
-        "@diia-inhouse/types": "14.2.3",
-        "@diia-inhouse/validators": "2.2.57",
+        "@diia-inhouse/configs": "7.1.0",
+        "@diia-inhouse/diia-logger": "4.4.49",
+        "@diia-inhouse/env": "3.3.48",
+        "@diia-inhouse/errors": "2.2.18",
+        "@diia-inhouse/oxc-config": "2.1.3",
+        "@diia-inhouse/test": "8.3.5",
+        "@diia-inhouse/types": "14.2.6",
+        "@diia-inhouse/validators": "2.2.61",
         "@types/node": "25.6.2",
         "@vitest/coverage-v8": "4.1.5",
         "@vitest/ui": "4.1.5",