@launchdarkly/react-sdk 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -3,10 +3,16 @@ 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.
+ * Represents the current initialization state of the LaunchDarkly client.
  */
-type InitializedState = LDWaitForInitializationResult['status'] | 'initializing' | 'unknown';
+type InitializationStatus = LDWaitForInitializationResult | {
+    status: 'initializing';
+};
+/**
+ * Initialization state of the client as a string union.
+ * Derived from {@link InitializationStatus} for consistency.
+ */
+type InitializedState = InitializationStatus['status'];
 /**
  * The LaunchDarkly client interface for React.
  */
@@ -40,6 +46,14 @@ interface LDReactClient extends LDClient {
      * @returns An unsubscribe function. Call it to stop receiving notifications.
      */
     onInitializationStatusChange(callback: (result: LDWaitForInitializationResult) => void): () => void;
+    /**
+     * Returns whether the client is ready to evaluate flags. This is true when the client
+     * has completed initialization (successfully or with failure), or when bootstrap data
+     * was provided.
+     *
+     * @returns {boolean} Whether the client can evaluate flags.
+     */
+    isReady(): boolean;
 }
 /**
  * The React context interface for the LaunchDarkly client.
@@ -123,13 +137,11 @@ interface LDReactProviderOptions {
      */
     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
+     * This option allows 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.
+     * @see {@link LDReactClientContext}
      */
     reactContext?: LDReactClientContext;
     /**
@@ -146,9 +158,32 @@ interface LDReactProviderOptions {
     bootstrap?: unknown;
 }
 
+/**
+ * Creates a new LaunchDarkly React context.
+ *
+ * @remarks
+ * This function can be used to create different LaunchDarkly contexts for the same
+ * application.
+ *
+ * **NOTE:** This function is not necessary if you are only using a single LaunchDarkly environment.
+ * If that is the case, you can use the {@link LDReactContext} directly.
+ *
+ * @returns A new React context for the LaunchDarkly client.
+ */
 declare function initLDReactContext(): LDReactClientContext;
 /**
- * The LaunchDarkly React context.
+ * The default LaunchDarkly React context.
+ *
+ * @example
+ * ```tsx
+ * import { LDReactContext, useLDClient } from '@launchdarkly/react-sdk';
+ *
+ * function MyComponent() {
+ *   const client = useLDClient(LDReactContext);
+ *   const flagValue = client.boolVariation('my-flag', false);
+ *   return <div>{flagValue ? 'on' : 'off'}</div>;
+ * }
+ * ```
  */
 declare const LDReactContext: LDReactClientContext;
 
@@ -156,7 +191,7 @@ 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}
+ * **NOTE:** We recommend using the 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
@@ -216,6 +251,54 @@ declare function createLDReactProvider(clientSideID: string, context: LDContext,
     children: React$1.ReactNode;
 }>;
 
+/**
+ * Props for {@link LDIsomorphicClientProvider}.
+ */
+interface LDIsomorphicClientProviderProps {
+    /**
+     * The LaunchDarkly client-side ID.
+     */
+    clientSideId: string;
+    /**
+     * The initial context to identify with.
+     */
+    context: LDContext;
+    /**
+     * Bootstrap data from the server. Pass the result of `flagsState.toJSON()` obtained
+     * from {@link LDServerSession.allFlagsState} on the server.
+     *
+     * @remarks
+     * **NOTE:** This interface is meant to be used with the server component {@link LDIsomorphicProvider}.
+     * If you are looking to providing your own bootstrap data, you should use
+     * the {@link createLDReactProvider} function directly.
+     *
+     */
+    bootstrap: unknown;
+    /**
+     * Additional options forwarded to {@link createLDReactProvider}.
+     *
+     * @remarks
+     * The omitted fields are hoisted to top level options because they are not
+     * serializable across the RSC boundary.
+     */
+    options?: Omit<LDReactProviderOptions, 'bootstrap' | 'reactContext'>;
+    /**
+     * Optional custom React context for the LaunchDarkly client. Use this when you need
+     * multiple LaunchDarkly client instances in the same application.
+     */
+    reactContext?: React$1.Context<LDReactClientContextValue>;
+    children: React$1.ReactNode;
+}
+/**
+ * A `'use client'` provider that initializes the LaunchDarkly browser client from
+ * server-evaluated flag values bootstrapped by {@link LDIsomorphicProvider}.
+ *
+ * @remarks
+ * **NOTE:** This provider is designed to be used in conjunction with {@link LDIsomorphicProvider}
+ * in a server component to compute the bootstrap data and render this provider automatically.
+ */
+declare function LDIsomorphicClientProvider({ clientSideId, context, bootstrap, options, reactContext, children, }: LDIsomorphicClientProviderProps): React$1.JSX.Element;
+
 /**
  * Creates a new instance of the LaunchDarkly client for React.
  *
@@ -232,7 +315,7 @@ declare function createLDReactProvider(clientSideID: string, context: LDContext,
  *
  * @example
  * ```tsx
- * import { createClient } from '@launchdarkly/react';
+ * import { createClient } from '@launchdarkly/react-sdk';
  * const client = createClient(clientSideID, context, options);
  *
  * await client.start();
@@ -259,21 +342,6 @@ declare function createClient(clientSideID: string, context: LDContext, options?
  */
 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.
  *
@@ -364,4 +432,4 @@ declare function useNumberVariationDetail(key: string, defaultValue: number, rea
  */
 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 };
+export { type InitializationStatus, type InitializedState, LDIsomorphicClientProvider, type LDIsomorphicClientProviderProps, 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 };

package/dist/index.d.ts

@@ -3,10 +3,16 @@ 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.
+ * Represents the current initialization state of the LaunchDarkly client.
  */
-type InitializedState = LDWaitForInitializationResult['status'] | 'initializing' | 'unknown';
+type InitializationStatus = LDWaitForInitializationResult | {
+    status: 'initializing';
+};
+/**
+ * Initialization state of the client as a string union.
+ * Derived from {@link InitializationStatus} for consistency.
+ */
+type InitializedState = InitializationStatus['status'];
 /**
  * The LaunchDarkly client interface for React.
  */
@@ -40,6 +46,14 @@ interface LDReactClient extends LDClient {
      * @returns An unsubscribe function. Call it to stop receiving notifications.
      */
     onInitializationStatusChange(callback: (result: LDWaitForInitializationResult) => void): () => void;
+    /**
+     * Returns whether the client is ready to evaluate flags. This is true when the client
+     * has completed initialization (successfully or with failure), or when bootstrap data
+     * was provided.
+     *
+     * @returns {boolean} Whether the client can evaluate flags.
+     */
+    isReady(): boolean;
 }
 /**
  * The React context interface for the LaunchDarkly client.
@@ -123,13 +137,11 @@ interface LDReactProviderOptions {
      */
     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
+     * This option allows 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.
+     * @see {@link LDReactClientContext}
      */
     reactContext?: LDReactClientContext;
     /**
@@ -146,9 +158,32 @@ interface LDReactProviderOptions {
     bootstrap?: unknown;
 }
 
+/**
+ * Creates a new LaunchDarkly React context.
+ *
+ * @remarks
+ * This function can be used to create different LaunchDarkly contexts for the same
+ * application.
+ *
+ * **NOTE:** This function is not necessary if you are only using a single LaunchDarkly environment.
+ * If that is the case, you can use the {@link LDReactContext} directly.
+ *
+ * @returns A new React context for the LaunchDarkly client.
+ */
 declare function initLDReactContext(): LDReactClientContext;
 /**
- * The LaunchDarkly React context.
+ * The default LaunchDarkly React context.
+ *
+ * @example
+ * ```tsx
+ * import { LDReactContext, useLDClient } from '@launchdarkly/react-sdk';
+ *
+ * function MyComponent() {
+ *   const client = useLDClient(LDReactContext);
+ *   const flagValue = client.boolVariation('my-flag', false);
+ *   return <div>{flagValue ? 'on' : 'off'}</div>;
+ * }
+ * ```
  */
 declare const LDReactContext: LDReactClientContext;
 
@@ -156,7 +191,7 @@ 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}
+ * **NOTE:** We recommend using the 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
@@ -216,6 +251,54 @@ declare function createLDReactProvider(clientSideID: string, context: LDContext,
     children: React$1.ReactNode;
 }>;
 
+/**
+ * Props for {@link LDIsomorphicClientProvider}.
+ */
+interface LDIsomorphicClientProviderProps {
+    /**
+     * The LaunchDarkly client-side ID.
+     */
+    clientSideId: string;
+    /**
+     * The initial context to identify with.
+     */
+    context: LDContext;
+    /**
+     * Bootstrap data from the server. Pass the result of `flagsState.toJSON()` obtained
+     * from {@link LDServerSession.allFlagsState} on the server.
+     *
+     * @remarks
+     * **NOTE:** This interface is meant to be used with the server component {@link LDIsomorphicProvider}.
+     * If you are looking to providing your own bootstrap data, you should use
+     * the {@link createLDReactProvider} function directly.
+     *
+     */
+    bootstrap: unknown;
+    /**
+     * Additional options forwarded to {@link createLDReactProvider}.
+     *
+     * @remarks
+     * The omitted fields are hoisted to top level options because they are not
+     * serializable across the RSC boundary.
+     */
+    options?: Omit<LDReactProviderOptions, 'bootstrap' | 'reactContext'>;
+    /**
+     * Optional custom React context for the LaunchDarkly client. Use this when you need
+     * multiple LaunchDarkly client instances in the same application.
+     */
+    reactContext?: React$1.Context<LDReactClientContextValue>;
+    children: React$1.ReactNode;
+}
+/**
+ * A `'use client'` provider that initializes the LaunchDarkly browser client from
+ * server-evaluated flag values bootstrapped by {@link LDIsomorphicProvider}.
+ *
+ * @remarks
+ * **NOTE:** This provider is designed to be used in conjunction with {@link LDIsomorphicProvider}
+ * in a server component to compute the bootstrap data and render this provider automatically.
+ */
+declare function LDIsomorphicClientProvider({ clientSideId, context, bootstrap, options, reactContext, children, }: LDIsomorphicClientProviderProps): React$1.JSX.Element;
+
 /**
  * Creates a new instance of the LaunchDarkly client for React.
  *
@@ -232,7 +315,7 @@ declare function createLDReactProvider(clientSideID: string, context: LDContext,
  *
  * @example
  * ```tsx
- * import { createClient } from '@launchdarkly/react';
+ * import { createClient } from '@launchdarkly/react-sdk';
  * const client = createClient(clientSideID, context, options);
  *
  * await client.start();
@@ -259,21 +342,6 @@ declare function createClient(clientSideID: string, context: LDContext, options?
  */
 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.
  *
@@ -364,4 +432,4 @@ declare function useNumberVariationDetail(key: string, defaultValue: number, rea
  */
 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 };
+export { type InitializationStatus, type InitializedState, LDIsomorphicClientProvider, type LDIsomorphicClientProviderProps, 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 };