@openfeature/react-sdk/dist/types.d.ts

OpenFeature React SDK

import { FlagEvaluationOptions, FlagValue as FlagValue$1, JsonValue, EvaluationDetails as EvaluationDetails$1, Client, ProviderStatus, Provider, EvaluationContext, Tracking } from '@openfeature/web-sdk';
export * from '@openfeature/web-sdk';
import { FlagValue, EvaluationDetails, FlagMetadata, StandardResolutionReasons, ErrorCode } from '@openfeature/core';
import * as React from 'react';
import React__default from 'react';

type ReactFlagEvaluationOptions = ({
    /**
     * Enable or disable all suspense functionality.
     * Cannot be used in conjunction with `suspendUntilReady` and `suspendWhileReconciling` options.
     * @experimental Suspense is an experimental feature subject to change in future versions.
     */
    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 false.
     * Cannot be used in conjunction with `suspend` option.
     * @experimental Suspense is an experimental feature subject to change in future versions.
     */
    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.
     * Cannot be used in conjunction with `suspend` option.
     * @experimental Suspense is an experimental feature subject to change in future versions.
     */
    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
     * are received by the associated provider.
     * Defaults to true.
     */
    updateOnConfigurationChanged?: boolean;
    /**
     * Update the component when the OpenFeature context changes.
     * Set to false to prevent components from re-rendering when attributes which
     * may be factors in flag evaluation change.
     * Defaults to true.
     */
    updateOnContextChanged?: boolean;
} & FlagEvaluationOptions;
type ReactFlagEvaluationNoSuspenseOptions = Omit<ReactFlagEvaluationOptions, 'suspend' | 'suspendUntilReady' | 'suspendWhileReconciling'>;
type NormalizedOptions = Omit<ReactFlagEvaluationOptions, 'suspend'>;

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>;
type UseFlagReturn<T extends FlagValue$1> = ReturnType<typeof useFlag<T>>;
/**
 * Equivalent to {@link useFlag} with `options: { suspend: true }`
 * @experimental Suspense is an experimental feature subject to change in future versions.
 * @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 {ReactFlagEvaluationNoSuspenseOptions} options for this evaluation
 * @returns { UseFlagReturn<T> } a queryable object containing useful information about the flag.
 */
declare function useSuspenseFlag<T extends FlagValue$1 = FlagValue$1>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationNoSuspenseOptions): UseFlagReturn<T>;
/**
 * 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
 * @returns { boolean} a EvaluationDetails object for this evaluation
 */
declare function useBooleanFlagValue(flagKey: string, defaultValue: boolean, options?: ReactFlagEvaluationOptions): boolean;
/**
 * 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$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): 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$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): 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$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
 * @param {ReactFlagEvaluationOptions} options options for this evaluation
 * @returns { boolean} a EvaluationDetails object for this evaluation
 */
declare function useObjectFlagValue<T extends JsonValue = JsonValue>(flagKey: string, defaultValue: T, options?: ReactFlagEvaluationOptions): T;
/**
 * 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$1<T>;

type ClientOrDomain = {
    /**
     * An identifier which logically binds clients with providers
     * @see OpenFeature.setProvider() and overloads.
     */
    domain?: string;
    client?: never;
} | {
    /**
     * OpenFeature client to use.
     */
    client?: Client;
    domain?: never;
};
type ProviderProps = {
    children?: React.ReactNode;
} & 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): 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;

/**
 * Get the {@link ProviderStatus} for the OpenFeatureClient.
 * @returns {ProviderStatus} status of the client for this scope
 */
declare function useOpenFeatureClientStatus(): ProviderStatus;

type FlagValueMap = {
    [flagKey: string]: JsonValue;
};
type TestProviderProps = Omit<React__default.ComponentProps<typeof OpenFeatureProvider>, 'client'> & ({
    provider?: never;
    /**
     * Optional map of flagKeys to flagValues for this OpenFeatureTestProvider context.
     * If not supplied, all flag evaluations will default.
     */
    flagValueMap?: FlagValueMap;
    /**
     * Optional delay for the underlying test provider's readiness and reconciliation.
     * Defaults to 0.
     */
    delayMs?: number;
} | {
    /**
     * An optional partial provider to pass for full control over the flag resolution for this OpenFeatureTestProvider context.
     * Any un-implemented methods or properties will no-op.
     */
    provider?: Partial<Provider>;
    flagValueMap?: never;
    delayMs?: never;
});
/**
 * A React Context provider based on the {@link InMemoryProvider}, specifically built for testing.
 * Use this for testing components that use flag evaluation hooks.
 * @param {TestProviderProps} testProviderOptions options for the OpenFeatureTestProvider
 * @returns {OpenFeatureProvider} OpenFeatureTestProvider
 */
declare function OpenFeatureTestProvider(testProviderOptions: TestProviderProps): React__default.JSX.Element;

type ContextMutationOptions = {
    /**
     * Mutate the default context instead of the domain scoped context applied at the `<OpenFeatureProvider/>`.
     * Note, if the `<OpenFeatureProvider/>` has no domain specified, the default is used.
     * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#manage-evaluation-context-for-domains|documentation} for more information.
     * @default false
     */
    defaultContext?: boolean;
};
type ContextMutation = {
    /**
     * Context-aware function to set the desired context (see: {@link ContextMutationOptions} for details).
     * There's generally no need to await the result of this function; flag evaluation hooks will re-render when the context is updated.
     * This promise never rejects.
     * @param updatedContext
     * @returns Promise for awaiting the context update
     */
    setContext: (updatedContext: EvaluationContext) => Promise<void>;
};
/**
 * Get context-aware tracking function(s) for mutating the evaluation context associated with this domain, or the default context if `defaultContext: true`.
 * See the {@link https://openfeature.dev/docs/reference/technologies/client/web/#targeting-and-context|documentation} for more information.
 * @param {ContextMutationOptions} options options for the generated function
 * @returns {ContextMutation} context-aware function(s) to mutate evaluation context
 */
declare function useContextMutator(options?: ContextMutationOptions): ContextMutation;

type Track = {
    /**
     * Context-aware tracking function for the parent `<OpenFeatureProvider/>`.
     * Track a user action or application state, usually representing a business objective or outcome.
     * @param trackingEventName an identifier for the event
     * @param trackingEventDetails the details of the tracking event
     */
    track: Tracking['track'];
};
/**
 * Get a context-aware tracking function.
 * @returns {Track} context-aware tracking
 */
declare function useTrack(): Track;

export { OpenFeatureProvider, OpenFeatureTestProvider, useBooleanFlagDetails, useBooleanFlagValue, useContextMutator, useFlag, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useOpenFeatureClientStatus, useStringFlagDetails, useStringFlagValue, useSuspenseFlag, useTrack, useWhenProviderReady };
export type { ContextMutation, ContextMutationOptions, FlagQuery, NormalizedOptions, ReactFlagEvaluationNoSuspenseOptions, ReactFlagEvaluationOptions, Track };