@replanejs/sdk 0.9.2 → 1.0.0

package/README.md

@@ -1,18 +1,31 @@
-# Replane JavaScript SDK
+<h1 align="center">Replane JavaScript SDK</h1>
+<p align="center">Dynamic configuration for Node.js, Deno, Bun, and browsers.</p>
 
-[![npm](https://img.shields.io/npm/v/@replanejs/sdk)](https://www.npmjs.com/package/@replanejs/sdk)
-[![License](https://img.shields.io/github/license/replane-dev/replane-javascript)](https://github.com/replane-dev/replane-javascript/blob/main/LICENSE)
-[![Community](https://img.shields.io/badge/discussions-join-blue?logo=github)](https://github.com/orgs/replane-dev/discussions)
+<p align="center">
+  <a href="https://cloud.replane.dev"><img src="https://img.shields.io/badge/Try-Replane%20Cloud-blue" alt="Replane Cloud"></a>
+  <a href="https://www.npmjs.com/package/@replanejs/sdk"><img src="https://img.shields.io/npm/v/@replanejs/sdk" alt="npm"></a>
+  <a href="https://github.com/replane-dev/replane-javascript/blob/main/LICENSE"><img src="https://img.shields.io/github/license/replane-dev/replane-javascript" alt="License"></a>
+  <a href="https://github.com/orgs/replane-dev/discussions"><img src="https://img.shields.io/badge/discussions-join-blue?logo=github" alt="Community"></a>
+</p>
 
-Small TypeScript client for watching configuration values from a Replane API with realtime updates and context-based override evaluation.
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/replane-dev/replane/main/public/replane-window-screenshot-dark-v1.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/replane-dev/replane/main/public/replane-window-screenshot-light-with-border-v2.jpg">
+    <img alt="Replane Screenshot" src="https://raw.githubusercontent.com/replane-dev/replane/main/public/replane-window-screenshot-light-with-border-v2.jpg">
+</picture>
 
-Part of the Replane project: [replane-dev/replane](https://github.com/replane-dev/replane).
+[Replane](https://github.com/replane-dev/replane) is a dynamic configuration manager. Store feature flags, app settings, and operational config in one place—with version history, optional approvals, and realtime sync to your services. No redeploys needed.
 
-> Status: early. Minimal surface area on purpose. Expect small breaking tweaks until 0.1.x.
+## Why Dynamic Configuration?
 
-## Why it exists
+- **Feature flags** – toggle features, run A/B tests, roll out to user segments
+- **Operational tuning** – adjust limits, TTLs, and timeouts without redeploying
+- **Per-environment settings** – different values for production, staging, dev
+- **Incident response** – instantly revert to a known-good version
+- **Cross-service configuration** – share settings with realtime sync
+- **Non-engineer access** – safe editing with schema validation
 
-You need: given a token + config name + optional context -> watch the value with realtime updates. This package does only that:
+## Features
 
 - Works in ESM and CJS (dual build)
 - Zero runtime deps (uses native `fetch` — bring a polyfill if your runtime lacks it)
@@ -33,8 +46,6 @@ yarn add @replanejs/sdk
 
 ## Quick start
 
-> **Important:** Each SDK key is tied to a specific project. The client can only access configs from the project that the SDK key belongs to. If you need configs from multiple projects, create separate SDK keys and initialize separate clients—one per project.
-
 ```ts
 import { Replane } from "@replanejs/sdk";
 
@@ -53,14 +64,17 @@ interface PasswordRequirements {
 // Create the client with optional constructor options
 const replane = new Replane<Configs>({
   context: {
-    environment: "production",
+    // example context
+    userId: "user-123",
+    plan: "premium",
+    region: "us-east",
   },
 });
 
 // Connect to the server
 await replane.connect({
   sdkKey: process.env.REPLANE_SDK_KEY!,
-  baseUrl: "https://replane.my-hosting.com",
+  baseUrl: "https://cloud.replane.dev", // or your self-hosted URL
 });
 
 // Get a config value (knows about latest updates via SSE)
@@ -79,9 +93,8 @@ const { minLength } = passwordReqs; // TypeScript knows this is PasswordRequirem
 // With context for override evaluation
 const enabled = replane.get("billing-enabled", {
   context: {
-    userId: "user-123",
-    plan: "premium",
-    region: "us-east",
+    plan: "free",
+    deviceType: "mobile",
   },
 });
 
@@ -158,7 +171,7 @@ interface Configs {
 const replane = new Replane<Configs>();
 await replane.connect({
   sdkKey: "your-sdk-key",
-  baseUrl: "https://replane.my-host.com",
+  baseUrl: "https://cloud.replane.dev", // or your self-hosted URL
 });
 
 // Get value without context - TypeScript knows this is boolean
@@ -176,31 +189,14 @@ const maxConnections = replane.get("max-connections", { default: 10 });
 replane.disconnect();
 ```
 
-### `replane.subscribe(callback)` or `replane.subscribe(configName, callback)`
-
-Subscribe to config changes and receive real-time updates when configs are modified.
+### `replane.subscribe(configName, callback)`
 
-**Two overloads:**
-
-1. **Subscribe to all config changes:**
-
-   ```ts
-   const unsubscribe = replane.subscribe((config) => {
-     console.log(`Config ${config.name} changed to:`, config.value);
-   });
-   ```
-
-2. **Subscribe to a specific config:**
-   ```ts
-   const unsubscribe = replane.subscribe("billing-enabled", (config) => {
-     console.log(`billing-enabled changed to:`, config.value);
-   });
-   ```
+Subscribe to a specific config's changes and receive real-time updates when it is modified.
 
 Parameters:
 
-- `callback` (function) – Function called when any config changes. Receives an object with `{ name, value }`.
-- `configName` (K extends keyof T) – Optional. If provided, only changes to this specific config will trigger the callback.
+- `configName` (K extends keyof T) – The config to watch for changes.
+- `callback` (function) – Function called when the config changes. Receives an object with `{ name, value }`.
 
 Returns a function to unsubscribe from the config changes.
 
@@ -215,12 +211,7 @@ interface Configs {
 const replane = new Replane<Configs>();
 await replane.connect({
   sdkKey: "your-sdk-key",
-  baseUrl: "https://replane.my-host.com",
-});
-
-// Subscribe to all config changes
-const unsubscribeAll = replane.subscribe((config) => {
-  console.log(`Config ${config.name} updated:`, config.value);
+  baseUrl: "https://cloud.replane.dev", // or your self-hosted URL
 });
 
 // Subscribe to a specific config
@@ -230,7 +221,6 @@ const unsubscribeFeature = replane.subscribe("feature-flag", (config) => {
 });
 
 // Later: unsubscribe when done
-unsubscribeAll();
 unsubscribeFeature();
 
 // Clean up when done
@@ -448,30 +438,18 @@ await replane.connect({
   baseUrl: "https://replane.my-host.com",
 });
 
-// Subscribe to all config changes
-const unsubscribeAll = replane.subscribe((config) => {
-  console.log(`Config ${config.name} changed:`, config.value);
-
-  // React to specific config changes
-  if (config.name === "feature-flag") {
-    console.log("Feature flag updated:", config.value);
-  }
-});
-
-// Subscribe to a specific config only
+// Subscribe to specific configs
 const unsubscribeFeature = replane.subscribe("feature-flag", (config) => {
   console.log("Feature flag changed:", config.value);
   // config.value is automatically typed as boolean
 });
 
-// Subscribe to multiple specific configs
 const unsubscribeMaxUsers = replane.subscribe("max-users", (config) => {
   console.log("Max users changed:", config.value);
   // config.value is automatically typed as number
 });
 
 // Cleanup
-unsubscribeAll();
 unsubscribeFeature();
 unsubscribeMaxUsers();
 replane.disconnect();

package/dist/index.cjs

@@ -31,6 +31,20 @@ var ReplaneError = class extends Error {
 //#endregion
 //#region src/utils.ts
 /**
+* Generates a random UUID using the Web Crypto API.
+* Falls back to a simple implementation if crypto.randomUUID is not available.
+*
+* @returns A random UUID string
+*/
+function generateClientId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		const v = c === "x" ? r : r & 3 | 8;
+		return v.toString(16);
+	});
+}
+/**
 * Returns a promise that resolves after the specified delay
 *
 * @param ms - Delay in milliseconds
@@ -482,12 +496,21 @@ function castToContextType(expectedValue, contextValue) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.9.2";
+const VERSION = "1.0.0";
 const DEFAULT_AGENT = `replane-js-sdk/${VERSION}`;
 
 //#endregion
 //#region src/client.ts
 /**
+* The context key for the auto-generated client ID.
+* This key is automatically set by the SDK and can be used for segmentation.
+* User-provided values for this key take precedence over the auto-generated value.
+*/
+const REPLANE_CLIENT_ID_KEY = "replaneClientId";
+function asReplaneHandle(replane) {
+	return replane;
+}
+/**
 * The Replane client for managing dynamic configuration.
 *
 * @example
@@ -526,12 +549,31 @@ const DEFAULT_AGENT = `replane-js-sdk/${VERSION}`;
 * ```
 */
 var Replane = class {
+	constructor(options = {}) {
+		asReplaneHandle(this)._replane = new ReplaneImpl(options);
+	}
+	connect(options) {
+		return asReplaneHandle(this)._replane.connect(options);
+	}
+	disconnect() {
+		asReplaneHandle(this)._replane.disconnect();
+	}
+	get(configName, options) {
+		return asReplaneHandle(this)._replane.get(configName, options);
+	}
+	subscribe(configName, callback) {
+		return asReplaneHandle(this)._replane.subscribe(configName, callback);
+	}
+	getSnapshot() {
+		return asReplaneHandle(this)._replane.getSnapshot();
+	}
+};
+var ReplaneImpl = class {
 	configs;
 	context;
 	logger;
 	storage = null;
 	configSubscriptions = new Map();
-	clientSubscriptions = new Set();
 	/**
 	* Create a new Replane client.
 	*
@@ -542,7 +584,11 @@ var Replane = class {
 	*/
 	constructor(options = {}) {
 		this.logger = options.logger ?? console;
-		this.context = { ...options.context ?? {} };
+		const autoGeneratedContext = { [REPLANE_CLIENT_ID_KEY]: generateClientId() };
+		this.context = {
+			...autoGeneratedContext,
+			...options.context ?? {}
+		};
 		const initialConfigs = [];
 		if (options.snapshot) for (const config of options.snapshot.configs) initialConfigs.push({
 			name: config.name,
@@ -647,29 +693,28 @@ var Replane = class {
 			return config.value;
 		}
 	}
-	subscribe(callbackOrConfigName, callbackOrUndefined) {
-		let configName = void 0;
-		let callback;
-		if (typeof callbackOrConfigName === "function") callback = callbackOrConfigName;
-		else {
-			configName = callbackOrConfigName;
-			if (callbackOrUndefined === void 0) throw new Error("callback is required when config name is provided");
-			callback = callbackOrUndefined;
-		}
-		const originalCallback = callback;
-		callback = (...args) => {
-			originalCallback(...args);
+	/**
+	* Subscribe to a specific config's changes.
+	*
+	* @param configName - The config to watch
+	* @param callback - Function called when the config changes
+	* @returns Unsubscribe function
+	*
+	* @example
+	* ```typescript
+	* const unsubscribe = client.subscribe('myConfig', (change) => {
+	*   console.log(`myConfig changed to ${change.value}`);
+	* });
+	* ```
+	*/
+	subscribe(configName, callback) {
+		const wrappedCallback = (config) => {
+			callback(config);
 		};
-		if (configName === void 0) {
-			this.clientSubscriptions.add(callback);
-			return () => {
-				this.clientSubscriptions.delete(callback);
-			};
-		}
 		if (!this.configSubscriptions.has(configName)) this.configSubscriptions.set(configName, new Set());
-		this.configSubscriptions.get(configName).add(callback);
+		this.configSubscriptions.get(configName).add(wrappedCallback);
 		return () => {
-			this.configSubscriptions.get(configName)?.delete(callback);
+			this.configSubscriptions.get(configName)?.delete(wrappedCallback);
 			if (this.configSubscriptions.get(configName)?.size === 0) this.configSubscriptions.delete(configName);
 		};
 	}
@@ -724,8 +769,13 @@ var Replane = class {
 				})
 			});
 			for await (const event of replicationStream) {
-				const updatedConfigs = event.type === "config_change" ? [event.config] : event.configs;
-				this.processConfigUpdates(updatedConfigs);
+				if (event.type === "init") {
+					this.processConfigUpdates(event.configs);
+					this.logger.info(`Replane: initialized with ${event.configs.length} config(s)`);
+				} else {
+					this.processConfigUpdates([event.config]);
+					this.logger.info(`Replane: config "${event.config.name}" updated`);
+				}
 				clientReady.resolve();
 			}
 		} catch (error) {
@@ -745,7 +795,6 @@ var Replane = class {
 				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);
 		}
 	}
@@ -834,6 +883,250 @@ async function getReplaneSnapshot(options) {
 }
 
 //#endregion
+//#region src/in-memory.ts
+function asHandle(client) {
+	return client;
+}
+/**
+* An in-memory Replane client for testing.
+*
+* This client provides the same interface as `Replane` but stores
+* all configs in memory. It's useful for unit tests where you don't want
+* to connect to a real Replane server.
+*
+* @example
+* ```typescript
+* // Basic usage
+* const client = new InMemoryReplaneClient({
+*   defaults: { "feature-enabled": true, "rate-limit": 100 },
+* });
+* expect(client.get("feature-enabled")).toBe(true);
+*
+* // Update config at runtime
+* client.set("feature-enabled", false);
+* expect(client.get("feature-enabled")).toBe(false);
+*
+* // With overrides
+* client.setConfig("rate-limit", 100, {
+*   overrides: [{
+*     name: "premium-users",
+*     conditions: [{ operator: "equals", property: "plan", value: "premium" }],
+*     value: 1000,
+*   }],
+* });
+* expect(client.get("rate-limit")).toBe(100);
+* expect(client.get("rate-limit", { context: { plan: "premium" } })).toBe(1000);
+* ```
+*
+* @typeParam T - Type definition for config keys and values
+*/
+var InMemoryReplaneClient = class {
+	constructor(options = {}) {
+		asHandle(this)._impl = new InMemoryReplaneClientImpl(options);
+	}
+	/**
+	* 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
+	*/
+	get(configName, options) {
+		return asHandle(this)._impl.get(configName, options);
+	}
+	/**
+	* Subscribe to a specific config's changes.
+	*
+	* @param configName - The config to watch
+	* @param callback - Function called when the config changes
+	* @returns Unsubscribe function
+	*/
+	subscribe(configName, callback) {
+		return asHandle(this)._impl.subscribe(configName, callback);
+	}
+	/**
+	* Get a serializable snapshot of the current client state.
+	*
+	* @returns Snapshot object that can be serialized to JSON
+	*/
+	getSnapshot() {
+		return asHandle(this)._impl.getSnapshot();
+	}
+	/**
+	* Set a config value (simple form without overrides).
+	*
+	* @param name - Config name
+	* @param value - Config value
+	*
+	* @example
+	* ```typescript
+	* client.set("feature-enabled", true);
+	* client.set("rate-limit", 500);
+	* ```
+	*/
+	set(name, value) {
+		asHandle(this)._impl.set(name, value);
+	}
+	/**
+	* Set a config with optional overrides.
+	*
+	* @param name - Config name
+	* @param value - Base config value
+	* @param options - Optional settings including overrides
+	*
+	* @example
+	* ```typescript
+	* client.setConfig("rate-limit", 100, {
+	*   overrides: [{
+	*     name: "premium-users",
+	*     conditions: [
+	*       { operator: "in", property: "plan", value: ["pro", "enterprise"] }
+	*     ],
+	*     value: 1000,
+	*   }],
+	* });
+	* ```
+	*/
+	setConfig(name, value, options) {
+		asHandle(this)._impl.setConfig(name, value, options);
+	}
+	/**
+	* Delete a config.
+	*
+	* @param name - Config name to delete
+	* @returns True if config was deleted, false if it didn't exist
+	*/
+	delete(name) {
+		return asHandle(this)._impl.delete(name);
+	}
+	/**
+	* Clear all configs.
+	*/
+	clear() {
+		asHandle(this)._impl.clear();
+	}
+	/**
+	* Check if a config exists.
+	*
+	* @param name - Config name to check
+	* @returns True if config exists
+	*/
+	has(name) {
+		return asHandle(this)._impl.has(name);
+	}
+	/**
+	* Get all config names.
+	*
+	* @returns Array of config names
+	*/
+	keys() {
+		return asHandle(this)._impl.keys();
+	}
+};
+var InMemoryReplaneClientImpl = class {
+	configs;
+	context;
+	logger;
+	configSubscriptions = new Map();
+	constructor(options = {}) {
+		this.logger = options.logger ?? console;
+		this.context = options.context ?? {};
+		const initialConfigs = [];
+		if (options.defaults) {
+			for (const [name, value] of Object.entries(options.defaults)) if (value !== void 0) initialConfigs.push({
+				name,
+				value,
+				overrides: []
+			});
+		}
+		this.configs = new Map(initialConfigs.map((config) => [config.name, config]));
+	}
+	get(configName, options = {}) {
+		const config = this.configs.get(String(configName));
+		if (config === void 0) {
+			if ("default" in options) return options.default;
+			throw new ReplaneError({
+				message: `Config not found: ${String(configName)}`,
+				code: ReplaneErrorCode.NotFound
+			});
+		}
+		try {
+			return evaluateOverrides(config.value, config.overrides, {
+				...this.context,
+				...options?.context ?? {}
+			}, this.logger);
+		} catch (error) {
+			this.logger.error(`Replane: error evaluating overrides for config ${String(configName)}:`, error);
+			return config.value;
+		}
+	}
+	subscribe(configName, callback) {
+		const wrappedCallback = (config) => {
+			callback(config);
+		};
+		if (!this.configSubscriptions.has(configName)) this.configSubscriptions.set(configName, new Set());
+		this.configSubscriptions.get(configName).add(wrappedCallback);
+		return () => {
+			this.configSubscriptions.get(configName)?.delete(wrappedCallback);
+			if (this.configSubscriptions.get(configName)?.size === 0) this.configSubscriptions.delete(configName);
+		};
+	}
+	getSnapshot() {
+		return { configs: [...this.configs.values()].map((config) => ({
+			name: config.name,
+			value: config.value,
+			overrides: config.overrides.map((override) => ({
+				name: override.name,
+				conditions: override.conditions,
+				value: override.value
+			}))
+		})) };
+	}
+	set(name, value) {
+		this.setConfig(name, value);
+	}
+	setConfig(name, value, options) {
+		const overrides = options?.overrides ?? [];
+		const config = {
+			name: String(name),
+			value,
+			overrides
+		};
+		this.configs.set(String(name), config);
+		this.notifySubscribers(name, value);
+	}
+	delete(name) {
+		const existed = this.configs.has(String(name));
+		this.configs.delete(String(name));
+		return existed;
+	}
+	clear() {
+		this.configs.clear();
+	}
+	has(name) {
+		return this.configs.has(String(name));
+	}
+	keys() {
+		return [...this.configs.keys()];
+	}
+	notifySubscribers(name, value) {
+		const change = {
+			name,
+			value
+		};
+		for (const callback of this.configSubscriptions.get(name) ?? []) try {
+			callback(change);
+		} catch (error) {
+			this.logger.error(`Replane: error in subscription callback for ${String(name)}:`, error);
+		}
+	}
+};
+
+//#endregion
+exports.InMemoryReplaneClient = InMemoryReplaneClient;
 exports.Replane = Replane;
 exports.ReplaneError = ReplaneError;
 exports.ReplaneErrorCode = ReplaneErrorCode;