@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): 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;

/**
 * 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 { type ContextMutation, type ContextMutationOptions, type FlagQuery, type NormalizedOptions, OpenFeatureProvider, OpenFeatureTestProvider, type ReactFlagEvaluationNoSuspenseOptions, type ReactFlagEvaluationOptions, type Track, useBooleanFlagDetails, useBooleanFlagValue, useContextMutator, useFlag, useNumberFlagDetails, useNumberFlagValue, useObjectFlagDetails, useObjectFlagValue, useOpenFeatureClient, useOpenFeatureClientStatus, useStringFlagDetails, useStringFlagValue, useSuspenseFlag, useTrack, useWhenProviderReady };