feat(guard): Add support for throwing throttling exceptions

src/throttler.guard.interface.ts

@@ -0,0 +1,26 @@
+import { ThrottlerStorageRecord } from './throttler-storage-record.interface';
+
+/**
+ * Interface describing the details of a rate limit applied by the ThrottlerGuard.
+ */
+export interface ThrottlerLimitDetail extends ThrottlerStorageRecord {
+  /**
+   * Time to live for the rate limit, in seconds. After this time has elapsed, the rate limit is removed.
+   */
+  ttl: number;
+
+  /**
+   * Maximum number of requests allowed within the time period defined by `ttl`.
+   */
+  limit: number;
+
+  /**
+   * Unique identifier for the rate limit. This field is used to group requests that share the same rate limit.
+   */
+  key: string;
+
+  /**
+   * A string representation of the tracker object used to keep track of the incoming requests and apply the rate limit.
+   */
+  tracker: string;
+}

src/throttler.guard.ts

@@ -6,6 +6,7 @@ import { ThrottlerStorage } from './throttler-storage.interface';
 import { THROTTLER_LIMIT, THROTTLER_SKIP, THROTTLER_TTL } from './throttler.constants';
 import { InjectThrottlerOptions, InjectThrottlerStorage } from './throttler.decorator';
 import { ThrottlerException, throttlerMessage } from './throttler.exception';
+import { ThrottlerLimitDetail } from './throttler.guard.interface';
 
 /**
  * @publicApi
@@ -82,7 +83,14 @@ export class ThrottlerGuard implements CanActivate {
     // Throw an error when the user reached their limit.
     if (totalHits > limit) {
       res.header('Retry-After', timeToExpire);
-      this.throwThrottlingException(context);
+      this.throwThrottlingException(context, {
+        limit,
+        ttl,
+        key,
+        tracker,
+        totalHits,
+        timeToExpire,
+      });
     }
 
     res.header(`${this.headerPrefix}-Limit`, limit);
@@ -123,7 +131,10 @@ export class ThrottlerGuard implements CanActivate {
    * @throws {ThrottlerException}
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  protected throwThrottlingException(context: ExecutionContext): void {
+  protected throwThrottlingException(
+    context: ExecutionContext,
+    throttlerLimitDetail: ThrottlerLimitDetail,
+  ): void {
     throw new ThrottlerException(this.errorMessage);
   }
 }