@replanejs/sdk 0.8.20 → 0.9.2

package/dist/index.cjs

@@ -230,13 +230,13 @@ const SUPPORTED_REPLICATION_STREAM_RECORD_TYPES = Object.keys({
 * and streams config updates via SSE.
 */
 var ReplaneRemoteStorage = class {
-	closeController = new AbortController();
+	disconnectController = new AbortController();
 	/**
 	* Start a replication stream that yields config updates.
 	* This method never throws - it retries on failure with exponential backoff.
 	*/
 	async *startReplicationStream(options) {
-		const { signal, cleanUpSignals } = combineAbortSignals([this.closeController.signal, options.signal]);
+		const { signal, cleanUpSignals } = combineAbortSignals([this.disconnectController.signal, options.signal]);
 		try {
 			let failedAttempts = 0;
 			while (!signal.aborted) try {
@@ -252,7 +252,6 @@ var ReplaneRemoteStorage = class {
 				const retryDelayMs = Math.min(options.retryDelayMs * 2 ** (failedAttempts - 1), 1e4);
 				if (!signal.aborted) {
 					options.logger.error(`Failed to fetch project events, retrying in ${retryDelayMs}ms...`, error);
-					options.onConnectionError?.(error);
 					await retryDelay(retryDelayMs);
 				}
 			}
@@ -289,7 +288,6 @@ var ReplaneRemoteStorage = class {
 				onConnect: () => {
 					resetInactivityTimer();
 					options.onConnect?.();
-					options.onConnected?.();
 				}
 			});
 			for await (const sseEvent of rawEvents) {
@@ -304,10 +302,11 @@ var ReplaneRemoteStorage = class {
 		}
 	}
 	/**
-	* Close the storage and abort any active connections
+	* Disconnect the storage and abort any active connections
 	*/
-	close() {
-		this.closeController.abort();
+	disconnect() {
+		this.disconnectController.abort();
+		this.disconnectController = new AbortController();
 	}
 	getAuthHeader(options) {
 		return `Bearer ${options.sdkKey}`;
@@ -483,66 +482,156 @@ function castToContextType(expectedValue, contextValue) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.8.20";
+const VERSION = "0.9.2";
 const DEFAULT_AGENT = `replane-js-sdk/${VERSION}`;
 
 //#endregion
 //#region src/client.ts
 /**
-* Creates the core client logic shared between createReplaneClient and restoreReplaneClient
+* The Replane client for managing dynamic configuration.
+*
+* @example
+* ```typescript
+* // Create client with defaults
+* const client = new Replane({
+*   defaults: { myConfig: 'defaultValue' }
+* });
+*
+* // Use immediately (returns defaults)
+* const value = client.get('myConfig');
+*
+* // Connect for real-time updates
+* await client.connect({
+*   baseUrl: 'https://app.replane.dev',
+*   sdkKey: 'your-sdk-key'
+* });
+* ```
+*
+* @example
+* ```typescript
+* // SSR/Hydration: Create from snapshot
+* const client = new Replane({
+*   snapshot: serverSnapshot
+* });
+* await client.connect({ baseUrl, sdkKey });
+* ```
+*
+* @example
+* ```typescript
+* // In-memory mode (no connection)
+* const client = new Replane({
+*   defaults: { feature: true, limit: 100 }
+* });
+* // Don't call connect() - works entirely in-memory
+* ```
 */
-function createClientCore(options) {
-	const { initialConfigs, context, logger, storage, streamOptions, requiredConfigs } = options;
-	const configs = new Map(initialConfigs.map((config) => [config.name, config]));
-	const clientReady = new Deferred();
-	const configSubscriptions = new Map();
-	const clientSubscriptions = new Set();
-	function processConfigUpdates(updatedConfigs) {
-		for (const config of updatedConfigs) {
-			configs.set(config.name, {
-				name: config.name,
-				overrides: config.overrides,
-				value: config.value
-			});
-			for (const callback of clientSubscriptions) callback({
-				name: config.name,
-				value: config.value
-			});
-			for (const callback of configSubscriptions.get(config.name) ?? []) callback({
-				name: config.name,
-				value: config.value
+var Replane = class {
+	configs;
+	context;
+	logger;
+	storage = null;
+	configSubscriptions = new Map();
+	clientSubscriptions = new Set();
+	/**
+	* Create a new Replane client.
+	*
+	* The client is usable immediately after construction with defaults or snapshot data.
+	* Call `connect()` to establish a real-time connection for live updates.
+	*
+	* @param options - Configuration options
+	*/
+	constructor(options = {}) {
+		this.logger = options.logger ?? console;
+		this.context = { ...options.context ?? {} };
+		const initialConfigs = [];
+		if (options.snapshot) for (const config of options.snapshot.configs) initialConfigs.push({
+			name: config.name,
+			value: config.value,
+			overrides: config.overrides
+		});
+		if (options.defaults) {
+			const snapshotNames = new Set(initialConfigs.map((c) => c.name));
+			for (const [name, value] of Object.entries(options.defaults)) if (value !== void 0 && !snapshotNames.has(name)) initialConfigs.push({
+				name,
+				value,
+				overrides: []
 			});
 		}
+		this.configs = new Map(initialConfigs.map((config) => [config.name, config]));
 	}
-	async function startStreaming() {
-		if (!storage || !streamOptions) return;
-		try {
-			const replicationStream = storage.startReplicationStream({
-				...streamOptions,
-				getBody: () => ({
-					currentConfigs: [...configs.values()].map((config) => ({
-						name: config.name,
-						overrides: config.overrides,
-						value: config.value
-					})),
-					requiredConfigs
-				})
-			});
-			for await (const event of replicationStream) {
-				const updatedConfigs = event.type === "config_change" ? [event.config] : event.configs;
-				processConfigUpdates(updatedConfigs);
-				clientReady.resolve();
-			}
-		} catch (error) {
-			logger.error("Replane: error in SSE connection:", error);
-			clientReady.reject(error);
-			throw error;
+	/**
+	* Connect to the Replane server for real-time config updates.
+	*
+	* This method establishes an SSE connection to receive live config updates.
+	* If already connected, it will disconnect first and reconnect with new options.
+	*
+	* @param options - Connection options including baseUrl and sdkKey
+	* @returns Promise that resolves when the initial connection is established
+	* @throws {ReplaneError} If connection times out and no defaults are available
+	*
+	* @example
+	* ```typescript
+	* await client.connect({
+	*   baseUrl: 'https://app.replane.dev',
+	*   sdkKey: 'rp_xxx'
+	* });
+	* ```
+	*/
+	async connect(options) {
+		this.disconnect();
+		const finalOptions = this.toFinalOptions(options);
+		this.storage = new ReplaneRemoteStorage();
+		const clientReady = new Deferred();
+		this.startStreaming(finalOptions, clientReady);
+		const timeoutId = setTimeout(() => {
+			this.disconnect();
+			clientReady.reject(new ReplaneError({
+				message: "Replane client connection timed out",
+				code: ReplaneErrorCode.Timeout
+			}));
+		}, finalOptions.connectTimeoutMs);
+		clientReady.promise.finally(() => clearTimeout(timeoutId));
+		await clientReady.promise;
+	}
+	/**
+	* Disconnect from the Replane server.
+	*
+	* Stops the SSE connection and cleans up resources.
+	* The client remains usable with cached config values.
+	* Can call `connect()` again to reconnect.
+	*/
+	disconnect() {
+		if (this.storage) {
+			this.storage.disconnect();
+			this.storage = null;
 		}
 	}
-	function get(configName, getConfigOptions = {}) {
-		const config = configs.get(String(configName));
+	/**
+	* Get a config value by name.
+	*
+	* Evaluates any overrides based on the client context and per-call context.
+	*
+	* @param configName - The name of the config to retrieve
+	* @param options - Optional settings for this call
+	* @returns The config value
+	* @throws {ReplaneError} If config not found and no default provided
+	*
+	* @example
+	* ```typescript
+	* // Simple get
+	* const value = client.get('myConfig');
+	*
+	* // With default fallback
+	* const value = client.get('myConfig', { default: 'fallback' });
+	*
+	* // With per-call context for override evaluation
+	* const value = client.get('myConfig', { context: { userId: '123' } });
+	* ```
+	*/
+	get(configName, options = {}) {
+		const config = this.configs.get(String(configName));
 		if (config === void 0) {
-			if ("default" in getConfigOptions) return getConfigOptions.default;
+			if ("default" in options) return options.default;
 			throw new ReplaneError({
 				message: `Config not found: ${String(configName)}`,
 				code: ReplaneErrorCode.NotFound
@@ -550,15 +639,15 @@ function createClientCore(options) {
 		}
 		try {
 			return evaluateOverrides(config.value, config.overrides, {
-				...context,
-				...getConfigOptions?.context ?? {}
-			}, logger);
+				...this.context,
+				...options?.context ?? {}
+			}, this.logger);
 		} catch (error) {
-			logger.error(`Replane: error evaluating overrides for config ${String(configName)}:`, error);
+			this.logger.error(`Replane: error evaluating overrides for config ${String(configName)}:`, error);
 			return config.value;
 		}
 	}
-	const subscribe = (callbackOrConfigName, callbackOrUndefined) => {
+	subscribe(callbackOrConfigName, callbackOrUndefined) {
 		let configName = void 0;
 		let callback;
 		if (typeof callbackOrConfigName === "function") callback = callbackOrConfigName;
@@ -572,20 +661,38 @@ function createClientCore(options) {
 			originalCallback(...args);
 		};
 		if (configName === void 0) {
-			clientSubscriptions.add(callback);
+			this.clientSubscriptions.add(callback);
 			return () => {
-				clientSubscriptions.delete(callback);
+				this.clientSubscriptions.delete(callback);
 			};
 		}
-		if (!configSubscriptions.has(configName)) configSubscriptions.set(configName, new Set());
-		configSubscriptions.get(configName).add(callback);
+		if (!this.configSubscriptions.has(configName)) this.configSubscriptions.set(configName, new Set());
+		this.configSubscriptions.get(configName).add(callback);
 		return () => {
-			configSubscriptions.get(configName)?.delete(callback);
-			if (configSubscriptions.get(configName)?.size === 0) configSubscriptions.delete(configName);
+			this.configSubscriptions.get(configName)?.delete(callback);
+			if (this.configSubscriptions.get(configName)?.size === 0) this.configSubscriptions.delete(configName);
 		};
-	};
-	const getSnapshot = () => ({
-		configs: [...configs.values()].map((config) => ({
+	}
+	/**
+	* Get a serializable snapshot of the current client state.
+	*
+	* Useful for SSR/hydration scenarios where you want to pass
+	* configs from server to client.
+	*
+	* @returns Snapshot object that can be serialized to JSON
+	*
+	* @example
+	* ```typescript
+	* // On server
+	* const snapshot = client.getSnapshot();
+	* const json = JSON.stringify(snapshot);
+	*
+	* // On client
+	* const client = new Replane({ snapshot: JSON.parse(json) });
+	* ```
+	*/
+	getSnapshot() {
+		return { configs: [...this.configs.values()].map((config) => ({
 			name: config.name,
 			value: config.value,
 			overrides: config.overrides.map((override) => ({
@@ -593,196 +700,83 @@ function createClientCore(options) {
 				conditions: override.conditions,
 				value: override.value
 			}))
-		})),
-		context
-	});
-	const close = () => storage?.close();
-	const client = {
-		get,
-		subscribe,
-		getSnapshot,
-		close
-	};
-	return {
-		client,
-		configs,
-		startStreaming,
-		clientReady
-	};
-}
-/**
-* Create a Replane client bound to an SDK key.
-*
-* @example
-* ```typescript
-* const client = await createReplaneClient({
-*   sdkKey: 'your-sdk-key',
-*   baseUrl: 'https://app.replane.dev'
-* });
-* const value = client.get('my-config');
-* ```
-*/
-async function createReplaneClient(sdkOptions) {
-	const storage = new ReplaneRemoteStorage();
-	return await createReplaneClientInternal(toFinalOptions(sdkOptions), storage);
-}
-/**
-* Create a Replane client that uses in-memory storage.
-* Useful for testing or when you have static config values.
-*
-* @example
-* ```typescript
-* const client = createInMemoryReplaneClient({ 'my-config': 123 });
-* const value = client.get('my-config'); // 123
-* ```
-*/
-function createInMemoryReplaneClient(initialData) {
-	return {
-		get: (configName, options) => {
-			const config = initialData[configName];
-			if (config === void 0) {
-				if (options && "default" in options) return options.default;
-				throw new ReplaneError({
-					message: `Config not found: ${String(configName)}`,
-					code: ReplaneErrorCode.NotFound
-				});
+		})) };
+	}
+	/**
+	* Check if the client is currently connected.
+	*/
+	get isConnected() {
+		return this.storage !== null;
+	}
+	async startStreaming(options, clientReady) {
+		if (!this.storage) return;
+		try {
+			const replicationStream = this.storage.startReplicationStream({
+				...options,
+				logger: this.logger,
+				getBody: () => ({
+					currentConfigs: [...this.configs.values()].map((config) => ({
+						name: config.name,
+						overrides: config.overrides,
+						value: config.value
+					})),
+					requiredConfigs: []
+				})
+			});
+			for await (const event of replicationStream) {
+				const updatedConfigs = event.type === "config_change" ? [event.config] : event.configs;
+				this.processConfigUpdates(updatedConfigs);
+				clientReady.resolve();
 			}
-			return config;
-		},
-		subscribe: () => {
-			return () => {};
-		},
-		getSnapshot: () => ({ configs: Object.entries(initialData).map(([name, value]) => ({
-			name,
-			value,
-			overrides: []
-		})) }),
-		close: () => {}
-	};
-}
-/**
-* Restore a Replane client from a snapshot.
-* This is useful for SSR/hydration scenarios where the server has already fetched configs.
-*
-* @example
-* ```typescript
-* // On the server:
-* const serverClient = await createReplaneClient({ ... });
-* const snapshot = serverClient.getSnapshot();
-* // Pass snapshot to client via props/serialization
-*
-* // On the client:
-* const client = restoreReplaneClient({
-*   snapshot,
-*   connection: { sdkKey, baseUrl }
-* });
-* const value = client.get('my-config');
-* ```
-*/
-function restoreReplaneClient(options) {
-	const { snapshot, connection } = options;
-	const context = options.context ?? snapshot.context ?? {};
-	const logger = connection?.logger ?? console;
-	const initialConfigs = snapshot.configs.map((config) => ({
-		name: config.name,
-		value: config.value,
-		overrides: config.overrides
-	}));
-	let storage = null;
-	let streamOptions = null;
-	if (connection) {
-		storage = new ReplaneRemoteStorage();
-		streamOptions = toFinalOptions(connection);
-	}
-	const { client, startStreaming } = createClientCore({
-		initialConfigs,
-		context,
-		logger,
-		storage,
-		streamOptions,
-		requiredConfigs: []
-	});
-	if (storage && streamOptions) startStreaming().catch((error) => {
-		logger.error("Replane: error in restored client SSE connection:", error);
-	});
-	return client;
-}
-/**
-* Internal function to create a Replane client with the given options and storage
-*/
-async function createReplaneClientInternal(sdkOptions, storage) {
-	const { client, configs, startStreaming, clientReady } = createClientCore({
-		initialConfigs: sdkOptions.defaults,
-		context: sdkOptions.context,
-		logger: sdkOptions.logger,
-		storage,
-		streamOptions: sdkOptions,
-		requiredConfigs: sdkOptions.requiredConfigs
-	});
-	startStreaming().catch((error) => {
-		sdkOptions.logger.error("Replane: error initializing client:", error);
-	});
-	const initializationTimeoutId = setTimeout(() => {
-		if (sdkOptions.defaults.length === 0) {
-			client.close();
-			clientReady.reject(new ReplaneError({
-				message: "Replane client initialization timed out",
-				code: ReplaneErrorCode.Timeout
-			}));
-			return;
+		} catch (error) {
+			this.logger.error("Replane: error in SSE connection:", error);
+			clientReady.reject(error);
+			throw error;
 		}
-		const missingRequiredConfigs = [];
-		for (const requiredConfigName of sdkOptions.requiredConfigs) if (!configs.has(requiredConfigName)) missingRequiredConfigs.push(requiredConfigName);
-		if (missingRequiredConfigs.length > 0) {
-			client.close();
-			clientReady.reject(new ReplaneError({
-				message: `Required configs are missing: ${missingRequiredConfigs.join(", ")}`,
-				code: ReplaneErrorCode.NotFound
-			}));
-			return;
+	}
+	processConfigUpdates(updatedConfigs) {
+		for (const config of updatedConfigs) {
+			this.configs.set(config.name, {
+				name: config.name,
+				overrides: config.overrides,
+				value: config.value
+			});
+			const change = {
+				name: config.name,
+				value: config.value
+			};
+			for (const callback of this.clientSubscriptions) callback(change);
+			for (const callback of this.configSubscriptions.get(config.name) ?? []) callback(change);
 		}
-		clientReady.resolve();
-	}, sdkOptions.initializationTimeoutMs);
-	clientReady.promise.then(() => clearTimeout(initializationTimeoutId));
-	await clientReady.promise;
-	return client;
-}
-/**
-* Convert user options to final options with defaults
-*/
-function toFinalOptions(options) {
-	return {
-		sdkKey: options.sdkKey ?? "",
-		baseUrl: (options.baseUrl ?? "").replace(/\/+$/, ""),
-		fetchFn: options.fetchFn ?? globalThis.fetch.bind(globalThis),
-		requestTimeoutMs: options.requestTimeoutMs ?? 2e3,
-		initializationTimeoutMs: options.initializationTimeoutMs ?? 5e3,
-		inactivityTimeoutMs: options.inactivityTimeoutMs ?? 3e4,
-		logger: options.logger ?? console,
-		retryDelayMs: options.retryDelayMs ?? 200,
-		context: { ...options.context ?? {} },
-		requiredConfigs: Array.isArray(options.required) ? options.required.map((name) => String(name)) : Object.entries(options.required ?? {}).filter(([_, value]) => value !== void 0).map(([name]) => name),
-		defaults: Object.entries(options.defaults ?? {}).filter(([_, value]) => value !== void 0).map(([name, value]) => ({
-			name,
-			overrides: [],
-			version: -1,
-			value
-		})),
-		agent: options.agent ?? DEFAULT_AGENT,
-		onConnectionError: options.onConnectionError,
-		onConnected: options.onConnected
-	};
-}
+	}
+	toFinalOptions(options) {
+		return {
+			sdkKey: options.sdkKey,
+			baseUrl: (options.baseUrl ?? "").replace(/\/+$/, ""),
+			fetchFn: options.fetchFn ?? globalThis.fetch.bind(globalThis),
+			requestTimeoutMs: options.requestTimeoutMs ?? 2e3,
+			connectTimeoutMs: options.connectTimeoutMs ?? 5e3,
+			inactivityTimeoutMs: options.inactivityTimeoutMs ?? 3e4,
+			retryDelayMs: options.retryDelayMs ?? 200,
+			agent: options.agent ?? DEFAULT_AGENT
+		};
+	}
+};
 
 //#endregion
 //#region src/snapshot.ts
 const clientCache = new Map();
+const pendingConnections = new Map();
 function getCacheKey(options) {
 	return `${options.baseUrl}:${options.sdkKey}`;
 }
 function setupCleanupTimeout(cacheKey, keepAliveMs) {
 	return setTimeout(() => {
-		clientCache.delete(cacheKey);
+		const cached = clientCache.get(cacheKey);
+		if (cached) {
+			cached.client.disconnect();
+			clientCache.delete(cacheKey);
+		}
 	}, keepAliveMs);
 }
 /**
@@ -793,35 +787,54 @@ function setupCleanupTimeout(cacheKey, keepAliveMs) {
 * @example
 * ```ts
 * const snapshot = await getReplaneSnapshot({
-*   baseUrl: process.env.REPLANE_BASE_URL!,
-*   sdkKey: process.env.REPLANE_SDK_KEY!,
+*   connection: {
+*     baseUrl: process.env.REPLANE_BASE_URL!,
+*     sdkKey: process.env.REPLANE_SDK_KEY!,
+*   },
 * });
 * ```
 */
 async function getReplaneSnapshot(options) {
-	const { keepAliveMs = 6e4,...clientOptions } = options;
-	const cacheKey = getCacheKey(clientOptions);
+	const { keepAliveMs = 6e4, logger, context, defaults, connection: connectionOptions } = options;
+	if (!connectionOptions) return { configs: [...Object.entries(defaults ?? {}).map(([name, value]) => ({
+		name,
+		value,
+		overrides: []
+	}))] };
+	const cacheKey = getCacheKey(connectionOptions);
 	const cached = clientCache.get(cacheKey);
 	if (cached) {
 		clearTimeout(cached.timeoutId);
 		cached.timeoutId = setupCleanupTimeout(cacheKey, keepAliveMs);
-		const client$1 = await cached.clientPromise;
+		return cached.client.getSnapshot();
+	}
+	const pending = pendingConnections.get(cacheKey);
+	if (pending) {
+		const client$1 = await pending.promise;
 		return client$1.getSnapshot();
 	}
-	const clientPromise = createReplaneClient(clientOptions);
-	const entry = {
-		clientPromise,
-		timeoutId: setupCleanupTimeout(cacheKey, keepAliveMs)
-	};
-	clientCache.set(cacheKey, entry);
-	const client = await clientPromise;
-	return client.getSnapshot();
+	const client = new Replane({
+		logger,
+		context,
+		defaults
+	});
+	const connectionPromise = client.connect(connectionOptions).then(() => client);
+	pendingConnections.set(cacheKey, { promise: connectionPromise });
+	try {
+		await connectionPromise;
+		const entry = {
+			client,
+			timeoutId: setupCleanupTimeout(cacheKey, keepAliveMs)
+		};
+		clientCache.set(cacheKey, entry);
+		return client.getSnapshot();
+	} finally {
+		pendingConnections.delete(cacheKey);
+	}
 }
 
 //#endregion
+exports.Replane = Replane;
 exports.ReplaneError = ReplaneError;
 exports.ReplaneErrorCode = ReplaneErrorCode;
-exports.createInMemoryReplaneClient = createInMemoryReplaneClient;
-exports.createReplaneClient = createReplaneClient;
-exports.getReplaneSnapshot = getReplaneSnapshot;
-exports.restoreReplaneClient = restoreReplaneClient;
+exports.getReplaneSnapshot = getReplaneSnapshot;