@openfeature/server-sdk 1.20.2 → 1.21.0

package/dist/types.d.ts

@@ -1,10 +1,11 @@
-import { BaseHook, FlagValue, EvaluationContext, HookHints, EvaluationDetails, JsonValue, CommonProvider, ServerProviderStatus, Logger, ResolutionDetails, GenericEventEmitter, ServerProviderEvents, ProviderEntryInput, ProviderMetadata, RegisteredProvider, BaseEvaluationStrategy, TrackingEventDetails, BaseStrategyProviderContext, BaseStrategyPerProviderContext, BaseProviderResolutionResult, BaseProviderResolutionSuccessResult, BaseProviderResolutionErrorResult, BaseFinalResult, BaseFirstMatchStrategy, BaseFirstSuccessfulStrategy, BaseComparisonStrategy, EvaluationLifeCycle, ManageContext, ManageLogger, Eventing, ClientMetadata, OpenFeatureCommonAPI, ProviderWrapper } from '@openfeature/core';
+import { BaseHook, FlagValue, EvaluationContext, BooleanFlagKey, HookHints, EvaluationDetails, StringFlagKey, NumberFlagKey, ObjectFlagKey, JsonValue, CommonProvider, ServerProviderStatus, Logger, ResolutionDetails, GenericEventEmitter, ServerProviderEvents, ProviderEntryInput, ProviderMetadata, RegisteredProvider, BaseEvaluationStrategy, TrackingEventDetails, BaseStrategyProviderContext, BaseStrategyPerProviderContext, BaseProviderResolutionResult, BaseProviderResolutionSuccessResult, BaseProviderResolutionErrorResult, BaseFinalResult, BaseFirstMatchStrategy, BaseFirstSuccessfulStrategy, BaseComparisonStrategy, EvaluationLifeCycle, ManageContext, ManageLogger, Eventing, ClientMetadata, OpenFeatureCommonAPI, ProviderWrapper } from '@openfeature/core';
 export * from '@openfeature/core';
 export { ServerProviderEvents as ProviderEvents, ServerProviderStatus as ProviderStatus, StrategyEvaluationContext } from '@openfeature/core';
 import { EventEmitter } from 'node:events';
 
 type Hook<TData = Record<string, unknown>> = BaseHook<FlagValue, TData, Promise<EvaluationContext | void> | EvaluationContext | void, Promise<void> | void>;
 
+type ConstrainedFlagKey<T> = T extends boolean ? BooleanFlagKey : T extends number ? NumberFlagKey : T extends string ? StringFlagKey : T extends JsonValue ? ObjectFlagKey : never;
 interface FlagEvaluationOptions {
     hooks?: Hook[];
     hookHints?: HookHints;
@@ -12,88 +13,88 @@ interface FlagEvaluationOptions {
 interface Features {
     /**
      * Performs a flag evaluation that returns a boolean.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {BooleanFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @param {boolean} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<boolean>} Flag evaluation response
      */
-    getBooleanValue(flagKey: string, defaultValue: boolean, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<boolean>;
+    getBooleanValue(flagKey: BooleanFlagKey, defaultValue: boolean, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<boolean>;
     /**
      * Performs a flag evaluation that a returns an evaluation details object.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {BooleanFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @param {boolean} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<EvaluationDetails<boolean>>} Flag evaluation details response
      */
-    getBooleanDetails(flagKey: string, defaultValue: boolean, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<boolean>>;
+    getBooleanDetails(flagKey: BooleanFlagKey, defaultValue: boolean, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<boolean>>;
     /**
      * Performs a flag evaluation that returns a string.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {StringFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {string} T A optional generic argument constraining the string
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<T>} Flag evaluation response
      */
-    getStringValue(flagKey: string, defaultValue: string, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<string>;
-    getStringValue<T extends string = string>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
+    getStringValue(flagKey: StringFlagKey, defaultValue: string, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<string>;
+    getStringValue<T extends string = string>(flagKey: StringFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
     /**
      * Performs a flag evaluation that a returns an evaluation details object.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {StringFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {string} T A optional generic argument constraining the string
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<EvaluationDetails<T>>} Flag evaluation details response
      */
-    getStringDetails(flagKey: string, defaultValue: string, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<string>>;
-    getStringDetails<T extends string = string>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
+    getStringDetails(flagKey: StringFlagKey, defaultValue: string, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<string>>;
+    getStringDetails<T extends string = string>(flagKey: StringFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
     /**
      * Performs a flag evaluation that returns a number.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {NumberFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {number} T A optional generic argument constraining the number
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<T>} Flag evaluation response
      */
-    getNumberValue(flagKey: string, defaultValue: number, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<number>;
-    getNumberValue<T extends number = number>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
+    getNumberValue(flagKey: NumberFlagKey, defaultValue: number, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<number>;
+    getNumberValue<T extends number = number>(flagKey: NumberFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
     /**
      * Performs a flag evaluation that a returns an evaluation details object.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {NumberFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {number} T A optional generic argument constraining the number
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<EvaluationDetails<T>>} Flag evaluation details response
      */
-    getNumberDetails(flagKey: string, defaultValue: number, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<number>>;
-    getNumberDetails<T extends number = number>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
+    getNumberDetails(flagKey: NumberFlagKey, defaultValue: number, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<number>>;
+    getNumberDetails<T extends number = number>(flagKey: NumberFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
     /**
      * Performs a flag evaluation that returns an object.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {ObjectFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {JsonValue} T A optional generic argument describing the structure
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<T>} Flag evaluation response
      */
-    getObjectValue(flagKey: string, defaultValue: JsonValue, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<JsonValue>;
-    getObjectValue<T extends JsonValue = JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
+    getObjectValue(flagKey: ObjectFlagKey, defaultValue: JsonValue, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<JsonValue>;
+    getObjectValue<T extends JsonValue = JsonValue>(flagKey: ObjectFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<T>;
     /**
      * Performs a flag evaluation that a returns an evaluation details object.
-     * @param {string} flagKey The flag key uniquely identifies a particular flag
+     * @param {ObjectFlagKey} flagKey The flag key uniquely identifies a particular flag
      * @template {JsonValue} T A optional generic argument describing the structure
      * @param {T} defaultValue The value returned if an error occurs
      * @param {EvaluationContext} context The evaluation context used on an individual flag evaluation
      * @param {FlagEvaluationOptions} options Additional flag evaluation options
      * @returns {Promise<EvaluationDetails<T>>} Flag evaluation details response
      */
-    getObjectDetails(flagKey: string, defaultValue: JsonValue, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<JsonValue>>;
-    getObjectDetails<T extends JsonValue = JsonValue>(flagKey: string, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
+    getObjectDetails(flagKey: ObjectFlagKey, defaultValue: JsonValue, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<JsonValue>>;
+    getObjectDetails<T extends JsonValue = JsonValue>(flagKey: ObjectFlagKey, defaultValue: T, context?: EvaluationContext, options?: FlagEvaluationOptions): Promise<EvaluationDetails<T>>;
 }
 
 /**
@@ -149,19 +150,23 @@ declare const NOOP_PROVIDER: NoopFeatureProvider;
  * but just for the in-memory provider.
  */
 
-type Variants<T> = Record<string, T>;
+type NoInfer<T> = [T][T extends unknown ? 0 : never];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type FlagVariants<T extends string> = Record<T, boolean> | Record<T, string> | Record<T, number> | Record<T, JsonValue>;
 /**
  * A Feature Flag definition, containing it's specification
  */
-type Flag = {
+type Flag<T extends string = string> = {
     /**
      * An object containing all possible flags mappings (variant -> flag value)
      */
-    variants: Variants<boolean> | Variants<string> | Variants<number> | Variants<JsonValue>;
+    variants: FlagVariants<T>;
     /**
      * The variant it will resolve to in STATIC evaluation
      */
-    defaultVariant: string;
+    defaultVariant: NoInfer<T>;
     /**
      * Determines if flag evaluation is enabled or not for this flag.
      * If false, falls back to the default value provided to the client
@@ -173,12 +178,22 @@ type Flag = {
      * If it does not return a valid variant it falls back to the default value provided to the client
      * @param EvaluationContext
      */
-    contextEvaluator?: (ctx: EvaluationContext) => string;
+    contextEvaluator?: (ctx: EvaluationContext) => NoInfer<T>;
+};
+/**
+ * The configuration object for the InMemoryProvider, containing all flags and their specifications.
+ *
+ * The generic ensures that the keys of the `variants` object in each flag specification are consistent with the `defaultVariant` and the return type of `contextEvaluator`.
+ */
+type FlagConfiguration<T extends Record<string, FlagVariants<string>> = Record<string, FlagVariants<string>>> = {
+    [K in keyof T]: Simplify<{
+        variants: T[K];
+    } & Omit<Flag<keyof T[K] & string>, 'variants'>>;
 };
-type FlagConfiguration = Record<string, Flag>;
 
 /**
  * A simple OpenFeature provider intended for demos and as a test stub.
+ * @deprecated Use {@link TypedInMemoryProvider} for type-safe flag configuration.
  */
 declare class InMemoryProvider implements Provider {
     readonly events: OpenFeatureEventEmitter;
@@ -200,6 +215,109 @@ declare class InMemoryProvider implements Provider {
     private resolveFlagWithReason;
     private lookupFlagValue;
 }
+/**
+ * A simple OpenFeature provider intended for demos and as a test stub.
+ * @example
+ * ```
+ * const provider = new TypedInMemoryProvider({
+ *   'my-flag': {
+ *     variants: { on: true, off: false },
+ *     defaultVariant: 'on',
+ *     contextEvaluator: (ctx) => ctx?.user?.id === '123' ? 'on' : 'off',
+ *     disabled: false,
+ *   },
+ * });
+ *
+ * const flags = {
+ *   'my-flag': {
+ *     variants: { on: true, off: false },
+ *     defaultVariant: 'on',
+ *     contextEvaluator: (ctx) => ctx?.user?.id === '123' ? 'on' : 'off',
+ *     disabled: false,
+ *   },
+ * } as const; // 'as const' needed to preserve the `defaultVariant` narrow literal type rather than `string`
+ * const provider = new TypedInMemoryProvider(flags);
+ * ```
+ */
+declare class TypedInMemoryProvider<T extends Record<string, FlagVariants<string>> = Record<string, FlagVariants<string>>> extends InMemoryProvider {
+    constructor(flagConfiguration?: FlagConfiguration<T>);
+    /**
+     * Overwrites the configured flags.
+     * @param { FlagConfiguration } flagConfiguration new flag configuration
+     * @example
+     * ```
+     * provider.putConfiguration({
+     *   'my-flag': {
+     *     variants: { on: true, off: false },
+     *     defaultVariant: 'on',
+     *     contextEvaluator: (ctx) => ctx?.user?.id === '123' ? 'on' : 'off',
+     *     disabled: false,
+     *   },
+     * });
+     *
+     * const flags = {
+     *   'my-flag': {
+     *     variants: { on: true, off: false },
+     *     defaultVariant: 'on',
+     *     contextEvaluator: (ctx) => ctx?.user?.id === '123' ? 'on' : 'off',
+     *     disabled: false,
+     *   },
+     * } as const; // 'as const' needed to preserve the `defaultVariant` narrow literal type rather than `string`
+     * provider.putConfiguration(flags);
+     * ```
+     */
+    putConfiguration<U extends Record<string, FlagVariants<string>> = Record<string, FlagVariants<string>>>(flagConfiguration: FlagConfiguration<U>): void;
+}
+/**
+ * The variants object for a flag in the {@link TypedInMemoryProvider}, containing all possible variants and their associated values.
+ *
+ * Can be used in combination with {@link InMemoryFlagConfiguration} to preserve type-safety when extending the provider class.
+ * @example
+ * ```
+ * export class CustomInMemoryProvider<
+ *   T extends Record<string, InMemoryFlagVariants<string>> = Record<string, InMemoryFlagVariants<string>>,
+ * > extends TypedInMemoryProvider<T> {
+ *   constructor(flagConfiguration: InMemoryFlagConfiguration<T>) {
+ *     super(flagConfiguration);
+ *     // custom logic ...
+ *   }
+ *
+ *   override putConfiguration<
+ *     U extends Record<string, InMemoryFlagVariants<string>> = Record<string, InMemoryFlagVariants<string>>,
+ *   >(flagConfiguration: InMemoryFlagConfiguration<U>) {
+ *     super.putConfiguration(flagConfiguration);
+ *     // custom logic ...
+ *   }
+ * }
+ * ```
+ */
+type InMemoryFlagVariants<T extends string> = FlagVariants<T>;
+/**
+ * The configuration object for the {@link TypedInMemoryProvider}, containing all flags and their specifications.
+ *
+ * Can be used in combination with {@link InMemoryFlagVariants} to preserve type-safety when extending the provider class.
+ *
+ * The generic ensures that the keys of the `variants` object in each flag specification are consistent with the `defaultVariant` and the return type of `contextEvaluator`.
+ * @example
+ * ```
+ * export class CustomInMemoryProvider<
+ *   T extends Record<string, InMemoryFlagVariants<string>> = Record<string, InMemoryFlagVariants<string>>,
+ * > extends TypedInMemoryProvider<T> {
+ *   constructor(flagConfiguration: InMemoryFlagConfiguration<T>) {
+ *     super(flagConfiguration);
+ *     // custom logic ...
+ *   }
+ *
+ *   override putConfiguration<
+ *     U extends Record<string, InMemoryFlagVariants<string>> = Record<string, InMemoryFlagVariants<string>>,
+ *   >(flagConfiguration: InMemoryFlagConfiguration<U>) {
+ *     super.putConfiguration(flagConfiguration);
+ *     // custom logic ...
+ *   }
+ * }
+ * ```
+ */
+type InMemoryFlagConfiguration<T extends Record<string, FlagVariants<string>> = Record<string, FlagVariants<string>>> = FlagConfiguration<T>;
 
 /**
  * The OpenFeatureEventEmitter can be used by provider developers to emit
@@ -487,5 +605,5 @@ declare class OpenFeatureAPI extends OpenFeatureCommonAPI<ServerProviderStatus,
  */
 declare const OpenFeature: OpenFeatureAPI;
 
-export { AsyncLocalStorageTransactionContextPropagator, ComparisonStrategy, FirstMatchStrategy, FirstSuccessfulStrategy, InMemoryProvider, MultiProvider, NOOP_PROVIDER, NOOP_TRANSACTION_CONTEXT_PROPAGATOR, OpenFeature, OpenFeatureAPI, OpenFeatureEventEmitter };
-export type { Client, Features, FinalResult, FlagEvaluationOptions, Hook, ManageTransactionContextPropagator, Provider, ProviderResolutionErrorResult, ProviderResolutionResult, ProviderResolutionSuccessResult, StrategyPerProviderContext, StrategyProviderContext, Tracking, TransactionContext, TransactionContextPropagator };
+export { AsyncLocalStorageTransactionContextPropagator, ComparisonStrategy, FirstMatchStrategy, FirstSuccessfulStrategy, InMemoryProvider, MultiProvider, NOOP_PROVIDER, NOOP_TRANSACTION_CONTEXT_PROPAGATOR, OpenFeature, OpenFeatureAPI, OpenFeatureEventEmitter, TypedInMemoryProvider };
+export type { Client, ConstrainedFlagKey, Features, FinalResult, FlagEvaluationOptions, Hook, InMemoryFlagConfiguration, InMemoryFlagVariants, ManageTransactionContextPropagator, Provider, ProviderResolutionErrorResult, ProviderResolutionResult, ProviderResolutionSuccessResult, StrategyPerProviderContext, StrategyProviderContext, Tracking, TransactionContext, TransactionContextPropagator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/server-sdk",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "description": "OpenFeature SDK for JavaScript",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -48,9 +48,10 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@openfeature/core": "^1.9.2"
+    "@openfeature/core": "^1.10.0"
   },
   "devDependencies": {
     "@openfeature/core": "^1.9.2"
-  }
+  },
+  "sideEffects": false
 }