@launchdarkly/react-sdk 0.0.0 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,367 @@
+import { LDWaitForInitializationResult, LDClient, LDContextStrict, LDOptions, LDStartOptions, LDContext, LDFlagSet, LDEvaluationDetailTyped } from '@launchdarkly/js-client-sdk';
+export * from '@launchdarkly/js-client-sdk';
+import React$1 from 'react';
+
+/**
+ * Initialization state of the client. This type should be consistent with
+ * the `status` field of the `LDWaitForInitializationResult` type.
+ */
+type InitializedState = LDWaitForInitializationResult['status'] | 'initializing' | 'unknown';
+/**
+ * The LaunchDarkly client interface for React.
+ */
+interface LDReactClient extends LDClient {
+    /**
+     * Returns the initialization state of the client. This function is helpful to determine
+     * whether LDClient can be used to evaluate flags on initial component render.
+     *
+     * @see {@link LDWaitForInitializationResult} for the possible values and their meaning
+     *
+     * @returns {InitializedState} The initialization state of the client.
+     */
+    getInitializationState(): InitializedState;
+    /**
+     * Returns the error that caused initialization to fail, if any.
+     * Only set when `getInitializationState()` returns `'failed'`.
+     */
+    getInitializationError(): Error | undefined;
+    /**
+     * Subscribes to context changes triggered by `identify()`. The callback is invoked
+     * after each successful `identify()` call with the new resolved context.
+     *
+     * @param callback Function called with the new context after each successful identify.
+     * @returns An unsubscribe function. Call it to stop receiving notifications.
+     */
+    onContextChange(callback: (context: LDContextStrict) => void): () => void;
+    /**
+     * Subscribes to initialization status changes triggered when the client is initialized.
+     *
+     * @param callback Function called with the initialization result.
+     * @returns An unsubscribe function. Call it to stop receiving notifications.
+     */
+    onInitializationStatusChange(callback: (result: LDWaitForInitializationResult) => void): () => void;
+}
+/**
+ * The React context interface for the LaunchDarkly client.
+ */
+interface LDReactClientContextValue {
+    /**
+     * The LaunchDarkly client.
+     */
+    client: LDReactClient;
+    /**
+     * The LaunchDarkly context. This will be undefined if the client is not initialized.
+     */
+    context?: LDContextStrict;
+    /**
+     * The initialization state of the client.
+     */
+    initializedState: InitializedState;
+    /**
+     * The error that caused the client to fail to initialize. Only set when `initializedState` is `'failed'`.
+     */
+    error?: Error;
+}
+/**
+ * The LaunchDarkly client context provider interface for React.
+ * This will be the type that is returned from our createContext function.
+ */
+type LDReactClientContext = React$1.Context<LDReactClientContextValue>;
+
+/**
+ * Initialization options for the LaunchDarkly React SDK.
+ */
+interface LDReactClientOptions extends LDOptions {
+    /**
+     * Whether the React SDK should transform flag keys into camel-cased format.
+     * Using camel-cased flag keys allow for easier use as prop values, however,
+     * these keys won't directly match the flag keys as known to LaunchDarkly.
+     * Consequently, flag key collisions may be possible and the Code References feature
+     * will not function properly.
+     *
+     * This is true by default, meaning that keys will automatically be converted to camel-case.
+     *
+     * For more information, see the React SDK Reference Guide on
+     * [flag keys](https://docs.launchdarkly.com/sdk/client-side/react/react-web#flag-keys).
+     *
+     * @deprecated This option is deprecated and will be removed in a future major version.
+     *
+     * @see https://docs.launchdarkly.com/sdk/client-side/react/react-web#flag-keys
+     */
+    useCamelCaseFlagKeys?: boolean;
+}
+/**
+ * Options for creating a React Provider.
+ */
+interface LDReactProviderOptions {
+    /**
+     * Options for the LaunchDarkly client.
+     *
+     * @remarks
+     * This option is used to pass options to the LaunchDarkly client.
+     *
+     * @see {@link LDReactClientOptions} for the possible options
+     */
+    ldOptions?: LDReactClientOptions;
+    /**
+     * Options for starting the LaunchDarkly client.
+     *
+     * @remarks
+     * This option is especially useful if you choose to not defer
+     * initialization and want to start the client immediately.
+     *
+     * @see {@link LDStartOptions} for the possible options
+     */
+    startOptions?: LDStartOptions;
+    /**
+     * If set to true, the LDClient will not start automatically.
+     *
+     * @default false
+     *
+     * If initialization is deferred, then the LDClient can be started manually
+     * by calling the `start` function.
+     */
+    deferInitialization?: boolean;
+    /**
+     * This option allow developers to provide their own named react context for
+     * the launchdarkly client. This is useful for cases where you want to have multiple
+     * clients in the same application. If not provided, the default context will be used.
+     *
+     * @see {@link LDReactClientContext} for the possible values and their meaning
+     *
+     * @returns {LDReactClientContext} The react context for the LaunchDarkly client.
+     */
+    reactContext?: LDReactClientContext;
+    /**
+     * Bootstrap data from the server. Pass the result of `flagsState.toJSON()` obtained
+     * from the server SDK's `allFlagsState` method.
+     *
+     * When provided, the client immediately uses these values before the first network
+     * response arrives — eliminating the flag-fetch waterfall on page load.
+     *
+     * This is merged into `startOptions.bootstrap` when the client is started. If both
+     * `bootstrap` and `startOptions.bootstrap` are provided, this top-level value takes
+     * precedence.
+     */
+    bootstrap?: unknown;
+}
+
+declare function initLDReactContext(): LDReactClientContext;
+/**
+ * The LaunchDarkly React context.
+ */
+declare const LDReactContext: LDReactClientContext;
+
+/**
+ * Creates a new LaunchDarkly React provider wrapping an existing client instance.
+ *
+ * @remarks
+ * **NOTE:** We recommend using the convenience factory function {@link createLDReactProvider}
+ * instead of this function if you can.
+ *
+ * This factory function is provided to allow the caller to use an existing client
+ * instance. When using this function, the caller is responsible for calling `client.start()`
+ * before or after mounting.
+ *
+ * @example
+ * ```tsx
+ * import { createClient, createLDReactProviderWithClient, initLDReactContext } from '@launchdarkly/react-sdk';
+ *
+ * const client = createClient(clientSideID, context);
+ * client.start();
+ * const LDProvider = createLDReactProviderWithClient(client);
+ * ```
+ *
+ * For multiple client instances, pass a custom React context:
+ * ```tsx
+ * const ReactContext = initLDReactContext();
+ * const LDProvider = createLDReactProviderWithClient(client, ReactContext);
+ * ```
+ *
+ * @param client launchdarkly client instance @see {@link createClient}
+ * @param ReactContext optional launchdarkly react context @see {@link initLDReactContext}
+ * @returns {React.FC<{ children: React.ReactNode }>} The LaunchDarkly React Client provider.
+ */
+declare function createLDReactProviderWithClient(client: LDReactClient, ReactContext?: React$1.Context<LDReactClientContextValue>): React$1.FC<{
+    children: React$1.ReactNode;
+}>;
+/**
+ * Creates a new LaunchDarkly React provider, creating the client internally.
+ *
+ * By default the client is started immediately (before the provider mounts).
+ * Pass `deferInitialization: true` in options to opt out of auto-start and call
+ * `client.start()` yourself via `useLDClient()`.
+ *
+ * @example
+ * ```tsx
+ * import { createLDReactProvider } from '@launchdarkly/react-sdk';
+ *
+ * const LDProvider = createLDReactProvider('your-client-side-id', { kind: 'user', key: 'user-key' });
+ *
+ * function Root() {
+ *   return (
+ *     <LDProvider>
+ *       <App />
+ *     </LDProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @param clientSideID launchdarkly client-side ID
+ * @param context the initial LaunchDarkly context
+ * @param options optional provider and client options
+ * @returns {React.FC<{ children: React.ReactNode }>} The LaunchDarkly React Client provider.
+ */
+declare function createLDReactProvider(clientSideID: string, context: LDContext, options?: LDReactProviderOptions): React$1.FC<{
+    children: React$1.ReactNode;
+}>;
+
+/**
+ * Creates a new instance of the LaunchDarkly client for React.
+ *
+ * @remarks
+ * **NOTE:** We recommend using the convenience factory function {@link createLDReactProvider}
+ * instead of this function to create your client instance if you can.
+ *
+ * This factory function is provided to allow the caller to have more control over their client instance.
+ * When using this function, the caller is responsible for:
+ *  - calling `client.start()` before or after mounting.
+ *  - subscribing to client lifecycle events.
+ *
+ * Refer to {@link createLDReactProviderWithClient} for the default behavior.
+ *
+ * @example
+ * ```tsx
+ * import { createClient } from '@launchdarkly/react';
+ * const client = createClient(clientSideID, context, options);
+ *
+ * await client.start();
+ * ```
+ *
+ * @param clientSideID launchdarkly client side id @see https://launchdarkly.com/docs/sdk/concepts/client-side-server-side#client-side-id
+ * @param context launchdarkly context @see https://launchdarkly.com/docs/sdk/concepts/context
+ * @param options options for the client @see {@link LDReactClientOptions}
+ * @returns the new client instance @see {@link LDReactClient}
+ */
+declare function createClient(clientSideID: string, context: LDContext, options?: LDReactClientOptions): LDReactClient;
+
+/**
+ * Returns all feature flags for the current context.
+ *
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns All current flag values, optionally with camelCased keys, wrapped in a proxy that
+ *   records evaluations.
+ *
+ * @deprecated This hook is provided to ease migration from older versions of the React SDK.
+ * For better performance, migrate to the typed variation hooks (`useBoolVariation`,
+ * `useStringVariation`, `useNumberVariation`, `useJsonVariation`) or use `useLDClient`
+ * with the client's `allFlags` method directly. This hook will be removed in a future major version.
+ */
+declare function useFlags<T extends LDFlagSet = LDFlagSet>(reactContext?: React.Context<LDReactClientContextValue>): T;
+
+/**
+ * Represents the current initialization state of the LaunchDarkly client.
+ */
+type InitializationStatus = {
+    status: 'unknown';
+} | {
+    status: 'initializing';
+} | {
+    status: 'complete';
+} | {
+    status: 'timeout';
+} | {
+    status: 'failed';
+    error: Error;
+};
+/**
+ * Returns the initialization status of the LaunchDarkly client.
+ *
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns An {@link InitializationStatus} object with the current state (and error, if failed).
+ */
+declare function useInitializationStatus(reactContext?: React.Context<LDReactClientContextValue>): InitializationStatus;
+
+/**
+ * Returns the LaunchDarkly client instance from the nearest provider.
+ *
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The {@link LDReactClient} instance.
+ */
+declare function useLDClient(reactContext?: React.Context<LDReactClientContextValue>): LDReactClient;
+
+/**
+ * Returns the boolean variation of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The boolean flag value, or `defaultValue` if the flag is unavailable.
+ */
+declare function useBoolVariation(key: string, defaultValue: boolean, reactContext?: React.Context<LDReactClientContextValue>): boolean;
+/**
+ * Returns the string variation of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The string flag value, or `defaultValue` if the flag is unavailable.
+ */
+declare function useStringVariation(key: string, defaultValue: string, reactContext?: React.Context<LDReactClientContextValue>): string;
+/**
+ * Returns the numeric variation of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The number flag value, or `defaultValue` if the flag is unavailable.
+ */
+declare function useNumberVariation(key: string, defaultValue: number, reactContext?: React.Context<LDReactClientContextValue>): number;
+/**
+ * Returns the JSON variation of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The JSON flag value, or `defaultValue` if the flag is unavailable.
+ */
+declare function useJsonVariation<T = unknown>(key: string, defaultValue: T, reactContext?: React.Context<LDReactClientContextValue>): T;
+
+/**
+ * Returns the boolean variation and evaluation detail of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The evaluation detail including `value`, `variationIndex`, and `reason`.
+ */
+declare function useBoolVariationDetail(key: string, defaultValue: boolean, reactContext?: React.Context<LDReactClientContextValue>): LDEvaluationDetailTyped<boolean>;
+/**
+ * Returns the string variation and evaluation detail of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The evaluation detail including `value`, `variationIndex`, and `reason`.
+ */
+declare function useStringVariationDetail(key: string, defaultValue: string, reactContext?: React.Context<LDReactClientContextValue>): LDEvaluationDetailTyped<string>;
+/**
+ * Returns the numeric variation and evaluation detail of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The evaluation detail including `value`, `variationIndex`, and `reason`.
+ */
+declare function useNumberVariationDetail(key: string, defaultValue: number, reactContext?: React.Context<LDReactClientContextValue>): LDEvaluationDetailTyped<number>;
+/**
+ * Returns the JSON variation and evaluation detail of a feature flag.
+ *
+ * @param key The feature flag key.
+ * @param defaultValue The value to return if the flag is not available.
+ * @param reactContext Optional React context to read from. Defaults to the global `LDReactContext`.
+ * @returns The evaluation detail including `value`, `variationIndex`, and `reason`.
+ */
+declare function useJsonVariationDetail<T = unknown>(key: string, defaultValue: T, reactContext?: React.Context<LDReactClientContextValue>): LDEvaluationDetailTyped<T>;
+
+export { type InitializationStatus, type InitializedState, type LDReactClient, type LDReactClientContext, type LDReactClientContextValue, type LDReactClientOptions, LDReactContext, type LDReactProviderOptions, createClient, createLDReactProvider, createLDReactProviderWithClient, initLDReactContext, useBoolVariation, useBoolVariationDetail, useFlags, useInitializationStatus, useJsonVariation, useJsonVariationDetail, useLDClient, useNumberVariation, useNumberVariationDetail, useStringVariation, useStringVariationDetail };