@openfeature/server-sdk 1.13.5 → 1.14.0

package/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.13.5">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.13.5&color=blue&style=for-the-badge" />
+  <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>
   <!-- x-release-please-end -->
   <br/>
@@ -44,7 +44,7 @@
 
 ### Requirements
 
-- Node.js version 16+
+- Node.js version 18+
 
 ### Install
 
@@ -54,6 +54,9 @@
 npm install --save @openfeature/server-sdk
 ```
 
+> [!TIP]
+> This SDK is designed to run in Node.JS. If you're interested in browser support, check out the [Web SDK](https://openfeature.dev/docs/reference/technologies/client/web/).
+
 #### yarn
 
 ```sh
@@ -158,6 +161,9 @@ const requestContext = {
 const boolValue = await client.getBooleanValue('some-flag', false, requestContext);
 ```
 
+Context is merged by the SDK before a flag evaluation occurs.
+The merge order is defined [here](https://openfeature.dev/specification/sections/evaluation-context#requirement-323) in the OpenFeature specification.
+
 ### 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.

package/dist/cjs/index.js

@@ -27,37 +27,14 @@ __export(src_exports, {
   NOOP_TRANSACTION_CONTEXT_PROPAGATOR: () => NOOP_TRANSACTION_CONTEXT_PROPAGATOR,
   OpenFeature: () => OpenFeature,
   OpenFeatureAPI: () => OpenFeatureAPI,
-  OpenFeatureClient: () => OpenFeatureClient,
   OpenFeatureEventEmitter: () => OpenFeatureEventEmitter,
-  ProviderEvents: () => import_core2.ServerProviderEvents,
-  ProviderStatus: () => import_core3.ServerProviderStatus
+  ProviderEvents: () => import_core6.ServerProviderEvents,
+  ProviderStatus: () => import_core.ServerProviderStatus
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/client/open-feature-client.ts
-var import_core7 = require("@openfeature/core");
-
-// 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");
+var import_core = require("@openfeature/core");
 
 // src/provider/no-op-provider.ts
 var REASON_NO_OP = "No-op";
@@ -87,17 +64,17 @@ var NoopFeatureProvider = class {
 var NOOP_PROVIDER = new NoopFeatureProvider();
 
 // src/provider/in-memory-provider/in-memory-provider.ts
-var import_core5 = require("@openfeature/core");
+var import_core3 = require("@openfeature/core");
 
 // src/provider/in-memory-provider/variant-not-found-error.ts
-var import_core4 = require("@openfeature/core");
-var VariantFoundError = class _VariantFoundError extends import_core4.OpenFeatureError {
+var import_core2 = require("@openfeature/core");
+var VariantFoundError = class _VariantFoundError extends import_core2.OpenFeatureError {
   code;
   constructor(message) {
     super(message);
     Object.setPrototypeOf(this, _VariantFoundError.prototype);
     this.name = "VariantFoundError";
-    this.code = import_core4.ErrorCode.GENERAL;
+    this.code = import_core2.ErrorCode.GENERAL;
   }
 };
 
@@ -119,7 +96,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_core2.ServerProviderEvents.ConfigurationChanged, { flagsChanged });
+    this.events.emit(import_core6.ServerProviderEvents.ConfigurationChanged, { flagsChanged });
   }
   resolveBooleanEvaluation(flagKey, defaultValue, context, logger) {
     return this.resolveFlagWithReason(flagKey, defaultValue, context, logger);
@@ -137,12 +114,12 @@ var InMemoryProvider = class {
     try {
       const resolutionResult = this.lookupFlagValue(flagKey, defaultValue, ctx, logger);
       if (typeof resolutionResult?.value != typeof defaultValue) {
-        throw new import_core5.TypeMismatchError();
+        throw new import_core3.TypeMismatchError();
       }
       return resolutionResult;
     } catch (error) {
-      if (!(error instanceof import_core5.OpenFeatureError)) {
-        throw new import_core5.GeneralError(error?.message || "unknown error");
+      if (!(error instanceof import_core3.OpenFeatureError)) {
+        throw new import_core3.GeneralError(error?.message || "unknown error");
       }
       throw error;
     }
@@ -151,11 +128,11 @@ var InMemoryProvider = class {
     if (!(flagKey in this._flagConfiguration)) {
       const message = `no flag found with key ${flagKey}`;
       logger?.debug(message);
-      throw new import_core5.FlagNotFoundError(message);
+      throw new import_core3.FlagNotFoundError(message);
     }
     const flagSpec = this._flagConfiguration[flagKey];
     if (flagSpec.disabled) {
-      return { value: defaultValue, reason: import_core5.StandardResolutionReasons.DISABLED };
+      return { value: defaultValue, reason: import_core3.StandardResolutionReasons.DISABLED };
     }
     const isContextEval = ctx && flagSpec?.contextEvaluator;
     const variant = isContextEval ? flagSpec.contextEvaluator?.(ctx) : flagSpec.defaultVariant;
@@ -168,122 +145,16 @@ var InMemoryProvider = class {
     return {
       value,
       ...variant && { variant },
-      reason: isContextEval ? import_core5.StandardResolutionReasons.TARGETING_MATCH : import_core5.StandardResolutionReasons.STATIC
+      reason: isContextEval ? import_core3.StandardResolutionReasons.TARGETING_MATCH : import_core3.StandardResolutionReasons.STATIC
     };
   }
 };
 
-// src/transaction-context/no-op-transaction-context-propagator.ts
-var NoopTransactionContextPropagator = class {
-  getTransactionContext() {
-    return {};
-  }
-  setTransactionContext(_, callback, ...args) {
-    callback(...args);
-  }
-};
-var NOOP_TRANSACTION_CONTEXT_PROPAGATOR = new NoopTransactionContextPropagator();
-
-// 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/open-feature.ts
-var GLOBAL_OPENFEATURE_API_KEY = Symbol.for("@openfeature/js-sdk/api");
-var _globalThis = globalThis;
-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() {
-    super("server");
-  }
-  /**
-   * Gets a singleton instance of the OpenFeature API.
-   * @ignore
-   * @returns {OpenFeatureAPI} OpenFeature API
-   */
-  static getInstance() {
-    const globalApi = _globalThis[GLOBAL_OPENFEATURE_API_KEY];
-    if (globalApi) {
-      return globalApi;
-    }
-    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;
-  }
-  getContext() {
-    return this._context;
-  }
-  getClient(domainOrContext, versionOrContext, contextOrUndefined) {
-    const domain = (0, import_core6.stringOrUndefined)(domainOrContext);
-    const version = (0, import_core6.stringOrUndefined)(versionOrContext);
-    const context = (0, import_core6.objectOrUndefined)(domainOrContext) ?? (0, import_core6.objectOrUndefined)(versionOrContext) ?? (0, import_core6.objectOrUndefined)(contextOrUndefined);
-    return new OpenFeatureClient(
-      () => this.getProviderForClient(domain),
-      () => this.getProviderStatus(domain),
-      () => this.buildAndCacheEventEmitterForClient(domain),
-      () => this._logger,
-      { domain, version },
-      context
-    );
-  }
-  /**
-   * Clears all registered providers and resets the default provider.
-   * @returns {Promise<void>}
-   */
-  clearProviders() {
-    return super.clearProvidersAndSetDefault(NOOP_PROVIDER);
-  }
-  setTransactionContextPropagator(transactionContextPropagator) {
-    const baseMessage = "Invalid TransactionContextPropagator, will not be set: ";
-    if (typeof transactionContextPropagator?.getTransactionContext !== "function") {
-      this._logger.error(`${baseMessage}: getTransactionContext is not a function.`);
-    } else if (typeof transactionContextPropagator?.setTransactionContext !== "function") {
-      this._logger.error(`${baseMessage}: setTransactionContext is not a function.`);
-    } else {
-      this._transactionContextPropagator = transactionContextPropagator;
-    }
-    return this;
-  }
-  setTransactionContext(transactionContext, callback, ...args) {
-    this._transactionContextPropagator.setTransactionContext(transactionContext, callback, ...args);
-  }
-  getTransactionContext() {
-    try {
-      return this._transactionContextPropagator.getTransactionContext();
-    } catch (err) {
-      const error = err;
-      this._logger.error(`Error getting transaction context: ${error?.message}, returning empty context.`);
-      this._logger.error(error?.stack);
-      return {};
-    }
-  }
-};
-var OpenFeature = OpenFeatureAPI.getInstance();
+var import_core7 = require("@openfeature/core");
 
-// src/client/open-feature-client.ts
+// src/client/internal/open-feature-client.ts
+var import_core4 = require("@openfeature/core");
 var OpenFeatureClient = class {
   constructor(providerAccessor, providerStatusAccessor, emitterAccessor, globalLogger, options, context = {}) {
     this.providerAccessor = providerAccessor;
@@ -310,7 +181,7 @@ var OpenFeatureClient = class {
   }
   addHandler(eventType, handler) {
     this.emitterAccessor().addHandler(eventType, handler);
-    const shouldRunNow = (0, import_core7.statusMatchesEvent)(eventType, this._providerStatus);
+    const shouldRunNow = (0, import_core4.statusMatchesEvent)(eventType, this._providerStatus);
     if (shouldRunNow) {
       try {
         handler({
@@ -330,7 +201,7 @@ var OpenFeatureClient = class {
     return this.emitterAccessor().getHandlers(eventType);
   }
   setLogger(logger) {
-    this._clientLogger = new import_core7.SafeLogger(logger);
+    this._clientLogger = new import_core4.SafeLogger(logger);
     return this;
   }
   setContext(context) {
@@ -423,10 +294,10 @@ 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");
+      if (this.providerStatus === import_core.ServerProviderStatus.NOT_READY) {
+        throw new import_core4.ProviderNotReadyError("provider has not yet initialized");
+      } else if (this.providerStatus === import_core.ServerProviderStatus.FATAL) {
+        throw new import_core4.ProviderFatalError("provider is in an irrecoverable error state");
       }
       const resolution = await resolver.call(this._provider, flagKey, defaultValue, frozenContext, this._logger);
       const evaluationDetails = {
@@ -434,17 +305,20 @@ var OpenFeatureClient = class {
         flagMetadata: Object.freeze(resolution.flagMetadata ?? {}),
         flagKey
       };
+      if (evaluationDetails.errorCode) {
+        throw (0, import_core4.instantiateErrorByErrorCode)(evaluationDetails.errorCode);
+      }
       await this.afterHooks(allHooksReversed, hookContext, evaluationDetails, options);
       return evaluationDetails;
     } catch (err) {
       const errorMessage = err?.message;
-      const errorCode = err?.code || import_core7.ErrorCode.GENERAL;
+      const errorCode = err?.code || import_core4.ErrorCode.GENERAL;
       await this.errorHooks(allHooksReversed, hookContext, err, options);
       return {
         errorCode,
         errorMessage,
         value: defaultValue,
-        reason: import_core7.StandardResolutionReasons.ERROR,
+        reason: import_core4.StandardResolutionReasons.ERROR,
         flagMetadata: Object.freeze({}),
         flagKey
       };
@@ -504,6 +378,150 @@ var OpenFeatureClient = class {
   }
 };
 
+// src/events/open-feature-event-emitter.ts
+var import_core5 = require("@openfeature/core");
+var import_node_events = require("events");
+var OpenFeatureEventEmitter = class extends import_core5.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_core6 = require("@openfeature/core");
+
+// src/transaction-context/no-op-transaction-context-propagator.ts
+var NoopTransactionContextPropagator = class {
+  getTransactionContext() {
+    return {};
+  }
+  setTransactionContext(_, callback, ...args) {
+    callback(...args);
+  }
+};
+var NOOP_TRANSACTION_CONTEXT_PROPAGATOR = new NoopTransactionContextPropagator();
+
+// 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/open-feature.ts
+var GLOBAL_OPENFEATURE_API_KEY = Symbol.for("@openfeature/js-sdk/api");
+var _globalThis = globalThis;
+var OpenFeatureAPI = class _OpenFeatureAPI extends import_core7.OpenFeatureCommonAPI {
+  _statusEnumType = import_core.ServerProviderStatus;
+  _apiEmitter = new OpenFeatureEventEmitter();
+  _defaultProvider = new import_core7.ProviderWrapper(
+    NOOP_PROVIDER,
+    import_core.ServerProviderStatus.NOT_READY,
+    this._statusEnumType
+  );
+  _domainScopedProviders = /* @__PURE__ */ new Map();
+  _createEventEmitter = () => new OpenFeatureEventEmitter();
+  _transactionContextPropagator = NOOP_TRANSACTION_CONTEXT_PROPAGATOR;
+  constructor() {
+    super("server");
+  }
+  /**
+   * Gets a singleton instance of the OpenFeature API.
+   * @ignore
+   * @returns {OpenFeatureAPI} OpenFeature API
+   */
+  static getInstance() {
+    const globalApi = _globalThis[GLOBAL_OPENFEATURE_API_KEY];
+    if (globalApi) {
+      return globalApi;
+    }
+    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;
+  }
+  async setProviderAndWait(domainOrProvider, providerOrUndefined) {
+    const domain = (0, import_core7.stringOrUndefined)(domainOrProvider);
+    const provider = domain ? (0, import_core7.objectOrUndefined)(providerOrUndefined) : (0, import_core7.objectOrUndefined)(domainOrProvider);
+    await this.setAwaitableProvider(domain, provider);
+  }
+  setProvider(clientOrProvider, providerOrUndefined) {
+    const domain = (0, import_core7.stringOrUndefined)(clientOrProvider);
+    const provider = domain ? (0, import_core7.objectOrUndefined)(providerOrUndefined) : (0, import_core7.objectOrUndefined)(clientOrProvider);
+    const maybePromise = this.setAwaitableProvider(domain, provider);
+    Promise.resolve(maybePromise).catch((err) => {
+      this._logger.error("Error during provider initialization:", err);
+    });
+    return this;
+  }
+  setContext(context) {
+    this._context = context;
+    return this;
+  }
+  getContext() {
+    return this._context;
+  }
+  getClient(domainOrContext, versionOrContext, contextOrUndefined) {
+    const domain = (0, import_core7.stringOrUndefined)(domainOrContext);
+    const version = (0, import_core7.stringOrUndefined)(versionOrContext);
+    const context = (0, import_core7.objectOrUndefined)(domainOrContext) ?? (0, import_core7.objectOrUndefined)(versionOrContext) ?? (0, import_core7.objectOrUndefined)(contextOrUndefined);
+    return new OpenFeatureClient(
+      () => this.getProviderForClient(domain),
+      () => this.getProviderStatus(domain),
+      () => this.buildAndCacheEventEmitterForClient(domain),
+      () => this._logger,
+      { domain, version },
+      context
+    );
+  }
+  /**
+   * Clears all registered providers and resets the default provider.
+   * @returns {Promise<void>}
+   */
+  clearProviders() {
+    return super.clearProvidersAndSetDefault(NOOP_PROVIDER);
+  }
+  setTransactionContextPropagator(transactionContextPropagator) {
+    const baseMessage = "Invalid TransactionContextPropagator, will not be set: ";
+    if (typeof transactionContextPropagator?.getTransactionContext !== "function") {
+      this._logger.error(`${baseMessage}: getTransactionContext is not a function.`);
+    } else if (typeof transactionContextPropagator?.setTransactionContext !== "function") {
+      this._logger.error(`${baseMessage}: setTransactionContext is not a function.`);
+    } else {
+      this._transactionContextPropagator = transactionContextPropagator;
+    }
+    return this;
+  }
+  setTransactionContext(transactionContext, callback, ...args) {
+    this._transactionContextPropagator.setTransactionContext(transactionContext, callback, ...args);
+  }
+  getTransactionContext() {
+    try {
+      return this._transactionContextPropagator.getTransactionContext();
+    } catch (err) {
+      const error = err;
+      this._logger.error(`Error getting transaction context: ${error?.message}, returning empty context.`);
+      this._logger.error(error?.stack);
+      return {};
+    }
+  }
+};
+var OpenFeature = OpenFeatureAPI.getInstance();
+
 // src/index.ts
 __reExport(src_exports, require("@openfeature/core"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
@@ -514,7 +532,6 @@ __reExport(src_exports, require("@openfeature/core"), module.exports);
   NOOP_TRANSACTION_CONTEXT_PROPAGATOR,
   OpenFeature,
   OpenFeatureAPI,
-  OpenFeatureClient,
   OpenFeatureEventEmitter,
   ProviderEvents,
   ProviderStatus,