@openfeature/react-sdk 0.2.3-experimental → 0.3.0-experimental

package/dist/types.d.ts

@@ -1,20 +1,33 @@
-import { EvaluationDetails, JsonValue, FlagEvaluationOptions, Client } from '@openfeature/web-sdk';
+import { FlagEvaluationOptions, FlagValue as FlagValue$1, JsonValue, EvaluationDetails as EvaluationDetails$1, Client } from '@openfeature/web-sdk';
 export * from '@openfeature/web-sdk';
+import { FlagValue, EvaluationDetails, FlagMetadata, StandardResolutionReasons, ErrorCode } from '@openfeature/core';
 import * as React from 'react';
 
-type ReactFlagEvaluationOptions = {
+type ReactFlagEvaluationOptions = ({
+    /**
+     * Enable or disable all suspense functionality.
+     * Cannot be used in conjunction with `suspendUntilReady` and `suspendWhileReconciling` options.
+     */
+    suspend?: boolean;
+    suspendUntilReady?: never;
+    suspendWhileReconciling?: never;
+} | {
     /**
      * Suspend flag evaluations while the provider is not ready.
      * Set to false if you don't want to show suspense fallbacks until the provider is initialized.
      * Defaults to true.
+     * Cannot be used in conjunction with `suspend` option.
      */
     suspendUntilReady?: boolean;
     /**
      * Suspend flag evaluations while the provider's context is being reconciled.
      * Set to true if you want to show suspense fallbacks while flags are re-evaluated after context changes.
-     * Defaults to false.
+     * Defaults to true.
+     * Cannot be used in conjunction with `suspend` option.
      */
     suspendWhileReconciling?: boolean;
+    suspend?: never;
+}) & {
     /**
      * Update the component if the provider emits a ConfigurationChanged event.
      * Set to false to prevent components from re-rendering when flag value changes
@@ -30,9 +43,71 @@ type ReactFlagEvaluationOptions = {
      */
     updateOnContextChanged?: boolean;
 } & FlagEvaluationOptions;
+
+interface FlagQuery<T extends FlagValue = FlagValue> {
+    /**
+     * A structure representing the result of the flag evaluation process
+     */
+    readonly details: EvaluationDetails<T>;
+    /**
+     * The flag value
+     */
+    readonly value: T;
+    /**
+     * A variant is a semantic identifier for a value.
+     * Not available from all providers.
+     */
+    readonly variant: string | undefined;
+    /**
+     * Arbitrary data associated with this flag or evaluation.
+     * Not available from all providers.
+     */
+    readonly flagMetadata: FlagMetadata;
+    /**
+     * The reason the evaluation resolved to the particular value.
+     * Not available from all providers.
+     */
+    readonly reason: typeof StandardResolutionReasons | string | undefined;
+    /**
+     * Indicates if this flag defaulted due to an error.
+     * Specifically, indicates reason equals {@link StandardResolutionReasons.ERROR} or the errorCode is set, this field is truthy.
+     */
+    readonly isError: boolean;
+    /**
+     * The error code, see {@link ErrorCode}.
+     */
+    readonly errorCode: ErrorCode | undefined;
+    /**
+     * A message associated with the error.
+     */
+    readonly errorMessage: string | undefined;
+    /**
+     * Indicates this flag is up-to-date and in sync with the source of truth.
+     * Specifically, indicates the evaluation did not default due to error, and the reason is neither {@link StandardResolutionReasons.STALE} or {@link StandardResolutionReasons.DISABLED}.
+     */
+    readonly isAuthoritative: boolean;
+    /**
+     * The type of the value, as returned by "typeof" operator.
+     */
+    readonly type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
+}
+
+/**
+ * Evaluates a feature flag generically, returning an react-flavored queryable object.
+ * The resolver method to use is based on the type of the defaultValue.
+ * For type-specific hooks, use {@link useBooleanFlagValue}, {@link useBooleanFlagDetails} and equivalents.
+ * By default, components will re-render when the flag value changes.
+ * @param {string} flagKey the flag identifier
+ * @template {FlagValue} T A optional generic argument constraining the default.
+ * @param {T} defaultValue the default value; used to determine what resolved type should be used.
+ * @param {ReactFlagEvaluationOptions} options for this evaluation
+ * @returns { FlagQuery } a queryable object containing useful information about the flag.
+ */
+declare function useFlag<T extends FlagValue$1 = FlagValue$1>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): FlagQuery<T extends boolean ? boolean : T extends number ? number : T extends string ? string : T extends JsonValue ? T : JsonValue>;
 /**
  * Evaluates a feature flag, returning a boolean.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @param {boolean} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
@@ -42,55 +117,61 @@ declare function useBooleanFlagValue(flagKey: string, defaultValue: boolean, opt
 /**
  * Evaluates a feature flag, returning evaluation details.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @param {boolean} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { EvaluationDetails<boolean>} a EvaluationDetails object for this evaluation
  */
-declare function useBooleanFlagDetails(flagKey: string, defaultValue: boolean, options?: ReactFlagEvaluationOptions): EvaluationDetails<boolean>;
+declare function useBooleanFlagDetails(flagKey: string, defaultValue: boolean, options?: ReactFlagEvaluationOptions): EvaluationDetails$1<boolean>;
 /**
  * Evaluates a feature flag, returning a string.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @template {string} [T=string] A optional generic argument constraining the string
  * @param {T} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { boolean} a EvaluationDetails object for this evaluation
  */
-declare function useStringFlagValue<T extends string = string>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): T;
+declare function useStringFlagValue<T extends string = string>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): string;
 /**
  * Evaluates a feature flag, returning evaluation details.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @template {string} [T=string] A optional generic argument constraining the string
  * @param {T} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { EvaluationDetails<string>} a EvaluationDetails object for this evaluation
  */
-declare function useStringFlagDetails<T extends string = string>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails<T>;
+declare function useStringFlagDetails<T extends string = string>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails$1<string>;
 /**
  * Evaluates a feature flag, returning a number.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @template {number} [T=number] A optional generic argument constraining the number
  * @param {T} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { boolean} a EvaluationDetails object for this evaluation
  */
-declare function useNumberFlagValue<T extends number = number>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): T;
+declare function useNumberFlagValue<T extends number = number>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): number;
 /**
  * Evaluates a feature flag, returning evaluation details.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @template {number} [T=number] A optional generic argument constraining the number
  * @param {T} defaultValue the default value
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { EvaluationDetails<number>} a EvaluationDetails object for this evaluation
  */
-declare function useNumberFlagDetails<T extends number = number>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails<T>;
+declare function useNumberFlagDetails<T extends number = number>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails$1<number>;
 /**
  * Evaluates a feature flag, returning an object.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @template {JsonValue} [T=JsonValue] A optional generic argument describing the structure
  * @param {T} defaultValue the default value
@@ -101,13 +182,14 @@ declare function useObjectFlagValue<T extends JsonValue = JsonValue>(flagKey: st
 /**
  * Evaluates a feature flag, returning evaluation details.
  * By default, components will re-render when the flag value changes.
+ * For a generic hook returning a queryable interface, see {@link useFlag}.
  * @param {string} flagKey the flag identifier
  * @param {T} defaultValue the default value
  * @template {JsonValue} [T=JsonValue] A optional generic argument describing the structure
  * @param {ReactFlagEvaluationOptions} options options for this evaluation
  * @returns { EvaluationDetails<T>} a EvaluationDetails object for this evaluation
  */
-declare function useObjectFlagDetails<T extends JsonValue = JsonValue>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails<T>;
+declare function useObjectFlagDetails<T extends JsonValue = JsonValue>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): EvaluationDetails$1<T>;
 
 type ClientOrDomain = {
     /**
@@ -125,8 +207,29 @@ type ClientOrDomain = {
 };
 type ProviderProps = {
     children?: React.ReactNode;
-} & ClientOrDomain;
-declare const OpenFeatureProvider: ({ client, domain, children }: ProviderProps) => React.JSX.Element;
-declare const useOpenFeatureClient: () => Client;
+} & ClientOrDomain & ReactFlagEvaluationOptions;
+/**
+ * Provides a scope for evaluating feature flags by binding a client to all child components.
+ * @param {ProviderProps} properties props for the context provider
+ * @returns {OpenFeatureProvider} context provider
+ */
+declare function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps): React.JSX.Element;
+
+/**
+ * Get the {@link Client} instance for this OpenFeatureProvider context.
+ * Note that the provider to which this is bound is determined by the OpenFeatureProvider's domain.
+ * @returns {Client} client for this scope
+ */
+declare function useOpenFeatureClient(): Client;
+
+type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
+/**
+ * Utility hook that triggers suspense until the provider is {@link ProviderStatus.READY}, without evaluating any flags.
+ * Especially useful for React v16/17 "Legacy Suspense", in which siblings to suspending components are
+ * initially mounted and then hidden (see: https://github.com/reactwg/react-18/discussions/7).
+ * @param {Options} options options for suspense
+ * @returns {boolean} boolean indicating if provider is {@link ProviderStatus.READY}, useful if suspense is disabled and you want to handle loaders on your own
+ */
+declare function useWhenProviderReady(options?: Options): boolean;
 
-export { OpenFeatureProvider, useBooleanFlagDetails, useBooleanFlagValue, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useStringFlagDetails, useStringFlagValue };
+export { FlagQuery, OpenFeatureProvider, useBooleanFlagDetails, useBooleanFlagValue, useFlag, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useStringFlagDetails, useStringFlagValue, useWhenProviderReady };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/react-sdk",
-  "version": "0.2.3-experimental",
+  "version": "0.3.0-experimental",
   "description": "OpenFeature React SDK",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -46,7 +46,7 @@
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
   "peerDependencies": {
-    "@openfeature/web-sdk": ">=1.0.0",
+    "@openfeature/web-sdk": "^1.0.2",
     "react": ">=16.8.0"
   },
   "devDependencies": {