You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## This PR
- Adds docs to the NestJS SDK.
### Notes
I think we're probably reaching a stable point for the NestJS SDK.
It would be great to have some feedback on the docs before it.
### Follow-up Tasks
- Blog post & announcement regarding the new SDK (maybe?)
---------
Signed-off-by: Luiz Ribeiro <[email protected]>
Signed-off-by: Luiz Guilherme Ribeiro <[email protected]>
Signed-off-by: Lukas Reining <[email protected]>
Co-authored-by: Michael Beemer <[email protected]>
Co-authored-by: Lukas Reining <[email protected]>
[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API
26
30
for feature flagging that works with your favorite feature flag management tool.
27
31
28
-
🧪 This SDK is experimental.
32
+
<!-- x-hide-in-docs-end -->
33
+
34
+
## Overview
35
+
36
+
The OpenFeature NestJS SDK is a package that provides a NestJS wrapper for the [OpenFeature Server SDK](https://openfeature.dev/docs/reference/technologies/server/javascript/).
37
+
38
+
Capabilities include:
39
+
40
+
- Provide a NestJS global module to simplify OpenFeature configuration and usage within NestJS;
41
+
- Injecting feature flags directly into controller route handlers by using decorators;
42
+
- Injecting transaction evaluation context for flag evaluations directly from [execution context](https://docs.nestjs.com/fundamentals/execution-context) (HTTP header values, client IPs, etc.);
43
+
- Injecting OpenFeature clients into NestJS services and controllers by using decorators;
44
+
- Setting up logging, event handling, hooks and providers directly when registering the module.
45
+
46
+
## 🚀 Quick start
47
+
48
+
### Requirements
49
+
50
+
- Node.js version 16+
51
+
- NestJS version 8+
52
+
53
+
### Install
54
+
55
+
#### npm
56
+
57
+
```sh
58
+
npm install --save @openfeature/nestjs-sdk
59
+
```
60
+
61
+
#### Required peer dependencies
29
62
30
-
#### Here's a basic example of how to use the OpenFeature NestJS API with `InMemoryProvider`.
63
+
The following list contains the peer dependencies of `@openfeature/nestjs-sdk` with it's expected and compatible versions:
31
64
32
-
#### Registering the Nest.js SDK module in the App Module:
65
+
*`@openfeature/server-sdk`: >=1.7.5
66
+
*`@nestjs/common`: ^8.0.0 || ^9.0.0 || ^10.0.0
67
+
*`@nestjs/core`: ^8.0.0 || ^9.0.0 || ^10.0.0
68
+
*`rxjs`: ^6.0.0 || ^7.0.0 || ^8.0.0
69
+
70
+
The minimum required version of `@openfeature/server-sdk` currently is `1.7.5`.
71
+
72
+
### Usage
73
+
74
+
The example below shows how to use the `OpenFeatureModule` with OpenFeature's `InMemoryProvider`.
33
75
34
76
```ts
35
77
import { Module } from'@nestjs/common';
@@ -44,24 +86,19 @@ import { InMemoryProvider } from '@openfeature/web-sdk';
44
86
testBooleanFlag: {
45
87
defaultVariant: 'default',
46
88
variants: { default: true },
47
-
disabled: false
89
+
disabled: false,
48
90
},
49
-
companyName: {
50
-
defaultVariant: 'default',
51
-
variants: { default: "BigCorp" },
52
-
disabled: false
53
-
}
54
91
}),
55
92
providers: {
56
-
differentProvider: newInMemoryProvider()
57
-
}
58
-
})
59
-
]
93
+
differentProvider: newInMemoryProvider(),
94
+
},
95
+
}),
96
+
],
60
97
})
61
98
exportclassAppModule {}
62
99
```
63
100
64
-
#### Injecting a feature flag with header value in evaluation context into an endpoint handler method
101
+
With the `OpenFeatureModule` configured, it's possible to inject flag evaluation details into route handlers like in the following code snippet.
65
102
66
103
```ts
67
104
import { Controller, ExecutionContext, Get } from'@nestjs/common';
@@ -70,40 +107,26 @@ import { BooleanFeatureFlag } from '@openfeature/nestjs-sdk';
Whenever a flag evaluation occurs, context can be provided with information like user e-mail, role, targeting key, etc in order to trigger specific evaluation rules or logic. The `OpenFeatureModule` provides a way to configure context for each request using the `contextFactory` option.
154
+
The `contextFactory` is ran in a NestJS interceptor scope to configure the evaluation context and than it is used in every flag evaluation related to this request.
155
+
By default, the interceptor is configured globally, but it can be changed by setting the `useGlobalInterceptor` to `false`. In this case, it is still possible to configure a `contextFactory` that can be injected into route, module or controller bound interceptors.
* NestJS interceptor used in {@link OpenFeatureModule}
9
+
* to configure flag evaluation context.
10
+
*
11
+
* This interceptor is configured globally by default.
12
+
* If `useGlobalInterceptor` is set to `false` in {@link OpenFeatureModule} it needs to be configured for the specific controllers or routes.
13
+
*
14
+
* If just the interceptor class is passed to the `UseInterceptors` like below, the `contextFactory` provided in the {@link OpenFeatureModule} will be injected and used in order to create the context.
15
+
* ```ts
16
+
* //route interceptor
17
+
* @UseInterceptors(EvaluationContextInterceptor)
18
+
* @Get('/user-info')
19
+
* getUserInfo(){}
20
+
* ```
21
+
*
22
+
* A different `contextFactory` can also be provided, but the interceptor instance has to be instantiated like in the following example.
0 commit comments