fixup: improve docs, param names

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

libs/hooks/debounce/README.md

@@ -23,18 +23,20 @@ NOTE: if you're using the React or Angular SDKs, you don't need to directly inst
 
 The hook maintains a simple expiring cache with a fixed max size and keeps a record of recent evaluations based on a user-defined key-generation function (keySupplier).
 Simply wrap your hook with the debounce hook by passing it a constructor arg, and then configure the remaining options.
-In the example below, we wrap a logging hook so that it only logs a maximum of once a minute for each flag key, no matter how many times that flag is evaluated.
+In the example below, we wrap the "after" stage of a logging hook so that it only logs a maximum of once a minute for each flag key, no matter how many times that flag is evaluated.
 
 ```ts
-// a function defining the key for the hook stage 
+// a function defining the key for the hook stage; if this matches a recent key, the hook execution for this stage will be bypassed
 const supplier = (flagKey: string, context: EvaluationContext, details: EvaluationDetails<T>) => flagKey;
 
-const hook = new DebounceHook<string>(loggingHook, {
-  afterCacheKeySupplier: supplier,  // if the key calculated by the supplier exists in the cache, the wrapped hook's stage will not run
-  ttlMs: 60_000,                    // how long to cache keys for
-  maxCacheItems: 100,               // max amount of items to keep in the LRU cache
-  cacheErrors: false                // whether or not to cache the errors thrown by hook stages
-});
+const hook = new DebounceHook<string>(loggingHook,
+  60_000,
+  {
+    debounceTime: 60_000,             // how long to wait before the hook can fire again (applied to each stage independently) in milliseconds
+    afterCacheKeySupplier: supplier,  // if the key calculated by the supplier exists in the cache, the wrapped hook's stage will not run
+    maxCacheItems: 100,               // max amount of items to keep in the cache; if exceeded, the oldest item is dropped
+    cacheErrors: false                // whether or not to cache the errors thrown by hook stages
+  });
 ```
 
 ## Development

libs/hooks/debounce/src/lib/debounce-hook.spec.ts

@@ -21,7 +21,7 @@ describe('DebounceHook', () => {
       afterCacheKeySupplier: supplier,
       errorCacheKeySupplier: supplier,
       finallyCacheKeySupplier: supplier,
-      ttlMs: 60_000,
+      debounceTime: 60_000,
       maxCacheItems: 100,
     });
 
@@ -85,7 +85,7 @@ describe('DebounceHook', () => {
 
       const hook = new DebounceHook<string>(innerHook, {
         beforeCacheKeySupplier: (flagKey: string) => flagKey,
-        ttlMs: 60_000,
+        debounceTime: 60_000,
         maxCacheItems: 1,
       });
 
@@ -97,7 +97,7 @@ describe('DebounceHook', () => {
       expect(innerHook.before).toHaveBeenCalledTimes(3);
     });
 
-    it('should rerun inner hook stage only after ttl', async () => {
+    it('should rerun inner hook only after debounce time', async () => {
       const innerHook: Hook = {
         before: jest.fn(),
       };
@@ -106,7 +106,7 @@ describe('DebounceHook', () => {
 
       const hook = new DebounceHook<string>(innerHook, {
         beforeCacheKeySupplier: (flagKey: string) => flagKey,
-        ttlMs: 500,
+        debounceTime: 500,
         maxCacheItems: 1,
       });
 
@@ -136,7 +136,7 @@ describe('DebounceHook', () => {
 
       // no suppliers defined, so we no-op (do no caching)
       const hook = new DebounceHook<string>(innerHook, {
-        ttlMs: 60_000,
+        debounceTime: 60_000,
         maxCacheItems: 100,
       });
 
@@ -182,7 +182,7 @@ describe('DebounceHook', () => {
       const hook = new DebounceHook<string>(innerErrorHook, {
         beforeCacheKeySupplier: (flagKey: string) => flagKey,
         maxCacheItems: 100,
-        ttlMs: 60_000,
+        debounceTime: 60_000,
         cacheErrors,
       });
 

libs/hooks/debounce/src/lib/debounce-hook.ts

@@ -87,9 +87,9 @@ export type Options<T extends FlagValue = FlagValue> = {
    */
   cacheErrors?: boolean;
   /**
-   * Time to live for items in cache in milliseconds.
+   * Debounce timeout - how long to wait before the hook can fire again (applied to each stage independently) in milliseconds.
    */
-  ttlMs: number;
+  debounceTime: number;
   /**
    * Max number of items to be kept in cache before the oldest entry falls out.
    */
@@ -107,7 +107,7 @@ export class DebounceHook<T extends FlagValue = FlagValue> implements Hook {
     this.cacheErrors = options.cacheErrors || false;
     this.cache = new FixedSizeExpiringCache<true | CachedError>({
       maxItems: options.maxCacheItems,
-      ttlMs: options.ttlMs,
+      ttlMs: options.debounceTime,
     });
   }
 
@@ -162,18 +162,19 @@ export class DebounceHook<T extends FlagValue = FlagValue> implements Hook {
           throw cached;
         }
         return;
-      }
-      try {
-        hookCallback();
-        this.cache.set(cacheKey, true);
-      } catch (error: unknown) {
-        if (this.cacheErrors) {
-          // cache error
-          this.cache.set(cacheKey, new CachedError(error));
+      } else {
+        try {
+          hookCallback();
+          this.cache.set(cacheKey, true);
+        } catch (error: unknown) {
+          if (this.cacheErrors) {
+            // cache error
+            this.cache.set(cacheKey, new CachedError(error));
+          }
+          throw error;
         }
-        throw error;
+        return;
       }
-      return;
     } else {
       hookCallback();
     }