@configdirector/react-native-sdk 1.9.0 → 1.10.0

package/README.md

@@ -11,10 +11,13 @@ npm install --save @configdirector/react-native-sdk
 ```
 
 Install `@react-native-async-storage/async-storage` as well, so the SDK recognizes the app install
-across app starts. For a context without an `id`, ConfigDirector derives an identifier from an ID
-the SDK stores for the install, so the context keeps that identifier, and counts as one monthly
-active user, however often the app is opened. It is an optional peer dependency and works in Expo
-Go. Without it, every app start looks like a new install and the SDK logs a warning.
+across app starts and keeps the last values it received on the device. For a context without an
+`id`, ConfigDirector derives an identifier from an ID the SDK stores for the install, so the context
+keeps that identifier, and counts as one monthly active user, however often the app is opened. The
+last values are served on the next app start of the same context until live values arrive, so an
+app opened without a network shows them instead of the in-code default values. It is an optional
+peer dependency and works in Expo Go. Without it, every app start looks like a new install, nothing
+is kept on the device, and the SDK logs a warning.
 
 ```bash
 npm install --save @react-native-async-storage/async-storage

package/dist/configdirector-react-native-testing.d.mts

@@ -1,4 +1,4 @@
-import { c as NativeJsonValue, d as ConfigDirectorContext, i as ConfigDirectorClient, l as NativeValue, p as ConfigDirectorLogger, u as NativeValues } from "./types-BBQmjjf5.mjs";
+import { c as NativeJsonValue, d as ConfigDirectorContext, i as ConfigDirectorClient, l as NativeValue, p as ConfigDirectorLogger, u as NativeValues } from "./types-DmbDeZqL.mjs";
 
 //#region ../shared/src/errors.d.ts
 declare class ConfigDirectorConnectionError extends Error {

package/dist/configdirector-react-native-testing.mjs

@@ -1,4 +1,4 @@
-import { c as createDefaultLogger, d as ConfigDirectorConnectionError, f as ConfigDirectorValidationError, l as nativeValueConfigState, m as _defineProperty, p as Emitter, r as DefaultConfigDirectorClient, s as discardingTelemetryClient, t as INSTALLED_TEST_CLIENT_SLOT } from "./installedTestClient-BluKT8Qj.mjs";
+import { c as createDefaultLogger, d as ConfigDirectorConnectionError, f as ConfigDirectorValidationError, l as nativeValueConfigState, m as _defineProperty, p as Emitter, r as DefaultConfigDirectorClient, s as discardingTelemetryClient, t as INSTALLED_TEST_CLIENT_SLOT } from "./installedTestClient-BaCuY_Ru.mjs";
 //#region ../js-client-core/src/testing/InMemoryConnection.ts
 const TEST_ENVIRONMENT = {
 	environmentId: "test-environment",
@@ -295,7 +295,7 @@ const installTestClient = (testClient) => {
 const createTestClient = (options) => {
 	return createTestClient$1({
 		sdkName: "react-native-sdk",
-		sdkVersion: "1.9.0"
+		sdkVersion: "1.10.0"
 	}, options);
 };
 //#endregion

package/dist/configdirector-react-native.d.mts

@@ -1,4 +1,4 @@
-import { a as ConfigDirectorClientOptions, d as ConfigDirectorContext, f as ConfigDirectorLogMessageDecorator, g as ConnectionMode, h as ConfigValueType, i as ConfigDirectorClient, m as ConfigDirectorLoggingLevel, n as CachingProvider, o as OfflineValue, p as ConfigDirectorLogger, r as ClientHooks, s as OfflineValues, t as CachingOptions } from "./types-BBQmjjf5.mjs";
+import { _ as ConnectionMode, a as ConfigDirectorClientOptions, d as ConfigDirectorContext, f as ConfigDirectorLogMessageDecorator, g as ConfigValueType, h as ConfigEvaluation, i as ConfigDirectorClient, m as ConfigDirectorLoggingLevel, n as CachingProvider, o as OfflineValue, p as ConfigDirectorLogger, r as ClientHooks, s as OfflineValues, t as CachingOptions, v as EvaluationReason } from "./types-DmbDeZqL.mjs";
 import { Component, PropsWithChildren } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
@@ -151,4 +151,4 @@ declare class ConfigDirectorReactContextError extends Error {
 //#region src/logger.d.ts
 declare const createConsoleLogger: (level?: ConfigDirectorLoggingLevel) => DefaultConsoleLogger;
 //#endregion
-export { type CachingOptions, type CachingProvider, type ClientStatus, type ConfigDirectorClient, type ConfigDirectorClientOptions, type ConfigDirectorContext, type ConfigDirectorLogger, type ConfigDirectorLoggingLevel, ConfigDirectorProvider, type ConfigDirectorProviderClientProps, type ConfigDirectorProviderOptions, type ConfigDirectorProviderProps, ConfigDirectorReactContextError, type ConnectionMode, type NetInfoSubscribe, type OfflineValue, type OfflineValues, createClient, createConsoleLogger, useClient, useConfigValue, useContext };
+export { type CachingOptions, type CachingProvider, type ClientStatus, type ConfigDirectorClient, type ConfigDirectorClientOptions, type ConfigDirectorContext, type ConfigDirectorLogger, type ConfigDirectorLoggingLevel, ConfigDirectorProvider, type ConfigDirectorProviderClientProps, type ConfigDirectorProviderOptions, type ConfigDirectorProviderProps, ConfigDirectorReactContextError, type ConfigEvaluation, type ConnectionMode, type EvaluationReason, type NetInfoSubscribe, type OfflineValue, type OfflineValues, createClient, createConsoleLogger, useClient, useConfigValue, useContext };

package/dist/configdirector-react-native.mjs

@@ -1,4 +1,4 @@
-import { a as DEFAULT_CACHING_SIZE_LIMIT_BYTES, c as createDefaultLogger, i as CACHED_VALUES_STORAGE_KEY_PREFIX, m as _defineProperty, n as readInstalledTestClient, o as fetchWithTimeout, r as DefaultConfigDirectorClient, u as isFetchErrorFatal } from "./installedTestClient-BluKT8Qj.mjs";
+import { a as DEFAULT_CACHING_SIZE_LIMIT_BYTES, c as createDefaultLogger, i as CACHED_VALUES_STORAGE_KEY_PREFIX, m as _defineProperty, n as readInstalledTestClient, o as fetchWithTimeout, r as DefaultConfigDirectorClient, u as isFetchErrorFatal } from "./installedTestClient-BaCuY_Ru.mjs";
 import React, { Component, useContext as useContext$1 } from "react";
 import { AppState, NativeModules } from "react-native";
 import { sha256 } from "@noble/hashes/sha2.js";
@@ -65,20 +65,24 @@ var ClientEventReporter = class {
 		_defineProperty(this, "metaContext", void 0);
 		_defineProperty(this, "logger", void 0);
 		_defineProperty(this, "url", void 0);
+		_defineProperty(this, "clientSession", void 0);
 		_defineProperty(this, "executeRequests", true);
 		this.sdkKey = options.sdkKey;
 		this.logger = options.logger;
 		this.sdkIdentity = options.sdkIdentity;
 		this.metaContext = options.metaContext;
 		this.url = options.urlFactory("client/telemetry/v1", options.baseUrl);
+		this.clientSession = options.clientSession;
 	}
 	async report({ context, discreteEvents, aggregatedEvents, droppedEvents }) {
 		if (!this.executeRequests) return {
 			success: false,
 			fatalError: true
 		};
+		const { instanceId } = await this.clientSession;
 		const eventReport = {
 			clientSdkKey: this.sdkKey,
+			instanceId,
 			metaContext: {
 				sdkName: this.sdkIdentity.sdkName,
 				sdkVersion: this.sdkIdentity.sdkVersion,
@@ -538,6 +542,41 @@ const findAsyncStorage = (logger) => importAsyncStorage().then((lookup) => {
 	return lookup;
 });
 //#endregion
+//#region src/cachingProvider.ts
+const asyncStorageCachingProvider = (asyncStorage) => (clientSdkKeyDigest) => {
+	const storageKey = clientSdkKeyDigest.then((digest) => CACHED_VALUES_STORAGE_KEY_PREFIX + digest);
+	return {
+		read: async () => {
+			const lookup = await asyncStorage;
+			return lookup.outcome === "installed" ? lookup.storage.getItem(await storageKey) : void 0;
+		},
+		write: async (value) => {
+			const lookup = await asyncStorage;
+			if (lookup.outcome === "installed") await lookup.storage.setItem(await storageKey, value);
+		},
+		remove: async () => {
+			const lookup = await asyncStorage;
+			if (lookup.outcome === "installed") await lookup.storage.removeItem(await storageKey);
+		},
+		sizeLimit: () => DEFAULT_CACHING_SIZE_LIMIT_BYTES
+	};
+};
+//#endregion
+//#region src/instanceIdStorage.ts
+const asyncStorageInstanceIdStorage = (asyncStorage) => {
+	const installedAsyncStorage = async () => {
+		const lookup = await asyncStorage;
+		switch (lookup.outcome) {
+			case "installed": return lookup.storage;
+			case "not installed": throw new Error("@react-native-async-storage/async-storage is not installed");
+		}
+	};
+	return {
+		getItem: async (key) => (await installedAsyncStorage()).getItem(key),
+		setItem: async (key, value) => (await installedAsyncStorage()).setItem(key, value)
+	};
+};
+//#endregion
 //#region src/utf8Encoder.ts
 /**
 * Encodes a string to a UTF-8 byte sequence.
@@ -578,42 +617,6 @@ const encodeManually = (str) => {
 	return new Uint8Array(bytes);
 };
 //#endregion
-//#region src/cachingProvider.ts
-const storageKeyFor = (clientSdkKey) => CACHED_VALUES_STORAGE_KEY_PREFIX + bytesToHex(sha256(encodeUtf8(clientSdkKey)));
-const asyncStorageCachingProvider = (asyncStorage) => (clientSdkKey) => {
-	const storageKey = storageKeyFor(clientSdkKey);
-	return {
-		read: async () => {
-			const lookup = await asyncStorage;
-			return lookup.outcome === "installed" ? lookup.storage.getItem(storageKey) : void 0;
-		},
-		write: async (value) => {
-			const lookup = await asyncStorage;
-			if (lookup.outcome === "installed") await lookup.storage.setItem(storageKey, value);
-		},
-		remove: async () => {
-			const lookup = await asyncStorage;
-			if (lookup.outcome === "installed") await lookup.storage.removeItem(storageKey);
-		},
-		sizeLimit: () => DEFAULT_CACHING_SIZE_LIMIT_BYTES
-	};
-};
-//#endregion
-//#region src/instanceIdStorage.ts
-const asyncStorageInstanceIdStorage = (asyncStorage) => {
-	const installedAsyncStorage = async () => {
-		const lookup = await asyncStorage;
-		switch (lookup.outcome) {
-			case "installed": return lookup.storage;
-			case "not installed": throw new Error("@react-native-async-storage/async-storage is not installed");
-		}
-	};
-	return {
-		getItem: async (key) => (await installedAsyncStorage()).getItem(key),
-		setItem: async (key, value) => (await installedAsyncStorage()).setItem(key, value)
-	};
-};
-//#endregion
 //#region src/reactNativeStreamingFetch.ts
 const abortError = (message) => {
 	const err = new Error(message);
@@ -750,6 +753,9 @@ var ReactNativeTelemetryClient = class {
 	}
 };
 //#endregion
+//#region src/sha256HexDigest.ts
+const sha256HexDigest = (text) => Promise.resolve(bytesToHex(sha256(encodeUtf8(text))));
+//#endregion
 //#region src/url.ts
 var MinimalUrl = class {
 	constructor(input, base) {
@@ -771,7 +777,7 @@ const createReactNativeClient = (clientSdkKey, clientOptions) => {
 	var _clientOptions$logger;
 	const sdkIdentity = {
 		sdkName: "react-native-sdk",
-		sdkVersion: "1.9.0"
+		sdkVersion: "1.10.0"
 	};
 	const logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createConsoleLogger("warn");
 	const metadata = resolveMetadata(clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata, logger);
@@ -782,7 +788,8 @@ const createReactNativeClient = (clientSdkKey, clientOptions) => {
 		metaContext: metadata,
 		baseUrl: liveTelemetry.baseUrl,
 		logger,
-		urlFactory
+		urlFactory,
+		clientSession: liveTelemetry.clientSession
 	}), clientSdkKey, sdkIdentity, {
 		...clientOptions,
 		logger,
@@ -791,6 +798,7 @@ const createReactNativeClient = (clientSdkKey, clientOptions) => {
 		fetch: reactNativeStreamingFetch,
 		urlFactory,
 		instanceIdStorage: asyncStorageInstanceIdStorage(asyncStorage),
+		sha256HexDigest,
 		platformCachingProvider: asyncStorageCachingProvider(asyncStorage)
 	});
 };

package/dist/{installedTestClient-BluKT8Qj.mjs → installedTestClient-BaCuY_Ru.mjs}

@@ -875,9 +875,12 @@ const parseJson = (jsonString, defaultValue, requestedType, valueId) => {
 };
 const isJsonTypeCompatible = (parsed, defaultValue) => {
 	if (parsed === null) return false;
-	const defaultType = typeof defaultValue;
-	if (defaultType === "bigint") return typeof parsed === "number";
-	return typeof parsed === defaultType;
+	return jsonShapeOf(parsed) === jsonShapeOf(defaultValue);
+};
+const jsonShapeOf = (value) => {
+	if (Array.isArray(value)) return "array";
+	const nativeType = typeof value;
+	return nativeType === "bigint" ? "number" : nativeType;
 };
 //#endregion
 //#region ../shared/src/logger.ts
@@ -1331,11 +1334,12 @@ const utf8ByteLength = (text) => {
 };
 //#endregion
 //#region ../js-client-core/src/cached-values.ts
-const ENTRY_FORMAT_VERSION = 1;
+const ENTRY_FORMAT_VERSION = 2;
+const FIRST_ENTRY_FORMAT_VERSION = 1;
 const DEFAULT_CONTEXT_KIND = "user";
 const CACHED_VALUES_STORAGE_KEY_PREFIX = "configdirector-sdk:cached-values:";
 const DEFAULT_CACHING_SIZE_LIMIT_BYTES = 256 * 1024;
-const planCaching = (connectionPlan, caching, platformProvider) => {
+const planCaching = (connectionPlan, caching, sha256HexDigest, platformCachingProvider) => {
 	var _caching$provider;
 	if (connectionPlan.kind === "stay-offline") return {
 		kind: "no cache",
@@ -1345,7 +1349,12 @@ const planCaching = (connectionPlan, caching, platformProvider) => {
 		kind: "no cache",
 		reason: "turned off"
 	};
-	const provider = (_caching$provider = caching === null || caching === void 0 ? void 0 : caching.provider) !== null && _caching$provider !== void 0 ? _caching$provider : platformProvider === null || platformProvider === void 0 ? void 0 : platformProvider(connectionPlan.clientSdkKey);
+	if (!sha256HexDigest) return {
+		kind: "no cache",
+		reason: "no SHA-256 available"
+	};
+	const clientSdkKeyDigest = sha256HexDigest(connectionPlan.clientSdkKey);
+	const provider = (_caching$provider = caching === null || caching === void 0 ? void 0 : caching.provider) !== null && _caching$provider !== void 0 ? _caching$provider : platformCachingProvider === null || platformCachingProvider === void 0 ? void 0 : platformCachingProvider(clientSdkKeyDigest);
 	if (!provider) return {
 		kind: "no cache",
 		reason: "no provider available"
@@ -1353,7 +1362,7 @@ const planCaching = (connectionPlan, caching, platformProvider) => {
 	return {
 		kind: "cache",
 		provider,
-		clientSdkKey: connectionPlan.clientSdkKey
+		clientSdkKeyDigest
 	};
 };
 const contextTagFor = (context, instanceId) => {
@@ -1389,15 +1398,30 @@ const isConfigStateMap = (candidate) => {
 	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return false;
 	return Object.values(candidate).every((config) => config && typeof config === "object" && typeof config.id === "string" && typeof config.key === "string");
 };
-const isEntryFor = (clientSdkKey, candidate) => {
+const isEntryFor = (clientSdkKeyDigest, candidate) => {
 	if (!candidate || typeof candidate !== "object") return false;
 	const entry = candidate;
-	return entry.formatVersion === ENTRY_FORMAT_VERSION && entry.clientSdkKey === clientSdkKey && isContextTag(entry.contextTag) && typeof entry.environmentId === "string" && typeof entry.projectId === "string" && isConfigStateMap(entry.configs) && typeof entry.receivedAt === "number";
+	return entry.formatVersion === ENTRY_FORMAT_VERSION && entry.clientSdkKeyDigest === clientSdkKeyDigest && isContextTag(entry.contextTag) && typeof entry.environmentId === "string" && typeof entry.projectId === "string" && isConfigStateMap(entry.configs) && typeof entry.receivedAt === "number";
+};
+const hasFirstFormatVersion = (candidate) => !!candidate && typeof candidate === "object" && candidate.formatVersion === FIRST_ENTRY_FORMAT_VERSION;
+const parseEntry = (raw, clientSdkKeyDigest) => {
+	let candidate;
+	try {
+		candidate = JSON.parse(raw);
+	} catch {
+		return { outcome: "unreadable" };
+	}
+	if (isEntryFor(clientSdkKeyDigest, candidate)) return {
+		outcome: "stored",
+		cachedValues: candidate
+	};
+	if (hasFirstFormatVersion(candidate)) return { outcome: "first format" };
+	return { outcome: "unreadable" };
 };
 var CachedValuesStore = class {
-	constructor(provider, clientSdkKey, logger) {
+	constructor(provider, clientSdkKeyDigest, logger) {
 		this.provider = provider;
-		this.clientSdkKey = clientSdkKey;
+		this.clientSdkKeyDigest = clientSdkKeyDigest;
 		this.logger = logger;
 		_defineProperty(this, "warned", /* @__PURE__ */ new Set());
 		_defineProperty(this, "pendingRead", void 0);
@@ -1422,23 +1446,16 @@ var CachedValuesStore = class {
 			return { outcome: "failed" };
 		}
 		if (raw == null || raw === "") return { outcome: "nothing stored" };
-		const entry = this.parseEntry(raw);
-		if (!entry) {
-			this.warnOnce("unreadable", "The values kept on the device could not be read and were removed, starting without them");
-			await this.removeEntry();
-			return { outcome: "unreadable" };
-		}
-		return {
-			outcome: "stored",
-			cachedValues: entry
-		};
-	}
-	parseEntry(raw) {
-		try {
-			const candidate = JSON.parse(raw);
-			return isEntryFor(this.clientSdkKey, candidate) ? candidate : void 0;
-		} catch {
-			return;
+		const entryParseOutcome = parseEntry(raw, await this.clientSdkKeyDigest);
+		switch (entryParseOutcome.outcome) {
+			case "stored": return entryParseOutcome;
+			case "first format":
+				await this.removeEntry();
+				return entryParseOutcome;
+			case "unreadable":
+				this.warnOnce("unreadable", "The values kept on the device could not be read and were removed, starting without them");
+				await this.removeEntry();
+				return entryParseOutcome;
 		}
 	}
 	async writeQueued() {
@@ -1457,7 +1474,7 @@ var CachedValuesStore = class {
 	async writeEntry(cachedValues) {
 		const entry = {
 			formatVersion: ENTRY_FORMAT_VERSION,
-			clientSdkKey: this.clientSdkKey,
+			clientSdkKeyDigest: await this.clientSdkKeyDigest,
 			...cachedValues
 		};
 		const serialized = JSON.stringify(entry);
@@ -1522,7 +1539,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		this.timeout = (_clientOptions$connec = clientOptions === null || clientOptions === void 0 || (_clientOptions$connec2 = clientOptions.connection) === null || _clientOptions$connec2 === void 0 ? void 0 : _clientOptions$connec2.timeout) !== null && _clientOptions$connec !== void 0 ? _clientOptions$connec : 3e3;
 		const urlFactory = (_internalClientOption = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.urlFactory) !== null && _internalClientOption !== void 0 ? _internalClientOption : defaultUrlFactory;
 		this.connectionPlan = planConnection(clientSdkKey, clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.connection, urlFactory);
-		this.cachedValuesStore = this.buildCachedValuesStore(planCaching(this.connectionPlan, clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.caching, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.platformCachingProvider));
+		this.cachedValuesStore = this.buildCachedValuesStore(planCaching(this.connectionPlan, clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.caching, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.sha256HexDigest, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.platformCachingProvider));
 		this.telemetryClient = this.buildTelemetryClient(liveTelemetryClient, clientOptions);
 		this.transport = (_internalClientOption2 = internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.transport) !== null && _internalClientOption2 !== void 0 ? _internalClientOption2 : this.buildTransport(sdkOptions, clientOptions, urlFactory, internalClientOptions);
 		this.transport.on("configSetReceived", (configSet) => {
@@ -1566,7 +1583,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 				this.logger.debug(`[ConfigDirectorClient] No values are kept on the device: ${cachingPlan.reason}`);
 				return;
 			case "cache": {
-				const store = new CachedValuesStore(cachingPlan.provider, cachingPlan.clientSdkKey, this.logger);
+				const store = new CachedValuesStore(cachingPlan.provider, cachingPlan.clientSdkKeyDigest, this.logger);
 				store.read();
 				return store;
 			}
@@ -1582,6 +1599,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		const read = await store.read();
 		switch (read.outcome) {
 			case "nothing stored":
+			case "first format":
 			case "unreadable":
 			case "failed": return;
 			case "stored": break;
@@ -1655,7 +1673,8 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 				clientSdkKey: plan.clientSdkKey,
 				baseUrl: plan.baseUrl,
 				logger: this.logger,
-				metadata: clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata
+				metadata: clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.metadata,
+				clientSession: this.clientSession
 			});
 		}
 	}
@@ -1778,7 +1797,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		var _this$configSet, _this$handlersMap$get;
 		const configState = (_this$configSet = this.configSet) === null || _this$configSet === void 0 ? void 0 : _this$configSet.configs[configKey];
 		(_this$handlersMap$get = this.handlersMap.get(configKey)) === null || _this$handlersMap$get === void 0 || _this$handlersMap$get.forEach((h) => {
-			const value = this.getValueFromConfigState(configKey, configState, h.defaultValue);
+			const value = this.evaluationOf(configKey, configState, h.defaultValue).value;
 			h.handler(value);
 		});
 	}
@@ -1803,12 +1822,15 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		} else handlers.splice(0);
 	}
 	getValue(configKey, defaultValue) {
+		return this.evaluate(configKey, defaultValue).value;
+	}
+	evaluate(configKey, defaultValue) {
 		var _this$configSet2;
 		this.validateDefaultValue(defaultValue);
 		const configState = (_this$configSet2 = this.configSet) === null || _this$configSet2 === void 0 ? void 0 : _this$configSet2.configs[configKey];
-		return this.getValueFromConfigState(configKey, configState, defaultValue);
+		return this.evaluationOf(configKey, configState, defaultValue);
 	}
-	getValueFromConfigState(configKey, configState, defaultValue) {
+	evaluationOf(configKey, configState, defaultValue) {
 		var _this$currentContext2, _parseResult$parsedVa;
 		if (!configState) {
 			var _this$currentContext;
@@ -1823,14 +1845,15 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 				usedDefault: true,
 				evaluationReason: reason
 			});
-			this.dispatchEvaluationEvent({
+			const evaluation = {
 				key: configKey,
 				value: defaultValue,
 				isDefaultValue: true,
 				reason,
 				context: this.context
-			});
-			return defaultValue;
+			};
+			this.dispatchEvaluationEvent(evaluation);
+			return evaluation;
 		}
 		const parseResult = parseConfigValue(configState, defaultValue);
 		const reason = this.servedReason(parseResult.reason);
@@ -1845,16 +1868,17 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 			usedDefault: parseResult.usedDefault,
 			evaluationReason: reason
 		});
-		this.dispatchEvaluationEvent({
+		const evaluation = {
 			key: configKey,
 			value: parseResult.parsedValue,
 			valueId: (_parseResult$parsedVa = parseResult.parsedValueId) !== null && _parseResult$parsedVa !== void 0 ? _parseResult$parsedVa : void 0,
 			isDefaultValue: parseResult.usedDefault,
 			reason,
 			context: this.context
-		});
+		};
+		this.dispatchEvaluationEvent(evaluation);
 		this.logger.debug(`[ConfigDirectorClient] Evaluated '${configKey}' to '${parseResult.parsedValue}'`);
-		return parseResult.parsedValue;
+		return evaluation;
 	}
 	dispatchEvaluationEvent(event) {
 		setTimeout(() => this.emit("configEvaluated", { evaluation: event }), 0);

package/dist/{types-BBQmjjf5.d.mts → types-DmbDeZqL.d.mts}

@@ -23,13 +23,24 @@ interface ConfigDirectorLogger {
 interface ConfigDirectorLogMessageDecorator {
   decorateMessage(message: string): string;
 }
+/**
+ * Why an evaluation returned the value it did. `found-match` returns a value from ConfigDirector,
+ * and `cached` a value kept on the device while a client SDK waits for live values. `value-missing`
+ * returns the in-code default value because the config has no value. Every other reason returns the
+ * in-code default value because of an error: the config does not exist (`config-state-missing`), no
+ * values have arrived yet (`client-not-ready`), or the value cannot be read as the type of the in-code
+ * default value.
+ */
 type EvaluationReason = "found-match" | "config-state-missing" | "client-not-ready" | "type-mismatch" | "value-missing" | "invalid-number" | "invalid-json" | "invalid-boolean" | "cached";
-type ConfigEvaluation = {
-  key: string;
-  value: ConfigValueType;
-  valueId?: string;
-  isDefaultValue: boolean;
-  reason: EvaluationReason;
+/**
+ * One evaluation of a config: the value it returned, why, and the context it was evaluated for.
+ */
+type ConfigEvaluation<T extends ConfigValueType = ConfigValueType> = {
+  /** The config key that was evaluated. */key: string; /** The value returned, which is the in-code default value when {@link isDefaultValue} is `true`. */
+  value: T; /** The ID ConfigDirector assigned to the value returned, when ConfigDirector sent one with it. */
+  valueId?: string; /** Whether the evaluation returned the in-code default value. */
+  isDefaultValue: boolean; /** Why the evaluation returned this value. */
+  reason: EvaluationReason; /** The context the config was evaluated for, if any. */
   context?: ConfigDirectorContext;
 };
 /**
@@ -350,6 +361,16 @@ interface ConfigDirectorClient extends EventProvider<ClientEvents> {
    * is called before initialization is done.
    */
   getValue<T extends ConfigValueType>(configKey: string, defaultValue: T): T;
+  /**
+   * Evaluates a config as {@link getValue} does and returns the evaluation: the value, the reason it
+   * was served and its value ID. Like every read, it fires `configEvaluated` and is counted in
+   * telemetry.
+   *
+   * @returns The evaluation, whose `value` is what {@link getValue} returns
+   * @param configKey The config key to evaluate
+   * @param defaultValue The in-code default value, returned when no value from ConfigDirector can be served
+   */
+  evaluate<T extends ConfigValueType>(configKey: string, defaultValue: T): ConfigEvaluation<T>;
   /**
    * Watches for changes to a a config evaluation value. Whenever the config value changes, the
    * provided callback function will be called with the new value. Changes can happen due to updates
@@ -397,4 +418,4 @@ interface ConfigDirectorClient extends EventProvider<ClientEvents> {
   dispose(): void;
 }
 //#endregion
-export { ConfigDirectorClientOptions as a, NativeJsonValue as c, ConfigDirectorContext as d, ConfigDirectorLogMessageDecorator as f, ConnectionMode as g, ConfigValueType as h, ConfigDirectorClient as i, NativeValue as l, ConfigDirectorLoggingLevel as m, CachingProvider as n, OfflineValue as o, ConfigDirectorLogger as p, ClientHooks as r, OfflineValues as s, CachingOptions as t, NativeValues as u };
+export { ConnectionMode as _, ConfigDirectorClientOptions as a, NativeJsonValue as c, ConfigDirectorContext as d, ConfigDirectorLogMessageDecorator as f, ConfigValueType as g, ConfigEvaluation as h, ConfigDirectorClient as i, NativeValue as l, ConfigDirectorLoggingLevel as m, CachingProvider as n, OfflineValue as o, ConfigDirectorLogger as p, ClientHooks as r, OfflineValues as s, CachingOptions as t, NativeValues as u, EvaluationReason as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/react-native-sdk",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "React Native client SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",