feat: add debounce hook

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

Author: toddbaert

.release-please-manifest.json

@@ -22,5 +22,6 @@
   "libs/providers/unleash-web": "0.1.1",
   "libs/providers/growthbook": "0.1.2",
   "libs/providers/aws-ssm": "0.1.3",
-  "libs/providers/flagsmith": "0.1.1"
+  "libs/providers/flagsmith": "0.1.1",
+  "libs/hooks/debounce": "0.1.0"
 }

libs/hooks/debounce/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../.eslintrc.json",
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": [
+          "error",
+          {
+            "ignoredFiles": ["{projectRoot}/eslint.config.{js,cjs,mjs}"]
+          }
+        ]
+      }
+    }
+  ]
+}

libs/hooks/debounce/README.md

@@ -0,0 +1,48 @@
+# Debounce Hook
+
+This is a utility "meta" hook, which can be used to effectively debounce or rate limit other hooks based on various parameters.
+This can be especially useful for certain UI frameworks and SDKs that frequently re-render and re-evaluate flags (React, Angular, etc).
+
+## Installation
+
+```
+$ npm install @openfeature/debounce-hook
+```
+
+### Peer dependencies
+
+Confirm that the following peer dependencies are installed:
+
+```
+$ npm install @openfeature/web-sdk
+```
+
+NOTE: if you're using the React or Angular SDKs, you don't need to directly install this web SDK.
+
+## Usage
+
+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.
+
+```ts
+// a function defining the key for the hook stage 
+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
+});
+```
+
+## Development
+
+### Building
+
+Run `nx package hooks-debounce` to build the library.
+
+### Running unit tests
+
+Run `nx test hooks-debounce` to execute the unit tests via [Jest](https://jestjs.io).

libs/hooks/debounce/babel.config.json

@@ -0,0 +1,3 @@
+{
+  "presets": [["minify", { "builtIns": false }]]
+}

libs/hooks/debounce/jest.config.ts

@@ -0,0 +1,9 @@
+export default {
+  displayName: 'debounce',
+  preset: '../../../jest.preset.js',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../coverage/hooks',
+};

libs/hooks/debounce/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@openfeature/debounce-hook",
+  "version": "0.0.1",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "scripts": {
+    "publish-if-not-exists": "cp $NPM_CONFIG_USERCONFIG .npmrc && if [ \"$(npm show $npm_package_name@$npm_package_version version)\" = \"$(npm run current-version -s)\" ]; then echo 'already published, skipping'; else npm publish --access public; fi",
+    "current-version": "echo $npm_package_version"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@openfeature/web-sdk": "^1.6.0"
+  }
+}

libs/hooks/debounce/project.json

@@ -0,0 +1,77 @@
+{
+  "name": "debounce",
+  "$schema": "../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "hooks/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "generatorOptions": {
+        "packageRoot": "dist/{projectRoot}",
+        "currentVersionResolver": "git-tag"
+      }
+    }
+  },
+  "tags": [],
+  "targets": {
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "{projectRoot}/jest.config.ts"
+      }
+    },
+    "package": {
+      "executor": "@nx/rollup:rollup",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "project": "libs/hooks/debounce/package.json",
+        "outputPath": "dist/libs/hooks/debounce",
+        "entryFile": "libs/hooks/debounce/src/index.ts",
+        "tsConfig": "libs/hooks/debounce/tsconfig.lib.json",
+        "compiler": "tsc",
+        "generateExportsField": true,
+        "umdName": "debounce",
+        "external": "all",
+        "format": ["cjs", "esm"],
+        "assets": [
+          {
+            "glob": "package.json",
+            "input": "./assets",
+            "output": "./src/"
+          },
+          {
+            "glob": "LICENSE",
+            "input": "./",
+            "output": "./"
+          },
+          {
+            "glob": "README.md",
+            "input": "./libs/hooks/debounce",
+            "output": "./"
+          }
+        ]
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm run publish-if-not-exists",
+        "cwd": "dist/libs/hooks/debounce"
+      },
+      "dependsOn": [
+        {
+          "projects": "self",
+          "target": "package"
+        }
+      ]
+    }
+  }
+}

libs/hooks/debounce/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/debounce-hook';

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

@@ -0,0 +1,195 @@
+import type { EvaluationDetails, Hook, HookContext } from '@openfeature/web-sdk';
+import { DebounceHook } from './debounce-hook';
+
+describe('DebounceHook', () => {
+  describe('caching', () => {
+    afterAll(() => {
+      jest.resetAllMocks();
+    });
+
+    const innerHook: Hook = {
+      before: jest.fn(),
+      after: jest.fn(),
+      error: jest.fn(),
+      finally: jest.fn(),
+    };
+
+    const supplier = (flagKey: string) => flagKey;
+
+    const hook = new DebounceHook<string>(innerHook, {
+      beforeCacheKeySupplier: supplier,
+      afterCacheKeySupplier: supplier,
+      errorCacheKeySupplier: supplier,
+      finallyCacheKeySupplier: supplier,
+      ttlMs: 60_000,
+      maxCacheItems: 100,
+    });
+
+    const evaluationDetails: EvaluationDetails<string> = {
+      value: 'testValue',
+    } as EvaluationDetails<string>;
+    const err: Error = new Error('fake error!');
+    const context = {};
+    const hints = {};
+
+    it.each([
+      {
+        flagKey: 'flag1',
+        calledTimesTotal: 1,
+      },
+      {
+        flagKey: 'flag2',
+        calledTimesTotal: 2,
+      },
+      {
+        flagKey: 'flag1',
+        calledTimesTotal: 2, // should not have been incremented, same cache key
+      },
+    ])('should cache each stage based on supplier', ({ flagKey, calledTimesTotal }) => {
+      hook.before({ flagKey, context } as HookContext, hints);
+      hook.after({ flagKey, context } as HookContext, evaluationDetails, hints);
+      hook.error({ flagKey, context } as HookContext, err, hints);
+      hook.finally({ flagKey, context } as HookContext, evaluationDetails, hints);
+
+      expect(innerHook.before).toHaveBeenNthCalledWith(calledTimesTotal, expect.objectContaining({ context }), hints);
+      expect(innerHook.after).toHaveBeenNthCalledWith(
+        calledTimesTotal,
+        expect.objectContaining({ context }),
+        evaluationDetails,
+        hints,
+      );
+      expect(innerHook.error).toHaveBeenNthCalledWith(
+        calledTimesTotal,
+        expect.objectContaining({ context }),
+        err,
+        hints,
+      );
+      expect(innerHook.finally).toHaveBeenNthCalledWith(
+        calledTimesTotal,
+        expect.objectContaining({ context }),
+        evaluationDetails,
+        hints,
+      );
+    });
+  });
+
+  describe('options', () => {
+    afterAll(() => {
+      jest.resetAllMocks();
+    });
+
+    it('maxCacheItems should limit size', () => {
+      const innerHook: Hook = {
+        before: jest.fn(),
+      };
+
+      const hook = new DebounceHook<string>(innerHook, {
+        beforeCacheKeySupplier: (flagKey: string) => flagKey,
+        ttlMs: 60_000,
+        maxCacheItems: 1,
+      });
+
+      hook.before({ flagKey: 'flag1' } as HookContext, {});
+      hook.before({ flagKey: 'flag2' } as HookContext, {});
+      hook.before({ flagKey: 'flag1' } as HookContext, {});
+
+      // every invocation should have run since we have only maxCacheItems: 1
+      expect(innerHook.before).toHaveBeenCalledTimes(3);
+    });
+
+    it('should rerun inner hook stage only after ttl', async () => {
+      const innerHook: Hook = {
+        before: jest.fn(),
+      };
+
+      const flagKey = 'some-flag';
+
+      const hook = new DebounceHook<string>(innerHook, {
+        beforeCacheKeySupplier: (flagKey: string) => flagKey,
+        ttlMs: 500,
+        maxCacheItems: 1,
+      });
+
+      hook.before({ flagKey } as HookContext, {});
+      hook.before({ flagKey } as HookContext, {});
+      hook.before({ flagKey } as HookContext, {});
+
+      await new Promise((r) => setTimeout(r, 1000));
+
+      hook.before({ flagKey } as HookContext, {});
+
+      // only the first and last should have invoked the inner hook
+      expect(innerHook.before).toHaveBeenCalledTimes(2);
+    });
+
+    it('noop if supplier not defined', () => {
+      const innerHook: Hook = {
+        before: jest.fn(),
+        after: jest.fn(),
+        error: jest.fn(),
+        finally: jest.fn(),
+      };
+
+      const flagKey = 'some-flag';
+      const context = {};
+      const hints = {};
+
+      // no suppliers defined, so we no-op (do no caching)
+      const hook = new DebounceHook<string>(innerHook, {
+        ttlMs: 60_000,
+        maxCacheItems: 100,
+      });
+
+      const evaluationDetails: EvaluationDetails<string> = {
+        value: 'testValue',
+      } as EvaluationDetails<string>;
+
+      for (let i = 0; i < 3; i++) {
+        hook.before({ flagKey, context } as HookContext, hints);
+        hook.after({ flagKey, context } as HookContext, evaluationDetails, hints);
+        hook.error({ flagKey, context } as HookContext, hints);
+        hook.finally({ flagKey, context } as HookContext, evaluationDetails, hints);
+      }
+
+      // every invocation should have run since we have only maxCacheItems: 1
+      expect(innerHook.before).toHaveBeenCalledTimes(3);
+      expect(innerHook.after).toHaveBeenCalledTimes(3);
+      expect(innerHook.error).toHaveBeenCalledTimes(3);
+      expect(innerHook.finally).toHaveBeenCalledTimes(3);
+    });
+
+    it.each([
+      {
+        cacheErrors: false,
+        timesCalled: 2, // should be called each time since the hook always errors
+      },
+      {
+        cacheErrors: true,
+        timesCalled: 1, // should be called once since we cached the error
+      },
+    ])('should cache errors if cacheErrors set', ({ cacheErrors, timesCalled }) => {
+      const innerErrorHook: Hook = {
+        before: jest.fn(() => {
+          // throw an error
+          throw new Error('fake!');
+        }),
+      };
+
+      const flagKey = 'some-flag';
+      const context = {};
+
+      // this hook caches error invocations
+      const hook = new DebounceHook<string>(innerErrorHook, {
+        beforeCacheKeySupplier: (flagKey: string) => flagKey,
+        maxCacheItems: 100,
+        ttlMs: 60_000,
+        cacheErrors,
+      });
+
+      expect(() => hook.before({ flagKey, context } as HookContext)).toThrow();
+      expect(() => hook.before({ flagKey, context } as HookContext)).toThrow();
+
+      expect(innerErrorHook.before).toHaveBeenCalledTimes(timesCalled);
+    });
+  });
+});