feat: add errorFactory parameter to rejectOnQuotaExceededOrRecordUsage method

Author: Jblew

README.md

@@ -191,7 +191,7 @@ const limiter = FirebaseFunctionsRateLimiter.mock()
 
 - `isQuotaExceededOrRecordUsage(qualifier?: string)` — Checks if quota was exceed. If not — it records the call time in the appropriate backend.
 
-- `rejectOnQuotaExceededOrRecordUsage(qualifier?: string)` — Checks if quota was exceed. If not — it records the call time in the appropriate backend and is rejected with *functions.https.HttpsException*. This particular exception can be caught when calling the firebase function directly (see https://firebase.google.com/docs/functions/callable).
+- `rejectOnQuotaExceededOrRecordUsage(qualifier?: string, errorFactory?: (configuration) => Error)` — Checks if quota was exceed. If not — it records the call time in the appropriate backend and is rejected with *functions.https.HttpsException*. This particular exception can be caught when calling the firebase function directly (see https://firebase.google.com/docs/functions/callable). When errorFactory is provided, it is used to obtain error that is thrown in case of exceeded limit.
 
 - `isQuotaAlreadyExceeded(qualifier?: string)` — Checks if quota was exceed, but does not record a usage. If you use this, you must call isQuotaExceededOrRecordUsage() to record the usage.
 

src/FirebaseFunctionsRateLimiter.integration.test.ts

@@ -7,6 +7,7 @@ import { _, expect, uuid } from "./_test/test_environment";
 import { FirebaseFunctionsRateLimiter } from "./FirebaseFunctionsRateLimiter";
 import { mock } from "./FirebaseFunctionsRateLimiter.mock.integration.test";
 import { PersistenceRecord } from "./persistence/PersistenceRecord";
+import { FirebaseFunctionsRateLimiterConfiguration } from "./FirebaseFunctionsRateLimiterConfiguration";
 
 describe("FirebaseFunctionsRateLimiter", () => {
     //
@@ -177,6 +178,36 @@ describe("FirebaseFunctionsRateLimiter", () => {
                             await expect(rateLimiter.rejectOnQuotaExceededOrRecordUsage(qualifier)).to.eventually.be
                                 .fulfilled;
                         });
+
+                        it("When error factory is provided, uses it to throw the error", async () => {
+                            const { rateLimiter } = mock(backend, {
+                                maxCalls: 1,
+                            });
+                            const qualifier = test.qualifierFactory();
+                            await rateLimiter.rejectOnQuotaExceededOrRecordUsage(qualifier);
+
+                            const errorFactory = () => new Error("error-from-factory");
+                            await expect(
+                                rateLimiter.rejectOnQuotaExceededOrRecordUsage(qualifier, errorFactory),
+                            ).to.eventually.be.rejectedWith(/error-from-factory/);
+                        });
+
+                        it("Provides valid configuration to error factory", async () => {
+                            const { rateLimiter, config } = mock(backend, {
+                                maxCalls: 1,
+                            });
+                            const qualifier = test.qualifierFactory();
+                            await rateLimiter.rejectOnQuotaExceededOrRecordUsage(qualifier);
+
+                            const errorFactory = configInErrorFactory => {
+                                expect(configInErrorFactory).to.deep.include(config);
+                                return new Error("error-from-factory");
+                            };
+
+                            await expect(
+                                rateLimiter.rejectOnQuotaExceededOrRecordUsage(qualifier, errorFactory),
+                            ).to.eventually.be.rejectedWith(/error-from-factory/);
+                        });
                     });
 
                     [

src/FirebaseFunctionsRateLimiter.ts

@@ -124,14 +124,20 @@ export class FirebaseFunctionsRateLimiter {
      * is rejected with functions.https.HttpsError (this is the type of error that can be caught when
      * firebase function is called directly: see https://firebase.google.com/docs/functions/callable)
      *
-     * @param qualifier  — a string that identifies the limited resource accessor (for example the user id)
+     * @param qualifier (optional) — a string that identifies the limited resource accessor (for example the user id)
+     * @param errorFactory (optional) — when errorFactory is provided, it is used to obtain
+     *                                  error that is thrown in case of exceeded limit.
      */
-    public async rejectOnQuotaExceededOrRecordUsage(qualifier?: string): Promise<void> {
+    public async rejectOnQuotaExceededOrRecordUsage(
+        qualifier?: string,
+        errorFactory?: (config: FirebaseFunctionsRateLimiterConfiguration) => Error,
+    ): Promise<void> {
         const isExceeded = await this.genericRateLimiter.isQuotaExceededOrRecordCall(
             qualifier || FirebaseFunctionsRateLimiter.DEFAULT_QUALIFIER,
         );
         if (isExceeded) {
-            throw this.constructRejectionError(qualifier);
+            if (errorFactory) throw errorFactory(this.getConfiguration());
+            else throw this.constructRejectionError(qualifier);
         }
     }