@replanejs/sdk 0.5.6

package/dist/index.js

@@ -0,0 +1,477 @@
+//#region src/index.ts
+const SUPPORTED_REPLICATION_STREAM_RECORD_TYPES = Object.keys({
+	config_change: true,
+	init: true
+});
+/**
+* FNV-1a 32-bit hash function
+*/
+function fnv1a32(input) {
+	const encoder = new TextEncoder();
+	const bytes = encoder.encode(input);
+	let hash = 2166136261;
+	for (let i = 0; i < bytes.length; i++) {
+		hash ^= bytes[i];
+		hash = Math.imul(hash, 16777619) >>> 0;
+	}
+	return hash >>> 0;
+}
+/**
+* Convert FNV-1a hash to [0, 1) for bucketing.
+*/
+function fnv1a32ToUnit(input) {
+	const h = fnv1a32(input);
+	return h / 2 ** 32;
+}
+/**
+* Evaluate config overrides based on context (client-side implementation)
+* This is a simplified version without debug info
+*/
+function evaluateOverrides(baseValue, overrides, context, logger) {
+	for (const override of overrides) {
+		let overrideResult = "matched";
+		const results = override.conditions.map((c) => evaluateCondition(c, context, logger));
+		if (results.some((r) => r === "not_matched")) overrideResult = "not_matched";
+		else if (results.some((r) => r === "unknown")) overrideResult = "unknown";
+		if (overrideResult === "matched") return override.value;
+	}
+	return baseValue;
+}
+/**
+* Evaluate a single condition
+*/
+function evaluateCondition(condition, context, logger) {
+	const operator = condition.operator;
+	if (operator === "and") {
+		const results = condition.conditions.map((c) => evaluateCondition(c, context, logger));
+		if (results.some((r) => r === "not_matched")) return "not_matched";
+		if (results.some((r) => r === "unknown")) return "unknown";
+		return "matched";
+	}
+	if (operator === "or") {
+		const results = condition.conditions.map((c) => evaluateCondition(c, context, logger));
+		if (results.some((r) => r === "matched")) return "matched";
+		if (results.some((r) => r === "unknown")) return "unknown";
+		return "not_matched";
+	}
+	if (operator === "not") {
+		const result = evaluateCondition(condition.condition, context, logger);
+		if (result === "matched") return "not_matched";
+		if (result === "not_matched") return "matched";
+		return "unknown";
+	}
+	if (operator === "segmentation") {
+		const contextValue$1 = context[condition.property];
+		if (contextValue$1 === void 0 || contextValue$1 === null) return "unknown";
+		const hashInput = String(contextValue$1) + condition.seed;
+		const unitValue = fnv1a32ToUnit(hashInput);
+		return unitValue >= condition.fromPercentage / 100 && unitValue < condition.toPercentage / 100 ? "matched" : "not_matched";
+	}
+	const property = condition.property;
+	const contextValue = context[property];
+	const expectedValue = condition.value;
+	if (contextValue === void 0) return "unknown";
+	const castedValue = castToContextType(expectedValue, contextValue);
+	switch (operator) {
+		case "equals": return contextValue === castedValue ? "matched" : "not_matched";
+		case "in":
+			if (!Array.isArray(castedValue)) return "unknown";
+			return castedValue.includes(contextValue) ? "matched" : "not_matched";
+		case "not_in":
+			if (!Array.isArray(castedValue)) return "unknown";
+			return !castedValue.includes(contextValue) ? "matched" : "not_matched";
+		case "less_than":
+			if (typeof contextValue === "number" && typeof castedValue === "number") return contextValue < castedValue ? "matched" : "not_matched";
+			if (typeof contextValue === "string" && typeof castedValue === "string") return contextValue < castedValue ? "matched" : "not_matched";
+			return "not_matched";
+		case "less_than_or_equal":
+			if (typeof contextValue === "number" && typeof castedValue === "number") return contextValue <= castedValue ? "matched" : "not_matched";
+			if (typeof contextValue === "string" && typeof castedValue === "string") return contextValue <= castedValue ? "matched" : "not_matched";
+			return "not_matched";
+		case "greater_than":
+			if (typeof contextValue === "number" && typeof castedValue === "number") return contextValue > castedValue ? "matched" : "not_matched";
+			if (typeof contextValue === "string" && typeof castedValue === "string") return contextValue > castedValue ? "matched" : "not_matched";
+			return "not_matched";
+		case "greater_than_or_equal":
+			if (typeof contextValue === "number" && typeof castedValue === "number") return contextValue >= castedValue ? "matched" : "not_matched";
+			if (typeof contextValue === "string" && typeof castedValue === "string") return contextValue >= castedValue ? "matched" : "not_matched";
+			return "not_matched";
+		default:
+			warnNever(operator, logger, `Unexpected operator: ${operator}`);
+			return "unknown";
+	}
+}
+function warnNever(value, logger, message) {
+	logger.warn(message, { value });
+}
+/**
+* Cast expected value to match context value type
+*/
+function castToContextType(expectedValue, contextValue) {
+	if (typeof contextValue === "number") {
+		if (typeof expectedValue === "string") {
+			const num = Number(expectedValue);
+			return isNaN(num) ? expectedValue : num;
+		}
+		return expectedValue;
+	}
+	if (typeof contextValue === "boolean") {
+		if (typeof expectedValue === "string") {
+			if (expectedValue === "true") return true;
+			if (expectedValue === "false") return false;
+		}
+		if (typeof expectedValue === "number") return expectedValue !== 0;
+		return expectedValue;
+	}
+	if (typeof contextValue === "string") {
+		if (typeof expectedValue === "number" || typeof expectedValue === "boolean") return String(expectedValue);
+		return expectedValue;
+	}
+	return expectedValue;
+}
+async function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryDelay(averageDelay) {
+	const jitter = averageDelay / 5;
+	const delayMs = averageDelay + Math.random() * jitter - jitter / 2;
+	await delay(delayMs);
+}
+var ReplaneRemoteStorage = class {
+	closeController = new AbortController();
+	async *startReplicationStream(options) {
+		const { signal, cleanUpSignals } = combineAbortSignals([this.closeController.signal, options.signal]);
+		try {
+			let failedAttempts = 0;
+			while (!signal.aborted) try {
+				for await (const event of this.startReplicationStreamImpl({
+					...options,
+					signal,
+					onConnect: () => {
+						failedAttempts = 0;
+					}
+				})) yield event;
+			} catch (error) {
+				failedAttempts++;
+				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);
+					await retryDelay(retryDelayMs);
+				}
+			}
+		} finally {
+			cleanUpSignals();
+		}
+	}
+	async *startReplicationStreamImpl(options) {
+		const rawEvents = fetchSse({
+			fetchFn: options.fetchFn,
+			headers: {
+				Authorization: this.getAuthHeader(options),
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(options.getBody()),
+			timeoutMs: options.requestTimeoutMs,
+			method: "POST",
+			signal: options.signal,
+			url: this.getApiEndpoint(`/sdk/v1/replication/stream`, options),
+			onConnect: options.onConnect
+		});
+		for await (const rawEvent of rawEvents) {
+			const event = JSON.parse(rawEvent);
+			if (typeof event === "object" && event !== null && "type" in event && typeof event.type === "string" && SUPPORTED_REPLICATION_STREAM_RECORD_TYPES.includes(event.type)) yield event;
+		}
+	}
+	close() {
+		this.closeController.abort();
+	}
+	getAuthHeader(options) {
+		return `Bearer ${options.sdkKey}`;
+	}
+	getApiEndpoint(path, options) {
+		return `${options.baseUrl}/api${path}`;
+	}
+};
+var ReplaneErrorCode = /* @__PURE__ */ function(ReplaneErrorCode$1) {
+	ReplaneErrorCode$1["NotFound"] = "not_found";
+	ReplaneErrorCode$1["Timeout"] = "timeout";
+	ReplaneErrorCode$1["NetworkError"] = "network_error";
+	ReplaneErrorCode$1["AuthError"] = "auth_error";
+	ReplaneErrorCode$1["Forbidden"] = "forbidden";
+	ReplaneErrorCode$1["ServerError"] = "server_error";
+	ReplaneErrorCode$1["ClientError"] = "client_error";
+	ReplaneErrorCode$1["Closed"] = "closed";
+	ReplaneErrorCode$1["NotInitialized"] = "not_initialized";
+	ReplaneErrorCode$1["Unknown"] = "unknown";
+	return ReplaneErrorCode$1;
+}(ReplaneErrorCode || {});
+var ReplaneError = class extends Error {
+	code;
+	constructor(params) {
+		super(params.message, { cause: params.cause });
+		this.name = "ReplaneError";
+		this.code = params.code;
+	}
+};
+/**
+* Create a Replane client bound to an SDK key.
+* Usage:
+*   const client = await createReplaneClient({ sdkKey: 'your-sdk-key', baseUrl: 'https://app.replane.dev' })
+*   const value = client.getConfig('my-config')
+*/
+async function createReplaneClient(sdkOptions) {
+	const storage = new ReplaneRemoteStorage();
+	return await _createReplaneClient(toFinalOptions(sdkOptions), storage);
+}
+/**
+* Create a Replane client that uses in-memory storage.
+* Usage:
+*   const client = createInMemoryReplaneClient({ 'my-config': 123 })
+*   const value = client.getConfig('my-config') // 123
+*/
+function createInMemoryReplaneClient(initialData) {
+	return {
+		getConfig: (configName) => {
+			const config = initialData[configName];
+			if (config === void 0) throw new ReplaneError({
+				message: `Config not found: ${String(configName)}`,
+				code: ReplaneErrorCode.NotFound
+			});
+			return config;
+		},
+		close: () => {}
+	};
+}
+async function _createReplaneClient(sdkOptions, storage) {
+	if (!sdkOptions.sdkKey) throw new Error("SDK key is required");
+	let configs = new Map(sdkOptions.fallbacks.map((config) => [config.name, config]));
+	const clientReady = new Deferred();
+	(async () => {
+		try {
+			const replicationStream = storage.startReplicationStream({
+				...sdkOptions,
+				getBody: () => ({
+					currentConfigs: [...configs.values()].map((config) => ({
+						name: config.name,
+						overrides: config.overrides,
+						version: config.version,
+						value: config.value
+					})),
+					requiredConfigs: sdkOptions.requiredConfigs
+				})
+			});
+			for await (const event of replicationStream) if (event.type === "init") {
+				configs = new Map(event.configs.map((config) => [config.name, config]));
+				clientReady.resolve();
+			} else if (event.type === "config_change") configs.set(event.configName, {
+				name: event.configName,
+				overrides: event.overrides,
+				version: event.version,
+				value: event.value
+			});
+			else warnNever(event, sdkOptions.logger, "Replane: unknown event type in event stream");
+		} catch (error) {
+			sdkOptions.logger.error("Replane: error initializing client:", error);
+			clientReady.reject(error);
+		}
+	})();
+	function getConfig(configName, getConfigOptions = {}) {
+		const config = configs.get(String(configName));
+		if (config === void 0) throw new ReplaneError({
+			message: `Config not found: ${String(configName)}`,
+			code: ReplaneErrorCode.NotFound
+		});
+		try {
+			return evaluateOverrides(config.value, config.overrides, {
+				...sdkOptions.context,
+				...getConfigOptions?.context ?? {}
+			}, sdkOptions.logger);
+		} catch (error) {
+			sdkOptions.logger.error(`Replane: error evaluating overrides for config ${String(configName)}:`, error);
+			return config.value;
+		}
+	}
+	const close = () => storage.close();
+	const initializationTimeoutId = setTimeout(() => {
+		if (sdkOptions.fallbacks.length === 0) {
+			close();
+			clientReady.reject(new ReplaneError({
+				message: "Replane client initialization timed out",
+				code: ReplaneErrorCode.Timeout
+			}));
+			return;
+		}
+		const missingRequiredConfigs = [];
+		for (const requiredConfigName of sdkOptions.requiredConfigs) if (!configs.has(requiredConfigName)) missingRequiredConfigs.push(requiredConfigName);
+		if (missingRequiredConfigs.length > 0) {
+			close();
+			clientReady.reject(new ReplaneError({
+				message: `Required configs are missing: ${missingRequiredConfigs.join(", ")}`,
+				code: ReplaneErrorCode.NotFound
+			}));
+			return;
+		}
+		clientReady.resolve();
+	}, sdkOptions.sdkInitializationTimeoutMs);
+	clientReady.promise.then(() => clearTimeout(initializationTimeoutId));
+	await clientReady.promise;
+	return {
+		getConfig,
+		close
+	};
+}
+function toFinalOptions(defaults) {
+	return {
+		sdkKey: defaults.sdkKey,
+		baseUrl: defaults.baseUrl.replace(/\/+$/, ""),
+		fetchFn: defaults.fetchFn ?? globalThis.fetch.bind(globalThis),
+		requestTimeoutMs: defaults.requestTimeoutMs ?? 2e3,
+		sdkInitializationTimeoutMs: defaults.sdkInitializationTimeoutMs ?? 5e3,
+		logger: defaults.logger ?? console,
+		retryDelayMs: defaults.retryDelayMs ?? 200,
+		context: { ...defaults.context ?? {} },
+		requiredConfigs: Array.isArray(defaults.required) ? defaults.required.map((name) => String(name)) : Object.entries(defaults.required ?? {}).filter(([_, value]) => value !== void 0).map(([name]) => name),
+		fallbacks: Object.entries(defaults.fallbacks ?? {}).filter(([_, value]) => value !== void 0).map(([name, value]) => ({
+			name,
+			overrides: [],
+			version: -1,
+			value
+		}))
+	};
+}
+async function fetchWithTimeout(input, init, timeoutMs, fetchFn) {
+	if (!fetchFn) throw new Error("Global fetch is not available. Provide options.fetchFn.");
+	if (!timeoutMs) return fetchFn(input, init);
+	const timeoutController = new AbortController();
+	const t = setTimeout(() => timeoutController.abort(), timeoutMs);
+	const { signal } = combineAbortSignals([init.signal, timeoutController.signal]);
+	try {
+		return await fetchFn(input, {
+			...init,
+			signal
+		});
+	} finally {
+		clearTimeout(t);
+	}
+}
+const SSE_DATA_PREFIX = "data:";
+async function* fetchSse(params) {
+	const abortController = new AbortController();
+	const { signal, cleanUpSignals } = params.signal ? combineAbortSignals([params.signal, abortController.signal]) : {
+		signal: abortController.signal,
+		cleanUpSignals: () => {}
+	};
+	try {
+		const res = await fetchWithTimeout(params.url, {
+			method: params.method ?? "GET",
+			headers: {
+				Accept: "text/event-stream",
+				...params.headers ?? {}
+			},
+			body: params.body,
+			signal
+		}, params.timeoutMs, params.fetchFn);
+		await ensureSuccessfulResponse(res, `SSE ${params.url}`);
+		const responseContentType = res.headers.get("content-type") ?? "";
+		if (!responseContentType.includes("text/event-stream")) throw new ReplaneError({
+			message: `Expected text/event-stream, got "${responseContentType}"`,
+			code: ReplaneErrorCode.ServerError
+		});
+		if (!res.body) throw new ReplaneError({
+			message: `Failed to fetch SSE ${params.url}: body is empty`,
+			code: ReplaneErrorCode.Unknown
+		});
+		if (params.onConnect) params.onConnect();
+		const decoded = res.body.pipeThrough(new TextDecoderStream());
+		const reader = decoded.getReader();
+		let buffer = "";
+		try {
+			while (true) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				buffer += value;
+				const frames = buffer.split(/\r?\n\r?\n/);
+				buffer = frames.pop() ?? "";
+				for (const frame of frames) {
+					const dataLines = [];
+					for (const rawLine of frame.split(/\r?\n/)) {
+						if (!rawLine) continue;
+						if (rawLine.startsWith(":")) continue;
+						if (rawLine.startsWith(SSE_DATA_PREFIX)) {
+							const line = rawLine.slice(SSE_DATA_PREFIX.length).replace(/^\s/, "");
+							dataLines.push(line);
+						}
+					}
+					if (dataLines.length) {
+						const payload = dataLines.join("\n");
+						yield payload;
+					}
+				}
+			}
+		} finally {
+			try {
+				await reader.cancel();
+			} catch {}
+			abortController.abort();
+		}
+	} finally {
+		cleanUpSignals();
+	}
+}
+async function ensureSuccessfulResponse(response, message) {
+	if (response.status === 404) throw new ReplaneError({
+		message: `Not found: ${message}`,
+		code: ReplaneErrorCode.NotFound
+	});
+	if (response.status === 401) throw new ReplaneError({
+		message: `Unauthorized access: ${message}`,
+		code: ReplaneErrorCode.AuthError
+	});
+	if (response.status === 403) throw new ReplaneError({
+		message: `Forbidden access: ${message}`,
+		code: ReplaneErrorCode.Forbidden
+	});
+	if (!response.ok) {
+		let body;
+		try {
+			body = await response.text();
+		} catch {
+			body = "<unable to read response body>";
+		}
+		const code = response.status >= 500 ? ReplaneErrorCode.ServerError : response.status >= 400 ? ReplaneErrorCode.ClientError : ReplaneErrorCode.Unknown;
+		throw new ReplaneError({
+			message: `Fetch response isn't successful (${message}): ${response.status} ${response.statusText} - ${body}`,
+			code
+		});
+	}
+}
+function combineAbortSignals(signals) {
+	const controller = new AbortController();
+	const onAbort = () => {
+		controller.abort();
+		cleanUpSignals();
+	};
+	const cleanUpSignals = () => {
+		for (const s of signals) s?.removeEventListener("abort", onAbort);
+	};
+	for (const s of signals) s?.addEventListener("abort", onAbort, { once: true });
+	if (signals.some((s) => s?.aborted)) onAbort();
+	return {
+		signal: controller.signal,
+		cleanUpSignals
+	};
+}
+var Deferred = class {
+	promise;
+	resolve;
+	reject;
+	constructor() {
+		this.promise = new Promise((resolve, reject) => {
+			this.resolve = resolve;
+			this.reject = reject;
+		});
+	}
+};
+
+//#endregion
+export { ReplaneError, createInMemoryReplaneClient, createReplaneClient };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@replanejs/sdk",
+  "version": "0.5.6",
+  "description": "Replane JavaScript SDK.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/replane-dev/replane-javascript#readme",
+  "bugs": {
+    "url": "https://github.com/replane-dev/replane-javascript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/replane-dev/replane-javascript.git"
+  },
+  "author": "Dmitry Tilyupo <tilyupo@gmail.com>",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "replane",
+    "config",
+    "configuration",
+    "sdk",
+    "feature-flags"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "pnpm run build:esm && pnpm run build:cjs",
+    "build:esm": "tsdown",
+    "build:cjs": "esbuild src/index.ts --platform=node --format=cjs --outfile=dist/index.cjs",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests --max-warnings 0",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"README.md\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"README.md\"",
+    "release": "pnpm run build && bumpp && npm publish"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/node": "^22.15.17",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "async-channel": "^0.2.0",
+    "bumpp": "^10.1.0",
+    "esbuild": "^0.23.1",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "tsdown": "^0.11.9",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.1.3"
+  },
+  "packageManager": "pnpm@10.7.0+sha1.66453f13fbf9078d3db193718206a8d738afdbdb"
+}