@replanejs/react 0.8.20 → 0.9.2

package/README.md

@@ -29,7 +29,7 @@ import { ReplaneProvider, useConfig } from "@replanejs/react";
 function App() {
   return (
     <ReplaneProvider
-      options={{
+      connection={{
         baseUrl: "https://your-replane-server.com",
         sdkKey: "your-sdk-key",
       }}
@@ -51,9 +51,9 @@ function MyComponent() {
 
 ### ReplaneProvider
 
-Provider component that makes the Replane client available to your component tree. Supports four usage patterns:
+Provider component that makes the Replane client available to your component tree. Supports multiple usage patterns:
 
-#### 1. With options (recommended)
+#### 1. With connection (recommended)
 
 The provider creates and manages the client internally. Use an Error Boundary to handle initialization errors:
 
@@ -62,7 +62,7 @@ import { ErrorBoundary } from "react-error-boundary";
 
 <ErrorBoundary fallback={<div>Failed to load configuration</div>}>
   <ReplaneProvider
-    options={{
+    connection={{
       baseUrl: "https://your-replane-server.com",
       sdkKey: "your-sdk-key",
     }}
@@ -73,29 +73,44 @@ import { ErrorBoundary } from "react-error-boundary";
 </ErrorBoundary>;
 ```
 
-#### Client Options
+#### Provider Props
 
-The `options` prop accepts all options from `@replanejs/sdk`. Key options:
+| Prop         | Type                        | Required | Description                                             |
+| ------------ | --------------------------- | -------- | ------------------------------------------------------- |
+| `connection` | `ConnectOptions \| null`    | Yes      | Connection options (see below), or `null` to skip connection |
+| `defaults`   | `Record<string, unknown>`   | No       | Default values if server is unavailable                 |
+| `context`    | `Record<string, unknown>`   | No       | Default context for override evaluations                |
+| `snapshot`   | `ReplaneSnapshot`           | No       | Snapshot for SSR hydration                              |
+| `logger`     | `ReplaneLogger`             | No       | Custom logger (default: console)                        |
+| `loader`     | `ReactNode`                 | No       | Component to show while loading                         |
+| `suspense`   | `boolean`                   | No       | Use React Suspense for loading state                    |
+| `async`      | `boolean`                   | No       | Connect asynchronously (renders immediately with defaults) |
 
-| Option                    | Type                   | Required | Description                                |
-| ------------------------- | ---------------------- | -------- | ------------------------------------------ |
-| `baseUrl`                 | `string`               | Yes      | Replane server URL                         |
-| `sdkKey`                  | `string`               | Yes      | SDK key for authentication                 |
-| `context`                 | `Record<string, any>`  | No       | Default context for override evaluations   |
-| `defaults`                | `Record<string, any>`  | No       | Default values if server is unavailable    |
-| `required`                | `string[]` or `object` | No       | Configs that must exist for initialization |
-| `initializationTimeoutMs` | `number`               | No       | SDK initialization timeout (default: 5000) |
+#### Connection Options
 
-See [`@replanejs/sdk` documentation](https://github.com/replane-dev/replane-javascript/tree/main/packages/sdk#options) for the complete list of options.
+The `connection` prop accepts the following options:
+
+| Option               | Type                  | Required | Description                                  |
+| -------------------- | --------------------- | -------- | -------------------------------------------- |
+| `baseUrl`            | `string`              | Yes      | Replane server URL                           |
+| `sdkKey`             | `string`              | Yes      | SDK key for authentication                   |
+| `connectTimeoutMs`   | `number`              | No       | SDK connection timeout (default: 5000)       |
+| `requestTimeoutMs`   | `number`              | No       | Timeout for SSE requests (default: 2000)     |
+| `retryDelayMs`       | `number`              | No       | Base delay between retries (default: 200)    |
+| `inactivityTimeoutMs`| `number`              | No       | SSE inactivity timeout (default: 30000)      |
+| `fetchFn`            | `typeof fetch`        | No       | Custom fetch implementation                  |
+
+See [`@replanejs/sdk` documentation](https://github.com/replane-dev/replane-javascript/tree/main/packages/sdk#api) for more details.
 
 #### 2. With pre-created client
 
 Use this when you need more control over client lifecycle:
 
 ```tsx
-import { createReplaneClient } from "@replanejs/sdk";
+import { Replane } from "@replanejs/sdk";
 
-const client = await createReplaneClient({
+const client = new Replane();
+await client.connect({
   baseUrl: "https://your-replane-server.com",
   sdkKey: "your-sdk-key",
 });
@@ -113,7 +128,7 @@ Integrates with React Suspense for loading states:
 <ErrorBoundary fallback={<div>Failed to load configuration</div>}>
   <Suspense fallback={<LoadingSpinner />}>
     <ReplaneProvider
-      options={{
+      connection={{
         baseUrl: "https://your-replane-server.com",
         sdkKey: "your-sdk-key",
       }}
@@ -125,32 +140,47 @@ Integrates with React Suspense for loading states:
 </ErrorBoundary>
 ```
 
-#### 4. With snapshot (for SSR/hydration)
+#### 4. With async mode
+
+Connect in the background while rendering immediately with defaults:
+
+```tsx
+<ReplaneProvider
+  connection={{
+    baseUrl: "https://your-replane-server.com",
+    sdkKey: "your-sdk-key",
+  }}
+  defaults={{ featureEnabled: false }}
+  async
+>
+  <App />
+</ReplaneProvider>
+```
+
+#### 5. With snapshot (for SSR/hydration)
 
 Restore a client from a snapshot obtained on the server. This is synchronous and useful for SSR scenarios:
 
 ```tsx
 // On the server
-const serverClient = await createReplaneClient({ baseUrl: "...", sdkKey: "..." });
+const serverClient = new Replane();
+await serverClient.connect({ baseUrl: "...", sdkKey: "..." });
 const snapshot = serverClient.getSnapshot();
 // Pass snapshot to client via props, context, or serialized HTML
 
 // On the client
 <ReplaneProvider
-  restoreOptions={{
-    snapshot,
-    // Optional: connect for live updates
-    connection: {
-      baseUrl: "https://your-replane-server.com",
-      sdkKey: "your-sdk-key",
-    },
+  connection={{
+    baseUrl: "https://your-replane-server.com",
+    sdkKey: "your-sdk-key",
   }}
+  snapshot={snapshot}
 >
   <App />
 </ReplaneProvider>;
 ```
 
-The restored client is immediately available with no loading state. If `connection` is provided, it will establish a connection for real-time updates in the background.
+The restored client is immediately available with no loading state. The provider will establish a connection for real-time updates in the background.
 
 ### useConfig
 
@@ -350,7 +380,7 @@ class ErrorBoundary extends Component<
 
 // Usage
 <ErrorBoundary fallback={<div>Configuration failed to load</div>}>
-  <ReplaneProvider options={options} loader={<Loading />}>
+  <ReplaneProvider connection={connection} loader={<Loading />}>
     <App />
   </ReplaneProvider>
 </ErrorBoundary>;
@@ -370,7 +400,7 @@ import { ErrorBoundary } from "react-error-boundary";
   )}
   onReset={() => clearSuspenseCache()}
 >
-  <ReplaneProvider options={options} loader={<Loading />}>
+  <ReplaneProvider connection={connection} loader={<Loading />}>
     <App />
   </ReplaneProvider>
 </ErrorBoundary>;

package/dist/index.cjs

@@ -31,11 +31,6 @@ const react_jsx_runtime = __toESM(require("react/jsx-runtime"));
 //#region src/context.ts
 const ReplaneContext = (0, react.createContext)(null);
 
-//#endregion
-//#region src/version.ts
-const VERSION = "0.8.20";
-const DEFAULT_AGENT = `replane-js-react/${VERSION}`;
-
 //#endregion
 //#region src/useReplaneClient.ts
 const suspenseCache = new Map();
@@ -43,10 +38,23 @@ function getCacheKey(options) {
 	return `${options.baseUrl}:${options.sdkKey}`;
 }
 /**
-* Hook to manage ReplaneClient creation internally.
+* Creates a Replane client and connects it.
+*/
+async function createAndConnectClient(options, connection) {
+	const client = new __replanejs_sdk.Replane({
+		logger: options.logger,
+		context: options.context,
+		defaults: options.defaults
+	});
+	if (!connection) return client;
+	await client.connect(connection);
+	return client;
+}
+/**
+* Hook to manage Replane client creation internally.
 * Handles loading state and cleanup.
 */
-function useReplaneClientInternal(options) {
+function useReplaneClientInternal(options, originalConnection) {
 	const [state, setState] = (0, react.useState)({
 		status: "loading",
 		client: null,
@@ -54,16 +62,15 @@ function useReplaneClientInternal(options) {
 	});
 	const clientRef = (0, react.useRef)(null);
 	const optionsRef = (0, react.useRef)(options);
+	const connectionJson = JSON.stringify(originalConnection);
 	(0, react.useEffect)(() => {
+		const connection = JSON.parse(connectionJson);
 		let cancelled = false;
 		async function initClient() {
 			try {
-				const client = await (0, __replanejs_sdk.createReplaneClient)({
-					...optionsRef.current,
-					agent: optionsRef.current.agent ?? DEFAULT_AGENT
-				});
+				const client = await createAndConnectClient(optionsRef.current, connection);
 				if (cancelled) {
-					client.close();
+					client.disconnect();
 					return;
 				}
 				clientRef.current = client;
@@ -86,29 +93,26 @@ function useReplaneClientInternal(options) {
 		return () => {
 			cancelled = true;
 			if (clientRef.current) {
-				clientRef.current.close();
+				clientRef.current.disconnect();
 				clientRef.current = null;
 			}
 		};
-	}, []);
+	}, [connectionJson]);
 	return state;
 }
 /**
 * Hook for Suspense-based client creation.
 * Throws a promise while loading, throws error on failure.
 */
-function useReplaneClientSuspense(options) {
-	const cacheKey = getCacheKey(options);
+function useReplaneClientSuspense(options, connection) {
+	const cacheKey = getCacheKey(connection);
 	const cached = suspenseCache.get(cacheKey);
 	if (cached) {
 		if (cached.error) throw cached.error;
 		if (cached.result) return cached.result;
 		throw cached.promise;
 	}
-	const promise = (0, __replanejs_sdk.createReplaneClient)({
-		...options,
-		agent: options.agent ?? DEFAULT_AGENT
-	}).then((client) => {
+	const promise = createAndConnectClient(options, connection).then((client) => {
 		const entry = suspenseCache.get(cacheKey);
 		if (entry) entry.result = client;
 		return client;
@@ -121,150 +125,59 @@ function useReplaneClientSuspense(options) {
 	throw promise;
 }
 /**
-* Clear the suspense cache for a specific options configuration.
+* Clear the suspense cache for a specific connection configuration.
 * Useful for testing or when you need to force re-initialization.
 */
-function clearSuspenseCache(options) {
-	if (options) suspenseCache.delete(getCacheKey(options));
+function clearSuspenseCache(connection) {
+	if (connection) suspenseCache.delete(getCacheKey(connection));
 	else suspenseCache.clear();
 }
 
-//#endregion
-//#region src/hooks.ts
-function useReplane() {
-	const context = (0, react.useContext)(ReplaneContext);
-	if (!context) throw new Error("useReplane must be used within a ReplaneProvider");
-	return context.client;
-}
-function useConfig(name, options) {
-	const client = useReplane();
-	const subscribe = (0, react.useCallback)((callback) => {
-		return client.subscribe(name, callback);
-	}, [client, name]);
-	const get = (0, react.useCallback)(() => {
-		return client.get(name, options);
-	}, [
-		client,
-		name,
-		options
-	]);
-	const value = (0, react.useSyncExternalStore)(subscribe, get, get);
-	return value;
-}
-/**
-* Creates a typed version of useReplane hook.
-*
-* @example
-* ```tsx
-* interface AppConfigs {
-*   theme: { darkMode: boolean };
-*   features: { beta: boolean };
-* }
-*
-* const useAppReplane = createReplaneHook<AppConfigs>();
-*
-* function MyComponent() {
-*   const replane = useAppReplane();
-*   // replane.get("theme") returns { darkMode: boolean }
-* }
-* ```
-*/
-function createReplaneHook() {
-	return function useTypedReplane() {
-		return useReplane();
-	};
-}
-/**
-* Creates a typed version of useConfig hook.
-*
-* @example
-* ```tsx
-* interface AppConfigs {
-*   theme: { darkMode: boolean };
-*   features: { beta: boolean };
-* }
-*
-* const useAppConfig = createConfigHook<AppConfigs>();
-*
-* function MyComponent() {
-*   const theme = useAppConfig("theme");
-*   // theme is typed as { darkMode: boolean }
-* }
-* ```
-*/
-function createConfigHook() {
-	return function useTypedConfig(name, options) {
-		return useConfig(String(name), options);
-	};
-}
-/**
-* Hook for creating stateful resources with cleanup support.
-* Unlike useMemo, this guarantees cleanup when dependencies change or on unmount.
-*
-* @param factory - Function that creates the resource
-* @param cleanup - Function that cleans up the resource
-* @param deps - Dependencies array (resource is recreated when these change)
-*/
-function useStateful(factory, cleanup, deps) {
-	const valueRef = (0, react.useRef)(null);
-	const initializedRef = (0, react.useRef)(false);
-	if (!initializedRef.current) {
-		valueRef.current = factory();
-		initializedRef.current = true;
-	}
-	(0, react.useEffect)(() => {
-		if (valueRef.current === null) valueRef.current = factory();
-		return () => {
-			if (valueRef.current !== null) {
-				cleanup(valueRef.current);
-				valueRef.current = null;
-			}
-		};
-	}, deps);
-	return valueRef.current;
-}
-
 //#endregion
 //#region src/types.ts
 /**
 * Type guard to check if props contain a pre-created client.
 */
 function hasClient(props) {
-	return "client" in props && props.client !== void 0;
+	return "client" in props && !!props.client;
 }
 
+//#endregion
+//#region src/version.ts
+const VERSION = "0.9.2";
+const DEFAULT_AGENT = `replane-js-react/${VERSION}`;
+
 //#endregion
 //#region src/provider.tsx
 /**
 * Internal provider component for pre-created client.
 */
 function ReplaneProviderWithClient({ client, children }) {
-	const value = (0, react.useMemo)(() => ({ client }), [client]);
+	const value = (0, react.useMemo)(() => ({ replane: client }), [client]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneContext.Provider, {
 		value,
 		children
 	});
 }
 /**
-* Internal provider component for restoring client from snapshot.
-* Uses restoreReplaneClient which is synchronous.
+* Internal provider component for creating a Replane client asynchronously.
+* Creates a Replane client synchronously and connects in background.
 */
-function ReplaneProviderWithSnapshot({ options, snapshot, children }) {
-	const client = useStateful(() => (0, __replanejs_sdk.restoreReplaneClient)({
-		snapshot,
-		connection: {
-			baseUrl: options.baseUrl,
-			sdkKey: options.sdkKey,
-			fetchFn: options.fetchFn,
-			requestTimeoutMs: options.requestTimeoutMs,
-			retryDelayMs: options.retryDelayMs,
-			inactivityTimeoutMs: options.inactivityTimeoutMs,
-			logger: options.logger,
-			agent: options.agent ?? DEFAULT_AGENT
-		},
-		context: options.context
-	}), (c) => c.close(), [snapshot, options]);
-	const value = (0, react.useMemo)(() => ({ client }), [client]);
+function AsyncReplaneProvider({ children, connection,...options }) {
+	const replaneRef = (0, react.useRef)(void 0);
+	if (!replaneRef.current) replaneRef.current = new __replanejs_sdk.Replane(options);
+	const connectionJson = connection ? JSON.stringify(connection) : void 0;
+	(0, react.useEffect)(() => {
+		const parsedConnection = connectionJson ? JSON.parse(connectionJson) : void 0;
+		if (!parsedConnection) return;
+		replaneRef.current.connect(parsedConnection).catch((err) => {
+			(options.logger ?? console)?.error("Failed to connect Replane client", err);
+		});
+		return () => {
+			replaneRef.current.disconnect();
+		};
+	}, [connectionJson, options.logger]);
+	const value = (0, react.useMemo)(() => ({ replane: replaneRef.current }), []);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneContext.Provider, {
 		value,
 		children
@@ -274,11 +187,12 @@ function ReplaneProviderWithSnapshot({ options, snapshot, children }) {
 * Internal provider component for options-based client creation (non-suspense).
 * Throws errors during rendering so they can be caught by Error Boundaries.
 */
-function ReplaneProviderWithOptions({ options, children, loader }) {
-	const state = useReplaneClientInternal(options);
+function LoaderReplaneProvider({ children, loader, connection,...options }) {
+	if (!connection) throw new Error("Connection is required when using Loader");
+	const state = useReplaneClientInternal(options, connection);
 	if (state.status === "loading") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: loader ?? null });
 	if (state.status === "error") throw state.error;
-	const value = { client: state.client };
+	const value = { replane: state.client };
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneContext.Provider, {
 		value,
 		children
@@ -287,22 +201,24 @@ function ReplaneProviderWithOptions({ options, children, loader }) {
 /**
 * Internal provider component for options-based client creation with Suspense.
 */
-function ReplaneProviderWithSuspense({ options, children }) {
-	const client = useReplaneClientSuspense(options);
-	const value = (0, react.useMemo)(() => ({ client }), [client]);
+function SuspenseReplaneProvider({ connection, children,...options }) {
+	if (!connection) throw new Error("Connection is required when using Suspense");
+	const client = useReplaneClientSuspense(options, connection);
+	const value = (0, react.useMemo)(() => ({ replane: client }), [client]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneContext.Provider, {
 		value,
 		children
 	});
 }
 /**
-* Provider component that makes a ReplaneClient available to the component tree.
+* Provider component that makes a Replane client available to the component tree.
 *
-* Can be used in three ways:
+* Can be used in several ways:
 *
 * 1. With a pre-created client:
 * ```tsx
-* const client = await createReplaneClient({ ... });
+* const client = new Replane({ defaults: { ... } });
+* await client.connect({ baseUrl: '...', sdkKey: '...' });
 * <ReplaneProvider client={client}>
 *   <App />
 * </ReplaneProvider>
@@ -352,16 +268,111 @@ function ReplaneProviderWithSuspense({ options, children }) {
 * allowing them to be caught by React Error Boundaries.
 */
 function ReplaneProvider(props) {
+	const originalConnection = props.connection;
+	const connection = (0, react.useMemo)(() => originalConnection ? {
+		...originalConnection,
+		agent: originalConnection.agent ?? DEFAULT_AGENT
+	} : void 0, [originalConnection]);
 	if (hasClient(props)) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneProviderWithClient, { ...props });
-	if (props.snapshot) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneProviderWithSnapshot, {
+	if (props.snapshot || !connection || props.async) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AsyncReplaneProvider, { ...props });
+	if (props.suspense) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SuspenseReplaneProvider, {
 		...props,
-		snapshot: props.snapshot
+		connection
 	});
-	if (props.suspense) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneProviderWithSuspense, { ...props });
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ReplaneProviderWithOptions, { ...props });
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LoaderReplaneProvider, {
+		...props,
+		connection
+	});
+}
+
+//#endregion
+//#region src/hooks.ts
+function useReplane() {
+	const context = (0, react.useContext)(ReplaneContext);
+	if (!context) throw new Error("useReplane must be used within a ReplaneProvider");
+	return context.replane;
+}
+function useConfig(name, options) {
+	const client = useReplane();
+	const subscribe = (0, react.useCallback)((callback) => {
+		return client.subscribe(name, callback);
+	}, [client, name]);
+	const get = (0, react.useCallback)(() => {
+		return client.get(name, options);
+	}, [
+		client,
+		name,
+		options
+	]);
+	const value = (0, react.useSyncExternalStore)(subscribe, get, get);
+	return value;
+}
+/**
+* Creates a typed version of useReplane hook.
+*
+* @example
+* ```tsx
+* interface AppConfigs {
+*   theme: { darkMode: boolean };
+*   features: { beta: boolean };
+* }
+*
+* const useAppReplane = createReplaneHook<AppConfigs>();
+*
+* function MyComponent() {
+*   const replane = useAppReplane();
+*   // replane.get("theme") returns { darkMode: boolean }
+* }
+* ```
+*/
+function createReplaneHook() {
+	return function useTypedReplane() {
+		return useReplane();
+	};
+}
+/**
+* Creates a typed version of useConfig hook.
+*
+* @example
+* ```tsx
+* interface AppConfigs {
+*   theme: { darkMode: boolean };
+*   features: { beta: boolean };
+* }
+*
+* const useAppConfig = createConfigHook<AppConfigs>();
+*
+* function MyComponent() {
+*   const theme = useAppConfig("theme");
+*   // theme is typed as { darkMode: boolean }
+* }
+* ```
+*/
+function createConfigHook() {
+	return function useTypedConfig(name, options) {
+		return useConfig(String(name), options);
+	};
 }
 
 //#endregion
+Object.defineProperty(exports, 'Replane', {
+  enumerable: true,
+  get: function () {
+    return __replanejs_sdk.Replane;
+  }
+});
+Object.defineProperty(exports, 'ReplaneError', {
+  enumerable: true,
+  get: function () {
+    return __replanejs_sdk.ReplaneError;
+  }
+});
+Object.defineProperty(exports, 'ReplaneErrorCode', {
+  enumerable: true,
+  get: function () {
+    return __replanejs_sdk.ReplaneErrorCode;
+  }
+});
 exports.ReplaneProvider = ReplaneProvider;
 exports.clearSuspenseCache = clearSuspenseCache;
 exports.createConfigHook = createConfigHook;