docs: Nest SDK

packages/nest/README.md

@@ -25,11 +25,45 @@
 [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.
 
+<!-- x-hide-in-docs-end -->
+
 🧪 This SDK is experimental.
 
-#### Here's a basic example of how to use the OpenFeature NestJS API with `InMemoryProvider`.
+## Overview
+
+The OpenFeature NestJS SDK is a package that provides a NestJS wrapper for the [OpenFeature Server SDK]().
+
+It's main capabilities are:
+- Provide a NestJS global module to simplify OpenFeature configuration and usage within NestJS;
+- Supply custom parameter decorators (for controllers), that inject observables with feature flags resolution details;
+- Inject context for flag evaluation seamlessly using NestJS interceptors
+- Provide decorators for OpenFeature Client injection into NestJS services and controllers
+- TODO: map other features
+
+## 🚀 Quick start
+
+### Requirements
+
+- Node.js version 16+
+- NestJS
 
-#### Registering the Nest.js SDK module in the App Module:
+### Install
+
+#### npm
+
+```sh
+npm install --save @openfeature/nestjs-sdk
+```
+
+#### yarn
+
+```sh
+yarn add @openfeature/nestjs-sdk
+```
+
+### Usage
+
+The example bellow shows how to use the `OpenFeatureModule` with OpenFeature's `InMemoryProvider`.
 
 ```ts
 import { Module } from '@nestjs/common';
@@ -46,11 +80,6 @@ import { InMemoryProvider } from '@openfeature/web-sdk';
           variants: { default: true },
           disabled: false
         },
-        companyName: {
-          defaultVariant: 'default',
-          variants: { default: "BigCorp" },
-          disabled: false
-        }
       }),
       providers: {
         differentProvider: new InMemoryProvider()
@@ -61,7 +90,7 @@ import { InMemoryProvider } from '@openfeature/web-sdk';
 export class AppModule {}
 ```
 
-#### Injecting a feature flag with header value in evaluation context into an endpoint handler method
+With the `OpenFeatureModule` configured it is now possible to inject flag evaluation details into route handlers like in the following code snippet.
 
 ```ts
 import { Controller, ExecutionContext, Get } from '@nestjs/common';
@@ -70,27 +99,13 @@ import { BooleanFeatureFlag } from '@openfeature/nestjs-sdk';
 import { EvaluationDetails } from '@openfeature/server-sdk';
 import { Request } from 'express';
 
-function getContext(executionContext: ExecutionContext) {
-  const request = executionContext.switchToHttp().getRequest<Request>();
-  const userId = request.header('x-user-id');
-
-  if (!userId) {
-    return undefined;
-  }
-
-  return {
-    targetingKey: userId,
-  };
-}
-
 @Controller()
 export class OpenFeatureController {
   @Get('/welcome')
   public async welcome(
     @BooleanFeatureFlag({
       flagKey: 'testBooleanFlag',
       defaultValue: false,
-      contextFactory: getContext,
     })
       feature: Observable<EvaluationDetails<boolean>>,
   ) {
@@ -103,7 +118,7 @@ export class OpenFeatureController {
 }
 ```
 
-#### Injecting the default and a named client into a service:
+It is also possible to inject the default and a named OpenFeature client into a service via it's constructor with Nest dependency injection system.
 
 ```ts
 import { Injectable } from '@nestjs/common';
@@ -114,15 +129,19 @@ import { FeatureClient } from '@openfeature/nestjs-sdk';
 export class OpenFeatureTestService {
   constructor(
     @FeatureClient() private defaultClient: Client,
-    @FeatureClient({ name: 'differentServer' }) private namedClient: Client,
-  ) {
-  }
+    @FeatureClient({ name: 'differentProvider' }) private namedClient: Client,
+  ) {}
 
-  public async getMessage() {
-    const companyName = await this.defaultClient.getStringValue('companyName', 'Unknown Company');
-    return `Hey User from ${companyName}`;
+  public async getBoolean() {
+    return await this.defaultClient.getBooleanValue('testBooleanFlag', false);
   }
 }
 ```
 
+## Module aditional information
+
+### Flag evaluation context injection
 
+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.
+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.
+By default the interceptor is cofigured 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.

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

@@ -3,6 +3,28 @@ import { ContextFactory, ContextFactoryToken } from './context-factory';
 import { Observable } from 'rxjs';
 import { OpenFeature } from '@openfeature/server-sdk';
 
+/** NestJS interceptor used in {@link OpenFeatureModule}
+ *  to configure flag evaluation context.
+ *
+ *  This interceptor is configured globally by dafault, but if
+ *  `useGlobalInterceptor` is set to `false` in {@link OpenFeatureModule} it needs to be configured for the specific controllers or routes.
+ *
+ *  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.
+ *  ```ts
+ *  //route interceptor
+ *  @UseInterceptors(EvaluationContextInterceptor)
+ *  @Get('/user-info')
+ *  getUserInfo(){}
+ *  ```
+ *
+ *  A different `contextFactory` can also be provided, but the interceptor instance has to be instantiated like in the following example.
+ *  ```ts
+ *  //route interceptor
+ *  @UseInterceptors(new EvaluationContextInterceptor(<context factory>))
+ *  @Get('/user-info')
+ *  getUserInfo(){}
+ *  ```
+ */
 @Injectable()
 export class EvaluationContextInterceptor implements NestInterceptor {
   constructor(@Inject(ContextFactoryToken) private contextFactory?: ContextFactory) {}

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

@@ -1,6 +1,5 @@
-import { TransactionContextPropagator } from '@openfeature/server-sdk';
+import { TransactionContextPropagator, EvaluationContext } from '@openfeature/server-sdk';
 import { AsyncLocalStorage } from 'async_hooks';
-import { EvaluationContext } from '@openfeature/server-sdk';
 
 export class AsyncLocalStorageTransactionContext implements TransactionContextPropagator {
   private asyncLocalStorage = new AsyncLocalStorage<EvaluationContext>();

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

@@ -13,6 +13,9 @@ import { APP_INTERCEPTOR } from '@nestjs/core';
 import { AsyncLocalStorageTransactionContext } from './evaluation-context-propagator';
 import { EvaluationContextInterceptor } from './evaluation-context-interceptor';
 
+/**
+ * NestJS OpenFeatureModule is a wrapper for OpenFeature Server-SDK compatible with NestJS.
+ */
 @Module({})
 export class OpenFeatureModule {
   static forRoot({ useGlobalInterceptor = true, ...options }: OpenFeatureModuleOptions): DynamicModule {