chore(main): release react-sdk 1.0.1 (#1235)

🤖 I have created a release *beep* *boop*
---


##
[1.0.1](https://github.com/open-feature/js-sdk/compare/react-sdk-v1.0.0...react-sdk-v1.0.1)
(2025-08-18)


### 🐛 Bug Fixes

* **react:** re-evaluate flags on re-render to detect silent provider …
([#1226](https://github.com/open-feature/js-sdk/issues/1226))
([3105595](3105595926))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Signed-off-by: OpenFeature Bot <109696520+openfeaturebot@users.noreply.github.com>

.eslintrc.json

@@ -1,63 +1,54 @@
 {
-	"env": {
-		"browser": true,
-		"es2021": true
-	},
-	"ignorePatterns": ["**/dist/**/*"],
-	"extends": [
-		"eslint:recommended",
-		"plugin:@typescript-eslint/recommended",
-		"prettier",
-		"plugin:jsdoc/recommended"
-	],
-	"parser": "@typescript-eslint/parser",
-	"parserOptions": {
-		"ecmaVersion": "latest",
-		"sourceType": "module"
-	},
-	"plugins": [
-		"@typescript-eslint",
-		"check-file",
-		"jsdoc"
-	],
-	"rules": {
-		"jsdoc/require-jsdoc": [
-			"warn",
-			{
-				"publicOnly": true
-			}
-		],
-		"jsdoc/check-tag-names": [
-			"warn",
-			{
-				"definedTags": [
-					"experimental"
-				]
-			}
-		],
-		"linebreak-style": [
-			"error",
-			"unix"
-		],
-		"quotes": [
-			"error",
-			"single",
-			{
-				"avoidEscape": true
-			}
-		],
-		"semi": [
-			"error",
-			"always"
-		],
-		"check-file/filename-naming-convention": [
-			"error",
-			{
-				"**/*.{js,ts}": "KEBAB_CASE"
-			},
-			{
-				"ignoreMiddleExtensions": true
-			}
-		]
-	}
-}
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "ignorePatterns": ["**/dist/**/*"],
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier", "plugin:jsdoc/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint", "check-file", "jsdoc"],
+  "rules": {
+    "@typescript-eslint/consistent-type-imports": [
+      "error",
+      {
+        "disallowTypeAnnotations": true,
+        "fixStyle": "separate-type-imports",
+        "prefer": "type-imports"
+      }
+    ],
+    "jsdoc/require-jsdoc": [
+      "warn",
+      {
+        "publicOnly": true
+      }
+    ],
+    "jsdoc/check-tag-names": [
+      "warn",
+      {
+        "definedTags": ["experimental"]
+      }
+    ],
+    "linebreak-style": ["error", "unix"],
+    "quotes": [
+      "error",
+      "single",
+      {
+        "avoidEscape": true
+      }
+    ],
+    "semi": ["error", "always"],
+    "check-file/filename-naming-convention": [
+      "error",
+      {
+        "**/*.{js,ts}": "KEBAB_CASE"
+      },
+      {
+        "ignoreMiddleExtensions": true
+      }
+    ]
+  }
+}

.github/workflows/audit-pending-releases.yml

@@ -29,21 +29,6 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: "https://registry.npmjs.org"
           cache: 'npm'
-
-      # if this is an @openfeature/core release, but the SDKs to use this version as a peer, and commit back
-      - name: Update Peer Version in Dependants
-        if: ${{ endsWith(github.ref_name, env.CORE_PACKAGE) }}
-        run: |
-          npm run update-core-peers && \
-          ! git diff-files --quiet && \
-          ( echo 'Updated peer dependency in dependents, committing...'
-          git add --all && \
-          git config user.name "openfeature-peer-update-bot" && \
-          git config user.email "openfeature-peer-update-bot@openfeature.dev" && \
-          git commit -m 'fix: bump @openfeature/${{ env.CORE_PACKAGE }} peer' -s && \
-          git push ) || echo 'Peer dependency in dependents is already up to date.'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/coverage.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           registry-url: 'https://registry.npmjs.org'
-          node-version: 18
+          node-version: 20
           cache: 'npm'
 
       - name: Install

.github/workflows/pr-checks.yaml

@@ -16,8 +16,9 @@ jobs:
     strategy:
       matrix:
         node-version:
-          - 18.x
           - 20.x
+          - 22.x
+          - 24.x
 
     steps:
       - uses: actions/checkout@v4
@@ -36,8 +37,11 @@ jobs:
       - name: Lint
         run: npm run lint
 
-      - name: Test
-        run: npm run test
+      - name: Test Jest Projects
+        run: npm run test:jest
+
+      - name: Test Angular SDK
+        run: npm run test:angular
 
   codecov-and-docs:
     runs-on: ubuntu-latest
@@ -46,7 +50,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: 'npm'
 
       - name: Install
@@ -68,8 +72,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          # we need 'fetch' for this test, which is only in 18
-          node-version: 18
+          node-version: 20
           cache: 'npm'
 
       - name: Install

.github/workflows/release-please.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
       - name: Generate SBOM
         run: |
           npm install -g npm@^10.2.0
@@ -54,6 +54,10 @@ jobs:
     needs: release-please
     runs-on: ubuntu-latest
     if: ${{ needs.release-please.outputs.release_created }}
+    environment: publish
+    permissions:
+      id-token: write
+      contents: write
     steps:
       # The logic below handles the npm publication:
       - name: Checkout Repository
@@ -61,7 +65,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: "https://registry.npmjs.org"
           cache: 'npm'
       - name: Build Packages
@@ -74,6 +78,8 @@ jobs:
       - name: Publish to NPM
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+          # https://docs.npmjs.com/generating-provenance-statements
+          NPM_CONFIG_PROVENANCE: true
         run: npm run publish-all
 
       - name: Build Docs

.release-please-manifest.json

@@ -1,7 +1,8 @@
 {
-  "packages/nest": "0.2.0-experimental",
-  "packages/react": "0.4.0",
-  "packages/client": "1.1.0",
-  "packages/server": "1.14.0",
-  "packages/shared": "1.2.0"
+  "packages/nest": "0.2.5",
+  "packages/react": "1.0.1",
+  "packages/web": "1.6.1",
+  "packages/server": "1.19.0",
+  "packages/shared": "1.9.0",
+  "packages/angular/projects/angular-sdk": "0.0.16"
 }

CODEOWNERS

@@ -3,4 +3,4 @@
 #
 # Managed by Peribolos: https://github.com/open-feature/community/blob/main/config/open-feature/sdk-javascript/workgroup.yaml
 #
-* @open-feature/sdk-javascript-maintainers
+* @open-feature/sdk-javascript-maintainers @open-feature/maintainers

CONTRIBUTING.md

@@ -8,7 +8,7 @@ node 16+, npm 8+ are recommended.
 
 ### Compilation Target(s)
 
-We target `es2022`, and publish both ES-modules and CommonJS modules.
+We target `es2015`, and publish both ES-modules and CommonJS modules.
 
 ### Installation and Dependencies
 
@@ -19,7 +19,7 @@ We value having as few runtime dependencies as possible. The addition of any dep
 ### Modules
 
 This repository uses [NPM workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces) to establish a simple monorepo.
-Within the root project, there is one common project (`packages/shared`) which features common interfaces and code, consumed by the published modules (`packages/server` and `packages/client`).
+Within the root project, there is one common project (`packages/shared`) which features common interfaces and code, consumed by the published modules (`packages/server` and `packages/web`).
 The shared module is built and published separately, and is a peer dependency of the SDK packages.
 Consumers need not install it separately, since `npm` and `yarn` automatically install required peers.
 In order to prevent regressions cause by incompatibilities due to version mismatches, the SDKs are locked to a particular version of the `@openfeature/core` module, and the CI enforces that it's released before any dependant SDKs (see [the related workflow](./.github/workflows/audit-pending-releases.yml)).
@@ -36,9 +36,9 @@ npm run e2e-server
 ```
 for the server e2e tests and
 ```
-npm run e2e-client
+npm run e2e-web
 ```
-for the client e2e tests.
+for the web e2e tests.
 
 ### Packaging
 
@@ -120,6 +120,16 @@ on each other), the owner should try to get people aligned by:
 - If none of the above worked and the PR has been stuck for more than 2 weeks,
   the owner should bring it to the OpenFeatures [meeting](README.md#contributing).
 
+## Releasing
+
+As with most OpenFeature repos, release-please supports our release process.
+For this SDK specifically, keep in mind this is a monorepo with dependencies with between components.
+If there are multiple release PRs open, ensure that you release them in order consistent with their dependency graph, waiting for each to fully complete.
+For example, if there are pending releases for: `@openfeature/core`, `@openfeature/web-sdk` and `@openfeature/react-sdk`, release them in that order.
+
+Also ensure that if there are changes in an artifact which depend on changes in a dependency, that you reflect that in the `peerDependencies` field.
+For example, if a new release of `@openfeature/web-sdk` depends on features added in `@openfeature/core`, update the required minimum version of the `@openfeature/core` peer in the `@openfeature/web-sdk` package.json.
+
 ## Design Choices
 
 As with other OpenFeature SDKs, js-sdk follows the

README.md

@@ -30,8 +30,8 @@ For details, including API documentation, see the respective README files.
 
 - [Server SDK](./packages/server/README.md), for use in Node.js and similar runtimes.
   - [NestJS SDK](./packages/nest/README.md), a distribution of the Server SDK with built-in NestJS-specific features.
-- [Client SDK](./packages/client/README.md), for use in the web browser.
-  - [React SDK](./packages/react//README.md), a distribution of the Client SDK with built-in React-specific features.
+- [Web SDK](./packages/web/README.md), for use in the web browser.
+  - [React SDK](./packages/react//README.md), a distribution of the Web SDK with built-in React-specific features.
 
 Each have slightly different APIs, but share many underlying types and components.
 

jest.config.ts

@@ -124,10 +124,10 @@ export default {
       },
     },
     {
-      displayName: 'client',
+      displayName: 'web',
       testEnvironment: 'node',
       preset: 'ts-jest',
-      testMatch: ['<rootDir>/packages/client/test/**/*.spec.ts'],
+      testMatch: ['<rootDir>/packages/web/test/**/*.spec.ts'],
       moduleNameMapper: {
         '@openfeature/core': '<rootDir>/packages/shared/src',
       },
@@ -143,10 +143,10 @@ export default {
       },
     },
     {
-      displayName: 'client-e2e',
+      displayName: 'web-e2e',
       testEnvironment: 'node',
       preset: 'ts-jest',
-      testMatch: ['<rootDir>/packages/client/e2e/**/*.spec.ts'],
+      testMatch: ['<rootDir>/packages/web/e2e/**/*.spec.ts'],
       modulePathIgnorePatterns: ['.*/node-modules/'],
       moduleNameMapper: {
         '^uuid$': require.resolve('uuid'),
@@ -161,6 +161,7 @@ export default {
       testMatch: ['<rootDir>/packages/nest/test/**/*.spec.ts'],
       moduleNameMapper: {
         '@openfeature/core': '<rootDir>/packages/shared/src',
+        '@openfeature/server-sdk': '<rootDir>/packages/server/src',
       },
       transform: {
         '^.+\\.ts$': [
@@ -178,7 +179,7 @@ export default {
       testMatch: ['<rootDir>/packages/react/test/**/*.spec.{ts,tsx}'],
       moduleNameMapper: {
         '@openfeature/core': '<rootDir>/packages/shared/src',
-        '@openfeature/web-sdk': '<rootDir>/packages/client/src',
+        '@openfeature/web-sdk': '<rootDir>/packages/web/src',
       },
       transform: {
         '^.+\\.(ts|tsx)$': [

package.json

@@ -1,20 +1,24 @@
 {
   "name": "@openfeature/js",
+  "engines": {
+    "npm": "^10.0.0"
+  },
   "version": "0.0.0",
   "private": true,
   "description": "OpenFeature SDK for JavaScript",
   "scripts": {
-    "test": "jest --selectProjects=shared --selectProjects=server --selectProjects=client --selectProjects=react --silent",
+    "test": "npm run test:jest && npm run test:angular",
+    "test:jest": "jest --selectProjects=shared --selectProjects=server --selectProjects=web --selectProjects=react --selectProjects=nest --silent",
+    "test:angular": "npm run test:coverage --workspace=packages/angular",
     "e2e-server": "git submodule update --init --recursive && shx cp test-harness/features/evaluation.feature packages/server/e2e/features && jest --selectProjects=server-e2e --verbose",
-    "e2e-client": "git submodule update --init --recursive && shx cp test-harness/features/evaluation.feature packages/client/e2e/features && jest --selectProjects=client-e2e --verbose",
-    "e2e": "npm run e2e-server && npm run e2e-client",
-    "lint": "npm run lint --workspace=packages/shared --workspace=packages/server --workspace=packages/client --workspace=packages/react --workspace=packages/nest",
+    "e2e-web": "git submodule update --init --recursive && shx cp test-harness/features/evaluation.feature packages/web/e2e/features && jest --selectProjects=web-e2e --verbose",
+    "e2e": "npm run e2e-server && npm run e2e-web",
+    "lint": "npm run lint --workspace=packages/shared --workspace=packages/server --workspace=packages/web --workspace=packages/react --workspace=packages/angular --workspace=packages/nest",
+    "lint:fix": "npm run lint:fix --workspace=packages/shared --workspace=packages/server --workspace=packages/web --workspace=packages/react --workspace=packages/angular --workspace=packages/nest",
     "clean": "shx rm -rf ./dist",
-    "build": "npm run build --workspace=packages/shared --workspace=packages/server --workspace=packages/client --workspace=packages/react --workspace=packages/nest",
-    "publish-all": "npm run publish-if-not-exists --workspace=packages/shared --workspace=packages/server --workspace=packages/client --workspace=packages/react --workspace=packages/nest",
-    "docs": "typedoc",
-    "core-version": "npm run version --workspace=packages/shared",
-    "update-core-peers": "export OPENFEATURE_CORE_VERSION=$(npm run --silent core-version) && npm run update-core-peer --workspace=packages/server --workspace=packages/client"
+    "build": "npm run build --workspace=packages/shared --workspace=packages/server --workspace=packages/web --workspace=packages/react --workspace=packages/angular --workspace=packages/nest",
+    "publish-all": "npm run publish-if-not-exists --workspace=packages/shared --workspace=packages/server --workspace=packages/web --workspace=packages/react --workspace=packages/angular --workspace=packages/nest",
+    "docs": "typedoc"
   },
   "repository": {
     "type": "git",
@@ -32,50 +36,49 @@
     "url": "https://github.com/open-feature/js-sdk/issues"
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
-  "engines": {
-    "node": ">=18"
-  },
   "devDependencies": {
-    "@rollup/plugin-typescript": "^11.1.6",
+    "@rollup/plugin-typescript": "^12.0.0",
     "@testing-library/jest-dom": "^6.4.2",
-    "@testing-library/react": "^15.0.0",
+    "@testing-library/react": "^16.0.0",
     "@types/jest": "^29.5.12",
-    "@types/node": "^20.11.16",
+    "@types/node": "^22.0.0",
     "@types/react": "^18.2.55",
-    "@types/uuid": "^9.0.8",
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^7.0.0",
-    "esbuild": "^0.20.0",
+    "@types/uuid": "^10.0.0",
+    "esbuild": "^0.25.0",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-alias": "^1.1.2",
     "eslint-plugin-check-file": "^2.6.2",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-jest": "^28.0.0",
-    "eslint-plugin-jsdoc": "^48.0.6",
+    "eslint-plugin-jsdoc": "^50.0.0",
     "eventemitter3": "^5.0.1",
     "jest": "^29.7.0",
     "jest-config": "^29.7.0",
-    "jest-cucumber": "^3.0.1",
+    "jest-cucumber": "^4.0.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-environment-node": "^29.7.0",
     "jest-junit": "^16.0.0",
     "prettier": "^3.2.5",
     "react": "^18.2.0",
-    "rollup": "^3.29.4",
-    "rollup-plugin-dts": "^5.3.1",
-    "shx": "^0.3.4",
+    "rollup": "^4.0.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "rxjs": "~7.8.0",
+    "shx": "^0.4.0",
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.25.7",
+    "tslib": "^2.3.0",
+    "typedoc": "^0.26.0",
     "typescript": "^4.7.4",
-    "uuid": "^9.0.1"
+    "uuid": "^11.0.0"
   },
   "workspaces": [
     "packages/shared",
     "packages/server",
-    "packages/client",
+    "packages/web",
     "packages/react",
+    "packages/angular",
+    "packages/angular/projects/angular-sdk",
     "packages/nest"
   ]
 }

packages/angular/.eslintrc.json

@@ -0,0 +1,29 @@
+{
+  "root": true,
+  "ignorePatterns": [
+    "projects/**/*"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "*.ts"
+      ],
+      "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended",
+        "plugin:@angular-eslint/recommended",
+        "plugin:@angular-eslint/template/process-inline-templates"
+      ]
+    },
+    {
+      "files": [
+        "*.html"
+      ],
+      "extends": [
+        "plugin:@angular-eslint/template/recommended",
+        "plugin:@angular-eslint/template/accessibility"
+      ],
+      "rules": {}
+    }
+  ]
+}

packages/angular/.gitignore

@@ -0,0 +1,45 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# Compiled output
+/dist
+/tmp
+/out-tsc
+/bazel-out
+
+# Node
+/node_modules
+npm-debug.log
+yarn-error.log
+
+# IDEs and editors
+.idea/
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# Miscellaneous
+/.angular/cache
+.sass-cache/
+/connect.lock
+/coverage
+/libpeerconnection.log
+testem.log
+/typings
+
+# System files
+.DS_Store
+Thumbs.db
+
+.nx/cache
+.nx/workspace-data

packages/angular/README.md

@@ -0,0 +1,27 @@
+# Angular
+
+This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.2.2.
+
+## Development server
+
+Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+
+## Code scaffolding
+
+Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+
+## Build
+
+Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Running unit tests
+
+Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Running end-to-end tests
+
+Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

packages/angular/angular.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "angular-sdk": {
+      "projectType": "library",
+      "root": "projects/angular-sdk",
+      "sourceRoot": "projects/angular-sdk/src",
+      "prefix": "lib",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:ng-packagr",
+          "options": {
+            "project": "projects/angular-sdk/ng-package.json"
+          },
+          "configurations": {
+            "production": {
+              "tsConfig": "projects/angular-sdk/tsconfig.lib.prod.json"
+            },
+            "development": {
+              "tsConfig": "projects/angular-sdk/tsconfig.lib.json"
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "lint": {
+          "builder": "@angular-eslint/builder:lint",
+          "options": {
+            "lintFilePatterns": [
+              "projects/angular-sdk/**/*.ts",
+              "projects/angular-sdk/**/*.html"
+            ]
+          }
+        },
+        "test": {
+          "builder": "@angular/build:unit-test",
+          "options": {
+            "tsConfig": "projects/angular-sdk/tsconfig.spec.json",
+            "providersFile": "projects/angular-sdk/src/test-provider.ts",
+            "runner": "vitest",
+            "buildTarget": "::development"
+          }
+        }
+      }
+    }
+  },
+  "cli": {
+    "schematicCollections": [
+      "@angular-eslint/schematics"
+    ],
+    "analytics": false
+  }
+}

packages/angular/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "angular",
+  "version": "0.0.0",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "lint": "ng lint",
+    "lint:fix": "ng lint --fix",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test",
+    "test:coverage": "ng test --no-watch --code-coverage",
+    "build": "ng build && npm run postbuild",
+    "postbuild": "shx cp ./../../LICENSE ./dist/angular/LICENSE",
+    "publish-if-not-exists": "cp $NPM_CONFIG_USERCONFIG .npmrc && if [ \"$(npm --prefix dist/angular run current-published-version -s)\" = \"$(npm --prefix dist/angular run current-version -s)\" ]; then echo 'already published, skipping'; else cd dist/angular && npm publish --access public; fi"
+  },
+  "private": true,
+  "devDependencies": {
+    "@angular-eslint/builder": "^20.1.1",
+    "@angular-eslint/eslint-plugin": "^20.1.1",
+    "@angular-eslint/eslint-plugin-template": "^20.1.1",
+    "@angular-eslint/schematics": "^20.1.1",
+    "@angular-eslint/template-parser": "^20.1.1",
+    "@angular/animations": "^20.1.1",
+    "@angular/build": "^20.1.1",
+    "@angular/cli": "^20.1.1",
+    "@angular/common": "^20.1.1",
+    "@angular/compiler": "^20.1.1",
+    "@angular/compiler-cli": "^20.1.1",
+    "@angular/core": "^20.1.1",
+    "@angular/forms": "^20.1.1",
+    "@angular/platform-browser": "^20.1.1",
+    "@angular/platform-browser-dynamic": "^20.1.1",
+    "@angular/router": "^20.1.1",
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/parser": "7.18.0",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^8.57.0",
+    "jsdom": "^26.1.0",
+    "ng-packagr": "^20.1.0",
+    "playwright": "^1.53.2",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "zone.js": "~0.15.0"
+  }
+}

packages/angular/projects/angular-sdk/.browserslistrc

@@ -0,0 +1,18 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# For Angular's browser support policy, please see:
+# https://angular.dev/reference/versions#browser-support
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+Chrome >= 107
+ChromeAndroid >= 107
+Edge >= 107
+Firefox >= 104
+FirefoxAndroid >= 104
+Safari >= 16
+iOS >= 16
+

packages/angular/projects/angular-sdk/.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../.eslintrc.json",
+  "ignorePatterns": [
+    "!**/*"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "*.ts"
+      ]
+    },
+    {
+      "files": [
+        "*.html"
+      ],
+      "rules": {}
+    }
+  ]
+}

packages/angular/projects/angular-sdk/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+
+## [0.0.16](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.15...angular-sdk-v0.0.16) (2025-07-25)
+
+
+### ✨ New Features
+
+* support Angular 20 ([#1220](https://github.com/open-feature/js-sdk/issues/1220)) ([aa232a9](https://github.com/open-feature/js-sdk/commit/aa232a9d6a8dfa416380ccdecd71843d3e361048))
+
+
+## [0.0.15](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.14...angular-sdk-v0.0.15) (2025-05-27)
+
+
+### 🐛 Bug Fixes
+
+* **angular:** update docs ([#1200](https://github.com/open-feature/js-sdk/issues/1200)) ([b6ea588](https://github.com/open-feature/js-sdk/commit/b6ea5884f2ab9f4f94c8b258c4cf7268ea6dbeb8))
+
+
+## [0.0.14](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.13...angular-sdk-v0.0.14) (2025-05-25)
+
+
+### 🐛 Bug Fixes
+
+* **angular:** add license and url field to package.json ([b2784f5](https://github.com/open-feature/js-sdk/commit/b2784f53b85a11c58abb8e2a0f87a31890885c54))
+
+
+## [0.0.13](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.12...angular-sdk-v0.0.13) (2025-04-20)
+
+
+### 📚 Documentation
+
+* fix readme typo ([#1174](https://github.com/open-feature/js-sdk/issues/1174)) ([21a32ec](https://github.com/open-feature/js-sdk/commit/21a32ec92ecde9ec43c9d72b5921035af13448d1))
+
+## [0.0.12](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.11...angular-sdk-v0.0.12) (2025-04-11)
+
+
+### ✨ New Features
+
+* **angular:** add docs for setting evaluation context in angular ([#1170](https://github.com/open-feature/js-sdk/issues/1170)) ([24f1b23](https://github.com/open-feature/js-sdk/commit/24f1b230bf1d57971a336ac21b9ee46e8baf0cab))
+
+
+## [0.0.11](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.10...angular-sdk-v0.0.11) (2025-04-11)
+
+
+### ✨ New Features
+
+* **angular:** add option for initial context injection ([aafdb43](https://github.com/open-feature/js-sdk/commit/aafdb4382f113f96a649f5fc0cecadb4178ada67))
+  
+
+## [0.0.10](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.9-experimental...angular-sdk-v0.0.10) (2025-02-13)
+
+
+### 🧹 Chore
+
+* **angular:** update angular package to a non-experimental version ([#1147](https://github.com/open-feature/js-sdk/issues/1147)) ([5272f76](https://github.com/open-feature/js-sdk/commit/5272f76c4075ebbd21f9b24dacac8f2d22e31ca9)), closes [#1110](https://github.com/open-feature/js-sdk/issues/1110)
+* update sdk peer ([#1142](https://github.com/open-feature/js-sdk/issues/1142)) ([8bb6206](https://github.com/open-feature/js-sdk/commit/8bb620601e2b8dc7b62d717169b585bd1c886996))
+
+## [0.0.9-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.8-experimental...angular-sdk-v0.0.9-experimental) (2024-11-21)
+
+
+### 🧹 Chore
+
+* **angular:** add repository to package.json ([#1093](https://github.com/open-feature/js-sdk/issues/1093)) ([35f000e](https://github.com/open-feature/js-sdk/commit/35f000e0f3c3ff7d60c05883312691d14f01c5fd))
+
+## [0.0.8-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.7-experimental...angular-sdk-v0.0.8-experimental) (2024-11-21)
+
+
+### ✨ New Features
+
+* **angular:** add angular 19 to peerDependencies ([4893d6f](https://github.com/open-feature/js-sdk/commit/4893d6f0003fbdcdcd4c7c061e9aed49e20b8976))
+
+
+## [0.0.7-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.6-experimental...angular-sdk-v0.0.7-experimental) (2024-11-21)
+
+
+Note: This version did not release
+
+
+## [0.0.6-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.5-experimental...angular-sdk-v0.0.6-experimental) (2024-10-28)
+
+
+### ✨ New Features
+
+* **angular:** add Angular 18 support ([#1063](https://github.com/open-feature/js-sdk/issues/1063)) ([e62d6d4](https://github.com/open-feature/js-sdk/commit/e62d6d4b7e4a5d0f40592a2c73e7124d22eec98e))
+
+
+## [0.0.5-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.4-experimental...angular-sdk-v0.0.5-experimental) (2024-10-21)
+
+
+### 🐛 Bug Fixes
+
+* **angular:** fix race condition on initialization ([#1052](https://github.com/open-feature/js-sdk/issues/1052)) ([12eaa97](https://github.com/open-feature/js-sdk/commit/12eaa9758d9deb788d74488ef03f18cbd31c0cbe))
+
+
+## [0.0.4-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.3-experimental...angular-sdk-v0.0.4-experimental) (2024-09-30)
+
+
+### 🐛 Bug Fixes
+
+* **angular:** add package description ([#1026](https://github.com/open-feature/js-sdk/issues/1026)) ([dc63ca8](https://github.com/open-feature/js-sdk/commit/dc63ca8b9d6fe8c16089e95f0e336d5e3f759f3b))
+
+## [0.0.3-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.2-experimental...angular-sdk-v0.0.3-experimental) (2024-09-22)
+
+
+### 🧹 Chore
+
+* add npm keywords for angular ([#1015](https://github.com/open-feature/js-sdk/issues/1015)) ([6b11165](https://github.com/open-feature/js-sdk/commit/6b11165aa102e62fb8cd4dd218643e2ef0e733cf))
+
+
+### 📚 Documentation
+
+* **angular:** improve angular readme layout ([#1013](https://github.com/open-feature/js-sdk/issues/1013)) ([ee52da9](https://github.com/open-feature/js-sdk/commit/ee52da9a01fe71fd5b4a4734659a06c48b6dc62c))
+
+## [0.0.2-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.1-experimental...angular-sdk-v0.0.2-experimental) (2024-09-14)
+
+
+### 🐛 Bug Fixes
+
+* copy license to package correctly ([#1011](https://github.com/open-feature/js-sdk/issues/1011)) ([458d278](https://github.com/open-feature/js-sdk/commit/458d278345fe8681a966fca3852b2e607bdafccb))
+
+## [0.0.1-experimental](https://github.com/open-feature/js-sdk/compare/angular-sdk-v0.0.2-experimental...angular-sdk-v0.0.3-experimental) (2024-09-14)
+
+
+### ✨ New Features
+
+* Angular SDK ([#997](https://github.com/open-feature/js-sdk/issues/997)) ([105fd95](https://github.com/open-feature/js-sdk/commit/105fd95e344822ffcfc54d328a28676b6f27f38e))

packages/angular/projects/angular-sdk/README.md

@@ -0,0 +1,352 @@
+<!-- markdownlint-disable MD033 -->
+<!-- x-hide-in-docs-start -->
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/white/openfeature-horizontal-white.svg" />
+    <img align="center" alt="OpenFeature Logo" src="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/black/openfeature-horizontal-black.svg" />
+  </picture>
+</p>
+
+<h2 align="center">OpenFeature Angular SDK</h2>
+
+<!-- x-hide-in-docs-end -->
+<!-- The 'github-badges' class is used in the docs -->
+<p align="center" class="github-badges">
+  <a href="https://github.com/open-feature/spec/releases/tag/v0.8.0">
+    <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
+  </a>
+  <!-- x-release-please-start-version -->
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/angular-sdk-v0.0.16">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.0.16&color=blue&style=for-the-badge" />
+  </a>
+  <!-- x-release-please-end -->
+  <br/>
+  <a href="https://codecov.io/gh/open-feature/js-sdk">
+    <img alt="codecov" src="https://codecov.io/gh/open-feature/js-sdk/branch/main/graph/badge.svg?token=3DC5XOEHMY" />
+  </a>
+  <a href="https://www.npmjs.com/package/@openfeature/angular-sdk">
+    <img alt="NPM Download" src="https://img.shields.io/npm/dm/%40openfeature%2Fangular-sdk" />
+  </a>
+</p>
+<!-- x-hide-in-docs-start -->
+
+[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API
+for feature flagging that works with your favorite feature flag management tool or in-house solution.
+
+<!-- x-hide-in-docs-end -->
+
+## Overview
+
+The OpenFeature Angular SDK adds Angular-specific functionality to
+the [OpenFeature Web SDK](https://openfeature.dev/docs/reference/technologies/client/web).
+
+In addition to the features provided by the [web sdk](https://openfeature.dev/docs/reference/technologies/client/web), capabilities include:
+
+- [Overview](#overview)
+- [Quick start](#quick-start)
+    - [Requirements](#requirements)
+    - [Install](#install)
+        - [npm](#npm)
+        - [yarn](#yarn)
+        - [Required peer dependencies](#required-peer-dependencies)
+    - [Usage](#usage)
+        - [Module](#module)
+            - [Minimal Example](#minimal-example)
+        - [How to use](#how-to-use)
+            - [Boolean Feature Flag](#boolean-feature-flag)
+            - [Number Feature Flag](#number-feature-flag)
+            - [String Feature Flag](#string-feature-flag)
+            - [Object Feature Flag](#object-feature-flag)
+            - [Opting-out of automatic re-rendering](#opting-out-of-automatic-re-rendering)
+            - [Consuming the evaluation details](#consuming-the-evaluation-details)
+            - [Setting Evaluation Context](#setting-evaluation-context)
+- [FAQ and troubleshooting](#faq-and-troubleshooting)
+- [Resources](#resources)
+
+## Quick start
+
+### Requirements
+
+- ES2015-compatible web browser (Chrome, Edge, Firefox, etc)
+- Angular version 16+
+
+### Install
+
+#### npm
+
+```sh
+npm install --save @openfeature/angular-sdk
+```
+
+#### yarn
+
+```sh
+# yarn requires manual installation of the peer dependencies (see below)
+yarn add @openfeature/angular-sdk @openfeature/web-sdk @openfeature/core
+```
+
+#### Required peer dependencies
+
+The following list contains the peer dependencies of `@openfeature/angular-sdk`.
+See the [package.json](./package.json) for the required versions.
+
+* `@openfeature/web-sdk`
+* `@angular/common`
+* `@angular/core`
+
+### Usage
+
+#### Module
+
+To include the OpenFeature Angular directives in your application, you need to import the `OpenFeatureModule` and
+configure it using the `forRoot` method.
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { OpenFeatureModule } from '@openfeature/angular-sdk';
+
+@NgModule({
+  declarations: [
+    // Other components
+  ],
+  imports: [
+    CommonModule,
+    OpenFeatureModule.forRoot({
+      provider: yourFeatureProvider,
+      // domainBoundProviders are optional, mostly needed if more than one provider is used in the application.
+      domainBoundProviders: {
+        domain1: new YourOpenFeatureProvider(),
+        domain2: new YourOtherOpenFeatureProvider(),
+      },
+    })
+  ],
+})
+export class AppModule {
+}
+```
+
+##### Minimal Example
+
+You don't need to provide all the templates. Here's a minimal example using a boolean feature flag:
+
+If `initializing` and `reconciling` are not given, the feature flag value that is returned by the provider will
+determine what will be rendered.
+
+```html
+<div *booleanFeatureFlag="'isFeatureEnabled'; default: true">
+  This is shown when the feature flag is enabled.
+</div>
+```
+
+This example shows content when the feature flag `isFeatureEnabled` is true with a default value of true.
+No `else`, `initializing`, or `reconciling` templates are required in this case.
+
+#### How to use
+
+The library provides four primary directives for feature flags, `booleanFeatureFlag`,
+`numberFeatureFlag`, `stringFeatureFlag` and `objectFeatureFlag`.
+
+The first value given to the directive is the flag key that should be evaluated.
+
+For all directives, the default value passed to OpenFeature has to be provided by the `default` parameter.
+
+For all non-boolean directives, the value to compare the evaluation result to can be provided by the `value` parameter.
+This parameter is optional, if omitted, the `thenTemplate` will always be rendered.
+
+The `domain` parameter is _optional_ and will be used as domain when getting the OpenFeature provider.
+
+The `updateOnConfigurationChanged` and `updateOnContextChanged` parameter are _optional_ and used to disable the
+automatic re-rendering on flag value or context change. They are set to `true` by default.
+
+The template referenced in `else` will be rendered if the evaluated feature flag is `false` for the `booleanFeatureFlag`
+directive and if the `value` does not match evaluated flag value for all other directives.
+This parameter is _optional_.
+
+The template referenced in `initializing` and `reconciling` will be rendered if OpenFeature provider is in the
+corresponding states.
+This parameter is _optional_, if omitted, the `then` and `else` templates will be rendered according to the flag value.
+
+##### Boolean Feature Flag
+
+```html
+<div
+  *booleanFeatureFlag="'isFeatureEnabled'; default: true; domain: 'userDomain'; else: booleanFeatureElse; initializing: booleanFeatureInitializing; reconciling: booleanFeatureReconciling">
+  This is shown when the feature flag is enabled.
+</div>
+<ng-template #booleanFeatureElse>
+  This is shown when the feature flag is disabled.
+</ng-template>
+<ng-template #booleanFeatureInitializing>
+  This is shown when the feature flag is initializing.
+</ng-template>
+<ng-template #booleanFeatureReconciling>
+  This is shown when the feature flag is reconciling.
+</ng-template>
+```
+
+##### Number Feature Flag
+
+```html
+<div
+  *numberFeatureFlag="'discountRate'; value: 10; default: 5; domain: 'userDomain'; else: numberFeatureElse; initializing: numberFeatureInitializing; reconciling: numberFeatureReconciling">
+  This is shown when the feature flag matches the specified discount rate.
+</div>
+<ng-template #numberFeatureElse>
+  This is shown when the feature flag does not match the specified discount rate.
+</ng-template>
+<ng-template #numberFeatureInitializing>
+  This is shown when the feature flag is initializing.
+</ng-template>
+<ng-template #numberFeatureReconciling>
+  This is shown when the feature flag is reconciling.
+</ng-template>
+```
+
+##### String Feature Flag
+
+```html
+<div
+  *stringFeatureFlag="'themeColor'; value: 'dark'; default: 'light'; domain: 'userDomain'; else: stringFeatureElse; initializing: stringFeatureInitializing; reconciling: stringFeatureReconciling">
+  This is shown when the feature flag matches the specified theme color.
+</div>
+<ng-template #stringFeatureElse>
+  This is shown when the feature flag does not match the specified theme color.
+</ng-template>
+<ng-template #stringFeatureInitializing>
+  This is shown when the feature flag is initializing.
+</ng-template>
+<ng-template #stringFeatureReconciling>
+  This is shown when the feature flag is reconciling.
+</ng-template>
+```
+
+##### Object Feature Flag
+
+```html
+<div
+  *objectFeatureFlag="'userConfig'; value: { theme: 'dark' }; default: { theme: 'light' }; domain: 'userDomain'; else: objectFeatureElse; initializing: objectFeatureInitializing; reconciling: objectFeatureReconciling">
+  This is shown when the feature flag matches the specified user configuration.
+</div>
+<ng-template #objectFeatureElse>
+  This is shown when the feature flag does not match the specified user configuration.
+</ng-template>
+<ng-template #objectFeatureInitializing>
+  This is shown when the feature flag is initializing.
+</ng-template>
+<ng-template #objectFeatureReconciling>
+  This is shown when the feature flag is reconciling.
+</ng-template>
+```
+
+##### Opting-out of automatic re-rendering
+
+By default, the directive re-renders when the flag value changes or the context changes.
+
+In cases, this is not desired, re-rendering can be disabled for both events:
+
+```html
+<div *booleanFeatureFlag="'isFeatureEnabled'; default: true; updateOnContextChanged: false; updateOnConfigurationChanged: false;">
+  This is shown when the feature flag is enabled.
+</div>
+```
+
+##### Consuming the evaluation details
+
+The `evaluation details` can be used when rendering the templates.
+The directives [`$implicit`](https://angular.dev/guide/directives/structural-directives#structural-directive-shorthand)
+value will be bound to the flag value and additionally the value `evaluationDetails` will be
+bound to the whole evaluation details.
+They can be referenced in all templates.
+
+The following example shows `value` being implicitly bound and `details` being bound to the evaluation details.
+
+```html
+<div
+  *stringFeatureFlag="'themeColor'; value: 'dark'; default: 'light'; else: stringFeatureElse; let value; let details = evaluationDetails">
+  It was a match!
+  The theme color is {{ value }} because of {{ details.reason }}
+</div>
+<ng-template #stringFeatureElse let-value let-details='evaluationDetails'>
+  It was no match!
+  The theme color is {{ value }} because of {{ details.reason }}
+</ng-template>
+```
+
+When the expected flag value is omitted, the template will always be rendered.
+This can be used to just render the flag value or details without conditional rendering.
+
+```html
+<div *stringFeatureFlag="'themeColor'; default: 'light'; let value;">
+  The theme color is {{ value }}.
+</div>
+```
+
+##### Setting evaluation context
+
+To set the initial evaluation context, you can add the `context` parameter to the `OpenFeatureModule` configuration.
+This context can be either an object or a factory function that returns an `EvaluationContext`.
+
+> [!TIP]
+> Updating the context can be done directly via the global OpenFeature API using `OpenFeature.setContext()`
+
+Here’s how you can define and use the initial client evaluation context:
+
+###### Using a static object
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { OpenFeatureModule } from '@openfeature/angular-sdk';
+
+const initialContext = {
+  user: {
+    id: 'user123',
+    role: 'admin',
+  }
+};
+
+@NgModule({
+  imports: [
+    CommonModule,
+    OpenFeatureModule.forRoot({
+      provider: yourFeatureProvider,
+      context: initialContext
+    })
+  ],
+})
+export class AppModule {}
+```
+
+###### Using a factory function
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { OpenFeatureModule, EvaluationContext } from '@openfeature/angular-sdk';
+
+const contextFactory = (): EvaluationContext => loadContextFromLocalStorage();
+
+@NgModule({
+  imports: [
+    CommonModule,
+    OpenFeatureModule.forRoot({
+      provider: yourFeatureProvider,
+      context: contextFactory
+    })
+  ],
+})
+export class AppModule {}
+```
+
+## FAQ and troubleshooting
+
+> I can import things form the `@openfeature/angular-sdk`, `@openfeature/web-sdk`, and `@openfeature/core`; which should I use?
+
+The `@openfeature/angular-sdk` re-exports everything from its peers (`@openfeature/web-sdk` and `@openfeature/core`), and adds the Angular-specific features.
+You can import everything from the `@openfeature/angular-sdk` directly.
+Avoid importing anything from `@openfeature/web-sdk` or `@openfeature/core`.
+
+## Resources
+
+- [Example repo](https://github.com/open-feature/angular-test-app)

packages/angular/projects/angular-sdk/ng-package.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/angular",
+  "keepLifecycleScripts": true,
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

packages/angular/projects/angular-sdk/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@openfeature/angular-sdk",
+  "version": "0.0.16",
+  "description": "OpenFeature Angular SDK",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-feature/js-sdk.git"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-feature/js-sdk/issues"
+  },
+  "homepage": "https://github.com/open-feature/js-sdk#readme",
+  "scripts": {
+    "current-published-version": "npm show $npm_package_name@$npm_package_version version",
+    "current-version": "echo $npm_package_version",
+    "prepack": "shx cp ./../../../../LICENSE ./LICENSE"
+  },
+  "peerDependencies": {
+    "@angular/common": "^16.2.12 || ^17.3.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
+    "@angular/core": "^16.2.12 || ^17.3.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
+    "@openfeature/web-sdk": "^1.4.1"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@openfeature/core": "^1.8.1",
+    "@openfeature/web-sdk": "^1.5.0",
+    "@angular/common": "^20.1.2",
+    "@angular/core": "^20.1.2"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "openfeature",
+    "feature",
+    "flags",
+    "toggles",
+    "browser",
+    "web",
+    "angular"
+  ]
+}

packages/angular/projects/angular-sdk/src/lib/feature-flag.directive.spec.ts

@@ -0,0 +1,608 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { Component, Input } from '@angular/core';
+import { OpenFeatureModule } from './open-feature.module';
+import { By } from '@angular/platform-browser';
+import { Client, ClientProviderEvents, FlagValue, InMemoryProvider, OpenFeature } from '@openfeature/web-sdk';
+import { TestingProvider } from '../test/test.utils';
+import { v4 } from 'uuid';
+import {
+  BooleanFeatureFlagDirective,
+  NumberFeatureFlagDirective,
+  ObjectFeatureFlagDirective,
+  StringFeatureFlagDirective,
+} from './feature-flag.directive';
+
+@Component({
+  standalone: true,
+  imports: [
+    BooleanFeatureFlagDirective,
+    NumberFeatureFlagDirective,
+    StringFeatureFlagDirective,
+    ObjectFeatureFlagDirective,
+  ],
+  template: `
+    <ng-container>
+      <div class="case-1">
+        <div *booleanFeatureFlag="'test-flag'; default: true; domain: domain" class="flag-status">Flag On</div>
+      </div>
+      <div class="case-2">
+        <div *booleanFeatureFlag="'test-flag'; default: true; else: elseTemplate; domain: domain" class="flag-status">
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+      <div class="case-3">
+        <div
+          *booleanFeatureFlag="'test-flag'; default: false; initializing: initializingTemplate; domain: domain"
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #initializingTemplate>
+          <div class="flag-status">Initializing</div>
+        </ng-template>
+      </div>
+      <div class="case-4">
+        <div
+          *booleanFeatureFlag="'test-flag'; default: false; reconciling: reconcilingTemplate; domain: domain"
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #reconcilingTemplate>
+          <div class="flag-status">Reconciling</div>
+        </ng-template>
+      </div>
+      <div class="case-5">
+        <div
+          *booleanFeatureFlag="
+            'test-flag';
+            default: false;
+            else: elseTemplate;
+            initializing: initializingTemplate;
+            reconciling: reconcilingTemplate;
+            domain: domain
+          "
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+        <ng-template #initializingTemplate>
+          <div class="flag-status">Initializing</div>
+        </ng-template>
+        <ng-template #reconcilingTemplate>
+          <div class="flag-status">Reconciling</div>
+        </ng-template>
+      </div>
+      <div class="case-6">
+        <div
+          *booleanFeatureFlag="specialFlagKey; default: true; else: elseTemplate; domain: domain"
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+      <div class="case-7">
+        <div
+          *numberFeatureFlag="'test-flag'; default: 0; value: 1; else: elseTemplate; domain: domain"
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+      <div class="case-8">
+        <div
+          *stringFeatureFlag="'test-flag'; default: 'default'; value: 'on'; else: elseTemplate; domain: domain"
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+      <div class="case-9">
+        <div
+          *objectFeatureFlag="
+            'test-flag';
+            default: {};
+            value: { prop2: true, prop1: true };
+            else: elseTemplate;
+            domain: domain
+          "
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+      <div class="case-10">
+        <div
+          *booleanFeatureFlag="
+            'test-flag';
+            default: false;
+            domain: domain;
+            else: elseTemplateWithContext;
+            let value;
+            let evaluationDetails = evaluationDetails
+          "
+          class="flag-status"
+        >
+          then {{ value }} {{ evaluationDetails.reason }}
+        </div>
+        <ng-template #elseTemplateWithContext let-value let-evaluationDetails="evaluationDetails">
+          <div class="flag-status">else {{ value }} {{ evaluationDetails.reason }}</div>
+        </ng-template>
+      </div>
+      <div class="case-11">
+        <div
+          *stringFeatureFlag="'test-flag'; default: 'default'; domain: domain; let value = $implicit"
+          class="flag-status"
+        >
+          {{ value }}
+        </div>
+      </div>
+      <div class="case-12">
+        <div
+          *booleanFeatureFlag="
+            'test-flag';
+            default: true;
+            else: elseTemplate;
+            domain: domain;
+            updateOnConfigurationChanged: false
+          "
+          class="flag-status"
+        >
+          Flag On
+        </div>
+        <ng-template #elseTemplate>
+          <div class="flag-status">Flag Off</div>
+        </ng-template>
+      </div>
+    </ng-container>
+  `,
+})
+class TestComponent {
+  @Input() domain: string;
+  @Input() specialFlagKey: string = 'test-flag';
+  protected readonly JSON = JSON;
+}
+
+describe('FeatureFlagDirective', () => {
+  describe('thenTemplate', () => {
+    it('should not be rendered if disabled by the flag', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+
+      await expectAmountElements(fixture, 'case-1', 0);
+    });
+
+    it('should be rendered if enabled by the flag', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+
+      await expectRenderedText(fixture, 'case-2', 'Flag On');
+    });
+  });
+
+  describe('elseTemplate', () => {
+    it('should not be rendered if not existent but enabled by the flag', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+
+      await expectAmountElements(fixture, 'case-1', 0);
+    });
+
+    it('should not be rendered if existent but disabled by the flag', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-2', 'Flag On');
+    });
+
+    it('should be rendered if existent and enabled by the flag', async () => {
+      const { fixture, provider } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-2', 'Flag On');
+
+      await updateFlagValue(provider, false);
+      fixture.detectChanges(); // Ensure change detection after flag update
+      await expectRenderedText(fixture, 'case-2', 'Flag Off');
+    });
+  });
+
+  describe('initializingTemplate', () => {
+    it('should not be rendered if provider is ready', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+
+      await expectRenderedText(fixture, 'case-3', 'Flag On');
+    });
+
+    it('should be rendered if provider is not ready', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+        providerInitDelay: 1000,
+      });
+
+      await expectRenderedText(fixture, 'case-3', 'Initializing');
+    });
+
+    it('should render until the provider is initialized', async () => {
+      const { fixture, client } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+        providerInitDelay: 1000,
+      });
+
+      await expectRenderedText(fixture, 'case-3', 'Initializing');
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-3', 'Flag On');
+    });
+  });
+
+  describe('reconcilingTemplate', () => {
+    it('should not be rendered if provider is ready', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+
+      await expectRenderedText(fixture, 'case-3', 'Flag On');
+    });
+
+    it('should be rendered while provider is reconciling', async () => {
+      const { fixture, domain, client } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+        providerInitDelay: 500,
+      });
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-4', 'Flag On');
+
+      const setContextPromise = OpenFeature.setContext(domain, { newCtx: true });
+      await expectRenderedText(fixture, 'case-4', 'Reconciling');
+
+      await setContextPromise;
+      await expectRenderedText(fixture, 'case-4', 'Flag On');
+    });
+  });
+
+  describe('complex case', () => {
+    it('should use initializing, then, else and reconciling in one go', async () => {
+      const { fixture, provider, client, domain } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+        providerInitDelay: 500,
+      });
+
+      // Initializing
+      await expectRenderedText(fixture, 'case-5', 'Initializing');
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-5', 'Flag On');
+
+      // Updating
+      await updateFlagValue(provider, false);
+      await expectRenderedText(fixture, 'case-5', 'Flag Off');
+
+      // Reconciling
+      const setContextPromise = OpenFeature.setContext(domain, { newCtx: true });
+      await expectRenderedText(fixture, 'case-5', 'Reconciling');
+      await setContextPromise;
+      await expectRenderedText(fixture, 'case-5', 'Flag Off');
+
+      // Updating 2
+      await updateFlagValue(provider, true);
+      await expectRenderedText(fixture, 'case-5', 'Flag On');
+    });
+
+    it('should evaluate on flag key change', async () => {
+      const { fixture, client } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+          'new-test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-6', 'Flag On');
+
+      fixture.componentRef.setInput('specialFlagKey', 'new-test-flag');
+      await fixture.whenStable();
+
+      await expectRenderedText(fixture, 'case-6', 'Flag Off');
+    });
+
+    it('should opt-out of re-rendering when flag value changes', async () => {
+      const { fixture, client, provider } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+          'new-test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-12', 'Flag On');
+
+      await updateFlagValue(provider, false);
+      await expectRenderedText(fixture, 'case-12', 'Flag On');
+    });
+
+    it('should evaluate on flag domain change', async () => {
+      const { fixture, client } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await waitForClientReady(client);
+      await expectRenderedText(fixture, 'case-6', 'Flag On');
+
+      const newDomain = v4();
+      const newProvider = new TestingProvider(
+        {
+          'test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+        0,
+      );
+      await OpenFeature.setProviderAndWait(newDomain, newProvider);
+
+      fixture.componentRef.setInput('domain', newDomain);
+      await fixture.whenStable();
+
+      await expectRenderedText(fixture, 'case-6', 'Flag Off');
+    });
+  });
+
+  describe('numberFeatureFlag', () => {
+    it('should render thenTemplate on match and else elseTemplate  ', async () => {
+      const { fixture, provider } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: 1 },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-7', 'Flag On');
+
+      await updateFlagValue(provider, 2);
+      await expectRenderedText(fixture, 'case-7', 'Flag Off');
+    });
+  });
+
+  describe('stringFeatureFlag', () => {
+    it('should render thenTemplate on match and else elseTemplate  ', async () => {
+      const { fixture, provider } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: 'on' },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-8', 'Flag On');
+
+      await updateFlagValue(provider, 'another-value');
+      await expectRenderedText(fixture, 'case-8', 'Flag Off');
+    });
+  });
+
+  describe('objectFeatureFlag', () => {
+    it('should render thenTemplate on match and else elseTemplate', async () => {
+      const { fixture, provider } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: { prop1: true, prop2: true } },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-9', 'Flag On');
+
+      await updateFlagValue(provider, { prop2: 'string' });
+      await expectRenderedText(fixture, 'case-9', 'Flag Off');
+    });
+  });
+
+  describe('context', () => {
+    it('should render thenTemplate from context', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: true },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-10', 'then true STATIC');
+    });
+
+    it('should render elseTemplate from context', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: false },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-10', 'else false STATIC');
+    });
+
+    it('should always render if no expected value is given', async () => {
+      const { fixture } = await createTestingModule({
+        flagConfiguration: {
+          'test-flag': {
+            variants: { default: 'flag-value' },
+            defaultVariant: 'default',
+            disabled: false,
+          },
+        },
+      });
+      await expectRenderedText(fixture, 'case-11', 'flag-value');
+    });
+  });
+});
+
+async function createTestingModule(config?: {
+  flagConfiguration?: ConstructorParameters<typeof InMemoryProvider>[0];
+  providerInitDelay?: number;
+}): Promise<{ fixture: ComponentFixture<TestComponent>; provider: TestingProvider; domain: string; client: Client }> {
+  const domain = v4();
+  const provider = new TestingProvider(config?.flagConfiguration ?? {}, config?.providerInitDelay ?? 0);
+
+  const fixture = TestBed.configureTestingModule({
+    imports: [
+      OpenFeatureModule.forRoot({ provider: new InMemoryProvider(), domainBoundProviders: { [domain]: provider } }),
+      TestComponent,
+    ],
+  }).createComponent(TestComponent);
+
+  fixture.componentRef.setInput('domain', domain);
+  await fixture.whenStable();
+
+  const client = OpenFeature.getClient(domain);
+  if (!config.providerInitDelay) {
+    await waitForClientReady(client);
+  }
+
+  return { provider, domain, client, fixture };
+}
+
+async function waitForClientReady(client: Client) {
+  await new Promise((resolve) => client.addHandler(ClientProviderEvents.Ready, resolve));
+}
+
+async function updateFlagValue<T extends FlagValue>(provider: TestingProvider, value: T) {
+  await provider.putConfiguration({
+    'test-flag': {
+      variants: { default: value },
+      defaultVariant: 'default',
+      disabled: false,
+    },
+  });
+}
+
+async function getElements(fixture: ComponentFixture<TestComponent>, testCase: string) {
+  fixture.detectChanges();
+  await fixture.whenStable();
+  return fixture.debugElement.queryAll(By.css(`.${testCase} .flag-status`));
+}
+
+async function expectAmountElements(fixture: ComponentFixture<TestComponent>, testCase: string, amount: number) {
+  const divElements = await getElements(fixture, testCase);
+  expect(divElements.length).toEqual(amount);
+}
+
+async function expectRenderedText(fixture: ComponentFixture<TestComponent>, testCase: string, rendered: string) {
+  const divElements = await getElements(fixture, testCase);
+  expect(divElements.length).toEqual(1);
+  expect(divElements[0].nativeElement.textContent.trim()).toBe(rendered);
+}

packages/angular/projects/angular-sdk/src/lib/feature-flag.directive.ts

@@ -0,0 +1,706 @@
+import {
+  ChangeDetectorRef,
+  Directive,
+  EmbeddedViewRef,
+  Input,
+  OnChanges,
+  OnDestroy,
+  OnInit,
+  TemplateRef,
+  ViewContainerRef,
+  inject,
+} from '@angular/core';
+import {
+  Client,
+  ClientProviderEvents,
+  ClientProviderStatus,
+  EvaluationDetails,
+  EventHandler,
+  FlagValue,
+  JsonValue,
+  OpenFeature,
+} from '@openfeature/web-sdk';
+
+class FeatureFlagDirectiveContext<T extends FlagValue> {
+  $implicit!: T;
+  evaluationDetails: EvaluationDetails<T>;
+
+  constructor(details: EvaluationDetails<T>) {
+    this.$implicit = details.value;
+    this.evaluationDetails = details;
+  }
+}
+
+@Directive({
+  standalone: true,
+  selector: '[featureFlag]',
+})
+export abstract class FeatureFlagDirective<T extends FlagValue> implements OnInit, OnDestroy, OnChanges {
+  protected _changeDetectorRef: ChangeDetectorRef;
+  protected _viewContainerRef: ViewContainerRef;
+
+  protected _featureFlagDefault: T;
+  protected _featureFlagDomain: string | undefined;
+
+  protected _featureFlagKey: string;
+  protected _featureFlagValue?: T;
+
+  protected _client: Client;
+  protected _lastEvaluationResult: EvaluationDetails<T>;
+
+  protected _readyHandler: EventHandler<ClientProviderEvents.Ready> | null = null;
+  protected _flagChangeHandler: EventHandler<ClientProviderEvents.ConfigurationChanged> | null = null;
+  protected _contextChangeHandler: EventHandler<ClientProviderEvents.Error> | null = null;
+  protected _reconcilingHandler: EventHandler<ClientProviderEvents.Reconciling> | null = null;
+
+  protected _updateOnContextChanged: boolean = true;
+  protected _updateOnConfigurationChanged: boolean = true;
+
+  protected _thenTemplateRef: TemplateRef<FeatureFlagDirectiveContext<T>> | null;
+  protected _thenViewRef: EmbeddedViewRef<unknown> | null;
+
+  protected _elseTemplateRef: TemplateRef<FeatureFlagDirectiveContext<T>> | null;
+  protected _elseViewRef: EmbeddedViewRef<unknown> | null;
+
+  protected _initializingTemplateRef: TemplateRef<FeatureFlagDirectiveContext<T>> | null;
+  protected _initializingViewRef: EmbeddedViewRef<unknown> | null;
+
+  protected _reconcilingTemplateRef: TemplateRef<FeatureFlagDirectiveContext<T>> | null;
+  protected _reconcilingViewRef: EmbeddedViewRef<unknown> | null;
+
+  protected constructor() {}
+
+  set featureFlagDomain(domain: string | undefined) {
+    /**
+     * We have to handle the change of the domain explicitly because we need to get a new client when the domain changes.
+     * This can not be done if we simply relay the onChanges method.
+     */
+    this._featureFlagDomain = domain;
+    this.initClient();
+  }
+
+  ngOnInit(): void {
+    this.initClient();
+  }
+
+  ngOnChanges(): void {
+    this._flagChangeHandler?.();
+  }
+
+  ngOnDestroy(): void {
+    if (this._client) {
+      this.disposeClient(this._client);
+      this._client = null;
+    }
+  }
+
+  private initClient(): void {
+    if (this._client) {
+      this.disposeClient(this._client);
+    }
+    this._client = OpenFeature.getClient(this._featureFlagDomain);
+
+    const baseHandler = () => {
+      const result = this.getFlagDetails(this._featureFlagKey, this._featureFlagDefault);
+      this.onFlagValue(result, this._client.providerStatus);
+    };
+
+    this._flagChangeHandler = () => {
+      if (this._updateOnConfigurationChanged) {
+        baseHandler();
+      }
+    };
+
+    this._contextChangeHandler = () => {
+      if (this._updateOnContextChanged) {
+        baseHandler();
+      }
+    };
+
+    this._readyHandler = () => baseHandler();
+    this._reconcilingHandler = () => baseHandler();
+
+    this._client.addHandler(ClientProviderEvents.ConfigurationChanged, this._flagChangeHandler);
+    this._client.addHandler(ClientProviderEvents.ContextChanged, this._contextChangeHandler);
+    this._client.addHandler(ClientProviderEvents.Ready, this._readyHandler);
+    this._client.addHandler(ClientProviderEvents.Reconciling, this._reconcilingHandler);
+  }
+
+  private disposeClient(client: Client) {
+    if (this._contextChangeHandler()) {
+      client.removeHandler(ClientProviderEvents.ContextChanged, this._contextChangeHandler);
+    }
+
+    if (this._flagChangeHandler) {
+      client.removeHandler(ClientProviderEvents.ConfigurationChanged, this._flagChangeHandler);
+    }
+
+    if (this._readyHandler) {
+      client.removeHandler(ClientProviderEvents.Ready, this._readyHandler);
+    }
+
+    if (this._reconcilingHandler) {
+      client.removeHandler(ClientProviderEvents.Reconciling, this._reconcilingHandler);
+    }
+  }
+
+  protected getFlagDetails(flagKey: string, defaultValue: T): EvaluationDetails<T> {
+    if (typeof defaultValue === 'boolean') {
+      return this._client.getBooleanDetails(flagKey, defaultValue) as EvaluationDetails<T>;
+    } else if (typeof defaultValue === 'number') {
+      return this._client.getNumberDetails(flagKey, defaultValue) as EvaluationDetails<T>;
+    } else if (typeof defaultValue === 'string') {
+      return this._client.getStringDetails(flagKey, defaultValue) as EvaluationDetails<T>;
+    } else {
+      return this._client.getObjectDetails(flagKey, defaultValue) as EvaluationDetails<T>;
+    }
+  }
+
+  protected onFlagValue(result: EvaluationDetails<T>, status: ClientProviderStatus): void {
+    const shouldInitialize = this._initializingTemplateRef && status === ClientProviderStatus.NOT_READY;
+    const shouldReconcile = this._reconcilingTemplateRef && status === ClientProviderStatus.RECONCILING;
+
+    const context = new FeatureFlagDirectiveContext(result);
+
+    const resultChanged = !deepEqual(this._lastEvaluationResult, result);
+    const isValueMatch = !this._featureFlagValue || deepEqual(result.value, this._featureFlagValue);
+
+    if (this._initializingViewRef && shouldInitialize && !resultChanged) {
+      return;
+    } else if (this._reconcilingViewRef && shouldReconcile && !resultChanged) {
+      return;
+    } else if (this._thenViewRef && isValueMatch && !shouldInitialize && !shouldReconcile && !resultChanged) {
+      return;
+    } else if (this._elseViewRef && !isValueMatch && !shouldInitialize && !shouldReconcile && !resultChanged) {
+      return;
+    }
+
+    this._lastEvaluationResult = result;
+    this._viewContainerRef.clear();
+    this._initializingViewRef = null;
+    this._reconcilingViewRef = null;
+    this._thenViewRef = null;
+    this._elseViewRef = null;
+
+    if (this._initializingTemplateRef && status === ClientProviderStatus.NOT_READY) {
+      this._initializingViewRef = this._viewContainerRef.createEmbeddedView(this._initializingTemplateRef, context);
+    } else if (this._reconcilingTemplateRef && status === ClientProviderStatus.RECONCILING) {
+      this._reconcilingViewRef = this._viewContainerRef.createEmbeddedView(this._reconcilingTemplateRef, context);
+    } else if (isValueMatch) {
+      this._thenViewRef = this._viewContainerRef.createEmbeddedView(this._thenTemplateRef, context);
+    } else if (this._elseTemplateRef) {
+      this._elseViewRef = this._viewContainerRef.createEmbeddedView(this._elseTemplateRef, context);
+    }
+
+    this._changeDetectorRef.markForCheck();
+  }
+}
+
+/**
+ * A structural directive that conditionally includes a template based on the evaluation
+ * of a boolean feature flag.
+ * When the flag evaluates to true, Angular renders the template provided in a `then` clause,
+ * and when false, Angular renders the template provided in an optional `else` clause.
+ * The default template for the `else` clause is blank.
+ *
+ * Usage examples:
+ *
+ * ```
+ * <div *booleanFeatureFlag="'flagKey'; default: false; let value">{{ value }}</div>
+ * ```
+ * ```
+ * <div *booleanFeatureFlag="flagKey; default: false; else: elseTemplate">Content to render when flag is true.</div>
+ * <ng-template #elseTemplate>Content to render when flag is false.</ng-template>
+ * ```
+ *
+ * @usageNotes
+ *
+ * You can specify templates for other statuses such as initializing and reconciling.
+ *
+ * ```
+ * <div *booleanFeatureFlag="flagKey; default:true; else: elseTemplate; initializing: initializingTemplate; reconciling: reconcilingTemplate">Content to render when flag is true.</div>
+ * <ng-template #elseTemplate>Content to render when flag is false.</ng-template>
+ * <ng-template #initializingTemplate>Loading...</ng-template>
+ * <ng-template #reconcilingTemplate>Reconfiguring...</ng-template>
+ * ```
+ *
+ */
+@Directive({
+  standalone: true,
+  selector: '[booleanFeatureFlag]',
+})
+export class BooleanFeatureFlagDirective extends FeatureFlagDirective<boolean> implements OnChanges {
+  override _changeDetectorRef = inject(ChangeDetectorRef);
+  override _viewContainerRef = inject(ViewContainerRef);
+  override _thenTemplateRef = inject<TemplateRef<FeatureFlagDirectiveContext<boolean>>>(TemplateRef);
+
+  /**
+   * The key of the boolean feature flag.
+   */
+  @Input({ required: true }) booleanFeatureFlag: string;
+
+  /**
+   * The default value for the boolean feature flag.
+   */
+  @Input({ required: true }) booleanFeatureFlagDefault: boolean;
+
+  constructor() {
+    super();
+  }
+
+  override ngOnChanges() {
+    this._featureFlagKey = this.booleanFeatureFlag;
+    this._featureFlagDefault = this.booleanFeatureFlagDefault;
+    this._featureFlagValue = true;
+    super.ngOnChanges();
+  }
+
+  /**
+   * The domain of the boolean feature flag.
+   */
+  @Input({ required: false })
+  set booleanFeatureFlagDomain(domain: string | undefined) {
+    super.featureFlagDomain = domain;
+  }
+
+  /**
+   * Update the component if the provider emits a ConfigurationChanged event.
+   * Set to false to prevent components from re-rendering when flag value changes
+   * are received by the associated provider.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set booleanFeatureFlagUpdateOnConfigurationChanged(enabled: boolean | undefined) {
+    this._updateOnConfigurationChanged = enabled ?? true;
+  }
+
+  /**
+   * Update the component when the OpenFeature context changes.
+   * Set to false to prevent components from re-rendering when attributes which
+   * may be factors in flag evaluation change.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set booleanFeatureFlagUpdateOnContextChanged(enabled: boolean | undefined) {
+    this._updateOnContextChanged = enabled ?? true;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is false.
+   */
+  @Input()
+  set booleanFeatureFlagElse(tpl: TemplateRef<FeatureFlagDirectiveContext<boolean>>) {
+    this._elseTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the provider is not ready.
+   */
+  @Input()
+  set booleanFeatureFlagInitializing(tpl: TemplateRef<FeatureFlagDirectiveContext<boolean>>) {
+    this._initializingTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the provider is reconciling.
+   */
+  @Input()
+  set booleanFeatureFlagReconciling(tpl: TemplateRef<FeatureFlagDirectiveContext<boolean>>) {
+    this._reconcilingTemplateRef = tpl;
+  }
+}
+
+/**
+ * A structural directive that conditionally includes a template based on the evaluation
+ * of a number feature flag.
+ * When the flag matches the provided value or no expected value is given, Angular renders the template provided
+ * in a `then` clause, and when it doesn't match, Angular renders the template provided
+ * in an optional `else` clause.
+ * The default template for the `else` clause is blank.
+ *
+ * Usage examples:
+ *
+ * ```
+ * <div *numberFeatureFlag="'flagKey'; default: 0; let value">{{ value }}</div>
+ * ```
+ * ```
+ * <div *numberFeatureFlag="'flagKey'; value: 1; default: 0; else: elseTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * ```
+ *
+ * @usageNotes
+ *
+ * You can specify templates for other statuses such as initializing and reconciling.
+ *
+ * ```
+ * <div *numberFeatureFlag="flagKey; default: 0; value: flagValue; else: elseTemplate; initializing: initializingTemplate; reconciling: reconcilingTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * <ng-template #initializingTemplate>Loading...</ng-template>
+ * <ng-template #reconcilingTemplate>Reconfiguring...</ng-template>
+ * ```
+ *
+ */
+@Directive({
+  standalone: true,
+  selector: '[numberFeatureFlag]',
+})
+export class NumberFeatureFlagDirective extends FeatureFlagDirective<number> implements OnChanges {
+  override _changeDetectorRef = inject(ChangeDetectorRef);
+  override _viewContainerRef = inject(ViewContainerRef);
+  override _thenTemplateRef = inject<TemplateRef<FeatureFlagDirectiveContext<number>>>(TemplateRef);
+
+  /**
+   * The key of the number feature flag.
+   */
+  @Input({ required: true }) numberFeatureFlag: string;
+
+  /**
+   * The default value for the number feature flag.
+   */
+  @Input({ required: true }) numberFeatureFlagDefault: number;
+
+  /**
+   * The expected value of this number feature flag, for which the `then` template should be rendered.
+   */
+  @Input({ required: false }) numberFeatureFlagValue?: number;
+
+  constructor() {
+    super();
+  }
+
+  override ngOnChanges() {
+    this._featureFlagKey = this.numberFeatureFlag;
+    this._featureFlagDefault = this.numberFeatureFlagDefault;
+    this._featureFlagValue = this.numberFeatureFlagValue;
+    super.ngOnChanges();
+  }
+
+  /**
+   * The domain of the number feature flag.
+   */
+  @Input({ required: false })
+  set numberFeatureFlagDomain(domain: string | undefined) {
+    super.featureFlagDomain = domain;
+  }
+
+  /**
+   * Update the component if the provider emits a ConfigurationChanged event.
+   * Set to false to prevent components from re-rendering when flag value changes
+   * are received by the associated provider.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set numberFeatureFlagUpdateOnConfigurationChanged(enabled: boolean | undefined) {
+    this._updateOnConfigurationChanged = enabled ?? true;
+  }
+
+  /**
+   * Update the component when the OpenFeature context changes.
+   * Set to false to prevent components from re-rendering when attributes which
+   * may be factors in flag evaluation change.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set numberFeatureFlagUpdateOnContextChanged(enabled: boolean | undefined) {
+    this._updateOnContextChanged = enabled ?? true;
+  }
+
+  /**
+   * Template to be displayed when the feature flag does not match value.
+   */
+  @Input()
+  set numberFeatureFlagElse(tpl: TemplateRef<FeatureFlagDirectiveContext<number>>) {
+    this._elseTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is not ready.
+   */
+  @Input()
+  set numberFeatureFlagInitializing(tpl: TemplateRef<FeatureFlagDirectiveContext<number>>) {
+    this._initializingTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is not ready.
+   */
+  @Input()
+  set numberFeatureFlagReconciling(tpl: TemplateRef<FeatureFlagDirectiveContext<number>>) {
+    this._reconcilingTemplateRef = tpl;
+  }
+}
+
+/**
+ * A structural directive that conditionally includes a template based on the evaluation
+ * of a string feature flag.
+ * When the flag matches the provided value or no expected value is given, Angular renders the template provided
+ * in a `then` clause, and when it doesn't match, Angular renders the template provided
+ * in an optional `else` clause.
+ * The default template for the `else` clause is blank.
+ *
+ * Usage examples:
+ *
+ * ```
+ * <div *stringFeatureFlag="'flagKey'; default: 'default'; let value">{{ value }}</div>
+ * ```
+ * ```
+ * <div *stringFeatureFlag="flagKey; default: 'default'; value: flagValue; else: elseTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * ```
+ *
+ * @usageNotes
+ *
+ * You can specify templates for other statuses such as initializing and reconciling.
+ *
+ * ```
+ * <div *stringFeatureFlag="flagKey; default: 'default'; value: flagValue; else: elseTemplate; initializing: initializingTemplate; reconciling: reconcilingTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * <ng-template #initializingTemplate>Loading...</ng-template>
+ * <ng-template #reconcilingTemplate>Reconfiguring...</ng-template>
+ * ```
+ *
+ */
+@Directive({
+  standalone: true,
+  selector: '[stringFeatureFlag]',
+})
+export class StringFeatureFlagDirective extends FeatureFlagDirective<string> implements OnChanges {
+  override _changeDetectorRef = inject(ChangeDetectorRef);
+  override _viewContainerRef = inject(ViewContainerRef);
+  override _thenTemplateRef = inject<TemplateRef<FeatureFlagDirectiveContext<string>>>(TemplateRef);
+
+  /**
+   * The key of the string feature flag.
+   */
+  @Input({ required: true }) stringFeatureFlag: string;
+
+  /**
+   * The default value for the string feature flag.
+   */
+  @Input({ required: true }) stringFeatureFlagDefault: string;
+
+  /**
+   * The expected value of this string feature flag, for which the `then` template should be rendered.
+   */
+  @Input({ required: false }) stringFeatureFlagValue?: string;
+
+  constructor() {
+    super();
+  }
+
+  override ngOnChanges() {
+    this._featureFlagKey = this.stringFeatureFlag;
+    this._featureFlagDefault = this.stringFeatureFlagDefault;
+    this._featureFlagValue = this.stringFeatureFlagValue;
+    super.ngOnChanges();
+  }
+
+  /**
+   * The domain for the string feature flag.
+   */
+  @Input({ required: false })
+  set stringFeatureFlagDomain(domain: string | undefined) {
+    super.featureFlagDomain = domain;
+  }
+
+  /**
+   * Update the component if the provider emits a ConfigurationChanged event.
+   * Set to false to prevent components from re-rendering when flag value changes
+   * are received by the associated provider.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set stringFeatureFlagUpdateOnConfigurationChanged(enabled: boolean | undefined) {
+    this._updateOnConfigurationChanged = enabled ?? true;
+  }
+
+  /**
+   * Update the component when the OpenFeature context changes.
+   * Set to false to prevent components from re-rendering when attributes which
+   * may be factors in flag evaluation change.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set stringFeatureFlagUpdateOnContextChanged(enabled: boolean | undefined) {
+    this._updateOnContextChanged = enabled ?? true;
+  }
+
+  /**
+   * Template to be displayed when the feature flag does not match value.
+   */
+  @Input()
+  set stringFeatureFlagElse(tpl: TemplateRef<FeatureFlagDirectiveContext<string>>) {
+    this._elseTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is not ready.
+   */
+  @Input()
+  set stringFeatureFlagInitializing(tpl: TemplateRef<FeatureFlagDirectiveContext<string>>) {
+    this._initializingTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is reconciling.
+   */
+  @Input()
+  set stringFeatureFlagReconciling(tpl: TemplateRef<FeatureFlagDirectiveContext<string>>) {
+    this._reconcilingTemplateRef = tpl;
+  }
+}
+
+/**
+ * A structural directive that conditionally includes a template based on the evaluation
+ * of an object feature flag.
+ * When the flag matches the provided value or no expected value is given, Angular renders the template provided
+ * in a `then` clause, and when it doesn't match, Angular renders the template provided
+ * in an optional `else` clause.
+ * The default template for the `else` clause is blank.
+ *
+ * Usage examples:
+ *
+ * ```
+ * <div *objectFeatureFlag="'flagKey'; default: {}; let value">{{ value }}</div>
+ * ```
+ * ```
+ * <div *objectFeatureFlag="flagKey; default: {}; value: flagValue; else: elseTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * ```
+ *
+ * @usageNotes
+ *
+ * You can specify templates for other statuses such as initializing and reconciling.
+ *
+ * ```
+ * <div *objectFeatureFlag="flagKey; default: {}; value: flagValue; else: elseTemplate; initializing: initializingTemplate; reconciling: reconcilingTemplate">Content to render when flag matches value.</div>
+ * <ng-template #elseTemplate>Content to render when flag does not match value.</ng-template>
+ * <ng-template #initializingTemplate>Loading...</ng-template>
+ * <ng-template #reconcilingTemplate>Reconfiguring...</ng-template>
+ * ```
+ *
+ */
+@Directive({
+  standalone: true,
+  selector: '[objectFeatureFlag]',
+})
+export class ObjectFeatureFlagDirective<T extends JsonValue> extends FeatureFlagDirective<T> implements OnChanges {
+  override _changeDetectorRef = inject(ChangeDetectorRef);
+  override _viewContainerRef = inject(ViewContainerRef);
+  override _thenTemplateRef = inject<TemplateRef<FeatureFlagDirectiveContext<T>>>(TemplateRef);
+
+  /**
+   * The key of the object feature flag.
+   */
+  @Input({ required: true }) objectFeatureFlag: string;
+
+  /**
+   * The default value for the object feature flag.
+   */
+  @Input({ required: true }) objectFeatureFlagDefault: T;
+
+  /**
+   * The expected value of this object feature flag, for which the `then` template should be rendered.
+   */
+  @Input({ required: false }) objectFeatureFlagValue?: T;
+
+  constructor() {
+    super();
+  }
+
+  override ngOnChanges() {
+    this._featureFlagKey = this.objectFeatureFlag;
+    this._featureFlagDefault = this.objectFeatureFlagDefault;
+    this._featureFlagValue = this.objectFeatureFlagValue;
+    super.ngOnChanges();
+  }
+
+  /**
+   * The domain for the object feature flag.
+   */
+  @Input({ required: false })
+  set objectFeatureFlagDomain(domain: string | undefined) {
+    super.featureFlagDomain = domain;
+  }
+
+  /**
+   * Update the component if the provider emits a ConfigurationChanged event.
+   * Set to false to prevent components from re-rendering when flag value changes
+   * are received by the associated provider.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set objectFeatureFlagUpdateOnConfigurationChanged(enabled: boolean | undefined) {
+    this._updateOnConfigurationChanged = enabled ?? true;
+  }
+
+  /**
+   * Update the component when the OpenFeature context changes.
+   * Set to false to prevent components from re-rendering when attributes which
+   * may be factors in flag evaluation change.
+   * Defaults to true.
+   */
+  @Input({ required: false })
+  set objectFeatureFlagUpdateOnContextChanged(enabled: boolean | undefined) {
+    this._updateOnContextChanged = enabled ?? true;
+  }
+
+  /**
+   * Template to be displayed when the feature flag does not match value.
+   */
+  @Input()
+  set objectFeatureFlagElse(tpl: TemplateRef<FeatureFlagDirectiveContext<T>>) {
+    this._elseTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is not ready.
+   */
+  @Input()
+  set objectFeatureFlagInitializing(tpl: TemplateRef<FeatureFlagDirectiveContext<T>>) {
+    this._initializingTemplateRef = tpl;
+  }
+
+  /**
+   * Template to be displayed when the feature flag is reconciling.
+   */
+  @Input()
+  set objectFeatureFlagReconciling(tpl: TemplateRef<FeatureFlagDirectiveContext<T>>) {
+    this._reconcilingTemplateRef = tpl;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deepEqual(obj1: any, obj2: any): boolean {
+  if (obj1 === obj2) {
+    // If both objects are identical
+    return true;
+  }
+
+  if (typeof obj1 !== 'object' || obj1 === null || typeof obj2 !== 'object' || obj2 === null) {
+    // One of them is not an object or one of them is null
+    return false;
+  }
+
+  const keys1 = Object.keys(obj1);
+  const keys2 = Object.keys(obj2);
+
+  if (keys1.length !== keys2.length) {
+    // Different number of properties
+    return false;
+  }
+
+  for (const key of keys1) {
+    if (!keys2.includes(key)) {
+      // obj2 does not have a property that obj1 has
+      return false;
+    }
+
+    // Recursive check for each property
+    if (!deepEqual(obj1[key], obj2[key])) {
+      return false;
+    }
+  }
+
+  return true;
+}

packages/angular/projects/angular-sdk/src/lib/open-feature.module.ts

@@ -0,0 +1,36 @@
+import { InjectionToken, ModuleWithProviders, NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { EvaluationContext, OpenFeature, Provider } from '@openfeature/web-sdk';
+
+export type EvaluationContextFactory = () => EvaluationContext;
+
+export interface OpenFeatureConfig {
+  provider: Provider;
+  domainBoundProviders?: Record<string, Provider>;
+  context?: EvaluationContext | EvaluationContextFactory;
+}
+
+export const OPEN_FEATURE_CONFIG_TOKEN = new InjectionToken<OpenFeatureConfig>('OPEN_FEATURE_CONFIG_TOKEN');
+
+@NgModule({
+  declarations: [],
+  imports: [CommonModule],
+  exports: [],
+})
+export class OpenFeatureModule {
+  static forRoot(config: OpenFeatureConfig): ModuleWithProviders<OpenFeatureModule> {
+    const context = typeof config.context === 'function' ? config.context() : config.context;
+    OpenFeature.setProvider(config.provider, context);
+
+    if (config.domainBoundProviders) {
+      Object.entries(config.domainBoundProviders).map(([domain, provider]) =>
+        OpenFeature.setProvider(domain, provider),
+      );
+    }
+
+    return {
+      ngModule: OpenFeatureModule,
+      providers: [{ provide: OPEN_FEATURE_CONFIG_TOKEN, useValue: config }],
+    };
+  }
+}

packages/angular/projects/angular-sdk/src/public-api.ts

@@ -0,0 +1,9 @@
+/*
+ * Public API Surface of angular
+ */
+
+export * from './lib/feature-flag.directive';
+export * from './lib/open-feature.module';
+
+// re-export the web-sdk so consumers can access that API from the angular-sdk
+export * from '@openfeature/web-sdk';

packages/angular/projects/angular-sdk/src/test-provider.ts

@@ -0,0 +1,3 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+
+export default [provideZonelessChangeDetection()];

packages/angular/projects/angular-sdk/src/test/test.utils.ts

@@ -0,0 +1,20 @@
+import { InMemoryProvider } from '@openfeature/web-sdk';
+
+export class TestingProvider extends InMemoryProvider {
+  constructor(
+    flagConfiguration: ConstructorParameters<typeof InMemoryProvider>[0],
+    private delay: number,
+  ) {
+    super(flagConfiguration);
+  }
+
+  // artificially delay our init (delaying PROVIDER_READY event)
+  async initialize(): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, this.delay));
+  }
+
+  // artificially delay context changes
+  async onContextChange(): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, this.delay));
+  }
+}

packages/angular/projects/angular-sdk/tsconfig.lib.json

@@ -0,0 +1,19 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": [],
+    "paths": {
+      "angular": [
+        "./dist/angular"
+      ],
+    }
+  },
+  "exclude": [
+    "**/*.spec.ts"
+  ]
+}

packages/angular/projects/angular-sdk/tsconfig.lib.prod.json

@@ -0,0 +1,15 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "paths": {
+    "angular": [
+      "./dist/angular"
+    ]
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

packages/angular/projects/angular-sdk/tsconfig.spec.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "types": [
+      "vitest/globals",
+      "node"
+    ],
+    "paths": {
+      "angular": [
+        "./dist/angular"
+      ]
+    },
+    "esModuleInterop": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": [
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts",
+    "src/test-provider.ts"
+  ]
+}

packages/angular/tsconfig.json

@@ -0,0 +1,42 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "paths": {
+      "angular": [
+        "./dist/angular"
+      ],
+      "@openfeature/core": [ "../shared/src" ],
+      "@openfeature/web-sdk": [ "../web/src" ]
+    },
+    "outDir": "./dist/out-tsc",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "declaration": false,
+    "experimentalDecorators": true,
+    "moduleResolution": "node",
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "ES2022",
+    "useDefineForClassFields": false,
+    "strictNullChecks": false,
+    "lib": [
+      "ES2022",
+      "dom"
+    ],
+  },
+  "angularCompilerOptions": {
+    "disableTypeScriptVersionCheck": true,
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}

packages/angular/tsconfig.spec.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "types": [
+      "vitest/globals",
+      "node"
+    ],
+    "esModuleInterop": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": [
+    "projects/angular-sdk/src/**/*.spec.ts",
+    "projects/angular-sdk/src/**/*.d.ts"
+  ]
+}

packages/angular/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});

packages/client/src/client/client.ts

@@ -1,12 +0,0 @@
-import { ClientMetadata, EvaluationLifeCycle, Eventing, ManageLogger } from '@openfeature/core';
-import { Features } from '../evaluation';
-import { ProviderStatus } from '../provider';
-import { ProviderEvents } from '../events';
-
-export interface Client extends EvaluationLifeCycle<Client>, Features, ManageLogger<Client>, Eventing<ProviderEvents> {
-  readonly metadata: ClientMetadata;
-  /**
-   * Returns the status of the associated provider.
-   */
-  readonly providerStatus: ProviderStatus;
-}

packages/client/src/hooks/hook.ts

@@ -1,3 +0,0 @@
-import { BaseHook, FlagValue } from '@openfeature/core';
-
-export type Hook = BaseHook<FlagValue, void, void>;

packages/nest/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.2.5](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.2.4...nestjs-sdk-v0.2.5) (2025-05-27)
+
+
+### ✨ New Features
+
+* adds RequireFlagsEnabled decorator ([#1159](https://github.com/open-feature/js-sdk/issues/1159)) ([59b8fe9](https://github.com/open-feature/js-sdk/commit/59b8fe904f053e4aa3d0c72631af34183ff54dc7))
+
+
+## [0.2.4](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.2.3...nestjs-sdk-v0.2.4) (2025-04-20)
+
+
+### 🧹 Chore
+
+* **nest:** allow nestjs version 11 ([#1176](https://github.com/open-feature/js-sdk/issues/1176)) ([42a3b39](https://github.com/open-feature/js-sdk/commit/42a3b39c2488002f249b37ce86794ef2f77eb31c))
+
+## [0.2.3](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.2.2...nestjs-sdk-v0.2.3) (2025-04-11)
+
+
+### 🧹 Chore
+
+* update sdk peer ([#1142](https://github.com/open-feature/js-sdk/issues/1142)) ([8bb6206](https://github.com/open-feature/js-sdk/commit/8bb620601e2b8dc7b62d717169b585bd1c886996))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @openfeature/server-sdk bumped from * to 1.18.0
+
+## [0.2.2](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.2.1-experimental...nestjs-sdk-v0.2.2) (2024-10-29)
+
+
+### 🧹 Chore
+
+* import type lint rule and fixes ([#1039](https://github.com/open-feature/js-sdk/issues/1039)) ([01fcb93](https://github.com/open-feature/js-sdk/commit/01fcb933d2cbd131a0f4a005173cdd1906087e18))
+
+## [0.2.1-experimental](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.2.0-experimental...nestjs-sdk-v0.2.1-experimental) (2024-06-11)
+
+
+### ✨ New Features
+
+* lower compilation target to es2015 ([#957](https://github.com/open-feature/js-sdk/issues/957)) ([c2d6c17](https://github.com/open-feature/js-sdk/commit/c2d6c1761ae19f937deaff2f011a0380f8af7350))
+
 ## [0.2.0-experimental](https://github.com/open-feature/js-sdk/compare/nestjs-sdk-v0.1.5-experimental...nestjs-sdk-v0.2.0-experimental) (2024-05-19)
 
 

packages/nest/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
   <!-- x-release-please-start-version -->
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/nestjs-sdk-v0.2.0-experimental">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.2.0-experimental&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/nestjs-sdk-v0.2.5">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.2.5&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -50,7 +50,7 @@ Capabilities include:
 
 ### Requirements
 
-- Node.js version 18+
+- Node.js version 20+
 - NestJS version 8+
 
 ### Install
@@ -72,10 +72,10 @@ yarn add @openfeature/nestjs-sdk @openfeature/server-sdk @openfeature/core
 
 The following list contains the peer dependencies of `@openfeature/nestjs-sdk` with its expected and compatible versions:
 
-* `@openfeature/server-sdk`: >=1.7.5
-* `@nestjs/common`: ^8.0.0 || ^9.0.0 || ^10.0.0
-* `@nestjs/core`: ^8.0.0 || ^9.0.0 || ^10.0.0
-* `rxjs`: ^6.0.0 || ^7.0.0 || ^8.0.0
+- `@openfeature/server-sdk`: >=1.7.5
+- `@nestjs/common`: ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0
+- `@nestjs/core`: ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0
+- `rxjs`: ^6.0.0 || ^7.0.0 || ^8.0.0
 
 The minimum required version of `@openfeature/server-sdk` currently is `1.7.5`.
 
@@ -152,6 +152,24 @@ export class OpenFeatureTestService {
 }
 ```
 
+#### Managing Controller or Route Access via Feature Flags
+
+The `RequireFlagsEnabled` decorator can be used to manage access to a controller or route based on the enabled state of a feature flag. The decorator will throw an exception if the required feature flag(s) are not enabled.
+
+```ts
+import { Controller, Get } from '@nestjs/common';
+import { RequireFlagsEnabled } from '@openfeature/nestjs-sdk';
+
+@Controller()
+export class OpenFeatureController {
+  @RequireFlagsEnabled({ flags: [{ flagKey: 'testBooleanFlag' }] })
+  @Get('/welcome')
+  public async welcome() {
+    return 'Welcome to this OpenFeature-enabled NestJS app!';
+  }
+}
+```
+
 ## Module additional information
 
 ### Flag evaluation context injection

packages/nest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/nestjs-sdk",
-  "version": "0.2.0-experimental",
+  "version": "0.2.5",
   "description": "OpenFeature Nest.js SDK",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -16,9 +16,10 @@
   "scripts": {
     "test": "jest --verbose",
     "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
     "clean": "shx rm -rf ./dist",
-    "build:esm": "esbuild src/index.ts --bundle --external:@nestjs/* --external:@openfeature/server-sdk --sourcemap --target=es2022 --platform=node --format=esm --outfile=./dist/esm/index.js --analyze",
-    "build:cjs": "esbuild src/index.ts --bundle --external:@nestjs/* --external:@openfeature/server-sdk --sourcemap --target=es2022 --platform=node --format=cjs --outfile=./dist/cjs/index.js --analyze",
+    "build:esm": "esbuild src/index.ts --bundle --external:@nestjs/* --external:@openfeature/server-sdk --sourcemap --target=es2015 --platform=node --format=esm --outfile=./dist/esm/index.js --analyze",
+    "build:cjs": "esbuild src/index.ts --bundle --external:@nestjs/* --external:@openfeature/server-sdk --sourcemap --target=es2015 --platform=node --format=cjs --outfile=./dist/cjs/index.js --analyze",
     "build:rollup-types": "rollup -c ../../rollup.config.mjs",
     "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:rollup-types",
     "postbuild": "shx cp ./../../package.esm.json ./dist/esm/package.json",
@@ -45,18 +46,18 @@
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
   "peerDependencies": {
-    "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0",
-    "@nestjs/core": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
     "rxjs": "^6.0.0 || ^7.0.0 || 8.0.0",
-    "@openfeature/server-sdk": ">=1.14.0"
+    "@openfeature/server-sdk": "^1.17.1"
   },
   "devDependencies": {
-    "@nestjs/common": "^10.3.6",
-    "@nestjs/core": "^10.3.6",
-    "@nestjs/platform-express": "^10.3.6",
-    "@nestjs/testing": "^10.3.6",
+    "@nestjs/common": "^11.0.20",
+    "@nestjs/core": "^11.0.20",
+    "@nestjs/platform-express": "^11.0.20",
+    "@nestjs/testing": "^11.0.20",
     "@openfeature/core": "*",
-    "@openfeature/server-sdk": "*",
+    "@openfeature/server-sdk": "1.18.0",
     "@types/supertest": "^6.0.0",
     "supertest": "^7.0.0"
   }

packages/nest/src/context-factory.ts

@@ -1,5 +1,6 @@
-import { EvaluationContext } from '@openfeature/core';
-import { ExecutionContext, Inject } from '@nestjs/common';
+import type { EvaluationContext } from '@openfeature/core';
+import type { ExecutionContext} from '@nestjs/common';
+import { Inject } from '@nestjs/common';
 
 /**
  * A factory function for creating an OpenFeature {@link EvaluationContext} from Nest {@link ExecutionContext}.

packages/nest/src/evaluation-context-interceptor.ts

@@ -1,5 +1,7 @@
-import { CallHandler, ExecutionContext, Inject, Injectable, NestInterceptor } from '@nestjs/common';
-import { ContextFactory, ContextFactoryToken } from './context-factory';
+import type { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
+import type { ContextFactory} from './context-factory';
+import { ContextFactoryToken } from './context-factory';
 import { Observable } from 'rxjs';
 import { OpenFeature } from '@openfeature/server-sdk';
 import { OpenFeatureModule } from './open-feature.module';

packages/nest/src/feature.decorator.ts

@@ -1,14 +1,10 @@
 import { createParamDecorator, Inject } from '@nestjs/common';
-import {
-  EvaluationContext,
-  EvaluationDetails,
-  FlagValue,
-  JsonValue,
-  OpenFeature,
-  Client,
-} from '@openfeature/server-sdk';
+import type { EvaluationContext, EvaluationDetails, FlagValue, JsonValue } from '@openfeature/server-sdk';
+import { Client } from '@openfeature/server-sdk';
 import { getOpenFeatureClientToken } from './open-feature.module';
-import { from, Observable } from 'rxjs';
+import type { Observable } from 'rxjs';
+import { from } from 'rxjs';
+import { getClientForEvaluation } from './utils';
 
 /**
  * Options for injecting an OpenFeature client into a constructor.
@@ -54,16 +50,6 @@ interface FeatureProps<T extends FlagValue> {
   context?: EvaluationContext;
 }
 
-/**
- * Returns a domain scoped or the default OpenFeature client with the given context.
- * @param {string} domain The domain of the OpenFeature client.
- * @param {EvaluationContext} context The evaluation context of the client.
- * @returns {Client} The OpenFeature client.
- */
-function getClientForEvaluation(domain?: string, context?: EvaluationContext) {
-  return domain ? OpenFeature.getClient(domain, context) : OpenFeature.getClient(context);
-}
-
 /**
  * Route handler parameter decorator.
  *

packages/nest/src/index.ts

@@ -2,5 +2,6 @@ export * from './open-feature.module';
 export * from './feature.decorator';
 export * from './evaluation-context-interceptor';
 export * from './context-factory';
+export * from './require-flags-enabled.decorator';
 // re-export the server-sdk so consumers can access that API from the nestjs-sdk
 export * from '@openfeature/server-sdk';

packages/nest/src/open-feature.module.ts

@@ -1,24 +1,27 @@
-import {
+import type {
   DynamicModule,
-  Module,
   FactoryProvider as NestFactoryProvider,
   ValueProvider,
   ClassProvider,
-  Provider as NestProvider,
+  Provider as NestProvider} from '@nestjs/common';
+import {
+  Module,
   ExecutionContext,
 } from '@nestjs/common';
-import {
+import type {
   Client,
   Hook,
-  OpenFeature,
   Provider,
   EvaluationContext,
   ServerProviderEvents,
   EventHandler,
-  Logger,
+  Logger} from '@openfeature/server-sdk';
+import {
+  OpenFeature,
   AsyncLocalStorageTransactionContextPropagator,
 } from '@openfeature/server-sdk';
-import { ContextFactory, ContextFactoryToken } from './context-factory';
+import type { ContextFactory} from './context-factory';
+import { ContextFactoryToken } from './context-factory';
 import { APP_INTERCEPTOR } from '@nestjs/core';
 import { EvaluationContextInterceptor } from './evaluation-context-interceptor';
 import { ShutdownService } from './shutdown.service';

packages/nest/src/require-flags-enabled.decorator.ts

@@ -0,0 +1,104 @@
+import type { CallHandler, ExecutionContext, HttpException, NestInterceptor } from '@nestjs/common';
+import { applyDecorators, mixin, NotFoundException, UseInterceptors } from '@nestjs/common';
+import { getClientForEvaluation } from './utils';
+import type { EvaluationContext } from '@openfeature/server-sdk';
+import type { ContextFactory } from './context-factory';
+
+type RequiredFlag = {
+  flagKey: string;
+  defaultValue?: boolean;
+};
+
+/**
+ * Options for using one or more Boolean feature flags to control access to a Controller or Route.
+ */
+interface RequireFlagsEnabledProps {
+  /**
+   * The key and default value of the feature flag.
+   * @see {@link Client#getBooleanValue}
+   */
+  flags: RequiredFlag[];
+
+  /**
+   * The exception to throw if any of the required feature flags are not enabled.
+   * Defaults to a 404 Not Found exception.
+   * @see {@link HttpException}
+   * @default new NotFoundException(`Cannot ${req.method} ${req.url}`)
+   */
+  exception?: HttpException;
+
+  /**
+   * The domain of the OpenFeature client, if a domain scoped client should be used.
+   * @see {@link OpenFeature#getClient}
+   */
+  domain?: string;
+
+  /**
+   * The {@link EvaluationContext} for evaluating the feature flag.
+   * @see {@link OpenFeature#setContext}
+   */
+  context?: EvaluationContext;
+
+  /**
+   * A factory function for creating an OpenFeature {@link EvaluationContext} from Nest {@link ExecutionContext}.
+   * For example, this can be used to get header info from an HTTP request or information from a gRPC call to be used in the {@link EvaluationContext}.
+   * @see {@link ContextFactory}
+   */
+  contextFactory?: ContextFactory;
+}
+
+/**
+ * Controller or Route permissions handler decorator.
+ *
+ * Requires that the given feature flags are enabled for the request to be processed, else throws an exception.
+ *
+ * For example:
+ * ```typescript
+ * @RequireFlagsEnabled({
+ *   flags: [                               // Required, an array of Boolean flags to check, with optional default values (defaults to false)
+ *     { flagKey: 'flagName' },
+ *     { flagKey: 'flagName2', defaultValue: true },
+ *   ],
+ *   exception: new ForbiddenException(),   // Optional, defaults to a 404 Not Found Exception
+ *   domain: 'my-domain',                   // Optional, defaults to the default OpenFeature Client
+ *   context: {                             // Optional, defaults to the global OpenFeature Context
+ *     targetingKey: 'user-id',
+ *   },
+ *   contextFactory: (context: ExecutionContext) => {  // Optional, defaults to the global OpenFeature Context. Takes precedence over the context option.
+ *     return {
+ *       targetingKey: context.switchToHttp().getRequest().headers['x-user-id'],
+ *     };
+ *   },
+ * })
+ * @Get('/')
+ * public async handleGetRequest()
+ * ```
+ * @param {RequireFlagsEnabledProps} props The options for injecting the feature flag.
+ * @returns {ClassDecorator & MethodDecorator} The decorator that can be used to require Boolean Feature Flags to be enabled for a controller or a specific route.
+ */
+export const RequireFlagsEnabled = (props: RequireFlagsEnabledProps): ClassDecorator & MethodDecorator =>
+  applyDecorators(UseInterceptors(FlagsEnabledInterceptor(props)));
+
+const FlagsEnabledInterceptor = (props: RequireFlagsEnabledProps) => {
+  class FlagsEnabledInterceptor implements NestInterceptor {
+    constructor() {}
+
+    async intercept(context: ExecutionContext, next: CallHandler) {
+      const req = context.switchToHttp().getRequest();
+      const evaluationContext = props.contextFactory ? await props.contextFactory(context) : props.context;
+      const client = getClientForEvaluation(props.domain, evaluationContext);
+
+      for (const flag of props.flags) {
+        const endpointAccessible = await client.getBooleanValue(flag.flagKey, flag.defaultValue ?? false);
+
+        if (!endpointAccessible) {
+          throw props.exception || new NotFoundException(`Cannot ${req.method} ${req.url}`);
+        }
+      }
+
+      return next.handle();
+    }
+  }
+
+  return mixin(FlagsEnabledInterceptor);
+};

packages/nest/src/shutdown.service.ts

@@ -1,4 +1,5 @@
-import { Injectable, OnApplicationShutdown } from '@nestjs/common';
+import type { OnApplicationShutdown } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { OpenFeature } from '@openfeature/server-sdk';
 
 @Injectable()

packages/nest/src/utils.ts

@@ -0,0 +1,12 @@
+import type { Client, EvaluationContext } from '@openfeature/server-sdk';
+import { OpenFeature } from '@openfeature/server-sdk';
+
+/**
+ * Returns a domain scoped or the default OpenFeature client with the given context.
+ * @param {string} domain The domain of the OpenFeature client.
+ * @param {EvaluationContext} context The evaluation context of the client.
+ * @returns {Client} The OpenFeature client.
+ */
+export function getClientForEvaluation(domain?: string, context?: EvaluationContext) {
+  return domain ? OpenFeature.getClient(domain, context) : OpenFeature.getClient(context);
+}

packages/nest/test/fixtures.ts

@@ -1,5 +1,6 @@
 import { InMemoryProvider } from '@openfeature/server-sdk';
-import { ExecutionContext } from '@nestjs/common';
+import type { EvaluationContext } from '@openfeature/server-sdk';
+import type { ExecutionContext } from '@nestjs/common';
 import { OpenFeatureModule } from '../src';
 
 export const defaultProvider = new InMemoryProvider({
@@ -23,6 +24,17 @@ export const defaultProvider = new InMemoryProvider({
     variants: { default: { client: 'default' } },
     disabled: false,
   },
+  testBooleanFlag2: {
+    defaultVariant: 'default',
+    variants: { default: false, enabled: true },
+    disabled: false,
+    contextEvaluator: (ctx: EvaluationContext) => {
+      if (ctx.targetingKey === '123') {
+        return 'enabled';
+      }
+      return 'default';
+    },
+  },
 });
 
 export const providers = {

packages/nest/test/open-feature-sdk.spec.ts

@@ -1,7 +1,13 @@
-import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication } from '@nestjs/common';
+import type { TestingModule } from '@nestjs/testing';
+import { Test } from '@nestjs/testing';
+import type { INestApplication } from '@nestjs/common';
 import supertest from 'supertest';
-import { OpenFeatureController, OpenFeatureControllerContextScopedController, OpenFeatureTestService } from './test-app';
+import {
+  OpenFeatureController,
+  OpenFeatureContextScopedController,
+  OpenFeatureRequireFlagsEnabledController,
+  OpenFeatureTestService,
+} from './test-app';
 import { exampleContextFactory, getOpenFeatureDefaultTestModule } from './fixtures';
 import { OpenFeatureModule } from '../src';
 import { defaultProvider, providers } from './fixtures';
@@ -13,11 +19,9 @@ describe('OpenFeature SDK', () => {
 
     beforeAll(async () => {
       moduleRef = await Test.createTestingModule({
-        imports: [
-          getOpenFeatureDefaultTestModule()
-        ],
+        imports: [getOpenFeatureDefaultTestModule()],
         providers: [OpenFeatureTestService],
-        controllers: [OpenFeatureController],
+        controllers: [OpenFeatureController, OpenFeatureRequireFlagsEnabledController],
       }).compile();
       app = moduleRef.createNestApplication();
       app = await app.init();
@@ -111,7 +115,7 @@ describe('OpenFeature SDK', () => {
     });
 
     describe('evaluation context service should', () => {
-      it('inject the evaluation context from contex factory', async function() {
+      it('inject the evaluation context from contex factory', async function () {
         const evaluationSpy = jest.spyOn(defaultProvider, 'resolveBooleanEvaluation');
         await supertest(app.getHttpServer())
           .get('/dynamic-context-in-service')
@@ -121,26 +125,77 @@ describe('OpenFeature SDK', () => {
         expect(evaluationSpy).toHaveBeenCalledWith('testBooleanFlag', false, { targetingKey: 'dynamic-user' }, {});
       });
     });
+
+    describe('require flags enabled decorator', () => {
+      describe('OpenFeatureController', () => {
+        it('should sucessfully return the response if the flag is enabled', async () => {
+          await supertest(app.getHttpServer()).get('/flags-enabled').expect(200).expect('Get Boolean Flag Success!');
+        });
+
+        it('should throw an exception if the flag is disabled', async () => {
+          jest.spyOn(defaultProvider, 'resolveBooleanEvaluation').mockResolvedValueOnce({
+            value: false,
+            reason: 'DISABLED',
+          });
+          await supertest(app.getHttpServer()).get('/flags-enabled').expect(404);
+        });
+
+        it('should throw a custom exception if the flag is disabled', async () => {
+          jest.spyOn(defaultProvider, 'resolveBooleanEvaluation').mockResolvedValueOnce({
+            value: false,
+            reason: 'DISABLED',
+          });
+          await supertest(app.getHttpServer()).get('/flags-enabled-custom-exception').expect(403);
+        });
+
+        it('should throw a custom exception if the flag is disabled with context', async () => {
+          await supertest(app.getHttpServer())
+            .get('/flags-enabled-custom-exception-with-context')
+            .set('x-user-id', '123')
+            .expect(403);
+        });
+      });
+
+      describe('OpenFeatureControllerRequireFlagsEnabled', () => {
+        it('should allow access to the RequireFlagsEnabled controller with global context interceptor', async () => {
+          await supertest(app.getHttpServer())
+            .get('/require-flags-enabled')
+            .set('x-user-id', '123')
+            .expect(200)
+            .expect('Hello, world!');
+        });
+
+        it('should throw a 403 - Forbidden exception if user does not match targeting requirements', async () => {
+          await supertest(app.getHttpServer()).get('/require-flags-enabled').set('x-user-id', 'not-123').expect(403);
+        });
+
+        it('should throw a 403 - Forbidden exception if one of the flags is disabled', async () => {
+          jest.spyOn(defaultProvider, 'resolveBooleanEvaluation').mockResolvedValueOnce({
+            value: false,
+            reason: 'DISABLED',
+          });
+          await supertest(app.getHttpServer()).get('/require-flags-enabled').set('x-user-id', '123').expect(403);
+        });
+      });
+    });
   });
 
   describe('Without global context interceptor', () => {
-
     let moduleRef: TestingModule;
     let app: INestApplication;
 
     beforeAll(async () => {
-
       moduleRef = await Test.createTestingModule({
         imports: [
           OpenFeatureModule.forRoot({
             contextFactory: exampleContextFactory,
             defaultProvider,
             providers,
-            useGlobalInterceptor: false
+            useGlobalInterceptor: false,
           }),
         ],
         providers: [OpenFeatureTestService],
-        controllers: [OpenFeatureController, OpenFeatureControllerContextScopedController],
+        controllers: [OpenFeatureController, OpenFeatureContextScopedController],
       }).compile();
       app = moduleRef.createNestApplication();
       app = await app.init();
@@ -157,7 +212,7 @@ describe('OpenFeature SDK', () => {
     });
 
     describe('evaluation context service should', () => {
-      it('inject empty context if no context interceptor is configured', async function() {
+      it('inject empty context if no context interceptor is configured', async function () {
         const evaluationSpy = jest.spyOn(defaultProvider, 'resolveBooleanEvaluation');
         await supertest(app.getHttpServer())
           .get('/dynamic-context-in-service')
@@ -171,9 +226,26 @@ describe('OpenFeature SDK', () => {
     describe('With Controller bound Context interceptor', () => {
       it('should not use context if global context interceptor is not configured', async () => {
         const evaluationSpy = jest.spyOn(defaultProvider, 'resolveBooleanEvaluation');
-        await supertest(app.getHttpServer()).get('/controller-context').set('x-user-id', '123').expect(200).expect('true');
+        await supertest(app.getHttpServer())
+          .get('/controller-context')
+          .set('x-user-id', '123')
+          .expect(200)
+          .expect('true');
         expect(evaluationSpy).toHaveBeenCalledWith('testBooleanFlag', false, { targetingKey: '123' }, {});
       });
     });
+
+    describe('require flags enabled decorator', () => {
+      it('should return a 404 - Not Found exception if the flag is disabled', async () => {
+        jest.spyOn(providers.domainScopedClient, 'resolveBooleanEvaluation').mockResolvedValueOnce({
+          value: false,
+          reason: 'DISABLED',
+        });
+        await supertest(app.getHttpServer())
+          .get('/controller-context/flags-enabled')
+          .set('x-user-id', '123')
+          .expect(404);
+      });
+    });
   });
 });

packages/nest/test/open-feature.module.spec.ts

@@ -1,6 +1,8 @@
-import { Test, TestingModule } from '@nestjs/testing';
+import type { TestingModule } from '@nestjs/testing';
+import { Test } from '@nestjs/testing';
 import { getOpenFeatureClientToken, OpenFeatureModule, ServerProviderEvents } from '../src';
-import { Client, OpenFeature } from '@openfeature/server-sdk';
+import type { Client} from '@openfeature/server-sdk';
+import { OpenFeature } from '@openfeature/server-sdk';
 import { getOpenFeatureDefaultTestModule } from './fixtures';
 
 describe('OpenFeatureModule', () => {

packages/nest/test/test-app.ts

@@ -1,7 +1,15 @@
-import { Controller, Get, Injectable, UseInterceptors } from '@nestjs/common';
-import { Observable, map } from 'rxjs';
-import { BooleanFeatureFlag, ObjectFeatureFlag, NumberFeatureFlag, OpenFeatureClient, StringFeatureFlag } from '../src';
-import { Client, EvaluationDetails, FlagValue } from '@openfeature/server-sdk';
+import { Controller, ForbiddenException, Get, Injectable, UseInterceptors } from '@nestjs/common';
+import type { Observable } from 'rxjs';
+import { map } from 'rxjs';
+import {
+  BooleanFeatureFlag,
+  ObjectFeatureFlag,
+  NumberFeatureFlag,
+  OpenFeatureClient,
+  StringFeatureFlag,
+  RequireFlagsEnabled,
+} from '../src';
+import type { Client, EvaluationDetails, FlagValue } from '@openfeature/server-sdk';
 import { EvaluationContextInterceptor } from '../src';
 
 @Injectable()
@@ -83,11 +91,40 @@ export class OpenFeatureController {
   public async handleDynamicContextInServiceRequest() {
     return this.testService.serviceMethodWithDynamicContext('testBooleanFlag');
   }
+
+  @RequireFlagsEnabled({
+    flags: [{ flagKey: 'testBooleanFlag' }],
+  })
+  @Get('/flags-enabled')
+  public async handleGuardedBooleanRequest() {
+    return 'Get Boolean Flag Success!';
+  }
+
+  @RequireFlagsEnabled({
+    flags: [{ flagKey: 'testBooleanFlag' }],
+    exception: new ForbiddenException(),
+  })
+  @Get('/flags-enabled-custom-exception')
+  public async handleBooleanRequestWithCustomException() {
+    return 'Get Boolean Flag Success!';
+  }
+
+  @RequireFlagsEnabled({
+    flags: [{ flagKey: 'testBooleanFlag2' }],
+    exception: new ForbiddenException(),
+    context: {
+      targetingKey: 'user-id',
+    },
+  })
+  @Get('/flags-enabled-custom-exception-with-context')
+  public async handleBooleanRequestWithCustomExceptionAndContext() {
+    return 'Get Boolean Flag Success!';
+  }
 }
 
 @Controller()
 @UseInterceptors(EvaluationContextInterceptor)
-export class OpenFeatureControllerContextScopedController {
+export class OpenFeatureContextScopedController {
   constructor(private testService: OpenFeatureTestService) {}
 
   @Get('/controller-context')
@@ -100,4 +137,27 @@ export class OpenFeatureControllerContextScopedController {
   ) {
     return feature.pipe(map((details) => this.testService.serviceMethod(details)));
   }
+
+  @RequireFlagsEnabled({
+    flags: [{ flagKey: 'testBooleanFlag' }],
+    domain: 'domainScopedClient',
+  })
+  @Get('/controller-context/flags-enabled')
+  public async handleBooleanRequest() {
+    return 'Get Boolean Flag Success!';
+  }
+}
+
+@Controller('require-flags-enabled')
+@RequireFlagsEnabled({
+  flags: [{ flagKey: 'testBooleanFlag', defaultValue: false }, { flagKey: 'testBooleanFlag2' }],
+  exception: new ForbiddenException(),
+})
+export class OpenFeatureRequireFlagsEnabledController {
+  constructor() {}
+
+  @Get('/')
+  public async handleGetRequest() {
+    return 'Hello, world!';
+  }
 }

packages/nest/tsconfig.json

@@ -9,10 +9,10 @@
     // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
     // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
     /* Language and Environment */
-    "target": "ES2022",
+    "target": "ES2015",
     /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
     "lib": [
-      "ES2022"
+      "ES2015"
     ],
     /* Specify a set of bundled library declaration files that describe the target runtime environment. */
     // "jsx": "preserve",                                /* Specify what JSX code is generated. */
@@ -27,7 +27,7 @@
     // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
     // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
     /* Modules */
-    "module": "ES2022",
+    "module": "ES2015",
     /* Specify what module code is generated. */
     // "rootDir": "./",                                  /* Specify the root folder within your source files. */
     "moduleResolution": "node",

packages/react/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## [1.0.1](https://github.com/open-feature/js-sdk/compare/react-sdk-v1.0.0...react-sdk-v1.0.1) (2025-08-18)
+
+
+### 🐛 Bug Fixes
+
+* **react:** re-evaluate flags on re-render to detect silent provider … ([#1226](https://github.com/open-feature/js-sdk/issues/1226)) ([3105595](https://github.com/open-feature/js-sdk/commit/31055959265a53f52102590f54fa3168811ec678))
+
+## [1.0.0](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.11...react-sdk-v1.0.0) (2025-04-14)
+
+
+### ✨ New Features
+
+* add polyfill for react use hook ([#1157](https://github.com/open-feature/js-sdk/issues/1157)) ([5afe61f](https://github.com/open-feature/js-sdk/commit/5afe61f9e351b037b04c93a1d81aee8016756748))
+* add support for abort controllers to event handlers ([#1151](https://github.com/open-feature/js-sdk/issues/1151)) ([6a22483](https://github.com/open-feature/js-sdk/commit/6a224830fa4e62fc30a7802536f6f6fc3f772038))
+
+## [0.4.11](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.10...react-sdk-v0.4.11) (2025-02-07)
+
+
+### ✨ New Features
+
+* export useOpenFeatureClientStatus hook ([#1082](https://github.com/open-feature/js-sdk/issues/1082)) ([4a6b860](https://github.com/open-feature/js-sdk/commit/4a6b8605444edeaf43355713357fecb97dd850b6))
+
+
+### 🧹 Chore
+
+* update sdk peer ([#1142](https://github.com/open-feature/js-sdk/issues/1142)) ([8bb6206](https://github.com/open-feature/js-sdk/commit/8bb620601e2b8dc7b62d717169b585bd1c886996))
+
+## [0.4.10](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.9...react-sdk-v0.4.10) (2024-12-18)
+
+
+### 🔄 Refactoring
+
+* export public option types ([#1101](https://github.com/open-feature/js-sdk/issues/1101)) ([16321c3](https://github.com/open-feature/js-sdk/commit/16321c31f27c5fce2c8e2adea893cf6e7e8ce3de))
+
+## [0.4.9](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.8...react-sdk-v0.4.9) (2024-12-04)
+
+
+### ✨ New Features
+
+* re-render if flagsChanged is falsy ([#1095](https://github.com/open-feature/js-sdk/issues/1095)) ([78516f4](https://github.com/open-feature/js-sdk/commit/78516f4181c82baf8c42fd64798fc2cfd8ff1056))
+
+
+### 📚 Documentation
+
+* fix typos, links, and format ([#1075](https://github.com/open-feature/js-sdk/issues/1075)) ([418409e](https://github.com/open-feature/js-sdk/commit/418409e3faafc6868a9f893267a4733db9931f93))
+
+## [0.4.8](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.7...react-sdk-v0.4.8) (2024-10-29)
+
+
+### 🧹 Chore
+
+* bump minimum web peer ([#1072](https://github.com/open-feature/js-sdk/issues/1072)) ([eca8205](https://github.com/open-feature/js-sdk/commit/eca8205da7945395d19c09a4da67cd4c2d516227))
+
+
+### 📚 Documentation
+
+* add tracking sections ([#1068](https://github.com/open-feature/js-sdk/issues/1068)) ([e131faf](https://github.com/open-feature/js-sdk/commit/e131faffad9025e9c7194f39558bf3b3cec31807))
+
+## [0.4.7](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.6...react-sdk-v0.4.7) (2024-10-29)
+
+
+### ✨ New Features
+
+* avoid re-resolving flags unaffected by a change event ([#1024](https://github.com/open-feature/js-sdk/issues/1024)) ([b8f9b4e](https://github.com/open-feature/js-sdk/commit/b8f9b4ebaf4bdd93669fc6da09d9f97a498174d9))
+* implement tracking as per spec ([#1020](https://github.com/open-feature/js-sdk/issues/1020)) ([80f182e](https://github.com/open-feature/js-sdk/commit/80f182e1afbd3a705bf3de6a0d9886ccb3424b44))
+* use mutate context hook ([#1031](https://github.com/open-feature/js-sdk/issues/1031)) ([ec3d967](https://github.com/open-feature/js-sdk/commit/ec3d967f8b9dd0854706a904a5360f0a0b843595))
+
+
+### 🧹 Chore
+
+* add js docs for context mutator hook ([#1045](https://github.com/open-feature/js-sdk/issues/1045)) ([def3fe8](https://github.com/open-feature/js-sdk/commit/def3fe8dafc3d6ed3451a493e76842b7d2e8363c))
+* import type lint rule and fixes ([#1039](https://github.com/open-feature/js-sdk/issues/1039)) ([01fcb93](https://github.com/open-feature/js-sdk/commit/01fcb933d2cbd131a0f4a005173cdd1906087e18))
+
+## [0.4.6](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.5...react-sdk-v0.4.6) (2024-09-23)
+
+
+### 🐛 Bug Fixes
+
+* failure to re-render on changes ([#1021](https://github.com/open-feature/js-sdk/issues/1021)) ([c927044](https://github.com/open-feature/js-sdk/commit/c927044c4934f0b8edfd2cdbbc0d60ad546b3dbc))
+
+## [0.4.5](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.4...react-sdk-v0.4.5) (2024-09-04)
+
+
+### ✨ New Features
+
+* **react:** prevent rerenders when value is unchanged ([#987](https://github.com/open-feature/js-sdk/issues/987)) ([b7fc08e](https://github.com/open-feature/js-sdk/commit/b7fc08e27d225bdbf72c1985e7eef85adcd896b0))
+
+## [0.4.4](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.3...react-sdk-v0.4.4) (2024-08-28)
+
+
+### 🧹 Chore
+
+* move client/ dir to web/ ([#991](https://github.com/open-feature/js-sdk/issues/991)) ([df4e72e](https://github.com/open-feature/js-sdk/commit/df4e72eabc3370801303470ca37263a0d4d9bb38))
+
+
+### 📚 Documentation
+
+* **react:** update the error message ([#978](https://github.com/open-feature/js-sdk/issues/978)) ([429c4ae](https://github.com/open-feature/js-sdk/commit/429c4ae941b66a1aa82b5aeea4bdb8b57bd05022))
+
+## [0.4.3](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.2...react-sdk-v0.4.3) (2024-08-22)
+
+
+### 🐛 Bug Fixes
+
+* race condition in test provider with suspense ([#980](https://github.com/open-feature/js-sdk/issues/980)) ([0f187fe](https://github.com/open-feature/js-sdk/commit/0f187fe0b584e66b6283531eb7879c320967f921))
+
+
+### 🧹 Chore
+
+* fix flaky test timing ([ad46ade](https://github.com/open-feature/js-sdk/commit/ad46ade143b10366103d4ac199d728e8ae5ba7e8))
+
+## [0.4.2](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.1...react-sdk-v0.4.2) (2024-07-29)
+
+
+### ✨ New Features
+
+* add test provider ([#971](https://github.com/open-feature/js-sdk/issues/971)) ([1c12d4d](https://github.com/open-feature/js-sdk/commit/1c12d4d548195bfc8c2f898a90ea97063aa8b3f7))
+
+## [0.4.1](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.4.0...react-sdk-v0.4.1) (2024-06-11)
+
+
+### ✨ New Features
+
+* lower compilation target to es2015 ([#957](https://github.com/open-feature/js-sdk/issues/957)) ([c2d6c17](https://github.com/open-feature/js-sdk/commit/c2d6c1761ae19f937deaff2f011a0380f8af7350))
+
 ## [0.4.0](https://github.com/open-feature/js-sdk/compare/react-sdk-v0.3.4...react-sdk-v0.4.0) (2024-05-13)
 
 

packages/react/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
   <!-- x-release-please-start-version -->
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v0.4.0">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.0&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v1.0.1">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.0.1&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -54,6 +54,8 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
     - [Re-rendering with Context Changes](#re-rendering-with-context-changes)
     - [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes)
     - [Suspense Support](#suspense-support)
+    - [Tracking](#tracking)
+  - [Testing](#testing)
 - [FAQ and troubleshooting](#faq-and-troubleshooting)
 - [Resources](#resources)
 
@@ -61,7 +63,7 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
 
 ### Requirements
 
-- ES2022-compatible web browser (Chrome, Edge, Firefox, etc)
+- ES2015-compatible web browser (Chrome, Edge, Firefox, etc)
 - React version 16.8+
 
 ### Install
@@ -131,7 +133,7 @@ function App() {
 
 #### Evaluation hooks
 
-Within the provider, you can use the various evaluation hooks to evaluate flags. 
+Within the provider, you can use the various evaluation hooks to evaluate flags.
 
 ```tsx
 function Page() {
@@ -147,7 +149,7 @@ function Page() {
 }
 ```
 
-You can use the strongly-typed flag value and flag evaluation detail hooks as well, if you prefer.
+You can use the strongly typed flag value and flag evaluation detail hooks as well if you prefer.
 
 ```tsx
 import { useBooleanFlagValue } from '@openfeature/react-sdk';
@@ -173,7 +175,7 @@ const {
 Multiple providers can be used by passing a `domain` to the `OpenFeatureProvider`:
 
 ```tsx
-// Flags within this domain will use the a client/provider associated with `my-domain`,
+// Flags within this domain will use the client/provider associated with `my-domain`,
 function App() {
   return (
     <OpenFeatureProvider domain={'my-domain'}>
@@ -189,7 +191,7 @@ This is analogous to:
 OpenFeature.getClient('my-domain');
 ```
 
-For more information about `domains`, refer to the [web SDK](https://github.com/open-feature/js-sdk/blob/main/packages/client/README.md).
+For more information about `domains`, refer to the [web SDK](https://github.com/open-feature/js-sdk/blob/main/packages/web/README.md).
 
 #### Re-rendering with Context Changes
 
@@ -231,16 +233,19 @@ function Page() {
 }
 ```
 
-Note that if your provider doesn't support updates, this configuration has no impact.
+If your provider doesn't support updates, this configuration has no impact.
+
+> [!NOTE]
+> If your provider includes a list of [flags changed](https://open-feature.github.io/js-sdk/types/_openfeature_server_sdk.ConfigChangeEvent.html) in its `PROVIDER_CONFIGURATION_CHANGED` event, that list of flags is used to decide which flag evaluation hooks should re-run by diffing the latest value of these flags with the previous render.
+> If your provider event does not the include the `flags changed` list, then the SDK diffs all flags with the previous render to determine which hooks should re-run.
 
 #### Suspense Support
 
-> [!NOTE]  
-> React suspense is an experimental feature and subject to change in future versions.
-
+> [!NOTE]
+> React suspense is an experimental feature and is subject to change in future versions.
 
 Frequently, providers need to perform some initial startup tasks.
-It may be desireable not to display components with feature flags until this is complete, or when the context changes.
+It may be desirable not to display components with feature flags until this is complete or when the context changes.
 Built-in [suspense](https://react.dev/reference/react/Suspense) support makes this easy.
 Use `useSuspenseFlag` or pass `{ suspend: true }` in the hook options to leverage this functionality.
 
@@ -273,33 +278,112 @@ function Fallback() {
   // component to render before READY.
   return <p>Waiting for provider to be ready...</p>;
 }
-
 ```
 
 This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)).
 
+#### Tracking
+
+The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
+This is essential for robust experimentation powered by feature flags.
+For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](https://openfeature.dev/docs/reference/technologies/client/web/#hooks) or [provider](https://openfeature.dev/docs/reference/technologies/client/web/#providers) can be associated with telemetry reported in the client's `track` function.
+
+The React SDK includes a hook for firing tracking events in the `<OpenFeatureProvider>` context in use:
+
+```tsx
+function MyComponent() {
+  // get a tracking function for this <OpenFeatureProvider>.
+  const { track } = useTrack();
+
+  // call the tracking event
+  // can be done in render, useEffect, or in handlers, depending on your use case
+  track(eventName, trackingDetails);
+
+  return <>...</>;
+}
+```
+
+### Testing
+
+The React SDK includes a built-in context provider for testing.
+This allows you to easily test components that use evaluation hooks, such as `useFlag`.
+If you try to test a component (in this case, `MyComponent`) which uses an evaluation hook, you might see an error message like:
+
+> No OpenFeature client available - components using OpenFeature must be wrapped with an `<OpenFeatureProvider>`.
+
+You can resolve this by simply wrapping your component under test in the OpenFeatureTestProvider:
+
+```tsx
+// use default values for all evaluations
+<OpenFeatureTestProvider>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+The basic configuration above will simply use the default value provided in code.
+If you'd like to control the values returned by the evaluation hooks, you can pass a map of flag keys and values:
+
+```tsx
+// return `true` for all evaluations of `'my-boolean-flag'`
+<OpenFeatureTestProvider flagValueMap={{ 'my-boolean-flag': true }}>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+Additionally, you can pass an artificial delay for the provider startup to test your suspense boundaries or loaders/spinners impacted by feature flags:
+
+```tsx
+// delay the provider start by 1000ms and then return `true` for all evaluations of `'my-boolean-flag'`
+<OpenFeatureTestProvider delayMs={1000} flagValueMap={{ 'my-boolean-flag': true }}>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+For maximum control, you can also pass your own mock provider implementation.
+The type of this option is `Partial<Provider>`, so you can pass an incomplete implementation:
+
+```tsx
+class MyTestProvider implements Partial<Provider> {
+  // implement the relevant resolver
+  resolveBooleanEvaluation(): ResolutionDetails<boolean> {
+    return {
+      value: true,
+      variant: 'my-variant',
+      reason: 'MY_REASON',
+    };
+  }
+}
+```
+
+```tsx
+// use your custom testing provider
+<OpenFeatureTestProvider provider={new MyTestProvider()}>
+  <MyComponent />
+</OpenFeatureTestProvider>,
+```
+
 ## FAQ and troubleshooting
 
 > I get an error that says something like: `A React component suspended while rendering, but no fallback UI was specified.`
 
 The OpenFeature React SDK features built-in [suspense support](#suspense-support).
-This means that it will render your loading fallback automatically while the your provider starts up, and during context reconciliation for any of your components using feature flags!
+This means that it will render your loading fallback automatically while your provider starts up and during context reconciliation for any of your components using feature flags!
 If you use suspense and neglect to create a suspense boundary around any components using feature flags, you will see this error.
 Add a suspense boundary to resolve this issue.
 Alternatively, you can disable this suspense (the default) by removing `suspendWhileReconciling=true`, `suspendUntilReady=true` or `suspend=true` in the [evaluation hooks](#evaluation-hooks) or the [OpenFeatureProvider](#openfeatureprovider-context-provider) (which applies to all evaluation hooks in child components).
 
-> I get odd rendering issues, or errors when components mount, if I use the suspense features.
+> I get odd rendering issues or errors when components mount if I use the suspense features.
 
 In React 16/17's "Legacy Suspense", when a component suspends, its sibling components initially mount and then are hidden.
 This can cause surprising effects and inconsistencies if sibling components are rendered while the provider is still getting ready.
 To fix this, you can upgrade to React 18, which uses "Concurrent Suspense", in which siblings are not mounted until their suspended sibling resolves.
 Alternatively, if you cannot upgrade to React 18, you can use the `useWhenProviderReady` utility hook in any sibling components to prevent them from mounting until the provider is ready.
 
-> I am using multiple `OpenFeatureProvider` contexts, but they are sharing the same provider or evaluation context. Why?
+> I am using multiple `OpenFeatureProvider` contexts, but they share the same provider or evaluation context. Why?
 
 The `OpenFeatureProvider` binds a `client` to all child components, but the provider and context associated with that client is controlled by the `domain` parameter.
 This is consistent with all OpenFeature SDKs.
-To scope an OpenFeatureProvider to a particular provider/context set the `domain` parameter on your `OpenFeatureProvider`:
+To scope an OpenFeatureProvider to a particular provider/context, set the `domain` parameter on your `OpenFeatureProvider`:
 
 ```tsx
 <OpenFeatureProvider domain={'my-domain'}>
@@ -309,7 +393,7 @@ To scope an OpenFeatureProvider to a particular provider/context set the `domain
 
 > I can import things form the `@openfeature/react-sdk`, `@openfeature/web-sdk`, and `@openfeature/core`; which should I use?
 
-The `@openfeature/react-sdk` re-exports everything from its peers (`@openfeature/web-sdk` and `@openfeature/core`), and adds the React-specific features.
+The `@openfeature/react-sdk` re-exports everything from its peers (`@openfeature/web-sdk` and `@openfeature/core`) and adds the React-specific features.
 You can import everything from the `@openfeature/react-sdk` directly.
 Avoid importing anything from `@openfeature/web-sdk` or `@openfeature/core`.
 

packages/react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/react-sdk",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "description": "OpenFeature React SDK",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -16,9 +16,10 @@
   "scripts": {
     "test": "jest --verbose",
     "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
     "clean": "shx rm -rf ./dist",
-    "build:react-esm": "esbuild src/index.ts --bundle  --external:react --external:@openfeature/web-sdk --sourcemap --target=es2022 --platform=browser --format=esm --outfile=./dist/esm/index.js --analyze",
-    "build:react-cjs": "esbuild src/index.ts --bundle  --external:react --external:@openfeature/web-sdk --sourcemap --target=es2022 --platform=browser --format=cjs --outfile=./dist/cjs/index.js --analyze",
+    "build:react-esm": "esbuild src/index.ts --bundle  --external:react --external:@openfeature/web-sdk --sourcemap --target=es2015 --platform=browser --format=esm --outfile=./dist/esm/index.js --analyze",
+    "build:react-cjs": "esbuild src/index.ts --bundle  --external:react --external:@openfeature/web-sdk --sourcemap --target=es2015 --platform=browser --format=cjs --outfile=./dist/cjs/index.js --analyze",
     "build:rollup-types": "rollup -c ../../rollup.config.mjs",
     "build": "npm run clean && npm run build:react-esm && npm run build:react-cjs && npm run build:rollup-types",
     "postbuild": "shx cp ./../../package.esm.json ./dist/esm/package.json",
@@ -46,7 +47,7 @@
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
   "peerDependencies": {
-    "@openfeature/web-sdk": "^1.0.2",
+    "@openfeature/web-sdk": "^1.5.0",
     "react": ">=16.8.0"
   },
   "devDependencies": {

packages/react/src/common/options.ts

@@ -1,83 +0,0 @@
-import { FlagEvaluationOptions } from '@openfeature/web-sdk';
-
-export type ReactFlagEvaluationOptions = ({
-  /**
-   * Enable or disable all suspense functionality.
-   * Cannot be used in conjunction with `suspendUntilReady` and `suspendWhileReconciling` options.
-   * @experimental Suspense is an experimental feature subject to change in future versions.
-   */
-  suspend?: boolean;
-  suspendUntilReady?: never;
-  suspendWhileReconciling?: never;
-} | {
-  /**
-   * Suspend flag evaluations while the provider is not ready.
-   * Set to false if you don't want to show suspense fallbacks until the provider is initialized.
-   * Defaults to false.
-   * Cannot be used in conjunction with `suspend` option.
-   * @experimental Suspense is an experimental feature subject to change in future versions.
-   */
-  suspendUntilReady?: boolean;
-  /**
-   * Suspend flag evaluations while the provider's context is being reconciled.
-   * Set to true if you want to show suspense fallbacks while flags are re-evaluated after context changes.
-   * Defaults to false.
-   * Cannot be used in conjunction with `suspend` option.
-   * @experimental Suspense is an experimental feature subject to change in future versions.
-   */
-  suspendWhileReconciling?: boolean;
-  suspend?: never;
-}) & {
-  /**
-   * Update the component if the provider emits a ConfigurationChanged event.
-   * Set to false to prevent components from re-rendering when flag value changes
-   * are received by the associated provider.
-   * Defaults to true.
-   */
-  updateOnConfigurationChanged?: boolean;
-  /**
-   * Update the component when the OpenFeature context changes.
-   * Set to false to prevent components from re-rendering when attributes which
-   * may be factors in flag evaluation change.
-   * Defaults to true.
-   */
-  updateOnContextChanged?: boolean;
-} & FlagEvaluationOptions;
-
-export type NormalizedOptions = Omit<ReactFlagEvaluationOptions, 'suspend'>;
-
-/**
- * Default options.
- * DO NOT EXPORT PUBLICLY
- * @internal
- */
-export const DEFAULT_OPTIONS: ReactFlagEvaluationOptions = {
-  updateOnContextChanged: true,
-  updateOnConfigurationChanged: true,
-  suspendUntilReady: false,
-  suspendWhileReconciling: false,
-};
-
-/**
- * Returns normalization options (all `undefined` fields removed, and `suspend` decomposed to `suspendUntilReady` and `suspendWhileReconciling`).
- * DO NOT EXPORT PUBLICLY
- * @internal
- * @param {ReactFlagEvaluationOptions} options  options to normalize
- * @returns {NormalizedOptions} normalized options
- */
-export const normalizeOptions: (options?: ReactFlagEvaluationOptions) => NormalizedOptions = (options: ReactFlagEvaluationOptions = {}) => {
-  const updateOnContextChanged = options.updateOnContextChanged;
-  const updateOnConfigurationChanged = options.updateOnConfigurationChanged;
-
-  // fall-back the suspense options to the catch-all `suspend` property 
-  const suspendUntilReady = 'suspendUntilReady' in options ? options.suspendUntilReady : options.suspend;
-  const suspendWhileReconciling = 'suspendWhileReconciling' in options ? options.suspendWhileReconciling : options.suspend;
-
-  return {
-    // only return these if properly set (no undefined to allow overriding with spread)
-    ...(typeof suspendUntilReady === 'boolean' && {suspendUntilReady}),
-    ...(typeof suspendWhileReconciling === 'boolean' && {suspendWhileReconciling}),
-    ...(typeof updateOnContextChanged === 'boolean' && {updateOnContextChanged}),
-    ...(typeof updateOnConfigurationChanged === 'boolean' && {updateOnConfigurationChanged}),
-  };
-};

packages/react/src/common/suspense.ts

@@ -1,20 +0,0 @@
-import { Client, ProviderEvents } from '@openfeature/web-sdk';
-
-/**
- * Suspends until the client is ready to evaluate feature flags.
- * DO NOT EXPORT PUBLICLY
- * @param {Client} client OpenFeature client
- */
-export function suspendUntilReady(client: Client): Promise<void> {
-  let resolve: (value: unknown) => void;
-  let reject: () => void;
-  throw new Promise((_resolve, _reject) => {
-    resolve = _resolve;
-    reject = _reject;
-    client.addHandler(ProviderEvents.Ready, resolve);
-    client.addHandler(ProviderEvents.Error, reject);
-  }).finally(() => {
-    client.removeHandler(ProviderEvents.Ready, resolve);
-    client.removeHandler(ProviderEvents.Ready, reject);
-  });
-}

packages/react/src/context/index.ts

@@ -0,0 +1 @@
+export * from './use-context-mutator';

packages/react/src/context/use-context-mutator.ts

@@ -0,0 +1,51 @@
+import { useCallback, useContext, useRef } from 'react';
+import type { EvaluationContext } from '@openfeature/web-sdk';
+import { OpenFeature } from '@openfeature/web-sdk';
+import { Context } from '../internal';
+
+export type ContextMutationOptions = {
+  /**
+   * Mutate the default context instead of the domain scoped context applied at the `<OpenFeatureProvider/>`.
+   * Note, if the `<OpenFeatureProvider/>` has no domain specified, the default is used.
+   * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#manage-evaluation-context-for-domains|documentation} for more information.
+   * @default false
+   */
+  defaultContext?: boolean;
+};
+
+export type ContextMutation = {
+  /**
+   * Context-aware function to set the desired context (see: {@link ContextMutationOptions} for details).
+   * There's generally no need to await the result of this function; flag evaluation hooks will re-render when the context is updated.
+   * This promise never rejects.
+   * @param updatedContext
+   * @returns Promise for awaiting the context update
+   */
+  setContext: (updatedContext: EvaluationContext) => Promise<void>;
+};
+
+/**
+ * Get context-aware tracking function(s) for mutating the evaluation context associated with this domain, or the default context if `defaultContext: true`.
+ * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#targeting-and-context|documentation} for more information.
+ * @param {ContextMutationOptions} options options for the generated function
+ * @returns {ContextMutation} context-aware function(s) to mutate evaluation context
+ */
+export function useContextMutator(options: ContextMutationOptions = { defaultContext: false }): ContextMutation {
+    const { domain } = useContext(Context) || {};
+    const previousContext = useRef<null | EvaluationContext>(null);
+
+    const setContext = useCallback(async (updatedContext: EvaluationContext) => {
+        if (previousContext.current !== updatedContext) {
+            if (!domain || options?.defaultContext) {
+                OpenFeature.setContext(updatedContext);
+            } else {
+                OpenFeature.setContext(domain, updatedContext);
+            }
+            previousContext.current = updatedContext;
+        }
+    }, [domain]);
+
+    return {
+        setContext,
+    };
+}

packages/react/src/evaluation/use-feature-flag.ts

@@ -1,20 +1,28 @@
-import {
+import type {
   Client,
+  ClientProviderEvents,
   EvaluationDetails,
+  EventHandler,
   FlagEvaluationOptions,
   FlagValue,
   JsonValue,
-  ProviderEvents,
-  ProviderStatus,
 } from '@openfeature/web-sdk';
-import { useEffect, useState } from 'react';
-import { DEFAULT_OPTIONS, ReactFlagEvaluationOptions, normalizeOptions } from '../common/options';
-import { suspendUntilReady } from '../common/suspense';
-import { useProviderOptions } from '../provider/context';
+import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  DEFAULT_OPTIONS,
+  isEqual,
+  normalizeOptions,
+  suspendUntilInitialized,
+  suspendUntilReconciled,
+  useProviderOptions,
+} from '../internal';
+import type { ReactFlagEvaluationNoSuspenseOptions, ReactFlagEvaluationOptions } from '../options';
 import { useOpenFeatureClient } from '../provider/use-open-feature-client';
 import { useOpenFeatureClientStatus } from '../provider/use-open-feature-client-status';
-import { FlagQuery } from '../query';
-import { HookFlagQuery } from './hook-flag-query';
+import { useOpenFeatureProvider } from '../provider/use-open-feature-provider';
+import type { FlagQuery } from '../query';
+import { HookFlagQuery } from '../internal/hook-flag-query';
 
 // This type is a bit wild-looking, but I think we need it.
 // We have to use the conditional, because otherwise useFlag('key', false) would return false, not boolean (too constrained).
@@ -31,9 +39,6 @@ type ConstrainedFlagQuery<T> = FlagQuery<
           : JsonValue
 >;
 
-// suspense options removed for the useSuspenseFlag hooks
-type NoSuspenseOptions = Omit<ReactFlagEvaluationOptions, 'suspend' | 'suspendUntilReady' | 'suspendWhileReconciling'>
-
 /**
  * Evaluates a feature flag generically, returning an react-flavored queryable object.
  * The resolver method to use is based on the type of the defaultValue.
@@ -50,15 +55,15 @@ export function useFlag<T extends FlagValue = FlagValue>(
   defaultValue: T,
   options?: ReactFlagEvaluationOptions,
 ): FlagQuery<
-T extends boolean
-  ? boolean
-  : T extends number
-    ? number
-    : T extends string
-      ? string
-      : T extends JsonValue
-        ? T
-        : JsonValue
+  T extends boolean
+    ? boolean
+    : T extends number
+      ? number
+      : T extends string
+        ? string
+        : T extends JsonValue
+          ? T
+          : JsonValue
 > {
   // use the default value to determine the resolver to call
   const query =
@@ -74,7 +79,7 @@ T extends boolean
 }
 
 // alias to the return value of useFlag, used to keep useSuspenseFlag consistent
-type UseFlagReturn<T extends FlagValue> = ReturnType<typeof useFlag<T>>
+type UseFlagReturn<T extends FlagValue> = ReturnType<typeof useFlag<T>>;
 
 /**
  * Equivalent to {@link useFlag} with `options: { suspend: true }`
@@ -82,13 +87,13 @@ type UseFlagReturn<T extends FlagValue> = ReturnType<typeof useFlag<T>>
  * @param {string} flagKey the flag identifier
  * @template {FlagValue} T A optional generic argument constraining the default.
  * @param {T} defaultValue the default value; used to determine what resolved type should be used.
- * @param {NoSuspenseOptions} options for this evaluation
+ * @param {ReactFlagEvaluationNoSuspenseOptions} options for this evaluation
  * @returns { UseFlagReturn<T> } a queryable object containing useful information about the flag.
  */
 export function useSuspenseFlag<T extends FlagValue = FlagValue>(
   flagKey: string,
   defaultValue: T,
-  options?: NoSuspenseOptions,
+  options?: ReactFlagEvaluationNoSuspenseOptions,
 ): UseFlagReturn<T> {
   return useFlag(flagKey, defaultValue, { ...options, suspendUntilReady: true, suspendWhileReconciling: true });
 }
@@ -263,61 +268,110 @@ export function useObjectFlagDetails<T extends JsonValue = JsonValue>(
   );
 }
 
+// determines if a flag should be re-evaluated based on a list of changed flags
+function shouldEvaluateFlag(flagKey: string, flagsChanged?: string[]): boolean {
+  // if flagsChange is missing entirely, we don't know what to re-render
+  return !flagsChanged || flagsChanged.includes(flagKey);
+}
+
 function attachHandlersAndResolve<T extends FlagValue>(
   flagKey: string,
   defaultValue: T,
-  resolver: (client: Client) => (flagKey: string, defaultValue: T, options?: FlagEvaluationOptions) => EvaluationDetails<T>,
+  resolver: (
+    client: Client,
+  ) => (flagKey: string, defaultValue: T, options?: FlagEvaluationOptions) => EvaluationDetails<T>,
   options?: ReactFlagEvaluationOptions,
 ): EvaluationDetails<T> {
   // highest priority > evaluation hook options > provider options > default options > lowest priority
   const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
   const client = useOpenFeatureClient();
   const status = useOpenFeatureClientStatus();
+  const provider = useOpenFeatureProvider();
+  const isFirstRender = useRef(true);
 
-  // suspense
   if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
-    suspendUntilReady(client);
+    suspendUntilInitialized(provider, client);
   }
 
   if (defaultedOptions.suspendWhileReconciling && status === ProviderStatus.RECONCILING) {
-    suspendUntilReady(client);
+    suspendUntilReconciled(client);
   }
 
-  const [evalutationDetails, setEvaluationDetails] = useState<EvaluationDetails<T>>(
+  const [evaluationDetails, setEvaluationDetails] = useState<EvaluationDetails<T>>(() =>
     resolver(client).call(client, flagKey, defaultValue, options),
   );
+  
+  // Re-evaluate when dependencies change (handles prop changes like flagKey), or if during a re-render, we have detected a change in the evaluated value
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    
+    const newDetails = resolver(client).call(client, flagKey, defaultValue, options);
+    if (!isEqual(newDetails.value, evaluationDetails.value)) {
+      setEvaluationDetails(newDetails);
+    }
+  }, [client, flagKey, defaultValue, options, resolver, evaluationDetails]);
 
-  const updateEvaluationDetailsRef = () => {
-    setEvaluationDetails(resolver(client).call(client, flagKey, defaultValue, options));
-  };
+  // Maintain a mutable reference to the evaluation details to have a up-to-date reference in the handlers.
+  const evaluationDetailsRef = useRef<EvaluationDetails<T>>(evaluationDetails);
+  useEffect(() => {
+    evaluationDetailsRef.current = evaluationDetails;
+  }, [evaluationDetails]);
+
+  const updateEvaluationDetailsCallback = useCallback(() => {
+    const updatedEvaluationDetails = resolver(client).call(client, flagKey, defaultValue, options);
+
+    /**
+     * Avoid re-rendering if the value hasn't changed. We could expose a means
+     * to define a custom comparison function if users require a more
+     * sophisticated comparison in the future.
+     */
+    if (!isEqual(updatedEvaluationDetails.value, evaluationDetailsRef.current.value)) {
+      setEvaluationDetails(updatedEvaluationDetails);
+    }
+  }, [client, flagKey, defaultValue, options, resolver]);
+
+  const configurationChangeCallback = useCallback<EventHandler<ClientProviderEvents.ConfigurationChanged>>(
+    (eventDetails) => {
+      if (shouldEvaluateFlag(flagKey, eventDetails?.flagsChanged)) {
+        updateEvaluationDetailsCallback();
+      }
+    },
+    [flagKey, updateEvaluationDetailsCallback],
+  );
 
   useEffect(() => {
+    const controller = new AbortController();
     if (status === ProviderStatus.NOT_READY) {
       // update when the provider is ready
-      client.addHandler(ProviderEvents.Ready, updateEvaluationDetailsRef);
+      client.addHandler(ProviderEvents.Ready, updateEvaluationDetailsCallback, { signal: controller.signal });
     }
 
     if (defaultedOptions.updateOnContextChanged) {
       // update when the context changes
-      client.addHandler(ProviderEvents.ContextChanged, updateEvaluationDetailsRef);
+      client.addHandler(ProviderEvents.ContextChanged, updateEvaluationDetailsCallback, { signal: controller.signal });
     }
-    return () => {
-      // cleanup the handlers
-      client.removeHandler(ProviderEvents.Ready, updateEvaluationDetailsRef);
-      client.removeHandler(ProviderEvents.ContextChanged, updateEvaluationDetailsRef);
-    };
-  }, []);
 
-  useEffect(() => {
     if (defaultedOptions.updateOnConfigurationChanged) {
       // update when the provider configuration changes
-      client.addHandler(ProviderEvents.ConfigurationChanged, updateEvaluationDetailsRef);
+      client.addHandler(ProviderEvents.ConfigurationChanged, configurationChangeCallback, {
+        signal: controller.signal,
+      });
     }
     return () => {
       // cleanup the handlers
-      client.removeHandler(ProviderEvents.ConfigurationChanged, updateEvaluationDetailsRef);
+      controller.abort();
     };
-  }, []);
+  }, [
+    client,
+    status,
+    defaultedOptions.updateOnContextChanged,
+    defaultedOptions.updateOnConfigurationChanged,
+    updateEvaluationDetailsCallback,
+    configurationChangeCallback,
+  ]);
 
-  return evalutationDetails;
+  return evaluationDetails;
 }

packages/react/src/index.ts

@@ -1,5 +1,8 @@
 export * from './evaluation';
 export * from './query';
 export * from './provider';
+export * from './context';
+export * from './tracking';
+export * from './options';
 // re-export the web-sdk so consumers can access that API from the react-sdk
 export * from '@openfeature/web-sdk';

packages/react/src/internal/context.ts

@@ -1,17 +1,22 @@
-import { Client } from '@openfeature/web-sdk';
+import type { Client } from '@openfeature/web-sdk';
 import React from 'react';
-import { NormalizedOptions, ReactFlagEvaluationOptions, normalizeOptions } from '../common/options';
+import type { NormalizedOptions, ReactFlagEvaluationOptions } from '../options';
+import { normalizeOptions } from '.';
 
 /**
  * The underlying React context.
- * DO NOT EXPORT PUBLICLY
+ *
+ * **DO NOT EXPORT PUBLICLY**
  * @internal
  */
-export const Context = React.createContext<{ client: Client; options: ReactFlagEvaluationOptions } | undefined>(undefined);
+export const Context = React.createContext<
+  { client: Client; domain?: string; options: ReactFlagEvaluationOptions } | undefined
+>(undefined);
 
 /**
  * Get a normalized copy of the options used for this OpenFeatureProvider, see {@link normalizeOptions}.
- * DO NOT EXPORT PUBLICLY
+ *
+ * **DO NOT EXPORT PUBLICLY**
  * @internal
  * @returns {NormalizedOptions} normalized options the defaulted options, not defaulted or normalized.
  */

packages/react/src/internal/errors.ts

@@ -0,0 +1,9 @@
+const context = 'Components using OpenFeature must be wrapped with an <OpenFeatureProvider>.';
+const tip = 'If you are seeing this in a test, see: https://openfeature.dev/docs/reference/technologies/client/web/react#testing';
+
+export class MissingContextError extends Error {
+  constructor(reason: string) {
+    super(`${reason}: ${context} ${tip}`);
+    this.name = 'MissingContextError';
+  }
+}

packages/react/src/internal/hook-flag-query.ts

@@ -1,9 +1,10 @@
-import {
+import type {
   EvaluationDetails,
-  FlagValue,
+  FlagValue} from '@openfeature/web-sdk';
+import {
   StandardResolutionReasons
 } from '@openfeature/web-sdk';
-import { FlagQuery } from '../query';
+import type { FlagQuery } from '../query';
 
 
 // FlagQuery implementation, do not export

packages/react/src/internal/index.ts

@@ -0,0 +1,4 @@
+export * from './context';
+export * from './is-equal';
+export * from './options';
+export * from './suspense';

packages/react/src/internal/is-equal.ts

@@ -0,0 +1,38 @@
+import { type FlagValue } from '@openfeature/web-sdk';
+
+/**
+ * Deeply compare two values to determine if they are equal.
+ * Supports primitives and serializable objects.
+ * @param {FlagValue} value First value to compare
+ * @param {FlagValue} other Second value to compare
+ * @returns {boolean} True if the values are equal
+ */
+export function isEqual(value: FlagValue, other: FlagValue): boolean {
+  if (value === other) {
+    return true;
+  }
+
+  if (typeof value !== typeof other) {
+    return false;
+  }
+
+  if (typeof value === 'object' && value !== null && other !== null) {
+    const valueKeys = Object.keys(value);
+    const otherKeys = Object.keys(other);
+
+    if (valueKeys.length !== otherKeys.length) {
+      return false;
+    }
+
+    for (const key of valueKeys) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      if (!isEqual((value as any)[key], (other as any)[key])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}

packages/react/src/internal/options.ts

@@ -0,0 +1,40 @@
+import type { ReactFlagEvaluationOptions, NormalizedOptions } from '../options';
+
+/**
+ * Default options.
+ * DO NOT EXPORT PUBLICLY
+ * @internal
+ */
+export const DEFAULT_OPTIONS: ReactFlagEvaluationOptions = {
+  updateOnContextChanged: true,
+  updateOnConfigurationChanged: true,
+  suspendUntilReady: false,
+  suspendWhileReconciling: false,
+};
+
+/**
+ * Returns normalization options (all `undefined` fields removed, and `suspend` decomposed to `suspendUntilReady` and `suspendWhileReconciling`).
+ * DO NOT EXPORT PUBLICLY
+ * @internal
+ * @param {ReactFlagEvaluationOptions} options  options to normalize
+ * @returns {NormalizedOptions} normalized options
+ */
+export const normalizeOptions: (options?: ReactFlagEvaluationOptions) => NormalizedOptions = (
+  options: ReactFlagEvaluationOptions = {},
+) => {
+  const updateOnContextChanged = options.updateOnContextChanged;
+  const updateOnConfigurationChanged = options.updateOnConfigurationChanged;
+
+  // fall-back the suspense options to the catch-all `suspend` property
+  const suspendUntilReady = 'suspendUntilReady' in options ? options.suspendUntilReady : options.suspend;
+  const suspendWhileReconciling =
+    'suspendWhileReconciling' in options ? options.suspendWhileReconciling : options.suspend;
+
+  return {
+    // only return these if properly set (no undefined to allow overriding with spread)
+    ...(typeof suspendUntilReady === 'boolean' && { suspendUntilReady }),
+    ...(typeof suspendWhileReconciling === 'boolean' && { suspendWhileReconciling }),
+    ...(typeof updateOnContextChanged === 'boolean' && { updateOnContextChanged }),
+    ...(typeof updateOnConfigurationChanged === 'boolean' && { updateOnConfigurationChanged }),
+  };
+};

packages/react/src/internal/suspense.ts

@@ -0,0 +1,56 @@
+import type { Client, Provider } from '@openfeature/web-sdk';
+import { NOOP_PROVIDER, ProviderEvents } from '@openfeature/web-sdk';
+import { use } from './use';
+
+/**
+ * A weak map is used to store the global suspense status for each provider. It's
+ * important for this to be global to avoid rerender loops. Using useRef won't
+ * work because the value isn't preserved when a promise is thrown in a component,
+ * which is how suspense operates.
+ */
+const globalProviderSuspenseStatus = new WeakMap<Provider, Promise<unknown>>();
+
+/**
+ * Suspends until the client is ready to evaluate feature flags.
+ *
+ * **DO NOT EXPORT PUBLICLY**
+ * @internal
+ * @param {Provider} provider the provider to suspend for
+ * @param {Client} client the client to check for readiness
+ */
+export function suspendUntilInitialized(provider: Provider, client: Client) {
+  const statusPromiseRef = globalProviderSuspenseStatus.get(provider);
+  if (!statusPromiseRef) {
+    // Noop provider is never ready, so we resolve immediately
+    const statusPromise = provider !== NOOP_PROVIDER ? isProviderReady(client) : Promise.resolve();
+    globalProviderSuspenseStatus.set(provider, statusPromise);
+    // Use will throw the promise and React will trigger a rerender when it's resolved
+    use(statusPromise);
+  } else {
+    // Reuse the existing promise, use won't rethrow if the promise has settled.
+    use(statusPromiseRef);
+  }
+}
+
+/**
+ * Suspends until the provider has finished reconciling.
+ *
+ * **DO NOT EXPORT PUBLICLY**
+ * @internal
+ * @param {Client} client the client to check for readiness
+ */
+export function suspendUntilReconciled(client: Client) {
+  use(isProviderReady(client));
+}
+
+async function isProviderReady(client: Client) {
+  const controller = new AbortController();
+  try {
+    return await new Promise((resolve, reject) => {
+      client.addHandler(ProviderEvents.Ready, resolve, { signal: controller.signal });
+      client.addHandler(ProviderEvents.Error, reject, { signal: controller.signal });
+    });
+  } finally {
+    controller.abort();
+  }
+}

packages/react/src/internal/use.ts

@@ -0,0 +1,53 @@
+/// <reference types="react/experimental" />
+// This function is adopted from https://github.com/vercel/swr
+import React from 'react';
+
+/**
+ * Extends a Promise-like value to include status tracking.
+ * The extra properties are used to manage the lifecycle of the Promise, indicating its current state.
+ * More information can be found in the React RFE for the use hook.
+ * @see https://github.com/reactjs/rfcs/pull/229
+ */
+export type UsePromise<T> =
+  Promise<T> & {
+    status?: 'pending' | 'fulfilled' | 'rejected';
+    value?: T;
+    reason?: unknown;
+  };
+
+/**
+ * React.use is a React API that lets you read the value of a resource like a Promise or context.
+ * It was officially added in React 19, so needs to be polyfilled to support older React versions.
+ * @param {UsePromise} thenable A thenable object that represents a Promise-like value.
+ * @returns {unknown} The resolved value of the thenable or throws if it's still pending or rejected.
+ */
+export const use =
+  React.use ||
+  // This extra generic is to avoid TypeScript mixing up the generic and JSX syntax
+  // and emitting an error.
+  // We assume that this is only for the `use(thenable)` case, not `use(context)`.
+  // https://github.com/facebook/react/blob/aed00dacfb79d17c53218404c52b1c7aa59c4a89/packages/react-server/src/ReactFizzThenable.js#L45
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  (<T, _>(thenable: UsePromise<T>): T => {
+    switch (thenable.status) {
+      case 'pending':
+        throw thenable;
+      case 'fulfilled':
+        return thenable.value as T;
+      case 'rejected':
+        throw thenable.reason;
+      default:
+        thenable.status = 'pending';
+        thenable.then(
+          (v) => {
+            thenable.status = 'fulfilled';
+            thenable.value = v;
+          },
+          (e) => {
+            thenable.status = 'rejected';
+            thenable.reason = e;
+          },
+        );
+        throw thenable;
+    }
+  });

packages/react/src/options.ts

@@ -0,0 +1,53 @@
+import type { FlagEvaluationOptions } from '@openfeature/web-sdk';
+
+export type ReactFlagEvaluationOptions = (
+  | {
+      /**
+       * Enable or disable all suspense functionality.
+       * Cannot be used in conjunction with `suspendUntilReady` and `suspendWhileReconciling` options.
+       * @experimental Suspense is an experimental feature subject to change in future versions.
+       */
+      suspend?: boolean;
+      suspendUntilReady?: never;
+      suspendWhileReconciling?: never;
+    }
+  | {
+      /**
+       * Suspend flag evaluations while the provider is not ready.
+       * Set to false if you don't want to show suspense fallbacks until the provider is initialized.
+       * Defaults to false.
+       * Cannot be used in conjunction with `suspend` option.
+       * @experimental Suspense is an experimental feature subject to change in future versions.
+       */
+      suspendUntilReady?: boolean;
+      /**
+       * Suspend flag evaluations while the provider's context is being reconciled.
+       * Set to true if you want to show suspense fallbacks while flags are re-evaluated after context changes.
+       * Defaults to false.
+       * Cannot be used in conjunction with `suspend` option.
+       * @experimental Suspense is an experimental feature subject to change in future versions.
+       */
+      suspendWhileReconciling?: boolean;
+      suspend?: never;
+    }
+) & {
+  /**
+   * Update the component if the provider emits a ConfigurationChanged event.
+   * Set to false to prevent components from re-rendering when flag value changes
+   * are received by the associated provider.
+   * Defaults to true.
+   */
+  updateOnConfigurationChanged?: boolean;
+  /**
+   * Update the component when the OpenFeature context changes.
+   * Set to false to prevent components from re-rendering when attributes which
+   * may be factors in flag evaluation change.
+   * Defaults to true.
+   */
+  updateOnContextChanged?: boolean;
+} & FlagEvaluationOptions;
+
+// suspense options removed for the useSuspenseFlag hooks
+export type ReactFlagEvaluationNoSuspenseOptions = Omit<ReactFlagEvaluationOptions, 'suspend' | 'suspendUntilReady' | 'suspendWhileReconciling'>;
+
+export type NormalizedOptions = Omit<ReactFlagEvaluationOptions, 'suspend'>;

packages/react/src/provider/index.ts

@@ -1,3 +1,5 @@
 export * from './provider';
 export * from './use-open-feature-client';
 export * from './use-when-provider-ready';
+export * from './use-open-feature-client-status';
+export * from './test-provider';

packages/react/src/provider/provider.tsx

@@ -1,7 +1,8 @@
-import { Client, OpenFeature } from '@openfeature/web-sdk';
+import type { Client} from '@openfeature/web-sdk';
+import { OpenFeature } from '@openfeature/web-sdk';
 import * as React from 'react';
-import { ReactFlagEvaluationOptions } from '../common/options';
-import { Context } from './context';
+import type { ReactFlagEvaluationOptions } from '../options';
+import { Context } from '../internal';
 
 type ClientOrDomain =
   | {
@@ -30,10 +31,10 @@ type ProviderProps = {
    * @param {ProviderProps} properties props for the context provider
    * @returns {OpenFeatureProvider} context provider
    */
-export function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps) {
+export function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps): JSX.Element {
   if (!client) {
     client = OpenFeature.getClient(domain);
   }
 
-  return <Context.Provider value={{ client, options }}>{children}</Context.Provider>;
+  return <Context.Provider value={{ client, options, domain }}>{children}</Context.Provider>;
 }

packages/react/src/provider/test-provider.tsx

@@ -0,0 +1,122 @@
+import type {
+  JsonValue,
+  Provider} from '@openfeature/web-sdk';
+import {
+  InMemoryProvider,
+  NOOP_PROVIDER,
+  OpenFeature
+} from '@openfeature/web-sdk';
+import React from 'react';
+import type { NormalizedOptions } from '../options';
+import { OpenFeatureProvider } from './provider';
+
+type FlagValueMap = { [flagKey: string]: JsonValue };
+type FlagConfig = ConstructorParameters<typeof InMemoryProvider>[0];
+type TestProviderProps = Omit<React.ComponentProps<typeof OpenFeatureProvider>, 'client'> &
+  (
+    | {
+        provider?: never;
+        /**
+         * Optional map of flagKeys to flagValues for this OpenFeatureTestProvider context.
+         * If not supplied, all flag evaluations will default.
+         */
+        flagValueMap?: FlagValueMap;
+        /**
+         * Optional delay for the underlying test provider's readiness and reconciliation.
+         * Defaults to 0.
+         */
+        delayMs?: number;
+      }
+    | {
+        /**
+         * An optional partial provider to pass for full control over the flag resolution for this OpenFeatureTestProvider context.
+         * Any un-implemented methods or properties will no-op.
+         */
+        provider?: Partial<Provider>;
+        flagValueMap?: never;
+        delayMs?: never;
+      }
+  );
+
+  const TEST_VARIANT = 'test-variant';
+  const TEST_PROVIDER = 'test-provider';
+
+// internal provider which is basically the in-memory provider with a simpler config and some optional fake delays
+class TestProvider extends InMemoryProvider {
+
+  // initially make this undefined, we still set it if a delay is specified
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore - For maximum compatibility with previous versions, we ignore a possible TS error here,
+  // since "initialize" was previously defined in superclass.
+  // We can safely remove this ts-ignore in a few versions
+  initialize: Provider['initialize'] = undefined;
+
+  // "place-holder" init function which we only assign if want a delay
+  private delayedInitialize = async () => {
+    await new Promise<void>((resolve) => setTimeout(resolve, this.delay));
+  };
+
+  constructor(
+    flagValueMap: FlagValueMap,
+    private delay = 0,
+  ) {
+    // convert the simple flagValueMap into an in-memory config
+    const flagConfig = Object.entries(flagValueMap).reduce((acc: FlagConfig, flag): FlagConfig => {
+      return {
+        ...acc,
+        [flag[0]]: {
+          variants: {
+            [TEST_VARIANT]: flag[1],
+          },
+          defaultVariant: TEST_VARIANT,
+          disabled: false,
+        },
+      };
+    }, {});
+    super(flagConfig);
+    // only define and init if there's a non-zero delay specified
+    this.initialize = this.delay ? this.delayedInitialize.bind(this) : undefined;
+  }
+
+  async onContextChange() {
+    return new Promise<void>((resolve) => setTimeout(resolve, this.delay));
+  }
+}
+
+/**
+ * A React Context provider based on the {@link InMemoryProvider}, specifically built for testing.
+ * Use this for testing components that use flag evaluation hooks.
+ * @param {TestProviderProps} testProviderOptions options for the OpenFeatureTestProvider
+ * @returns {OpenFeatureProvider} OpenFeatureTestProvider
+ */
+export function OpenFeatureTestProvider(testProviderOptions: TestProviderProps) {
+  const { flagValueMap, provider } = testProviderOptions;
+  const effectiveProvider = (
+    flagValueMap ? new TestProvider(flagValueMap, testProviderOptions.delayMs) : mixInNoop(provider) || NOOP_PROVIDER
+  ) as Provider;
+  testProviderOptions.domain
+    ? OpenFeature.setProvider(testProviderOptions.domain, effectiveProvider)
+    : OpenFeature.setProvider(effectiveProvider);
+
+  return (
+    <OpenFeatureProvider {...(testProviderOptions as NormalizedOptions)} domain={testProviderOptions.domain}>
+      {testProviderOptions.children}
+    </OpenFeatureProvider>
+  );
+}
+
+// mix in the no-op provider when the partial is passed
+function mixInNoop(provider: Partial<Provider> = {}) {
+  // fill in any missing methods with no-ops
+  for (const prop of Object.getOwnPropertyNames(Object.getPrototypeOf(NOOP_PROVIDER)).filter(prop => prop !== 'constructor')) {
+    const patchedProvider = provider as {[key: string]: keyof Provider};
+    if (!Object.getPrototypeOf(patchedProvider)[prop] && !patchedProvider[prop]) {
+      patchedProvider[prop] = Object.getPrototypeOf(NOOP_PROVIDER)[prop];
+    }
+  }
+  // fill in the metadata if missing
+  if (!provider.metadata || !provider.metadata.name) {
+    (provider.metadata as unknown) = { name: TEST_PROVIDER };
+  }
+  return provider;
+}

packages/react/src/provider/use-open-feature-client-status.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { useOpenFeatureClient } from './use-open-feature-client';
-import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
+import type { ProviderStatus } from '@openfeature/web-sdk';
+import { ProviderEvents } from '@openfeature/web-sdk';
 
 /**
  * Get the {@link ProviderStatus} for the OpenFeatureClient.
@@ -8,23 +9,19 @@ import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
  */
 export function useOpenFeatureClientStatus(): ProviderStatus {
   const client = useOpenFeatureClient();
-  const [status, setStatus] = useState(client.providerStatus);
+  const [status, setStatus] = useState<ProviderStatus>(client.providerStatus);
+  const controller = new AbortController();
 
   useEffect(() => {
     const updateStatus = () => setStatus(client.providerStatus);
-    client.addHandler(ProviderEvents.ConfigurationChanged, updateStatus);
-    client.addHandler(ProviderEvents.ContextChanged, updateStatus);
-    client.addHandler(ProviderEvents.Error, updateStatus);
-    client.addHandler(ProviderEvents.Ready, updateStatus);
-    client.addHandler(ProviderEvents.Stale, updateStatus);
-    client.addHandler(ProviderEvents.Reconciling, updateStatus);
+    client.addHandler(ProviderEvents.ConfigurationChanged, updateStatus, { signal: controller.signal });
+    client.addHandler(ProviderEvents.ContextChanged, updateStatus, { signal: controller.signal });
+    client.addHandler(ProviderEvents.Error, updateStatus, { signal: controller.signal });
+    client.addHandler(ProviderEvents.Ready, updateStatus, { signal: controller.signal });
+    client.addHandler(ProviderEvents.Stale, updateStatus, { signal: controller.signal });
+    client.addHandler(ProviderEvents.Reconciling, updateStatus, { signal: controller.signal });
     return () => {
-      client.removeHandler(ProviderEvents.ConfigurationChanged, updateStatus);
-      client.removeHandler(ProviderEvents.ContextChanged, updateStatus);
-      client.removeHandler(ProviderEvents.Error, updateStatus);
-      client.removeHandler(ProviderEvents.Ready, updateStatus);
-      client.removeHandler(ProviderEvents.Stale, updateStatus);
-      client.removeHandler(ProviderEvents.Reconciling, updateStatus);
+      controller.abort();
     };
   }, [client]);
 

packages/react/src/provider/use-open-feature-client.ts

@@ -1,6 +1,7 @@
 import React from 'react';
-import { Context } from './context';
-import { Client } from '@openfeature/web-sdk';
+import { Context } from '../internal';
+import { type Client } from '@openfeature/web-sdk';
+import { MissingContextError } from '../internal/errors';
 
 /**
  * Get the {@link Client} instance for this OpenFeatureProvider context.
@@ -11,9 +12,7 @@ export function useOpenFeatureClient(): Client {
   const { client } = React.useContext(Context) || {};
 
   if (!client) {
-    throw new Error(
-      'No OpenFeature client available - components using OpenFeature must be wrapped with an <OpenFeatureProvider>',
-    );
+    throw new MissingContextError('No OpenFeature client available');
   }
 
   return client;

packages/react/src/provider/use-open-feature-provider.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import { Context } from '../internal';
+import { OpenFeature } from '@openfeature/web-sdk';
+import type { Provider } from '@openfeature/web-sdk';
+import { MissingContextError } from '../internal/errors';
+
+/**
+ * Get the {@link Provider} bound to the domain specified in the OpenFeatureProvider context.
+ * Note that it isn't recommended to interact with the provider directly, but rather through
+ * an OpenFeature client.
+ * @returns {Provider} provider for this scope
+ */
+export function useOpenFeatureProvider(): Provider {
+  const openFeatureContext = React.useContext(Context);
+
+  if (!openFeatureContext) {
+    throw new MissingContextError('No OpenFeature context available');
+  }
+
+  return OpenFeature.getProvider(openFeatureContext.domain);
+}

packages/react/src/provider/use-when-provider-ready.ts

@@ -1,9 +1,9 @@
 import { ProviderStatus } from '@openfeature/web-sdk';
-import { DEFAULT_OPTIONS, ReactFlagEvaluationOptions, normalizeOptions } from '../common/options';
-import { useProviderOptions } from './context';
 import { useOpenFeatureClient } from './use-open-feature-client';
 import { useOpenFeatureClientStatus } from './use-open-feature-client-status';
-import { suspendUntilReady } from '../common/suspense';
+import type { ReactFlagEvaluationOptions } from '../options';
+import { DEFAULT_OPTIONS, useProviderOptions, normalizeOptions, suspendUntilInitialized } from '../internal';
+import { useOpenFeatureProvider } from './use-open-feature-provider';
 
 type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
 
@@ -15,14 +15,14 @@ type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
  * @returns {boolean} boolean indicating if provider is {@link ProviderStatus.READY}, useful if suspense is disabled and you want to handle loaders on your own
  */
 export function useWhenProviderReady(options?: Options): boolean {
-  const client = useOpenFeatureClient();
-  const status = useOpenFeatureClientStatus();
   // highest priority > evaluation hook options > provider options > default options > lowest priority
   const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
+  const client = useOpenFeatureClient();
+  const status = useOpenFeatureClientStatus();
+  const provider = useOpenFeatureProvider();
 
-  // suspense
   if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
-    suspendUntilReady(client);
+    suspendUntilInitialized(provider, client);
   }
 
   return status === ProviderStatus.READY;

packages/react/src/query/query.ts

@@ -1,4 +1,4 @@
-import { ErrorCode, EvaluationDetails, FlagMetadata, FlagValue, StandardResolutionReasons } from '@openfeature/core';
+import type { ErrorCode, EvaluationDetails, FlagMetadata, FlagValue, StandardResolutionReasons } from '@openfeature/core';
 
 export interface FlagQuery<T extends FlagValue = FlagValue> {
   /**

packages/react/src/tracking/index.ts

@@ -0,0 +1 @@
+export * from './use-track';

packages/react/src/tracking/use-track.ts

@@ -0,0 +1,29 @@
+import type { Tracking, TrackingEventDetails } from '@openfeature/web-sdk';
+import { useCallback } from 'react';
+import { useOpenFeatureClient } from '../provider';
+
+export type Track = {
+  /**
+   * Context-aware tracking function for the parent `<OpenFeatureProvider/>`.
+   * Track a user action or application state, usually representing a business objective or outcome.
+   * @param trackingEventName an identifier for the event
+   * @param trackingEventDetails the details of the tracking event
+   */
+  track: Tracking['track'];
+};
+
+/**
+ * Get a context-aware tracking function.
+ * @returns {Track} context-aware tracking
+ */
+export function useTrack(): Track {
+  const client = useOpenFeatureClient();
+
+  const track = useCallback((trackingEventName: string, trackingEventDetails?: TrackingEventDetails) => {
+    client.track(trackingEventName, trackingEventDetails);
+  }, []);
+
+  return {
+    track,
+  };
+}

packages/react/test/evaluation.spec.tsx

@@ -1,17 +1,18 @@
-import {
-  EvaluationContext,
-  Hook,
-  InMemoryProvider,
-  OpenFeature,
-  StandardResolutionReasons,
-  EvaluationDetails,
-  ErrorCode,
-} from '@openfeature/web-sdk';
+import { jest } from '@jest/globals';
+import type { ProviderEmittableEvents } from '@openfeature/web-sdk';
+import { ClientProviderEvents } from '@openfeature/web-sdk';
+import type { FlagConfiguration } from '@openfeature/web-sdk/src/provider/in-memory-provider/flag-configuration';
 import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/react-testing-library/setup
 import { act, render, renderHook, screen, waitFor } from '@testing-library/react';
 import * as React from 'react';
+import { startTransition, useState } from 'react';
+import type { EvaluationContext, EvaluationDetails, EventContext, Hook } from '../src/';
 import {
+  ErrorCode,
+  InMemoryProvider,
+  OpenFeature,
   OpenFeatureProvider,
+  StandardResolutionReasons,
   useBooleanFlagDetails,
   useBooleanFlagValue,
   useFlag,
@@ -23,13 +24,26 @@ import {
   useStringFlagValue,
   useSuspenseFlag,
 } from '../src/';
+import { HookFlagQuery } from '../src/internal/hook-flag-query';
 import { TestingProvider } from './test.utils';
-import { HookFlagQuery } from '../src/evaluation/hook-flag-query';
-import { startTransition, useState } from 'react';
+
+// custom provider to have better control over the emitted events
+class CustomEventInMemoryProvider extends InMemoryProvider {
+  putConfigurationWithCustomEvent(
+    flagConfiguration: FlagConfiguration,
+    event: ProviderEmittableEvents,
+    eventContext: EventContext,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this['_flagConfiguration'] = { ...flagConfiguration }; // private access hack
+    this.events.emit(event, eventContext);
+  }
+}
 
 describe('evaluation', () => {
   const EVALUATION = 'evaluation';
   const BOOL_FLAG_KEY = 'boolean-flag';
+  const CONTEXT_BOOL_FLAG_KEY = 'context-sensitive-flag';
   const BOOL_FLAG_VARIANT = 'on';
   const BOOL_FLAG_VALUE = true;
   const STRING_FLAG_KEY = 'string-flag';
@@ -46,42 +60,54 @@ describe('evaluation', () => {
   const REASON_ATTR_VALUE = StandardResolutionReasons.STATIC;
   const TYPE_ATTR = 'data-type';
   const BUTTON_TEXT = 'button';
+  const FLAG_CONFIG: ConstructorParameters<typeof InMemoryProvider>[0] = {
+    [BOOL_FLAG_KEY]: {
+      disabled: false,
+      variants: {
+        [BOOL_FLAG_VARIANT]: BOOL_FLAG_VALUE,
+        off: false,
+      },
+      defaultVariant: BOOL_FLAG_VARIANT,
+    },
+    [STRING_FLAG_KEY]: {
+      disabled: false,
+      variants: {
+        [STRING_FLAG_VARIANT]: STRING_FLAG_VALUE,
+        parting: 'bye',
+      },
+      defaultVariant: STRING_FLAG_VARIANT,
+    },
+    [NUMBER_FLAG_KEY]: {
+      disabled: false,
+      variants: {
+        [NUMBER_FLAG_VARIANT]: NUMBER_FLAG_VALUE,
+        '2^1': 2,
+      },
+      defaultVariant: NUMBER_FLAG_VARIANT,
+    },
+    [OBJECT_FLAG_KEY]: {
+      disabled: false,
+      variants: {
+        [OBJECT_FLAG_VARIANT]: OBJECT_FLAG_VALUE,
+        empty: {},
+      },
+      defaultVariant: OBJECT_FLAG_VARIANT,
+    },
+    [CONTEXT_BOOL_FLAG_KEY]: {
+      disabled: false,
+      defaultVariant: 'off',
+      variants: {
+        off: false,
+        on: true,
+      },
+      contextEvaluator(ctx) {
+        return ctx.change ? 'on' : 'off';
+      },
+    },
+  };
 
   const makeProvider = () => {
-    return new InMemoryProvider({
-      [BOOL_FLAG_KEY]: {
-        disabled: false,
-        variants: {
-          [BOOL_FLAG_VARIANT]: BOOL_FLAG_VALUE,
-          off: false,
-        },
-        defaultVariant: BOOL_FLAG_VARIANT,
-      },
-      [STRING_FLAG_KEY]: {
-        disabled: false,
-        variants: {
-          [STRING_FLAG_VARIANT]: STRING_FLAG_VALUE,
-          parting: 'bye',
-        },
-        defaultVariant: STRING_FLAG_VARIANT,
-      },
-      [NUMBER_FLAG_KEY]: {
-        disabled: false,
-        variants: {
-          [NUMBER_FLAG_VARIANT]: NUMBER_FLAG_VALUE,
-          '2^1': 2,
-        },
-        defaultVariant: NUMBER_FLAG_VARIANT,
-      },
-      [OBJECT_FLAG_KEY]: {
-        disabled: false,
-        variants: {
-          [OBJECT_FLAG_VARIANT]: OBJECT_FLAG_VALUE,
-          empty: {},
-        },
-        defaultVariant: OBJECT_FLAG_VARIANT,
-      },
-    });
+    return new InMemoryProvider(FLAG_CONFIG);
   };
 
   OpenFeature.setProvider(EVALUATION, makeProvider());
@@ -246,9 +272,276 @@ describe('evaluation', () => {
         expect(objectElement).toHaveAttribute(REASON_ATTR, REASON_ATTR_VALUE);
       });
     });
+
+    describe('re-render', () => {
+      const RERENDER_DOMAIN = 'rerender';
+      const rerenderProvider = new CustomEventInMemoryProvider(FLAG_CONFIG);
+
+      function TestComponentFactory() {
+        let renderCount = 0;
+
+        return function TestComponent() {
+          const {
+            value: booleanVal,
+            reason: boolReason,
+            variant: boolVariant,
+            type: booleanType,
+          } = useFlag(BOOL_FLAG_KEY, false);
+
+          const {
+            value: contextBooleanVal,
+            reason: contextBoolReason,
+            variant: contextBoolVariant,
+            type: contextBooleanType,
+          } = useFlag('context-sensitive-flag', false);
+
+          const {
+            value: stringVal,
+            reason: stringReason,
+            variant: stringVariant,
+            type: stringType,
+          } = useFlag(STRING_FLAG_KEY, 'default');
+
+          const {
+            value: numberVal,
+            reason: numberReason,
+            variant: numberVariant,
+            type: numberType,
+          } = useFlag(NUMBER_FLAG_KEY, 0);
+
+          const {
+            value: objectVal,
+            reason: objectReason,
+            variant: objectVariant,
+            type: objectType,
+          } = useFlag(OBJECT_FLAG_KEY, {});
+
+          renderCount++;
+          return (
+            <>
+              <div data-testid="render-count">{renderCount}</div>
+              <div data-type={booleanType} data-variant={boolVariant} data-reason={boolReason}>{`${booleanVal}`}</div>
+              <div
+                data-type={contextBooleanType}
+                data-variant={contextBoolVariant}
+                data-reason={contextBoolReason}
+              >{`${contextBooleanVal}`}</div>
+              <div data-type={stringType} data-variant={stringVariant} data-reason={stringReason}>
+                {stringVal}
+              </div>
+              <div data-type={numberType} data-variant={numberVariant} data-reason={numberReason}>{`${numberVal}`}</div>
+              <div data-type={objectType} data-variant={objectVariant} data-reason={objectReason}>
+                {JSON.stringify(objectVal)}
+              </div>
+            </>
+          );
+        };
+      }
+
+      OpenFeature.setProvider(RERENDER_DOMAIN, rerenderProvider);
+
+      beforeEach(async () => {
+        await rerenderProvider.putConfiguration(FLAG_CONFIG);
+        await OpenFeature.setContext(RERENDER_DOMAIN, {});
+      });
+
+      afterEach(() => {
+        jest.clearAllMocks();
+      });
+
+      it('should not rerender on context change because the evaluated values did not change', async () => {
+        const TestComponent = TestComponentFactory();
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+
+        await act(async () => {
+          await OpenFeature.setContext(RERENDER_DOMAIN, {});
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+      });
+
+      it('should rerender on context change because the evaluated values changed', async () => {
+        const TestComponent = TestComponentFactory();
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+
+        await act(async () => {
+          await OpenFeature.setContext(RERENDER_DOMAIN, { change: true });
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('2');
+      });
+
+      it('should not render on flag change when the provider change event has empty flagsChanged', async () => {
+        const TestComponent = TestComponentFactory();
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+        await act(async () => {
+          await rerenderProvider.putConfigurationWithCustomEvent(
+            {
+              ...FLAG_CONFIG,
+              [BOOL_FLAG_KEY]: {
+                ...FLAG_CONFIG[BOOL_FLAG_KEY],
+                // Change the default; this should be ignored and not cause a re-render because flagsChanged is empty
+                defaultVariant: 'off',
+              },
+              // if the flagsChanged is empty, we know nothing has changed, so we don't bother diffing
+            },
+            ClientProviderEvents.ConfigurationChanged,
+            { flagsChanged: [] },
+          );
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+      });
+
+      it('should re-render on flag change because the provider change event has falsy flagsChanged', async () => {
+        const TestComponent = TestComponentFactory();
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+        await act(async () => {
+          await rerenderProvider.putConfigurationWithCustomEvent(
+            {
+              ...FLAG_CONFIG,
+              [BOOL_FLAG_KEY]: {
+                ...FLAG_CONFIG[BOOL_FLAG_KEY],
+                // Change the default variant to trigger a rerender since not only do we check flagsChanged, but we also diff the value
+                defaultVariant: 'off',
+              },
+              // if the flagsChanged is falsy, we don't know what flags changed - so we attempt to diff everything
+            },
+            ClientProviderEvents.ConfigurationChanged,
+            { flagsChanged: undefined },
+          );
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('2');
+      });
+
+      it('should not rerender on flag change because the evaluated values did not change', async () => {
+        const TestComponent = TestComponentFactory();
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+
+        await act(async () => {
+          await rerenderProvider.putConfiguration({
+            ...FLAG_CONFIG,
+            'new-flag': {
+              disabled: false,
+              defaultVariant: 'off',
+              variants: {
+                off: false,
+                on: true,
+              },
+            },
+          });
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+      });
+
+      it('should not rerender on flag change because the config values did not change', async () => {
+        const TestComponent = TestComponentFactory();
+        const resolverSpy = jest.spyOn(rerenderProvider, 'resolveBooleanEvaluation');
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+
+        await act(async () => {
+          await rerenderProvider.putConfiguration({
+            ...FLAG_CONFIG,
+          });
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+        // The resolver should not be called again because the flag config did not change
+        expect(resolverSpy).toHaveBeenNthCalledWith(
+          1,
+          BOOL_FLAG_KEY,
+          expect.anything(),
+          expect.anything(),
+          expect.anything(),
+        );
+      });
+
+      it('should rerender on flag change because the evaluated values changed', async () => {
+        const TestComponent = TestComponentFactory();
+        const resolverSpy = jest.spyOn(rerenderProvider, 'resolveBooleanEvaluation');
+        render(
+          <OpenFeatureProvider domain={RERENDER_DOMAIN}>
+            <TestComponent></TestComponent>
+          </OpenFeatureProvider>,
+        );
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
+
+        await act(async () => {
+          await rerenderProvider.putConfiguration({
+            ...FLAG_CONFIG,
+            [BOOL_FLAG_KEY]: {
+              ...FLAG_CONFIG[BOOL_FLAG_KEY],
+              // Change the default variant to trigger a rerender
+              defaultVariant: 'off',
+            },
+          });
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('2');
+
+        await act(async () => {
+          await rerenderProvider.putConfiguration({
+            ...FLAG_CONFIG,
+            [BOOL_FLAG_KEY]: {
+              ...FLAG_CONFIG[BOOL_FLAG_KEY],
+              // Change the default variant to trigger a rerender
+              defaultVariant: 'on',
+            },
+          });
+        });
+
+        expect(screen.queryByTestId('render-count')).toHaveTextContent('3');
+        expect(resolverSpy).toHaveBeenNthCalledWith(
+          3,
+          BOOL_FLAG_KEY,
+          expect.anything(),
+          expect.anything(),
+          expect.anything(),
+        );
+      });
+    });
   });
 
-  describe('re-rending and suspense', () => {
+  describe('re-rendering and suspense', () => {
     /**
      * artificial delay for various async operations for our provider,
      * multiples of it are used in assertions as well
@@ -284,12 +577,42 @@ describe('evaluation', () => {
       },
     };
 
+    afterEach(() => {
+      OpenFeature.clearProviders();
+    });
+
     const suspendingProvider = () => {
       return new TestingProvider(CONFIG, DELAY); // delay init by 100ms
     };
 
-    describe('updateOnConfigurationChanged=true (default)', () => {
+    describe('when using the noop provider', () => {
+      function TestComponent() {
+        const { value } = useSuspenseFlag(SUSPENSE_FLAG_KEY, DEFAULT);
+        return (
+          <>
+            <div>{value}</div>
+          </>
+        );
+      }
+      it('should fallback to the default value on the next rerender', async () => {
+        render(
+          <OpenFeatureProvider>
+            <React.Suspense fallback={<div>{FALLBACK}</div>}>
+              <TestComponent></TestComponent>
+            </React.Suspense>
+          </OpenFeatureProvider>,
+        );
+        // The loading indicator should be shown on the first render
+        expect(screen.queryByText(FALLBACK)).toBeInTheDocument();
 
+        // The default value should be shown on the next render
+        await waitFor(() => expect(screen.queryByText(DEFAULT)).toBeInTheDocument(), {
+          timeout: DELAY,
+        });
+      });
+    });
+
+    describe('updateOnConfigurationChanged=true (default)', () => {
       function TestComponent() {
         const { value } = useFlag(SUSPENSE_FLAG_KEY, DEFAULT);
         return (
@@ -297,7 +620,7 @@ describe('evaluation', () => {
             <div>{value}</div>
           </>
         );
-      } 
+      }
 
       it('should re-render after flag config changes', async () => {
         const provider = suspendingProvider();
@@ -334,7 +657,6 @@ describe('evaluation', () => {
     });
 
     describe.each([useFlag, useSuspenseFlag])('suspendUntilReady=true', (hook) => {
-
       const SUSPEND_UNTIL_READY_ON = 'suspendUntilReady';
 
       function TestComponent() {
@@ -344,7 +666,7 @@ describe('evaluation', () => {
             <div>{value}</div>
           </>
         );
-      }  
+      }
 
       it('should suspend until ready and then render', async () => {
         OpenFeature.setProvider(SUSPEND_UNTIL_READY_ON, suspendingProvider());
@@ -420,7 +742,6 @@ describe('evaluation', () => {
     });
 
     describe('suspendWhileReconciling=true', () => {
-      
       const SUSPEND_WHILE_RECONCILING_ON = 'suspendWhileReconciling=true';
 
       it('should suspend until reconciled and then render', async () => {
@@ -474,7 +795,7 @@ describe('evaluation', () => {
       it('should show the previous UI while reconciling during a transition', async () => {
         await OpenFeature.setContext(SUSPEND_WHILE_RECONCILING_ON, {});
         OpenFeature.setProvider(SUSPEND_WHILE_RECONCILING_ON, suspendingProvider());
-  
+
         function Component() {
           const { value } = useFlag(SUSPENSE_FLAG_KEY, DEFAULT, { suspendWhileReconciling: true });
           return <div>{value}</div>;
@@ -488,20 +809,20 @@ describe('evaluation', () => {
             </React.Suspense>
           </OpenFeatureProvider>,
         );
-  
+
         // initially should be default, because suspendUntilReady={false}
         expect(screen.queryByText(DEFAULT)).toBeInTheDocument();
-  
+
         // update the context without awaiting
         act(() => {
           startTransition(() => {
             OpenFeature.setContext(SUSPEND_WHILE_RECONCILING_ON, { user: TARGETED_USER });
           });
         });
-  
+
         // we should still see the same UI, because this is a transition update
         expect(screen.queryByText(DEFAULT)).toBeInTheDocument();
-  
+
         // make sure we updated after reconciling
         await waitFor(() => expect(screen.queryByText(TARGETED_FLAG_VALUE)).toBeInTheDocument(), {
           timeout: DELAY * 2,
@@ -510,8 +831,7 @@ describe('evaluation', () => {
     });
 
     describe.each([useFlag, useSuspenseFlag])('suspend=true', () => {
-      
-      const SUSPEND_ON = 'suspend=true';      
+      const SUSPEND_ON = 'suspend=true';
 
       it('should suspend on ready and reconcile and then render', async () => {
         await OpenFeature.setContext(SUSPEND_ON, {});
@@ -544,7 +864,9 @@ describe('evaluation', () => {
         expect(screen.queryByText(FALLBACK)).toBeInTheDocument();
 
         // expect to see value once we are ready
-        await waitFor(() => expect(screen.queryByText(STATIC_FLAG_VALUE_A)).toBeInTheDocument(), { timeout: DELAY * 2 });
+        await waitFor(() => expect(screen.queryByText(STATIC_FLAG_VALUE_A)).toBeInTheDocument(), {
+          timeout: DELAY * 2,
+        });
 
         // update the context without awaiting
         act(() => {
@@ -565,7 +887,6 @@ describe('evaluation', () => {
     });
 
     describe('suspend=false (default)', () => {
-
       const SUSPEND_OFF = 'suspend=false';
 
       function TestComponent() {
@@ -575,7 +896,7 @@ describe('evaluation', () => {
             <div>{value}</div>
           </>
         );
-      } 
+      }
       it('should not suspend until reconciled and then render', async () => {
         await OpenFeature.setContext(SUSPEND_OFF, {});
         OpenFeature.setProvider(SUSPEND_OFF, suspendingProvider());
@@ -603,17 +924,124 @@ describe('evaluation', () => {
           OpenFeature.setContext(SUSPEND_OFF, { user: TARGETED_USER });
         });
 
-        // expect to see static value until we reconcile
-        await waitFor(() => expect(screen.queryByText(STATIC_FLAG_VALUE_A)).toBeInTheDocument(), {
-          timeout: DELAY / 2,
-        });
-
-        // make sure we updated after reconciling
+        // With the fix for useState initialization, the hook now immediately
+        // reflects provider state changes. This is intentional to handle cases
+        // where providers don't emit proper events.
+        // The value updates immediately to the targeted value.
         await waitFor(() => expect(screen.queryByText(TARGETED_FLAG_VALUE)).toBeInTheDocument(), {
           timeout: DELAY * 2,
         });
       });
     });
+
+    describe('re-render behavior when flag values change without provider events', ()=> {
+      it('should reflect provider state changes on re-render even without provider events', async () => {
+        let providerValue = 'initial-value';
+        
+        class SilentUpdateProvider extends InMemoryProvider {
+          resolveBooleanEvaluation() {
+            return {
+              value: true,
+              variant: 'on',
+              reason: StandardResolutionReasons.STATIC,
+            };
+          }
+          
+          resolveStringEvaluation() {
+            return {
+              value: providerValue,
+              variant: providerValue,
+              reason: StandardResolutionReasons.STATIC,
+            };
+          }
+        }
+        
+        const provider = new SilentUpdateProvider({});
+        await OpenFeature.setProviderAndWait('test', provider);
+        
+        // The triggerRender prop forces a re-render
+        const TestComponent = ({ triggerRender }: { triggerRender: number }) => {
+          const { value } = useFlag('test-flag', 'default');
+          return <div data-testid="flag-value" data-render-count={triggerRender}>{value}</div>;
+        };
+        
+        const WrapperComponent = () => {
+          const [renderCount, setRenderCount] = useState(0);
+          return (
+            <>
+              <button onClick={() => setRenderCount(c => c + 1)}>Force Re-render</button>
+              <TestComponent triggerRender={renderCount} />
+            </>
+          );
+        };
+        
+        const { getByText } = render(
+          <OpenFeatureProvider client={OpenFeature.getClient('test')}>
+            <WrapperComponent />
+          </OpenFeatureProvider>
+        );
+        
+        // Initial value should be rendered
+        await waitFor(() => {
+          expect(screen.getByTestId('flag-value')).toHaveTextContent('initial-value');
+        });
+        
+        // Change the provider's internal state (without emitting events)
+        providerValue = 'updated-value';
+        
+        // Force a re-render of the component
+        act(() => {
+          getByText('Force Re-render').click();
+        });
+        
+        await waitFor(() => {
+          expect(screen.getByTestId('flag-value')).toHaveTextContent('updated-value');
+        });
+      });
+
+      it('should update flag value when flag key prop changes without provider events', async () => {
+        const provider = new InMemoryProvider({
+          'flag-a': {
+            disabled: false,
+            variants: { on: 'value-a' },
+            defaultVariant: 'on',
+          },
+          'flag-b': {
+            disabled: false,
+            variants: { on: 'value-b' },
+            defaultVariant: 'on',
+          },
+        });
+        
+        await OpenFeature.setProviderAndWait(EVALUATION, provider);
+        
+        const TestComponent = ({ flagKey }: { flagKey: string }) => {
+          const { value } = useFlag(flagKey, 'default');
+          return <div data-testid="flag-value">{value}</div>;
+        };
+        
+        const { rerender } = render(
+          <OpenFeatureProvider client={OpenFeature.getClient(EVALUATION)}>
+            <TestComponent flagKey="flag-a" />
+          </OpenFeatureProvider>
+        );
+        
+        await waitFor(() => {
+          expect(screen.getByTestId('flag-value')).toHaveTextContent('value-a');
+        });
+        
+        // Change to flag-b (without any provider events)
+        rerender(
+          <OpenFeatureProvider client={OpenFeature.getClient(EVALUATION)}>
+            <TestComponent flagKey="flag-b" />
+          </OpenFeatureProvider>
+        );
+        
+        await waitFor(() => {
+          expect(screen.getByTestId('flag-value')).toHaveTextContent('value-b');
+        });
+      });
+    });
   });
 
   describe('context, hooks and options', () => {
@@ -772,12 +1200,12 @@ describe('evaluation', () => {
       });
     });
 
-    describe('HookFlagQuery',  () => {
+    describe('HookFlagQuery', () => {
       it('should return details', () => {
         const details: EvaluationDetails<string> = {
           flagKey: 'flag-key',
-          flagMetadata : {},
-          value: 'string'
+          flagMetadata: {},
+          value: 'string',
         };
         const hookFlagQuery = new HookFlagQuery(details);
         expect(hookFlagQuery.details).toEqual(details);
@@ -785,7 +1213,7 @@ describe('evaluation', () => {
 
       it('should return flag metadata', () => {
         const flagMetadata = {
-          'ping': 'pong'
+          ping: 'pong',
         };
         const details: EvaluationDetails<boolean> = {
           flagKey: 'with-flagMetadata',
@@ -797,22 +1225,26 @@ describe('evaluation', () => {
       });
 
       it.each([
-        [{
-          flagKey: 'i-dont-exist',
-          flagMetadata: {},
-          errorMessage: 'no flag found with key i-dont-exist',
-          errorCode: ErrorCode.FLAG_NOT_FOUND,
-          value: true
-        }],
-        [{
-          flagKey: 'i-dont-exist',
-          flagMetadata: {},
-          errorMessage: 'no flag found with key i-dont-exist',
-          errorCode: undefined,
-          reason: StandardResolutionReasons.ERROR,
-          value: true
-        }],
-      ])('should return errors if reason is error or errorCode is set',(details) => {;
+        [
+          {
+            flagKey: 'i-dont-exist',
+            flagMetadata: {},
+            errorMessage: 'no flag found with key i-dont-exist',
+            errorCode: ErrorCode.FLAG_NOT_FOUND,
+            value: true,
+          },
+        ],
+        [
+          {
+            flagKey: 'i-dont-exist',
+            flagMetadata: {},
+            errorMessage: 'no flag found with key i-dont-exist',
+            errorCode: undefined,
+            reason: StandardResolutionReasons.ERROR,
+            value: true,
+          },
+        ],
+      ])('should return errors if reason is error or errorCode is set', (details) => {
         const hookFlagQuery = new HookFlagQuery(details);
         expect(hookFlagQuery.isError).toEqual(true);
         expect(hookFlagQuery.errorCode).toEqual(details.errorCode);
@@ -820,33 +1252,46 @@ describe('evaluation', () => {
       });
 
       it.each([
-        [{
-          flagKey: 'isAuthorative-true',
-          flagMetadata : {},
-          value: 7,
-        }, true],
-        [{
-          flagKey: 'with-error',
-          flagMetadata : {},
-          value: 7,
-          errorCode: ErrorCode.FLAG_NOT_FOUND
-        }, false],
-        [{
-          flagKey: 'with-reason-stale',
-          flagMetadata : {},
-          value: 7,
-          reason: StandardResolutionReasons.STALE
-        }, false],
-        [{
-          flagKey: 'with-reason-disabled',
-          flagMetadata : {},
-          value: 7,
-          reason: StandardResolutionReasons.DISABLED
-        }, false],
-      ])('should return isAuthorative if Reason != STALE/DISABLED and errorCode unset',(details, expected) => {
+        [
+          {
+            flagKey: 'isAuthoritative-true',
+            flagMetadata: {},
+            value: 7,
+          },
+          true,
+        ],
+        [
+          {
+            flagKey: 'with-error',
+            flagMetadata: {},
+            value: 7,
+            errorCode: ErrorCode.FLAG_NOT_FOUND,
+          },
+          false,
+        ],
+        [
+          {
+            flagKey: 'with-reason-stale',
+            flagMetadata: {},
+            value: 7,
+            reason: StandardResolutionReasons.STALE,
+          },
+          false,
+        ],
+        [
+          {
+            flagKey: 'with-reason-disabled',
+            flagMetadata: {},
+            value: 7,
+            reason: StandardResolutionReasons.DISABLED,
+          },
+          false,
+        ],
+      ])('should return isAuthoritative if Reason != STALE/DISABLED and errorCode unset', (details, expected) => {
         const hookFlagQuery = new HookFlagQuery(details);
         expect(hookFlagQuery.isAuthoritative).toEqual(expected);
       });
     });
   });
 });
+

packages/react/test/is-equal.spec.ts

@@ -0,0 +1,50 @@
+import { isEqual } from '../src/internal/is-equal';
+
+describe('isEqual', () => {
+  it('should return true for equal primitive values', () => {
+    expect(isEqual(5, 5)).toBe(true);
+    expect(isEqual('hello', 'hello')).toBe(true);
+    expect(isEqual(true, true)).toBe(true);
+  });
+
+  it('should return false for different primitive values', () => {
+    expect(isEqual(5, 10)).toBe(false);
+    expect(isEqual('hello', 'world')).toBe(false);
+    expect(isEqual(true, false)).toBe(false);
+  });
+
+  it('should return true for equal serializable objects', () => {
+    const obj1 = { name: 'John', age: 30 };
+    const obj2 = { name: 'John', age: 30 };
+    expect(isEqual(obj1, obj2)).toBe(true);
+  });
+
+  it('should return false for different serializable objects', () => {
+    const obj1 = { name: 'John', age: 30 };
+    const obj2 = { name: 'Jane', age: 25 };
+    expect(isEqual(obj1, obj2)).toBe(false);
+  });
+
+  it('should return true for equal deep objects', () => {
+    const obj1 = { name: 'John', age: 30, address: { city: 'New York', country: 'USA' } };
+    const obj2 = { name: 'John', age: 30, address: { city: 'New York', country: 'USA' } };
+    expect(isEqual(obj1, obj2)).toBe(true);
+  });
+
+  it('should return true for equal deep objects with properties in a different order', () => {
+    const obj1 = { name: 'John', age: 30, address: { city: 'New York', country: 'USA' } };
+    const obj2 = { address: { country: 'USA', city: 'New York' }, age: 30, name: 'John' };
+    expect(isEqual(obj1, obj2)).toBe(true);
+  });
+  it('should return true for equal arrays', () => {
+    const arr1 = [1, 2, 3];
+    const arr2 = [1, 2, 3];
+    expect(isEqual(arr1, arr2)).toBe(true);
+  });
+
+  it('should return false for different arrays', () => {
+    const arr1 = [1, 2, 3];
+    const arr2 = [3, 2, 1];
+    expect(isEqual(arr1, arr2)).toBe(false);
+  });
+});

packages/react/test/options.spec.ts

@@ -1,4 +1,4 @@
-import { normalizeOptions } from '../src/common/options';
+import { normalizeOptions } from '../src/internal/options';
 
 describe('normalizeOptions', () => {
   // we spread results from this function, so we never want to return null

packages/react/test/provider.spec.tsx

@@ -1,11 +1,18 @@
-import { EvaluationContext, OpenFeature } from '@openfeature/web-sdk';
+import type { EvaluationContext} from '@openfeature/web-sdk';
+import { InMemoryProvider, OpenFeature } from '@openfeature/web-sdk';
 import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/react-testing-library/setup
-import { render, renderHook, screen, waitFor } from '@testing-library/react';
+import { render, renderHook, screen, waitFor, fireEvent, act } from '@testing-library/react';
 import * as React from 'react';
-import { OpenFeatureProvider, useOpenFeatureClient, useWhenProviderReady } from '../src';
+import {
+  OpenFeatureProvider,
+  useOpenFeatureClient,
+  useWhenProviderReady,
+  useContextMutator,
+  useStringFlagValue,
+} from '../src';
 import { TestingProvider } from './test.utils';
 
-describe('provider', () => {
+describe('OpenFeatureProvider', () => {
   /**
    * artificial delay for various async operations for our provider,
    * multiples of it are used in assertions as well
@@ -33,6 +40,9 @@ describe('provider', () => {
             if (context.user == 'bob@flags.com') {
               return 'both';
             }
+            if (context.done === true) {
+              return 'parting';
+            }
             return 'greeting';
           },
         },
@@ -137,4 +147,148 @@ describe('provider', () => {
       });
     });
   });
+  describe('useMutateContext', () => {
+    const MutateButton = () => {
+      const { setContext } = useContextMutator();
+
+      return <button onClick={() => setContext({ user: 'bob@flags.com' })}>Update Context</button>;
+    };
+    const TestComponent = ({ name }: { name: string }) => {
+      const flagValue = useStringFlagValue<'hi' | 'bye' | 'aloha'>(SUSPENSE_FLAG_KEY, 'hi');
+
+      return (
+        <div>
+          <MutateButton />
+          <div>{`${name} says ${flagValue}`}</div>
+        </div>
+      );
+    };
+
+    it('should update context when a domain is set', async () => {
+      const DOMAIN = 'mutate-context-tests';
+      OpenFeature.setProvider(DOMAIN, suspendingProvider());
+      render(
+        <OpenFeatureProvider domain={DOMAIN}>
+          <React.Suspense fallback={<div>{FALLBACK}</div>}>
+            <TestComponent name="Will" />
+          </React.Suspense>
+        </OpenFeatureProvider>,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByText('Will says hi')).toBeInTheDocument();
+      });
+
+      act(() => {
+        fireEvent.click(screen.getByText('Update Context'));
+      });
+      await waitFor(
+        () => {
+          expect(screen.getByText('Will says aloha')).toBeInTheDocument();
+        },
+        { timeout: DELAY * 4 },
+      );
+    });
+
+    it('should update nested contexts', async () => {
+      const DOMAIN1 = 'Wills Domain';
+      const DOMAIN2 = 'Todds Domain';
+      OpenFeature.setProvider(DOMAIN1, suspendingProvider());
+      OpenFeature.setProvider(DOMAIN2, suspendingProvider());
+      render(
+        <OpenFeatureProvider domain={DOMAIN1}>
+          <React.Suspense fallback={<div>{FALLBACK}</div>}>
+            <TestComponent name="Will" />
+            <OpenFeatureProvider domain={DOMAIN2}>
+              <React.Suspense fallback={<div>{FALLBACK}</div>}>
+                <TestComponent name="Todd" />
+              </React.Suspense>
+            </OpenFeatureProvider>
+          </React.Suspense>
+        </OpenFeatureProvider>,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByText('Todd says hi')).toBeInTheDocument();
+      });
+
+      act(() => {
+        // Click the Update context button in Todds domain
+        fireEvent.click(screen.getAllByText('Update Context')[1]);
+      });
+      await waitFor(
+        () => {
+          expect(screen.getByText('Todd says aloha')).toBeInTheDocument();
+        },
+        { timeout: DELAY * 4 },
+      );
+      await waitFor(
+        () => {
+          expect(screen.getByText('Will says hi')).toBeInTheDocument();
+        },
+        { timeout: DELAY * 4 },
+      );
+    });
+
+    it('should update nested global contexts', async () => {
+      const DOMAIN1 = 'Wills Domain';
+      OpenFeature.setProvider(DOMAIN1, suspendingProvider());
+      OpenFeature.setProvider(new InMemoryProvider({
+        globalFlagsHere: {
+          defaultVariant: 'a',
+          variants: {
+            a: 'Smile',
+            b: 'Frown',
+          },
+          disabled: false,
+          contextEvaluator: (ctx: EvaluationContext) => {
+            if (ctx.user === 'bob@flags.com') {
+              return 'b';
+            }
+
+            return 'a';
+          },
+        }
+      }));
+      const GlobalComponent = ({ name }: { name: string }) => {
+        const flagValue = useStringFlagValue<'b' | 'a'>('globalFlagsHere', 'a');
+
+        return (
+          <div>
+            <MutateButton />
+            <div>{`${name} likes to ${flagValue}`}</div>
+          </div>
+        );
+      };
+      render(
+        <OpenFeatureProvider domain={DOMAIN1}>
+          <React.Suspense fallback={<div>{FALLBACK}</div>}>
+            <TestComponent name="Will" />
+            <OpenFeatureProvider>
+              <React.Suspense fallback={<div>{FALLBACK}</div>}>
+                <GlobalComponent name="Todd" />
+              </React.Suspense>
+            </OpenFeatureProvider>
+          </React.Suspense>
+        </OpenFeatureProvider>,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByText('Todd likes to Smile')).toBeInTheDocument();
+      });
+
+      act(() => {
+        // Click the Update context button in Todds domain
+        fireEvent.click(screen.getAllByText('Update Context')[1]);
+      });
+      await waitFor(
+        () => {
+          expect(screen.getByText('Todd likes to Frown')).toBeInTheDocument();
+        },
+        { timeout: DELAY * 4 },
+      );
+
+      expect(screen.getByText('Will says aloha')).toBeInTheDocument();
+    });
+  });
 });

packages/react/test/test-provider.spec.tsx

@@ -0,0 +1,131 @@
+import type { Provider, ResolutionDetails } from '@openfeature/web-sdk';
+import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/react-testing-library/setup
+import { render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { OpenFeatureTestProvider, useFlag } from '../src';
+
+const FLAG_KEY = 'thumbs';
+
+function TestComponent(props: { suspend: boolean }) {
+  const { value: thumbs, reason } = useFlag(FLAG_KEY, false, { suspend: props.suspend });
+  return (
+    <>
+      <div>{thumbs ? '👍' : '👎'}</div>
+      <div>reason: {`${reason}`}</div>
+      </>
+  );
+}
+
+describe('OpenFeatureTestProvider', () => {
+  describe('no args', () => {
+    it('renders default', async () => {
+      render(
+        <OpenFeatureTestProvider>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+      expect(screen.getByText('👎')).toBeInTheDocument();
+    });
+  });
+
+  describe('flagValueMap set', () => {
+    it('renders value from map', async () => {
+      render(
+        <OpenFeatureTestProvider flagValueMap={{ [FLAG_KEY]: true }}>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+
+      expect(screen.getByText('👍')).toBeInTheDocument();
+    });
+  });
+
+  describe('delay and flagValueMap set', () => {
+    it('renders value after delay', async () => {
+      const delay = 100;
+      render(
+        <OpenFeatureTestProvider delayMs={delay} flagValueMap={{ [FLAG_KEY]: true }}>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+
+      // should only be resolved after delay
+      expect(screen.getByText('👎')).toBeInTheDocument();
+      await new Promise((resolve) => setTimeout(resolve, delay * 4));
+      expect(screen.getByText('👍')).toBeInTheDocument();
+    });
+  });
+
+  describe('provider set', () => {
+    const reason = 'MY_REASON';
+
+    it('renders provider-returned value', async () => {
+      class MyTestProvider implements Partial<Provider> {
+        resolveBooleanEvaluation(): ResolutionDetails<boolean> {
+          return {
+            value: true,
+            variant: 'test-variant',
+            reason,
+          };
+        }
+      }
+
+      render(
+        <OpenFeatureTestProvider provider={new MyTestProvider()}>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+
+      expect(screen.getByText('👍')).toBeInTheDocument();
+      expect(screen.getByText(new RegExp(`${reason}`))).toBeInTheDocument();
+    });
+
+    it('falls back to no-op for missing methods', async () => {
+      class MyEmptyProvider implements Partial<Provider> {}
+
+      render(
+        <OpenFeatureTestProvider provider={new MyEmptyProvider()}>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+
+      expect(screen.getByText('👎')).toBeInTheDocument();
+      expect(screen.getByText(/No-op/)).toBeInTheDocument();
+    });
+  });
+
+  describe('component under test suspends', () => {
+    describe('delay non-zero', () => {
+      it('renders fallback then value after delay', async () => {
+        const delay = 100;
+        render(
+          <OpenFeatureTestProvider delayMs={delay} flagValueMap={{ [FLAG_KEY]: true }}>
+            <React.Suspense fallback={<>🕒</>}>
+              <TestComponent suspend={true} />
+            </React.Suspense>
+          </OpenFeatureTestProvider>,
+        );
+
+        // should initially show fallback, then resolve
+        expect(screen.getByText('🕒')).toBeInTheDocument();
+        await new Promise((resolve) => setTimeout(resolve, delay * 4));
+        expect(screen.getByText('👍')).toBeInTheDocument();
+      });
+    });
+
+    describe('delay zero', () => {
+      it('renders value immediately', async () => {
+        render(
+          <OpenFeatureTestProvider delayMs={0} flagValueMap={{ [FLAG_KEY]: true }}>
+            <React.Suspense fallback={<>🕒</>}>
+              <TestComponent suspend={true} />
+            </React.Suspense>
+          </OpenFeatureTestProvider>,
+        );
+
+        // should resolve immediately since delay is falsy
+        expect(screen.getByText('👍')).toBeInTheDocument();
+      });
+    });
+  });
+});

packages/react/test/test.utils.ts

@@ -1,4 +1,4 @@
-import { EvaluationContext, InMemoryProvider } from '@openfeature/web-sdk';
+import { InMemoryProvider } from '@openfeature/web-sdk';
 
 export class TestingProvider extends InMemoryProvider {
     constructor(
@@ -9,9 +9,8 @@ export class TestingProvider extends InMemoryProvider {
     }
   
     // artificially delay our init (delaying PROVIDER_READY event)
-    async initialize(context?: EvaluationContext | undefined): Promise<void> {
+    async initialize(): Promise<void> {
       await new Promise((resolve) => setTimeout(resolve, this.delay));
-      return super.initialize(context);
     }
   
     // artificially delay context changes

packages/react/test/tracking.spec.tsx

@@ -0,0 +1,88 @@
+import { jest } from '@jest/globals';
+import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/react-testing-library/setup
+import { render } from '@testing-library/react';
+import * as React from 'react';
+import type { Provider, TrackingEventDetails } from '../src';
+import {
+  OpenFeature,
+  OpenFeatureProvider,
+  useTrack
+} from '../src';
+
+describe('tracking', () => {
+
+  const eventName = 'test-tracking-event';
+  const trackingValue = 1234;
+  const trackingDetails: TrackingEventDetails = {
+    value: trackingValue,
+  };
+  const domain = 'someDomain';
+
+  const mockProvider = () => {
+    const mockProvider: Provider = {
+      metadata: {
+        name: 'mock',
+      },
+
+      track: jest.fn((): void => {
+        return;
+      }),
+    } as unknown as Provider;
+
+    return mockProvider;
+  };
+
+  describe('no domain', () => {
+    it('should call default provider', async () => {
+
+      const provider = mockProvider();
+      await OpenFeature.setProviderAndWait(provider);
+
+      function Component() {
+        const { track } = useTrack();
+        track(eventName, trackingDetails);
+
+        return <div></div>;
+      }
+
+      render(
+        <OpenFeatureProvider suspend={false} >
+            <Component></Component>
+        </OpenFeatureProvider>,
+      );
+
+      expect(provider.track).toHaveBeenCalledWith(
+        eventName,
+        expect.anything(),
+        expect.objectContaining({ value: trackingValue }),
+      );
+    });
+  });
+
+  describe('domain set', () => {
+    it('should call provider for domain', async () => {
+
+      const domainProvider = mockProvider();
+      await OpenFeature.setProviderAndWait(domain, domainProvider);
+
+      function Component() {
+        const { track } = useTrack();
+        track(eventName, trackingDetails);
+
+        return <div></div>;
+      }
+
+      render(
+        <OpenFeatureProvider domain={domain} suspend={false} >
+            <Component></Component>
+        </OpenFeatureProvider>,
+      );
+
+      expect(domainProvider.track).toHaveBeenCalledWith(
+        eventName,
+        expect.anything(),
+        expect.objectContaining({ value: trackingValue }),
+      );
+    });
+  });
+});

packages/react/tsconfig.json

@@ -10,9 +10,9 @@
     // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
     // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
     /* Language and Environment */
-    "target": "ES2022", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "target": "ES2015", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
     "lib": [
-      "ES2022",
+      "ES2015",
       "DOM"
     ], /* Specify a set of bundled library declaration files that describe the target runtime environment. */
     // "jsx": "preserve",                                /* Specify what JSX code is generated. */
@@ -25,13 +25,13 @@
     // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
     // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
     /* Modules */
-    "module": "ES2022", /* Specify what module code is generated. */
+    "module": "ES2015", /* Specify what module code is generated. */
     // "rootDir": "./",                                  /* Specify the root folder within your source files. */
     "moduleResolution": "node", /* Specify how TypeScript looks up a file from a given module specifier. */
     // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
     "paths": {
       "@openfeature/core": [ "../shared/src" ],
-      "@openfeature/web-sdk": [ "../client/src" ]
+      "@openfeature/web-sdk": [ "../web/src" ]
     },                                     /* Specify a set of entries that re-map imports to additional lookup locations. */
     // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
     // "typeRoots": [],                                  /* Specify multiple folders that act like `./node_modules/@types`. */

packages/server/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## [1.19.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.18.0...server-sdk-v1.19.0) (2025-08-14)
+
+
+### ✨ New Features
+
+* add evaluation-scoped hook data ([#1216](https://github.com/open-feature/js-sdk/issues/1216)) ([07af3a9](https://github.com/open-feature/js-sdk/commit/07af3a9eda895e9edb24c7ee1e3c1c4f16e17431))
+
+
+### 🐛 Bug Fixes
+
+* update core dep ([#1228](https://github.com/open-feature/js-sdk/issues/1228)) ([845d24c](https://github.com/open-feature/js-sdk/commit/845d24c5fecc80de3080e49fde839f08ecac6b33))
+
+
+### 🧹 Chore
+
+* update node to v20+ ([#1203](https://github.com/open-feature/js-sdk/issues/1203)) ([1f33453](https://github.com/open-feature/js-sdk/commit/1f33453c23df0763cbf0d0b44db8d91216377009))
+
+
+### 📚 Documentation
+
+* Clarify the behavior of setProviderAndWait ([#1180](https://github.com/open-feature/js-sdk/issues/1180)) ([4fe8d87](https://github.com/open-feature/js-sdk/commit/4fe8d87a2e5df2cbd4086cc4f4a380e8857ed8ba))
+
+## [1.18.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.17.1...server-sdk-v1.18.0) (2025-04-11)
+
+
+### ✨ New Features
+
+* add a top-level method for accessing providers ([#1152](https://github.com/open-feature/js-sdk/issues/1152)) ([ae8fce8](https://github.com/open-feature/js-sdk/commit/ae8fce87530005ed20f7e68dc696ce67053fca31))
+* add support for abort controllers to event handlers ([#1151](https://github.com/open-feature/js-sdk/issues/1151)) ([6a22483](https://github.com/open-feature/js-sdk/commit/6a224830fa4e62fc30a7802536f6f6fc3f772038))
+
+## [1.17.1](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.17.0...server-sdk-v1.17.1) (2025-02-07)
+
+
+### 🐛 Bug Fixes
+
+* msg missing when providers return err resolutions ([#1134](https://github.com/open-feature/js-sdk/issues/1134)) ([bc9f6e4](https://github.com/open-feature/js-sdk/commit/bc9f6e44da3f1c0a66659aee2d0316629ac34fbf))
+
+
+### 🧹 Chore
+
+* update core peer ([8bbd43e](https://github.com/open-feature/js-sdk/commit/8bbd43e579a0c2e0c5b7eec00f94bbcffce04773))
+
+
+### 📚 Documentation
+
+* fix eval context link ([#1132](https://github.com/open-feature/js-sdk/issues/1132)) ([f6bc695](https://github.com/open-feature/js-sdk/commit/f6bc6951a32fbbed9b35c1bdfd023b02874b87a1))
+
+## [1.17.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.16.2...server-sdk-v1.17.0) (2024-12-18)
+
+### ⚠ BREAKING CHANGES
+
+The signature of the `finally` hook stage has been changed. The signature now includes the `evaluation details`, as per the [OpenFeature specification](https://openfeature.dev/specification/sections/hooks#requirement-438). Note that since hooks are still `experimental,` this does not constitute a change requiring a new major version. To migrate, update any hook that implements the `finally` stage to accept `evaluation details` as the second argument.
+
+* add evaluation details to finally hook ([#1087](https://github.com/open-feature/js-sdk/issues/1087)) ([2135254](https://github.com/open-feature/js-sdk/commit/2135254c4bee52b4bcadfbf8b99a896cfd930cca))
+
+### ✨ New Features
+
+* add evaluation details to finally hook ([#1087](https://github.com/open-feature/js-sdk/issues/1087)) ([2135254](https://github.com/open-feature/js-sdk/commit/2135254c4bee52b4bcadfbf8b99a896cfd930cca))
+
+
+### 📚 Documentation
+
+* fix comment in README for Hook’s after method ([#1103](https://github.com/open-feature/js-sdk/issues/1103)) ([e335615](https://github.com/open-feature/js-sdk/commit/e3356157d5910d9196e8968c20d4c9a46c4de910))
+
+
+### 🔄 Refactoring
+
+* improve track interface for providers ([#1100](https://github.com/open-feature/js-sdk/issues/1100)) ([5e5b160](https://github.com/open-feature/js-sdk/commit/5e5b16022122b71760634ac90e3fd962aa831c74))
+
+## [1.16.2](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.16.1...server-sdk-v1.16.2) (2024-11-07)
+
+
+### 🧹 Chore
+
+* loosen peer dependency requirements, remove some ci automation ([#1080](https://github.com/open-feature/js-sdk/issues/1080)) ([ef3ba21](https://github.com/open-feature/js-sdk/commit/ef3ba2167ac95cd0c6a046d206bd60bbcf84e80c))
+
+
+### 🚀 Performance
+
+* avoid using exceptions for flow control ([#1074](https://github.com/open-feature/js-sdk/issues/1074)) ([26264d6](https://github.com/open-feature/js-sdk/commit/26264d6d090b2ed31b27d36e71194b9fa911563b))
+
+## [1.16.1](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.16.0...server-sdk-v1.16.1) (2024-10-29)
+
+
+### 📚 Documentation
+
+* add tracking sections ([#1068](https://github.com/open-feature/js-sdk/issues/1068)) ([e131faf](https://github.com/open-feature/js-sdk/commit/e131faffad9025e9c7194f39558bf3b3cec31807))
+
+## [1.16.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.15.1...server-sdk-v1.16.0) (2024-10-29)
+
+
+### ✨ New Features
+
+* implement tracking as per spec ([#1020](https://github.com/open-feature/js-sdk/issues/1020)) ([80f182e](https://github.com/open-feature/js-sdk/commit/80f182e1afbd3a705bf3de6a0d9886ccb3424b44))
+
+
+### 🧹 Chore
+
+* import type lint rule and fixes ([#1039](https://github.com/open-feature/js-sdk/issues/1039)) ([01fcb93](https://github.com/open-feature/js-sdk/commit/01fcb933d2cbd131a0f4a005173cdd1906087e18))
+* **main:** release core 1.5.0 ([#1040](https://github.com/open-feature/js-sdk/issues/1040)) ([fe3ad8e](https://github.com/open-feature/js-sdk/commit/fe3ad8eeb9219ff08ba287cab228016da0b88e88))
+
+## [1.15.1](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.15.0...server-sdk-v1.15.1) (2024-08-28)
+
+
+### 🧹 Chore
+
+* add assertion for hook context contents ([#977](https://github.com/open-feature/js-sdk/issues/977)) ([964d65b](https://github.com/open-feature/js-sdk/commit/964d65b7751d1a78a932e928d1ecfd9c071e1109))
+* **main:** release core 1.4.0 ([#984](https://github.com/open-feature/js-sdk/issues/984)) ([01344b2](https://github.com/open-feature/js-sdk/commit/01344b28c1381d9de3aefde89be841b597a00b70))
+
+## [1.15.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.14.0...server-sdk-v1.15.0) (2024-06-11)
+
+
+### ✨ New Features
+
+* lower compilation target to es2015 ([#957](https://github.com/open-feature/js-sdk/issues/957)) ([c2d6c17](https://github.com/open-feature/js-sdk/commit/c2d6c1761ae19f937deaff2f011a0380f8af7350))
+
+
+### 🧹 Chore
+
+* **main:** release core 1.3.0 ([#958](https://github.com/open-feature/js-sdk/issues/958)) ([25086c5](https://github.com/open-feature/js-sdk/commit/25086c5456d81fa040ce95ea1a067543408e3150))
+
 ## [1.14.0](https://github.com/open-feature/js-sdk/compare/server-sdk-v1.13.5...server-sdk-v1.14.0) (2024-05-13)
 
 

packages/server/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
   <!-- x-release-please-start-version -->
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/server-sdk-v1.14.0">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.14.0&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/server-sdk-v1.19.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.19.0&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -64,7 +64,7 @@ npm install --save @openfeature/server-sdk
 yarn add @openfeature/server-sdk @openfeature/core
 ```
 
-> [!NOTE]  
+> [!NOTE]
 > `@openfeature/core` contains common components used by all OpenFeature JavaScript implementations.
 > Every SDK version has a requirement on a single, specific version of this dependency.
 > For more information, and similar implications on libraries developed with OpenFeature see [considerations when extending](#considerations).
@@ -75,7 +75,11 @@ yarn add @openfeature/server-sdk @openfeature/core
 import { OpenFeature } from '@openfeature/server-sdk';
 
 // Register your feature flag provider
-await OpenFeature.setProviderAndWait(new YourProviderOfChoice());
+try {
+  await OpenFeature.setProviderAndWait(new YourProviderOfChoice());
+} catch (error) {
+  console.error('Failed to initialize provider:', error);
+}
 
 // create a new client
 const client = OpenFeature.getClient();
@@ -96,15 +100,16 @@ See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_server_sdk
 
 | Status | Features                                                            | Description                                                                                                                           |
 | ------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| ✅     | [Providers](#providers)                                             | Integrate with a commercial, open source, or in-house feature management tool.                                                        |
-| ✅     | [Targeting](#targeting)                                             | Contextually-aware flag evaluation using [evaluation context](/docs/reference/concepts/evaluation-context).                           |
-| ✅     | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                |
-| ✅     | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                              |
-| ✅     | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                |
-| ✅     | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                     |
-| ✅     | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                           |
-| ✅     | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
-| ✅     | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                   |
+| ✅      | [Providers](#providers)                                             | Integrate with a commercial, open source, or in-house feature management tool.                                                        |
+| ✅      | [Targeting](#targeting)                                             | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).                           |
+| ✅      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                |
+| ✅      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                              |
+| ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                |
+| ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                     |
+| ✅      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
+| ✅      | [Tracking](#tracking)                                               | Associate user actions with feature flag evaluations, particularly for A/B testing.                                                   |
+| ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                           |
+| ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                   |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
 
@@ -289,6 +294,21 @@ app.use((req: Request, res: Response, next: NextFunction) => {
 })
 ```
 
+### Tracking
+
+The tracking API allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
+This is essential for robust experimentation powered by feature flags.
+For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](#hooks) or [provider](#providers) can be associated with telemetry reported in the client's `track` function.
+
+```ts
+// flag is evaluated
+await client.getBooleanValue('new-feature', false);
+
+// new feature is used and track function is called recording the usage
+useNewFeature();
+client.track('new-feature-used');
+```
+
 ### Shutdown
 
 The OpenFeature API provides a close function to perform a cleanup of all registered providers.
@@ -367,7 +387,7 @@ import type { Hook, HookContext, EvaluationDetails, FlagValue } from "@openfeatu
 
 export class MyHook implements Hook {
   after(hookContext: HookContext, evaluationDetails: EvaluationDetails<FlagValue>) {
-    // code that runs when there's an error during a flag evaluation
+    // code that runs after flag values are successfully resolved from the provider
   }
 }
 ```

packages/server/e2e/step-definitions/evaluation.spec.ts

@@ -1,9 +1,10 @@
-import {
+import type {
   EvaluationContext,
   EvaluationDetails,
   JsonObject,
   JsonValue,
-  ResolutionDetails,
+  ResolutionDetails} from '@openfeature/core';
+import {
   StandardResolutionReasons,
 } from '@openfeature/core';
 import { defineFeature, loadFeature } from 'jest-cucumber';

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/server-sdk",
-  "version": "1.14.0",
+  "version": "1.19.0",
   "description": "OpenFeature SDK for JavaScript",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -16,16 +16,16 @@
   "scripts": {
     "test": "jest --verbose",
     "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
     "clean": "shx rm -rf ./dist",
-    "build:esm": "esbuild src/index.ts --bundle --external:@openfeature/core --sourcemap --target=es2022 --platform=node --format=esm --outfile=./dist/esm/index.js --analyze",
-    "build:cjs": "esbuild src/index.ts --bundle --external:@openfeature/core --sourcemap --target=es2022 --platform=node --format=cjs --outfile=./dist/cjs/index.js --analyze",
+    "build:esm": "esbuild src/index.ts --bundle --external:@openfeature/core --sourcemap --target=es2015 --platform=node --format=esm --outfile=./dist/esm/index.js --analyze",
+    "build:cjs": "esbuild src/index.ts --bundle --external:@openfeature/core --sourcemap --target=es2015 --platform=node --format=cjs --outfile=./dist/cjs/index.js --analyze",
     "build:rollup-types": "rollup -c ../../rollup.config.mjs",
     "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:rollup-types",
     "postbuild": "shx cp ./../../package.esm.json ./dist/esm/package.json",
     "current-version": "echo $npm_package_version",
     "prepack": "shx cp ./../../LICENSE ./LICENSE",
-    "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",
-    "update-core-peer": "npm install --save-peer --save-exact @openfeature/core@$OPENFEATURE_CORE_VERSION"
+    "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"
   },
   "repository": {
     "type": "git",
@@ -45,12 +45,12 @@
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "peerDependencies": {
-    "@openfeature/core": "1.2.0"
+    "@openfeature/core": "^1.9.0"
   },
   "devDependencies": {
-    "@openfeature/core": "1.2.0"
+    "@openfeature/core": "^1.9.0"
   }
 }

packages/server/src/client/client.ts

@@ -1,19 +1,21 @@
-import {
+import type {
   ClientMetadata,
   EvaluationLifeCycle,
   Eventing,
   ManageContext,
   ManageLogger,
 } from '@openfeature/core';
-import { Features } from '../evaluation';
-import { ProviderStatus } from '../provider';
-import { ProviderEvents } from '../events';
+import type { Features } from '../evaluation';
+import type { ProviderStatus } from '../provider';
+import type { ProviderEvents } from '../events';
+import type { Tracking } from '../tracking';
 
 export interface Client
   extends EvaluationLifeCycle<Client>,
     Features,
     ManageContext<Client>,
     ManageLogger<Client>,
+    Tracking,
     Eventing<ProviderEvents> {
   readonly metadata: ClientMetadata;
   /**

packages/server/src/client/internal/open-feature-client.ts

@@ -1,6 +1,5 @@
-import {
+import type {
   ClientMetadata,
-  ErrorCode,
   EvaluationContext,
   EvaluationDetails,
   EventHandler,
@@ -9,22 +8,29 @@ import {
   HookContext,
   JsonValue,
   Logger,
+  TrackingEventDetails,
   OpenFeatureError,
+  FlagMetadata,
+  ResolutionDetails,
+  EventOptions,
+} from '@openfeature/core';
+import {
+  ErrorCode,
   ProviderFatalError,
   ProviderNotReadyError,
-  ResolutionDetails,
   SafeLogger,
   StandardResolutionReasons,
   instantiateErrorByErrorCode,
   statusMatchesEvent,
+  MapHookData,
 } from '@openfeature/core';
-import { FlagEvaluationOptions } from '../../evaluation';
-import { ProviderEvents } from '../../events';
-import { InternalEventEmitter } from '../../events/internal/internal-event-emitter';
-import { Hook } from '../../hooks';
-import { OpenFeature } from '../../open-feature';
-import { Provider, ProviderStatus } from '../../provider';
-import { Client } from './../client';
+import type { FlagEvaluationOptions } from '../../evaluation';
+import type { ProviderEvents } from '../../events';
+import type { InternalEventEmitter } from '../../events/internal/internal-event-emitter';
+import type { Hook } from '../../hooks';
+import type { Provider } from '../../provider';
+import { ProviderStatus } from '../../provider';
+import type { Client } from './../client';
 
 type OpenFeatureClientOptions = {
   /**
@@ -51,6 +57,9 @@ export class OpenFeatureClient implements Client {
     private readonly providerAccessor: () => Provider,
     private readonly providerStatusAccessor: () => ProviderStatus,
     private readonly emitterAccessor: () => InternalEventEmitter,
+    private readonly apiContextAccessor: () => EvaluationContext,
+    private readonly apiHooksAccessor: () => Hook[],
+    private readonly transactionContextAccessor: () => EvaluationContext,
     private readonly globalLogger: () => Logger,
     private readonly options: OpenFeatureClientOptions,
     context: EvaluationContext = {},
@@ -72,7 +81,7 @@ export class OpenFeatureClient implements Client {
     return this.providerStatusAccessor();
   }
 
-  addHandler(eventType: ProviderEvents, handler: EventHandler): void {
+  addHandler(eventType: ProviderEvents, handler: EventHandler, options?: EventOptions): void {
     this.emitterAccessor().addHandler(eventType, handler);
     const shouldRunNow = statusMatchesEvent(eventType, this._providerStatus);
 
@@ -88,6 +97,12 @@ export class OpenFeatureClient implements Client {
         this._logger?.error('Error running event handler:', err);
       }
     }
+
+    if (options?.signal && typeof options.signal.addEventListener === 'function') {
+      options.signal.addEventListener('abort', () => {
+        this.removeHandler(eventType, handler);
+      });
+    }
   }
 
   removeHandler(eventType: ProviderEvents, handler: EventHandler) {
@@ -221,6 +236,22 @@ export class OpenFeatureClient implements Client {
     return this.evaluate<T>(flagKey, this._provider.resolveObjectEvaluation, defaultValue, 'object', context, options);
   }
 
+  track(occurrenceKey: string, context: EvaluationContext = {}, occurrenceDetails: TrackingEventDetails = {}): void {
+    try {
+      this.shortCircuitIfNotReady();
+
+      if (typeof this._provider.track === 'function') {
+        // freeze the merged context
+        const frozenContext = Object.freeze(this.mergeContexts(context));
+        return this._provider.track?.(occurrenceKey, frozenContext, occurrenceDetails);
+      } else {
+        this._logger.debug('Provider does not support the track function; will no-op.');
+      }
+    } catch (err) {
+      this._logger.debug('Error recording tracking event.', err);
+    }
+  }
+
   private async evaluate<T extends FlagValue>(
     flagKey: string,
     resolver: (
@@ -237,110 +268,114 @@ export class OpenFeatureClient implements Client {
     // merge global, client, and evaluation context
 
     const allHooks = [
-      ...OpenFeature.getHooks(),
+      ...this.apiHooksAccessor(),
       ...this.getHooks(),
       ...(options.hooks || []),
       ...(this._provider.hooks || []),
     ];
     const allHooksReversed = [...allHooks].reverse();
 
-    // merge global and client contexts
-    const mergedContext = {
-      ...OpenFeature.getContext(),
-      ...OpenFeature.getTransactionContext(),
-      ...this._context,
-      ...invocationContext,
-    };
+    const mergedContext = this.mergeContexts(invocationContext);
 
-    // this reference cannot change during the course of evaluation
-    // it may be used as a key in WeakMaps
-    const hookContext: Readonly<HookContext> = {
-      flagKey,
-      defaultValue,
-      flagValueType: flagType,
-      clientMetadata: this.metadata,
-      providerMetadata: this._provider.metadata,
-      context: mergedContext,
-      logger: this._logger,
-    };
+    // Create hook context instances for each hook (stable object references for the entire evaluation)
+    // This ensures hooks can use WeakMaps with hookContext as keys across lifecycle methods
+    // NOTE: Uses the reversed order to reduce the number of times we have to calculate the index.
+    const hookContexts = allHooksReversed.map<HookContext>(() =>
+      Object.freeze({
+        flagKey,
+        defaultValue,
+        flagValueType: flagType,
+        clientMetadata: this.metadata,
+        providerMetadata: this._provider.metadata,
+        context: mergedContext,
+        logger: this._logger,
+        hookData: new MapHookData(),
+      }),
+    );
+
+    let evaluationDetails: EvaluationDetails<T>;
 
     try {
-      const frozenContext = await this.beforeHooks(allHooks, hookContext, options);
+      const frozenContext = await this.beforeHooks(allHooks, hookContexts, mergedContext, options);
 
-      // short circuit evaluation entirely if provider is in a bad state
-      if (this.providerStatus === ProviderStatus.NOT_READY) {
-        throw new ProviderNotReadyError('provider has not yet initialized');
-      } else if (this.providerStatus === ProviderStatus.FATAL) {
-        throw new ProviderFatalError('provider is in an irrecoverable error state');
-      }
+      this.shortCircuitIfNotReady();
 
       // run the referenced resolver, binding the provider.
       const resolution = await resolver.call(this._provider, flagKey, defaultValue, frozenContext, this._logger);
 
-      const evaluationDetails = {
+      const resolutionDetails = {
         ...resolution,
         flagMetadata: Object.freeze(resolution.flagMetadata ?? {}),
         flagKey,
       };
 
-      if (evaluationDetails.errorCode) {
-        throw instantiateErrorByErrorCode(evaluationDetails.errorCode);
+      if (resolutionDetails.errorCode) {
+        const err = instantiateErrorByErrorCode(resolutionDetails.errorCode, resolutionDetails.errorMessage);
+        await this.errorHooks(allHooksReversed, hookContexts, err, options);
+        evaluationDetails = this.getErrorEvaluationDetails(flagKey, defaultValue, err, resolutionDetails.flagMetadata);
+      } else {
+        await this.afterHooks(allHooksReversed, hookContexts, resolutionDetails, options);
+        evaluationDetails = resolutionDetails;
       }
-
-      await this.afterHooks(allHooksReversed, hookContext, evaluationDetails, options);
-
-      return evaluationDetails;
     } catch (err: unknown) {
-      const errorMessage: string = (err as Error)?.message;
-      const errorCode: ErrorCode = (err as OpenFeatureError)?.code || ErrorCode.GENERAL;
-
-      await this.errorHooks(allHooksReversed, hookContext, err, options);
-
-      return {
-        errorCode,
-        errorMessage,
-        value: defaultValue,
-        reason: StandardResolutionReasons.ERROR,
-        flagMetadata: Object.freeze({}),
-        flagKey,
-      };
-    } finally {
-      await this.finallyHooks(allHooksReversed, hookContext, options);
+      await this.errorHooks(allHooksReversed, hookContexts, err, options);
+      evaluationDetails = this.getErrorEvaluationDetails(flagKey, defaultValue, err);
     }
+
+    await this.finallyHooks(allHooksReversed, hookContexts, evaluationDetails, options);
+    return evaluationDetails;
   }
 
-  private async beforeHooks(hooks: Hook[], hookContext: HookContext, options: FlagEvaluationOptions) {
-    for (const hook of hooks) {
-      // freeze the hookContext
-      Object.freeze(hookContext);
+  private async beforeHooks(
+    hooks: Hook[],
+    hookContexts: HookContext[],
+    mergedContext: EvaluationContext,
+    options: FlagEvaluationOptions,
+  ) {
+    let accumulatedContext = mergedContext;
 
-      // use Object.assign to avoid modification of frozen hookContext
-      Object.assign(hookContext.context, {
-        ...hookContext.context,
-        ...(await hook?.before?.(hookContext, Object.freeze(options.hookHints))),
-      });
+    for (const [index, hook] of hooks.entries()) {
+      const hookContextIndex = hooks.length - 1 - index; // reverse index for before hooks
+      const hookContext = hookContexts[hookContextIndex];
+
+      // Update the context on the stable hook context object
+      Object.assign(hookContext.context, accumulatedContext);
+
+      const hookResult = await hook?.before?.(hookContext, Object.freeze(options.hookHints));
+      if (hookResult) {
+        accumulatedContext = {
+          ...accumulatedContext,
+          ...hookResult,
+        };
+
+        for (let i = 0; i < hooks.length; i++) {
+          Object.assign(hookContexts[hookContextIndex].context, accumulatedContext);
+        }
+      }
     }
 
     // after before hooks, freeze the EvaluationContext.
-    return Object.freeze(hookContext.context);
+    return Object.freeze(accumulatedContext);
   }
 
   private async afterHooks(
     hooks: Hook[],
-    hookContext: HookContext,
+    hookContexts: HookContext[],
     evaluationDetails: EvaluationDetails<FlagValue>,
     options: FlagEvaluationOptions,
   ) {
     // run "after" hooks sequentially
-    for (const hook of hooks) {
+    for (const [index, hook] of hooks.entries()) {
+      const hookContext = hookContexts[index];
       await hook?.after?.(hookContext, evaluationDetails, options.hookHints);
     }
   }
 
-  private async errorHooks(hooks: Hook[], hookContext: HookContext, err: unknown, options: FlagEvaluationOptions) {
+  private async errorHooks(hooks: Hook[], hookContexts: HookContext[], err: unknown, options: FlagEvaluationOptions) {
     // run "error" hooks sequentially
-    for (const hook of hooks) {
+    for (const [index, hook] of hooks.entries()) {
       try {
+        const hookContext = hookContexts[index];
         await hook?.error?.(hookContext, err, options.hookHints);
       } catch (err) {
         this._logger.error(`Unhandled error during 'error' hook: ${err}`);
@@ -352,11 +387,17 @@ export class OpenFeatureClient implements Client {
     }
   }
 
-  private async finallyHooks(hooks: Hook[], hookContext: HookContext, options: FlagEvaluationOptions) {
+  private async finallyHooks(
+    hooks: Hook[],
+    hookContexts: HookContext[],
+    evaluationDetails: EvaluationDetails<FlagValue>,
+    options: FlagEvaluationOptions,
+  ) {
     // run "finally" hooks sequentially
-    for (const hook of hooks) {
+    for (const [index, hook] of hooks.entries()) {
       try {
-        await hook?.finally?.(hookContext, options.hookHints);
+        const hookContext = hookContexts[index];
+        await hook?.finally?.(hookContext, evaluationDetails, options.hookHints);
       } catch (err) {
         this._logger.error(`Unhandled error during 'finally' hook: ${err}`);
         if (err instanceof Error) {
@@ -378,4 +419,42 @@ export class OpenFeatureClient implements Client {
   private get _logger() {
     return this._clientLogger || this.globalLogger();
   }
+
+  private mergeContexts(invocationContext: EvaluationContext) {
+    // merge global and client contexts
+    return {
+      ...this.apiContextAccessor(),
+      ...this.transactionContextAccessor(),
+      ...this._context,
+      ...invocationContext,
+    };
+  }
+
+  private shortCircuitIfNotReady() {
+    // short circuit evaluation entirely if provider is in a bad state
+    if (this.providerStatus === ProviderStatus.NOT_READY) {
+      throw new ProviderNotReadyError('provider has not yet initialized');
+    } else if (this.providerStatus === ProviderStatus.FATAL) {
+      throw new ProviderFatalError('provider is in an irrecoverable error state');
+    }
+  }
+
+  private getErrorEvaluationDetails<T extends FlagValue>(
+    flagKey: string,
+    defaultValue: T,
+    err: unknown,
+    flagMetadata: FlagMetadata = {},
+  ): EvaluationDetails<T> {
+    const errorMessage: string = (err as Error)?.message;
+    const errorCode: ErrorCode = (err as OpenFeatureError)?.code || ErrorCode.GENERAL;
+
+    return {
+      errorCode,
+      errorMessage,
+      value: defaultValue,
+      reason: StandardResolutionReasons.ERROR,
+      flagMetadata: Object.freeze(flagMetadata),
+      flagKey,
+    };
+  }
 }

packages/server/src/evaluation/evaluation.ts

@@ -1,5 +1,5 @@
-import { EvaluationContext, EvaluationDetails, HookHints, JsonValue } from '@openfeature/core';
-import { Hook } from '../hooks';
+import type { EvaluationContext, EvaluationDetails, HookHints, JsonValue } from '@openfeature/core';
+import type { Hook } from '../hooks';
 
 export interface FlagEvaluationOptions {
   hooks?: Hook[];

packages/server/src/events/internal/internal-event-emitter.ts

@@ -1,5 +1,5 @@
 import { GenericEventEmitter } from '@openfeature/core';
-import { ProviderEvents } from '../events';
+import type { ProviderEvents } from '../events';
 
 /**
  * The InternalEventEmitter is not exported publicly and should only be used within the SDK. It extends the

packages/server/src/events/open-feature-event-emitter.ts

@@ -1,6 +1,6 @@
 import { GenericEventEmitter } from '@openfeature/core';
 import { EventEmitter } from 'node:events';
-import { ProviderEvents } from './events';
+import type { ProviderEvents } from './events';
 
 /**
  * The OpenFeatureEventEmitter can be used by provider developers to emit

packages/server/src/hooks/hook.ts

@@ -1,7 +1,8 @@
-import { BaseHook, EvaluationContext, FlagValue } from '@openfeature/core';
+import type { BaseHook, EvaluationContext, FlagValue } from '@openfeature/core';
 
-export type Hook = BaseHook<
+export type Hook<TData = Record<string, unknown>> = BaseHook<
   FlagValue,
+  TData,
   Promise<EvaluationContext | void> | EvaluationContext | void,
   Promise<void> | void
 >;

packages/server/src/index.ts

@@ -5,4 +5,5 @@ export * from './open-feature';
 export * from './transaction-context';
 export * from './events';
 export * from './hooks';
+export * from './tracking';
 export * from '@openfeature/core';