@openfeature/server-sdk 1.11.0 → 1.13.0

package/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.7.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.11.0">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.11.0&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/server-sdk-v1.13.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.13.0&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -86,16 +86,17 @@ See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_server_sdk
 
 ## 🌟 Features
 
-| 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](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.                                                                                           |
-| ✅      | [Named clients](#named-clients) | Utilize multiple providers in a single application.                                                                                |
-| ✅      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
-| ✅      | [Shutdown](#shutdown)           | Gracefully clean up a provider during application shutdown.                                                                        |
-| ✅      | [Extending](#extending)         | Extend OpenFeature with custom providers and hooks.                                                                                |
+| 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](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.                                                                                            |
+| ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                  |
+| ✅      | [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) |                                                                                                                               |
+| ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
 
@@ -113,7 +114,7 @@ To register a provider and ensure it is ready before further actions are taken,
 
 ```ts
 await OpenFeature.setProviderAndWait(new MyProvider());
-```  
+```
 
 #### Synchronous
 
@@ -126,7 +127,7 @@ OpenFeature.setProvider(new MyProvider());
 Once the provider has been registered, the status can be tracked using [events](#eventing).
 
 In some situations, it may be beneficial to register multiple providers in the same application.
-This is possible using [named clients](#named-clients), which is covered in more details below.
+This is possible using [domains](#domains), which is covered in more details below.
 
 ### Targeting
 
@@ -154,7 +155,7 @@ const boolValue = await client.getBooleanValue('some-flag', false, requestContex
 
 ### Hooks
 
-[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle
+[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
 Look [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Bcategory%5D%5B0%5D=Server-side&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=JavaScript) for a complete list of available hooks.
 If the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.
 
@@ -176,7 +177,7 @@ const boolValue = await client.getBooleanValue("bool-flag", false, { hooks: [new
 
 ### Logging
 
-The JS SDK will log warning and errors to the console by default.
+The Node.JS SDK will log warnings and errors to the console by default.
 This behavior can be overridden by passing a custom logger either globally or per client.
 A custom logger must implement the [Logger interface](../shared/src/logger/logger.ts).
 
@@ -186,7 +187,7 @@ import type { Logger } from "@openfeature/server-sdk";
 // The logger can be anything that conforms with the Logger interface
 const logger: Logger = console;
 
-// Sets a global logger 
+// Sets a global logger
 OpenFeature.setLogger(logger);
 
 // Sets a client logger
@@ -194,11 +195,11 @@ const client = OpenFeature.getClient();
 client.setLogger(logger);
 ```
 
-### Named clients
+### Domains
 
-Clients can be given a name.
-A name is a logical identifier which can be used to associate clients with a particular provider.
-If a name has no associated provider, the global provider is used.
+Clients can be assigned to a domain.
+A domain is a logical identifier which can be used to associate clients with a particular provider.
+If a domain has no associated provider, the default provider is used.
 
 ```ts
 import { OpenFeature, InMemoryProvider } from "@openfeature/server-sdk";
@@ -216,16 +217,16 @@ const myFlags = {
 
 // Registering the default provider
 OpenFeature.setProvider(InMemoryProvider(myFlags));
-// Registering a named provider
-OpenFeature.setProvider("otherClient", new InMemoryProvider(someOtherFlags));
+// Registering a provider to a domain
+OpenFeature.setProvider("my-domain", new InMemoryProvider(someOtherFlags));
 
-// A Client backed by default provider
+// A Client bound to the default provider
 const clientWithDefault = OpenFeature.getClient();
-// A Client backed by NewCachedProvider
-const clientForCache = OpenFeature.getClient("otherClient");
+// A Client bound to the InMemoryProvider provider
+const domainScopedClient = OpenFeature.getClient("my-domain");
 ```
 
-Named providers can be set in an awaitable or synchronous way.
+Domains can be defined on a provider during registration.
 For more details, please refer to the [providers](#providers) section.
 
 ### Eventing
@@ -251,6 +252,32 @@ client.addHandler(ProviderEvents.Error, (eventDetails) => {
 });
 ```
 
+### Transaction Context Propagation
+
+Transaction context is a container for transaction-specific evaluation context (e.g. user id, user agent, IP).
+Transaction context can be set where specific data is available (e.g. an auth service or request handler) and by using the transaction context propagator it will automatically be applied to all flag evaluations within a transaction (e.g. a request or thread).
+
+The following example shows an Express middleware using transaction context propagation to propagate the request ip and user id into request scoped transaction context.
+
+```ts
+import express, { Request, Response, NextFunction } from "express";
+import { OpenFeature, AsyncLocalStorageTransactionContextPropagator } from '@openfeature/server-sdk';
+
+OpenFeature.setTransactionContextPropagator(new AsyncLocalStorageTransactionContextPropagator())
+
+/**
+ * This example is based on an express middleware.
+ */
+const app = express();
+app.use((req: Request, res: Response, next: NextFunction) => {
+  const ip = res.headers.get("X-Forwarded-For")
+  OpenFeature.setTransactionContext({ targetingKey: req.user.id, ipAddress: ip }, () => {
+    // The transaction context is used in any flag evaluation throughout the whole call chain of next
+    next();
+  });
+})
+```
+
 ### Shutdown
 
 The OpenFeature API provides a close function to perform a cleanup of all registered providers.
@@ -279,7 +306,6 @@ import {
   Logger,
   Provider,
   ProviderEventEmitter,
-  ProviderStatus,
   ResolutionDetails
 } from '@openfeature/server-sdk';
 
@@ -305,10 +331,8 @@ class MyProvider implements Provider {
     // code to evaluate an object
   }
 
-  status?: ProviderStatus | undefined;
-
   // implement with "new OpenFeatureEventEmitter()", and use "emit()" to emit events
-  events?: ProviderEventEmitter<AnyProviderEvent> | undefined; 
+  events?: ProviderEventEmitter<AnyProviderEvent> | undefined;
 
   initialize?(context?: EvaluationContext | undefined): Promise<void> {
     // code to initialize your provider

package/dist/cjs/index.js

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -18,19 +16,12 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AsyncLocalStorageTransactionContextPropagator: () => AsyncLocalStorageTransactionContextPropagator,
   InMemoryProvider: () => InMemoryProvider,
   NOOP_PROVIDER: () => NOOP_PROVIDER,
   NOOP_TRANSACTION_CONTEXT_PROPAGATOR: () => NOOP_TRANSACTION_CONTEXT_PROPAGATOR,
@@ -38,23 +29,42 @@ __export(src_exports, {
   OpenFeatureAPI: () => OpenFeatureAPI,
   OpenFeatureClient: () => OpenFeatureClient,
   OpenFeatureEventEmitter: () => OpenFeatureEventEmitter,
-  ProviderEvents: () => import_core5.ServerProviderEvents
+  ProviderEvents: () => import_core2.ServerProviderEvents,
+  ProviderStatus: () => import_core3.ServerProviderStatus
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/client/open-feature-client.ts
 var import_core7 = require("@openfeature/core");
 
-// src/provider/no-op-provider.ts
+// src/open-feature.ts
+var import_core6 = require("@openfeature/core");
+
+// src/events/open-feature-event-emitter.ts
 var import_core = require("@openfeature/core");
+var import_node_events = require("events");
+var OpenFeatureEventEmitter = class extends import_core.GenericEventEmitter {
+  eventEmitter = new import_node_events.EventEmitter({ captureRejections: true });
+  constructor() {
+    super();
+    this.eventEmitter.on("error", (err) => {
+      this._logger?.error("Error running event handler:", err);
+    });
+  }
+};
+
+// src/events/events.ts
+var import_core2 = require("@openfeature/core");
+
+// src/provider/provider.ts
+var import_core3 = require("@openfeature/core");
+
+// src/provider/no-op-provider.ts
 var REASON_NO_OP = "No-op";
 var NoopFeatureProvider = class {
   metadata = {
     name: "No-op Provider"
   };
-  get status() {
-    return import_core.ProviderStatus.NOT_READY;
-  }
   resolveBooleanEvaluation(_, defaultValue) {
     return this.noOp(defaultValue);
   }
@@ -77,17 +87,17 @@ var NoopFeatureProvider = class {
 var NOOP_PROVIDER = new NoopFeatureProvider();
 
 // src/provider/in-memory-provider/in-memory-provider.ts
-var import_core3 = require("@openfeature/core");
+var import_core5 = require("@openfeature/core");
 
 // src/provider/in-memory-provider/variant-not-found-error.ts
-var import_core2 = require("@openfeature/core");
-var VariantFoundError = class extends import_core2.OpenFeatureError {
+var import_core4 = require("@openfeature/core");
+var VariantFoundError = class _VariantFoundError extends import_core4.OpenFeatureError {
   code;
   constructor(message) {
     super(message);
-    Object.setPrototypeOf(this, VariantFoundError.prototype);
+    Object.setPrototypeOf(this, _VariantFoundError.prototype);
     this.name = "VariantFoundError";
-    this.code = import_core2.ErrorCode.GENERAL;
+    this.code = import_core4.ErrorCode.GENERAL;
   }
 };
 
@@ -109,7 +119,7 @@ var InMemoryProvider = class {
   putConfiguration(flagConfiguration) {
     const flagsChanged = Object.entries(flagConfiguration).filter(([key, value]) => this._flagConfiguration[key] !== value).map(([key]) => key);
     this._flagConfiguration = { ...flagConfiguration };
-    this.events.emit(import_core5.ServerProviderEvents.ConfigurationChanged, { flagsChanged });
+    this.events.emit(import_core2.ServerProviderEvents.ConfigurationChanged, { flagsChanged });
   }
   resolveBooleanEvaluation(flagKey, defaultValue, context, logger) {
     return this.resolveFlagWithReason(flagKey, defaultValue, context, logger);
@@ -127,12 +137,12 @@ var InMemoryProvider = class {
     try {
       const resolutionResult = this.lookupFlagValue(flagKey, defaultValue, ctx, logger);
       if (typeof resolutionResult?.value != typeof defaultValue) {
-        throw new import_core3.TypeMismatchError();
+        throw new import_core5.TypeMismatchError();
       }
       return resolutionResult;
     } catch (error) {
-      if (!(error instanceof import_core3.OpenFeatureError)) {
-        throw new import_core3.GeneralError(error?.message || "unknown error");
+      if (!(error instanceof import_core5.OpenFeatureError)) {
+        throw new import_core5.GeneralError(error?.message || "unknown error");
       }
       throw error;
     }
@@ -141,11 +151,11 @@ var InMemoryProvider = class {
     if (!(flagKey in this._flagConfiguration)) {
       const message = `no flag found with key ${flagKey}`;
       logger?.debug(message);
-      throw new import_core3.FlagNotFoundError(message);
+      throw new import_core5.FlagNotFoundError(message);
     }
     const flagSpec = this._flagConfiguration[flagKey];
     if (flagSpec.disabled) {
-      return { value: defaultValue, reason: import_core3.StandardResolutionReasons.DISABLED };
+      return { value: defaultValue, reason: import_core5.StandardResolutionReasons.DISABLED };
     }
     const isContextEval = ctx && flagSpec?.contextEvaluator;
     const variant = isContextEval ? flagSpec.contextEvaluator?.(ctx) : flagSpec.defaultVariant;
@@ -158,47 +168,42 @@ var InMemoryProvider = class {
     return {
       value,
       ...variant && { variant },
-      reason: isContextEval ? import_core3.StandardResolutionReasons.TARGETING_MATCH : import_core3.StandardResolutionReasons.STATIC
+      reason: isContextEval ? import_core5.StandardResolutionReasons.TARGETING_MATCH : import_core5.StandardResolutionReasons.STATIC
     };
   }
 };
 
-// src/open-feature.ts
-var import_core6 = require("@openfeature/core");
-
 // src/transaction-context/no-op-transaction-context-propagator.ts
 var NoopTransactionContextPropagator = class {
   getTransactionContext() {
     return {};
   }
-  setTransactionContext(_, callback) {
-    callback();
+  setTransactionContext(_, callback, ...args) {
+    callback(...args);
   }
 };
 var NOOP_TRANSACTION_CONTEXT_PROPAGATOR = new NoopTransactionContextPropagator();
 
-// src/events/open-feature-event-emitter.ts
-var import_core4 = require("@openfeature/core");
-var import_events = __toESM(require("events"));
-var OpenFeatureEventEmitter = class extends import_core4.GenericEventEmitter {
-  eventEmitter = new import_events.default({ captureRejections: true });
-  constructor() {
-    super();
-    this.eventEmitter.on("error", (err) => {
-      this._logger?.error("Error running event handler:", err);
-    });
+// src/transaction-context/async-local-storage-transaction-context-propagator.ts
+var import_async_hooks = require("async_hooks");
+var AsyncLocalStorageTransactionContextPropagator = class {
+  asyncLocalStorage = new import_async_hooks.AsyncLocalStorage();
+  getTransactionContext() {
+    return this.asyncLocalStorage.getStore() ?? {};
+  }
+  setTransactionContext(transactionContext, callback, ...args) {
+    this.asyncLocalStorage.run(transactionContext, callback, ...args);
   }
 };
 
-// src/events/events.ts
-var import_core5 = require("@openfeature/core");
-
 // src/open-feature.ts
 var GLOBAL_OPENFEATURE_API_KEY = Symbol.for("@openfeature/js-sdk/api");
 var _globalThis = globalThis;
-var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
-  _events = new OpenFeatureEventEmitter();
-  _defaultProvider = NOOP_PROVIDER;
+var OpenFeatureAPI = class _OpenFeatureAPI extends import_core6.OpenFeatureCommonAPI {
+  _statusEnumType = import_core3.ServerProviderStatus;
+  _apiEmitter = new OpenFeatureEventEmitter();
+  _defaultProvider = new import_core6.ProviderWrapper(NOOP_PROVIDER, import_core3.ServerProviderStatus.NOT_READY, this._statusEnumType);
+  _domainScopedProviders = /* @__PURE__ */ new Map();
   _createEventEmitter = () => new OpenFeatureEventEmitter();
   _transactionContextPropagator = NOOP_TRANSACTION_CONTEXT_PROPAGATOR;
   constructor() {
@@ -214,10 +219,16 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
     if (globalApi) {
       return globalApi;
     }
-    const instance = new OpenFeatureAPI();
+    const instance = new _OpenFeatureAPI();
     _globalThis[GLOBAL_OPENFEATURE_API_KEY] = instance;
     return instance;
   }
+  getProviderStatus(domain) {
+    if (!domain) {
+      return this._defaultProvider.status;
+    }
+    return this._domainScopedProviders.get(domain)?.status ?? this._defaultProvider.status;
+  }
   setContext(context) {
     this._context = context;
     return this;
@@ -225,15 +236,16 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
   getContext() {
     return this._context;
   }
-  getClient(nameOrContext, versionOrContext, contextOrUndefined) {
-    const name = (0, import_core6.stringOrUndefined)(nameOrContext);
+  getClient(domainOrContext, versionOrContext, contextOrUndefined) {
+    const domain = (0, import_core6.stringOrUndefined)(domainOrContext);
     const version = (0, import_core6.stringOrUndefined)(versionOrContext);
-    const context = (0, import_core6.objectOrUndefined)(nameOrContext) ?? (0, import_core6.objectOrUndefined)(versionOrContext) ?? (0, import_core6.objectOrUndefined)(contextOrUndefined);
+    const context = (0, import_core6.objectOrUndefined)(domainOrContext) ?? (0, import_core6.objectOrUndefined)(versionOrContext) ?? (0, import_core6.objectOrUndefined)(contextOrUndefined);
     return new OpenFeatureClient(
-      () => this.getProviderForClient(name),
-      () => this.buildAndCacheEventEmitterForClient(name),
+      () => this.getProviderForClient(domain),
+      () => this.getProviderStatus(domain),
+      () => this.buildAndCacheEventEmitterForClient(domain),
       () => this._logger,
-      { name, version },
+      { domain, version },
       context
     );
   }
@@ -273,8 +285,9 @@ var OpenFeature = OpenFeatureAPI.getInstance();
 
 // src/client/open-feature-client.ts
 var OpenFeatureClient = class {
-  constructor(providerAccessor, emitterAccessor, globalLogger, options, context = {}) {
+  constructor(providerAccessor, providerStatusAccessor, emitterAccessor, globalLogger, options, context = {}) {
     this.providerAccessor = providerAccessor;
+    this.providerStatusAccessor = providerStatusAccessor;
     this.emitterAccessor = emitterAccessor;
     this.globalLogger = globalLogger;
     this.options = options;
@@ -285,17 +298,26 @@ var OpenFeatureClient = class {
   _clientLogger;
   get metadata() {
     return {
-      name: this.options.name,
+      // Use domain if name is not provided
+      name: this.options.domain ?? this.options.name,
+      domain: this.options.domain ?? this.options.name,
       version: this.options.version,
       providerMetadata: this.providerAccessor().metadata
     };
   }
+  get providerStatus() {
+    return this.providerStatusAccessor();
+  }
   addHandler(eventType, handler) {
     this.emitterAccessor().addHandler(eventType, handler);
-    const shouldRunNow = (0, import_core7.statusMatchesEvent)(eventType, this._provider.status);
+    const shouldRunNow = (0, import_core7.statusMatchesEvent)(eventType, this._providerStatus);
     if (shouldRunNow) {
       try {
-        handler({ clientName: this.metadata.name, providerName: this._provider.metadata.name });
+        handler({
+          clientName: this.metadata.name,
+          domain: this.metadata.domain,
+          providerName: this._provider.metadata.name
+        });
       } catch (err) {
         this._logger?.error("Error running event handler:", err);
       }
@@ -401,6 +423,11 @@ var OpenFeatureClient = class {
     };
     try {
       const frozenContext = await this.beforeHooks(allHooks, hookContext, options);
+      if (this.providerStatus === import_core3.ServerProviderStatus.NOT_READY) {
+        throw new import_core7.ProviderNotReadyError("provider has not yet initialized");
+      } else if (this.providerStatus === import_core3.ServerProviderStatus.FATAL) {
+        throw new import_core7.ProviderFatalError("provider is in an irrecoverable error state");
+      }
       const resolution = await resolver.call(this._provider, flagKey, defaultValue, frozenContext, this._logger);
       const evaluationDetails = {
         ...resolution,
@@ -469,6 +496,9 @@ var OpenFeatureClient = class {
   get _provider() {
     return this.providerAccessor();
   }
+  get _providerStatus() {
+    return this.providerStatusAccessor();
+  }
   get _logger() {
     return this._clientLogger || this.globalLogger();
   }
@@ -478,6 +508,7 @@ var OpenFeatureClient = class {
 __reExport(src_exports, require("@openfeature/core"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AsyncLocalStorageTransactionContextPropagator,
   InMemoryProvider,
   NOOP_PROVIDER,
   NOOP_TRANSACTION_CONTEXT_PROPAGATOR,
@@ -485,6 +516,8 @@ __reExport(src_exports, require("@openfeature/core"), module.exports);
   OpenFeatureAPI,
   OpenFeatureClient,
   OpenFeatureEventEmitter,
-  ProviderEvents
+  ProviderEvents,
+  ProviderStatus,
+  ...require("@openfeature/core")
 });
 //# sourceMappingURL=index.js.map