@configdirector/react-native-sdk 1.8.0 → 1.9.0

package/README.md

@@ -10,9 +10,11 @@ React Native SDK for [ConfigDirector](https://www.configdirector.com), remote co
 npm install --save @configdirector/react-native-sdk
 ```
 
-Install `@react-native-async-storage/async-storage` as well, so the SDK can keep the same client
-session for six hours across app starts. It is an optional peer dependency and works in Expo Go.
-Without it, every app start begins a new client session and the SDK logs a warning.
+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.
 
 ```bash
 npm install --save @react-native-async-storage/async-storage
@@ -86,7 +88,7 @@ transform, so a Jest setup must let `transformIgnorePatterns` transform both pac
 `jest-expo` requires `@react-native/jest-preset` as a peer dependency, so install it in either case.
 The test client never touches AsyncStorage. A test that builds a real client instead, through
 `createClient` or a provider given an `sdkKey`, logs the warning that AsyncStorage is missing and
-starts a new client session under either preset; add `@babel/plugin-transform-dynamic-import` to the
+connects as a new install under either preset; add `@babel/plugin-transform-dynamic-import` to the
 Babel test environment for that client to use the AsyncStorage Jest mock instead.
 
 ## Documentation

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

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

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

@@ -1,4 +1,4 @@
-import { a as discardingTelemetryClient, d as Emitter, f as _defineProperty, l as ConfigDirectorConnectionError, o as createDefaultLogger, r as DefaultConfigDirectorClient, s as nativeValueConfigState, t as INSTALLED_TEST_CLIENT_SLOT, u as ConfigDirectorValidationError } from "./installedTestClient-CKjaEilj.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-BluKT8Qj.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.8.0"
+		sdkVersion: "1.9.0"
 	}, options);
 };
 //#endregion

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

@@ -1,4 +1,4 @@
-import { a as OfflineValues, d as ConfigDirectorLogger, f as ConfigDirectorLoggingLevel, i as OfflineValue, l as ConfigDirectorContext, m as ConnectionMode, n as ConfigDirectorClient, p as ConfigValueType, r as ConfigDirectorClientOptions, t as ClientHooks, u as ConfigDirectorLogMessageDecorator } from "./types-DoORnGTD.mjs";
+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 { Component, PropsWithChildren } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
@@ -74,6 +74,12 @@ type ConfigDirectorProviderOptions = {
   context?: ConfigDirectorContext;
   logger?: ConfigDirectorLogger;
   hooks?: ClientHooks;
+  /**
+   * Options for the values the client keeps on the device between launches. The last values received
+   * are kept by default and served, with the evaluation reason `cached`, on the next launch of the same
+   * context until live values arrive.
+   */
+  caching?: CachingOptions;
   netInfoSubscribe?: NetInfoSubscribe;
 };
 /**
@@ -145,4 +151,4 @@ declare class ConfigDirectorReactContextError extends Error {
 //#region src/logger.d.ts
 declare const createConsoleLogger: (level?: ConfigDirectorLoggingLevel) => DefaultConsoleLogger;
 //#endregion
-export { 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 ConnectionMode, type NetInfoSubscribe, type OfflineValue, type OfflineValues, createClient, createConsoleLogger, useClient, useConfigValue, useContext };

package/dist/configdirector-react-native.mjs

@@ -1,7 +1,8 @@
-import { c as isFetchErrorFatal, f as _defineProperty, i as fetchWithTimeout, n as readInstalledTestClient, o as createDefaultLogger, r as DefaultConfigDirectorClient } from "./installedTestClient-CKjaEilj.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-BluKT8Qj.mjs";
 import React, { Component, useContext as useContext$1 } from "react";
 import { AppState, NativeModules } from "react-native";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 import { jsx } from "react/jsx-runtime";
 //#region ../shared/src/telemetry/utils.ts
 const CONFIG_VALUE_MAX_LENGTH = 500;
@@ -520,8 +521,8 @@ const resolveMetadata = (provided, logger) => {
 	return metadata;
 };
 //#endregion
-//#region src/instanceIdStorage.ts
-const lookUpAsyncStorage = async () => {
+//#region src/asyncStorage.ts
+const importAsyncStorage = async () => {
 	try {
 		const { default: storage } = await import("@react-native-async-storage/async-storage");
 		return {
@@ -532,23 +533,10 @@ const lookUpAsyncStorage = async () => {
 		return { outcome: "not installed" };
 	}
 };
-const asyncStorageInstanceIdStorage = (logger) => {
-	const asyncStorageLookup = lookUpAsyncStorage().then((lookup) => {
-		if (lookup.outcome === "not installed") logger.warn("The ConfigDirector SDK could not find @react-native-async-storage/async-storage, so every app start counts as a new client session. Install it for the SDK to keep the client session for six hours across app starts.");
-		return lookup;
-	});
-	const installedAsyncStorage = async () => {
-		const lookup = await asyncStorageLookup;
-		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)
-	};
-};
+const findAsyncStorage = (logger) => importAsyncStorage().then((lookup) => {
+	if (lookup.outcome === "not installed") logger.warn("The ConfigDirector SDK could not find @react-native-async-storage/async-storage, so every app start looks like a new install to ConfigDirector, a context without an id gets a new identifier each time, and no values are kept on the device between app starts. Install it for the SDK to recognize the install across app starts and to serve the last values when the app starts without a network.");
+	return lookup;
+});
 //#endregion
 //#region src/utf8Encoder.ts
 /**
@@ -590,6 +578,42 @@ 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);
@@ -747,10 +771,11 @@ const createReactNativeClient = (clientSdkKey, clientOptions) => {
 	var _clientOptions$logger;
 	const sdkIdentity = {
 		sdkName: "react-native-sdk",
-		sdkVersion: "1.8.0"
+		sdkVersion: "1.9.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);
+	const asyncStorage = findAsyncStorage(logger);
 	return new DefaultConfigDirectorClient((liveTelemetry) => new ReactNativeTelemetryClient({
 		sdkKey: liveTelemetry.clientSdkKey,
 		sdkIdentity,
@@ -765,7 +790,8 @@ const createReactNativeClient = (clientSdkKey, clientOptions) => {
 	}, {
 		fetch: reactNativeStreamingFetch,
 		urlFactory,
-		instanceIdStorage: asyncStorageInstanceIdStorage(logger)
+		instanceIdStorage: asyncStorageInstanceIdStorage(asyncStorage),
+		platformCachingProvider: asyncStorageCachingProvider(asyncStorage)
 	});
 };
 //#endregion
@@ -785,7 +811,8 @@ const buildClient = (options) => {
 			appVersion: options.appVersion
 		},
 		logger: (_options$logger = options.logger) !== null && _options$logger !== void 0 ? _options$logger : createConsoleLogger("warn"),
-		hooks: options.hooks
+		hooks: options.hooks,
+		caching: options.caching
 	});
 };
 const hasGivenClient = (props) => "client" in props && props.client !== void 0;

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

@@ -982,10 +982,34 @@ const generateInstanceId = () => {
 	});
 };
 //#endregion
+//#region ../js-client-core/src/browser-globals.ts
+const read = (readValue) => {
+	try {
+		return readValue(globalThis);
+	} catch {
+		return;
+	}
+};
+const readUserAgent = () => read((globals) => {
+	var _globals$navigator;
+	return (_globals$navigator = globals.navigator) === null || _globals$navigator === void 0 ? void 0 : _globals$navigator.userAgent;
+});
+const readHost = () => read((globals) => {
+	var _globals$location;
+	return (_globals$location = globals.location) === null || _globals$location === void 0 ? void 0 : _globals$location.host;
+});
+const localStorageIfAvailable = () => {
+	try {
+		var _localStorage;
+		return (_localStorage = globalThis.localStorage) !== null && _localStorage !== void 0 ? _localStorage : void 0;
+	} catch {
+		return;
+	}
+};
+//#endregion
 //#region ../js-client-core/src/client-session.ts
 const STORAGE_KEY = "configdirector-sdk:instance-id";
 const RECORD_VERSION = 1;
-const MAX_AGE_MS = 360 * 60 * 1e3;
 const STORAGE_DEADLINE_MS = 1e3;
 const CHECKSUM_SALT = "configdirector.instanceId.v1";
 const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -1002,14 +1026,6 @@ const checksumFor = (id, createdAt) => {
 	const low = fnv1a(payload, 2166136261);
 	return fnv1a(`${low}|${payload}`, 16777619).toString(16).padStart(8, "0") + low.toString(16).padStart(8, "0");
 };
-const localStorageIfAvailable = () => {
-	try {
-		var _localStorage;
-		return (_localStorage = globalThis.localStorage) !== null && _localStorage !== void 0 ? _localStorage : void 0;
-	} catch {
-		return;
-	}
-};
 const isUsableRecord = (record) => {
 	if (!record || typeof record !== "object") return false;
 	const { v, id, createdAt, checksum } = record;
@@ -1038,11 +1054,6 @@ const readStoredInstanceId = async (storage, logger) => {
 		logger.debug("[ConfigDirectorClient] The stored instance id failed validation, generating a new one");
 		return { outcome: "nothing usable" };
 	}
-	const age = Date.now() - record.createdAt;
-	if (age < 0 || age >= MAX_AGE_MS) {
-		logger.debug("[ConfigDirectorClient] The stored instance id has expired, generating a new one");
-		return { outcome: "nothing usable" };
-	}
 	return {
 		outcome: "stored",
 		instanceId: record.id
@@ -1262,23 +1273,6 @@ var PollingTransport = class extends AbstractPollingTransport {
 	}
 };
 //#endregion
-//#region ../js-client-core/src/browser-globals.ts
-const read = (readValue) => {
-	try {
-		return readValue(globalThis);
-	} catch {
-		return;
-	}
-};
-const readUserAgent = () => read((globals) => {
-	var _globals$navigator;
-	return (_globals$navigator = globals.navigator) === null || _globals$navigator === void 0 ? void 0 : _globals$navigator.userAgent;
-});
-const readHost = () => read((globals) => {
-	var _globals$location;
-	return (_globals$location = globals.location) === null || _globals$location === void 0 ? void 0 : _globals$location.host;
-});
-//#endregion
 //#region ../shared/src/context-kind.ts
 const CONTEXT_KIND_MAXIMUM_LENGTH = 64;
 const KIND_SAMPLE_MAXIMUM_CHARACTERS = 128;
@@ -1319,15 +1313,190 @@ const admitContext = (context) => {
 	};
 };
 //#endregion
+//#region ../shared/src/utf8-byte-length.ts
+const isHighSurrogate = (codeUnit) => codeUnit >= 55296 && codeUnit <= 56319;
+const isLowSurrogate = (codeUnit) => codeUnit >= 56320 && codeUnit <= 57343;
+const utf8ByteLength = (text) => {
+	let bytes = 0;
+	for (let i = 0; i < text.length; i++) {
+		const codeUnit = text.charCodeAt(i);
+		if (codeUnit <= 127) bytes += 1;
+		else if (codeUnit <= 2047) bytes += 2;
+		else if (isHighSurrogate(codeUnit) && i + 1 < text.length && isLowSurrogate(text.charCodeAt(i + 1))) {
+			bytes += 4;
+			i++;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+//#endregion
+//#region ../js-client-core/src/cached-values.ts
+const 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) => {
+	var _caching$provider;
+	if (connectionPlan.kind === "stay-offline") return {
+		kind: "no cache",
+		reason: "offline mode"
+	};
+	if ((caching === null || caching === void 0 ? void 0 : caching.enabled) === false) return {
+		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 (!provider) return {
+		kind: "no cache",
+		reason: "no provider available"
+	};
+	return {
+		kind: "cache",
+		provider,
+		clientSdkKey: connectionPlan.clientSdkKey
+	};
+};
+const contextTagFor = (context, instanceId) => {
+	var _context$kind;
+	const contextKind = (_context$kind = context === null || context === void 0 ? void 0 : context.kind) !== null && _context$kind !== void 0 ? _context$kind : DEFAULT_CONTEXT_KIND;
+	if ((context === null || context === void 0 ? void 0 : context.id) != null) return {
+		contextKind,
+		contextId: context.id
+	};
+	return {
+		contextKind,
+		anonymousInstanceId: instanceId
+	};
+};
+const sameContextTag = (stored, launch) => {
+	if (stored.contextKind !== launch.contextKind) return false;
+	if ("contextId" in stored && "contextId" in launch) return stored.contextId === launch.contextId;
+	if ("anonymousInstanceId" in stored && "anonymousInstanceId" in launch) return stored.anonymousInstanceId === launch.anonymousInstanceId;
+	return false;
+};
+const decideCachedValuesAdoption = (cachedValues, launchContextTag, hasReceivedLiveValues) => {
+	if (hasReceivedLiveValues) return "live values already arrived";
+	if (!sameContextTag(cachedValues.contextTag, launchContextTag)) return "context mismatch";
+	return "adopt";
+};
+const isContextTag = (candidate) => {
+	if (!candidate || typeof candidate !== "object") return false;
+	const { contextKind, contextId, anonymousInstanceId } = candidate;
+	if (typeof contextKind !== "string") return false;
+	return typeof contextId === "string" || typeof anonymousInstanceId === "string";
+};
+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) => {
+	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";
+};
+var CachedValuesStore = class {
+	constructor(provider, clientSdkKey, logger) {
+		this.provider = provider;
+		this.clientSdkKey = clientSdkKey;
+		this.logger = logger;
+		_defineProperty(this, "warned", /* @__PURE__ */ new Set());
+		_defineProperty(this, "pendingRead", void 0);
+		_defineProperty(this, "queuedCachedValues", void 0);
+		_defineProperty(this, "writing", false);
+	}
+	read() {
+		var _this$pendingRead;
+		(_this$pendingRead = this.pendingRead) !== null && _this$pendingRead !== void 0 || (this.pendingRead = this.readEntry());
+		return this.pendingRead;
+	}
+	replace(cachedValues) {
+		this.queuedCachedValues = cachedValues;
+		this.writeQueued();
+	}
+	async readEntry() {
+		let raw;
+		try {
+			raw = await this.provider.read();
+		} catch (error) {
+			this.warnOnce("read failed", "Could not read the values kept on the device, starting without them:", error);
+			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;
+		}
+	}
+	async writeQueued() {
+		if (this.writing) return;
+		this.writing = true;
+		try {
+			while (this.queuedCachedValues) {
+				const cachedValues = this.queuedCachedValues;
+				this.queuedCachedValues = void 0;
+				await this.writeEntry(cachedValues);
+			}
+		} finally {
+			this.writing = false;
+		}
+	}
+	async writeEntry(cachedValues) {
+		const entry = {
+			formatVersion: ENTRY_FORMAT_VERSION,
+			clientSdkKey: this.clientSdkKey,
+			...cachedValues
+		};
+		const serialized = JSON.stringify(entry);
+		const size = utf8ByteLength(serialized);
+		const limit = this.provider.sizeLimit();
+		if (size > limit) {
+			this.warnOnce("over the size limit", `The values received (${size} bytes) exceed the caching provider's limit of ${limit} bytes, so no values are kept on the device`);
+			await this.removeEntry();
+			return;
+		}
+		try {
+			await this.provider.write(serialized);
+		} catch (error) {
+			this.warnOnce("write failed", "Could not keep the values on the device:", error);
+		}
+	}
+	async removeEntry() {
+		try {
+			await this.provider.remove();
+		} catch (error) {
+			this.warnOnce("remove failed", "Could not remove the values kept on the device:", error);
+		}
+	}
+	warnOnce(warning, message, ...details) {
+		if (this.warned.has(warning)) return;
+		this.warned.add(warning);
+		this.logger.warn(`[ConfigDirectorClient] ${message}`, ...details);
+	}
+};
+//#endregion
 //#region ../js-client-core/src/DefaultConfigDirectorClient.ts
 const MAX_EXPONENTIAL_DELAY = 9;
 var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
-	static from(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions) {
-		if (typeof clientSdkKeyOrOptions === "object") return new DefaultConfigDirectorClient(liveTelemetryClient, void 0, sdkOptions, clientSdkKeyOrOptions);
-		return new DefaultConfigDirectorClient(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions);
+	static from(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions) {
+		if (typeof clientSdkKeyOrOptions === "object") return new DefaultConfigDirectorClient(liveTelemetryClient, void 0, sdkOptions, clientSdkKeyOrOptions, internalClientOptions);
+		return new DefaultConfigDirectorClient(liveTelemetryClient, clientSdkKeyOrOptions, sdkOptions, clientOptions, internalClientOptions);
 	}
 	constructor(liveTelemetryClient, clientSdkKey, sdkOptions, clientOptions, internalClientOptions) {
-		var _clientOptions$logger, _clientOptions$connec, _clientOptions$connec2, _internalClientOption, _internalClientOption2, _clientOptions$hooks, _clientOptions$hooks2, _clientOptions$hooks3, _clientOptions$hooks4, _clientOptions$hooks5;
+		var _clientOptions$logger, _clientOptions$connec, _clientOptions$connec2, _internalClientOption, _internalClientOption2, _clientOptions$hooks, _clientOptions$hooks2, _clientOptions$hooks3, _clientOptions$hooks4, _clientOptions$hooks5, _clientOptions$hooks6;
 		_defineProperty(this, "logger", void 0);
 		_defineProperty(this, "telemetryClient", void 0);
 		_defineProperty(this, "configSet", void 0);
@@ -1342,18 +1511,24 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		_defineProperty(this, "readyPromise", void 0);
 		_defineProperty(this, "readyResolve", void 0);
 		_defineProperty(this, "currentContext", void 0);
+		_defineProperty(this, "submittedContext", void 0);
 		_defineProperty(this, "connectionPlan", void 0);
 		_defineProperty(this, "clientSession", void 0);
+		_defineProperty(this, "cachedValuesStore", void 0);
+		_defineProperty(this, "servingCachedValues", false);
+		_defineProperty(this, "cachedValuesAdoptionStarted", false);
 		this.logger = (_clientOptions$logger = clientOptions === null || clientOptions === void 0 ? void 0 : clientOptions.logger) !== null && _clientOptions$logger !== void 0 ? _clientOptions$logger : createDefaultLogger();
 		this.clientSession = resolveClientSession(this.logger, internalClientOptions === null || internalClientOptions === void 0 ? void 0 : internalClientOptions.instanceIdStorage);
 		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.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) => {
 			var _this$readyResolve;
 			this.hasReceivedConfigSet = true;
+			this.servingCachedValues = false;
 			(_this$readyResolve = this.readyResolve) === null || _this$readyResolve === void 0 || _this$readyResolve.call(this);
 			const removedKeys = this.findKeysRemovedBy(configSet);
 			if (!this.configSet || configSet.kind == "full") this.configSet = configSet;
@@ -1361,6 +1536,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 				...this.configSet.configs,
 				...configSet.configs
 			};
+			this.keepValuesOnTheDevice(this.configSet);
 			const keys = Object.keys(configSet.configs);
 			this.emit("configsUpdated", {
 				keys,
@@ -1382,6 +1558,80 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		this.registerHandler("configsUpdated", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks3 = clientOptions.hooks) === null || _clientOptions$hooks3 === void 0 ? void 0 : _clientOptions$hooks3.configsUpdated);
 		this.registerHandler("contextUpdated", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks4 = clientOptions.hooks) === null || _clientOptions$hooks4 === void 0 ? void 0 : _clientOptions$hooks4.contextUpdated);
 		this.registerHandler("connectionError", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks5 = clientOptions.hooks) === null || _clientOptions$hooks5 === void 0 ? void 0 : _clientOptions$hooks5.connectionError);
+		this.registerHandler("cachedValuesLoaded", clientOptions === null || clientOptions === void 0 || (_clientOptions$hooks6 = clientOptions.hooks) === null || _clientOptions$hooks6 === void 0 ? void 0 : _clientOptions$hooks6.cachedValuesLoaded);
+	}
+	buildCachedValuesStore(cachingPlan) {
+		switch (cachingPlan.kind) {
+			case "no cache":
+				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);
+				store.read();
+				return store;
+			}
+		}
+	}
+	startCachedValuesAdoption() {
+		const store = this.cachedValuesStore;
+		if (!store || this.cachedValuesAdoptionStarted) return;
+		this.cachedValuesAdoptionStarted = true;
+		this.adoptCachedValues(store);
+	}
+	async adoptCachedValues(store) {
+		const read = await store.read();
+		switch (read.outcome) {
+			case "nothing stored":
+			case "unreadable":
+			case "failed": return;
+			case "stored": break;
+		}
+		const { instanceId } = await this.clientSession;
+		const launchContextTag = contextTagFor(this.submittedContext, instanceId);
+		const adoption = decideCachedValuesAdoption(read.cachedValues, launchContextTag, this.hasReceivedConfigSet);
+		switch (adoption) {
+			case "adopt":
+				this.serveCachedValues(read.cachedValues);
+				return;
+			case "live values already arrived":
+			case "context mismatch":
+				this.logger.debug(`[ConfigDirectorClient] The values kept on the device were not adopted: ${adoption}`);
+				return;
+		}
+	}
+	serveCachedValues(cachedValues) {
+		const { environmentId, projectId, configs } = cachedValues;
+		this.configSet = {
+			environmentId,
+			projectId,
+			configs,
+			kind: "full"
+		};
+		this.servingCachedValues = true;
+		const keys = Object.keys(configs);
+		this.emit("cachedValuesLoaded", {});
+		this.emit("configsUpdated", {
+			keys,
+			removedKeys: []
+		});
+		this.updateWatchers(keys);
+		this.logger.debug("[ConfigDirectorClient] Serving the values kept on the device until live values arrive:", { keys });
+	}
+	keepValuesOnTheDevice(configSet) {
+		const store = this.cachedValuesStore;
+		if (!store) return;
+		const context = this.submittedContext;
+		const receivedAt = Date.now();
+		this.clientSession.then(({ instanceId }) => store.replace({
+			contextTag: contextTagFor(context, instanceId),
+			environmentId: configSet.environmentId,
+			projectId: configSet.projectId,
+			configs: configSet.configs,
+			receivedAt
+		}));
+	}
+	servedReason(reason) {
+		return this.servingCachedValues && reason === "found-match" ? "cached" : reason;
 	}
 	registerHandler(event, handler) {
 		if (!handler) return;
@@ -1477,6 +1727,8 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 		return this.currentContext;
 	}
 	async connectToTransport(context, caller) {
+		this.submittedContext = context;
+		if (caller === "initialization") this.startCachedValuesAdoption();
 		try {
 			this.ready = false;
 			this.readyPromise = new Promise((resolve) => {
@@ -1581,6 +1833,7 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 			return defaultValue;
 		}
 		const parseResult = parseConfigValue(configState, defaultValue);
+		const reason = this.servedReason(parseResult.reason);
 		this.telemetryClient.evaluatedConfig({
 			contextId: (_this$currentContext2 = this.currentContext) === null || _this$currentContext2 === void 0 ? void 0 : _this$currentContext2.id,
 			type: configState.type,
@@ -1590,14 +1843,14 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 			evaluatedValue: parseResult.parsedValue,
 			evaluatedValueId: parseResult.parsedValueId,
 			usedDefault: parseResult.usedDefault,
-			evaluationReason: parseResult.reason
+			evaluationReason: reason
 		});
 		this.dispatchEvaluationEvent({
 			key: configKey,
 			value: parseResult.parsedValue,
 			valueId: (_parseResult$parsedVa = parseResult.parsedValueId) !== null && _parseResult$parsedVa !== void 0 ? _parseResult$parsedVa : void 0,
 			isDefaultValue: parseResult.usedDefault,
-			reason: parseResult.reason,
+			reason,
 			context: this.context
 		});
 		this.logger.debug(`[ConfigDirectorClient] Evaluated '${configKey}' to '${parseResult.parsedValue}'`);
@@ -1677,4 +1930,4 @@ var DefaultConfigDirectorClient = class DefaultConfigDirectorClient {
 const INSTALLED_TEST_CLIENT_SLOT = Symbol.for("@configdirector/installed-test-client");
 const readInstalledTestClient = () => globalThis[INSTALLED_TEST_CLIENT_SLOT];
 //#endregion
-export { discardingTelemetryClient as a, isFetchErrorFatal as c, Emitter as d, _defineProperty as f, fetchWithTimeout as i, ConfigDirectorConnectionError as l, readInstalledTestClient as n, createDefaultLogger as o, DefaultConfigDirectorClient as r, nativeValueConfigState as s, INSTALLED_TEST_CLIENT_SLOT as t, ConfigDirectorValidationError as u };
+export { DEFAULT_CACHING_SIZE_LIMIT_BYTES as a, createDefaultLogger as c, ConfigDirectorConnectionError as d, ConfigDirectorValidationError as f, CACHED_VALUES_STORAGE_KEY_PREFIX as i, nativeValueConfigState as l, _defineProperty as m, readInstalledTestClient as n, fetchWithTimeout as o, Emitter as p, DefaultConfigDirectorClient as r, discardingTelemetryClient as s, INSTALLED_TEST_CLIENT_SLOT as t, isFetchErrorFatal as u };

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

@@ -23,7 +23,7 @@ interface ConfigDirectorLogger {
 interface ConfigDirectorLogMessageDecorator {
   decorateMessage(message: string): string;
 }
-type EvaluationReason = "found-match" | "config-state-missing" | "client-not-ready" | "type-mismatch" | "value-missing" | "invalid-number" | "invalid-json" | "invalid-boolean";
+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;
@@ -42,9 +42,11 @@ type ConfigDirectorContext = {
    * The context's identifier. This should be a value that uniquely identifies the user or other
    * entity among contexts of the same {@link kind}.
    * In the case of anonymous users, you could generate a UUID or alternatively not provide
-   * the {@link id} and the SDK will generate a random UUID. However, keep in mind that this
-   * value is used for segmenting contexts in percentage rollouts, and changes to the {@link id}
-   * could result in the context being assigned to a different percentile.
+   * the {@link id}. In a client SDK, ConfigDirector then derives an identifier from an ID the SDK
+   * stores for the app install or the website, so it stays the same until the app is uninstalled
+   * or the site's data is cleared. However, keep in mind that this value is used for segmenting
+   * contexts in percentage rollouts, and changes to the {@link id} could result in the context
+   * being assigned to a different percentile.
    */
   id?: string;
   /**
@@ -100,6 +102,45 @@ type NativeValue = boolean | number | string | NativeJsonValue[] | {
 type NativeValues = Record<string, NativeValue>;
 //#endregion
 //#region ../js-client-core/src/types.d.ts
+/**
+ * A store for the values the client keeps on the device between launches. One provider instance
+ * serves one client: the provider decides where the entry lives, and the SDK owns the entry's
+ * format, which may change between SDK versions.
+ */
+type CachingProvider = {
+  /**
+   * Returns the stored entry, or `null` or `undefined` when nothing is stored.
+   */
+  read(): string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Replaces the stored entry. The SDK never writes an entry larger than {@link sizeLimit}.
+   */
+  write(value: string): void | Promise<void>;
+  /**
+   * Removes the stored entry.
+   */
+  remove(): void | Promise<void>;
+  /**
+   * The largest entry, in UTF-8 bytes, the provider accepts. When the values received from
+   * ConfigDirector exceed it, the SDK removes the stored entry and keeps nothing on the device.
+   */
+  sizeLimit(): number;
+};
+/**
+ * Options for the values the client keeps on the device, served on the next launch of the same
+ * context until live values arrive. Ignored in `offline` mode.
+ */
+type CachingOptions = {
+  /**
+   * Whether to keep the last values received on the device. Defaults to `true`.
+   */
+  enabled?: boolean;
+  /**
+   * The store for the values. Defaults to the platform's own store: `localStorage` in the
+   * browser, AsyncStorage on React Native.
+   */
+  provider?: CachingProvider;
+};
 /**
  * One value an offline client serves for a config key. The config type follows from the value: a
  * boolean, an integral number (`integer`), any other number (`float`), a string, or a plain object
@@ -170,6 +211,12 @@ type ConfigDirectorClientOptions = {
    * Connection options
    */
   connection?: ConnectionOptions;
+  /**
+   * Options for the values the client keeps on the device between launches. The last values
+   * received are kept by default and served, with the evaluation reason `cached`, on the next
+   * launch of the same context until live values arrive. See {@link CachingOptions}.
+   */
+  caching?: CachingOptions;
   /**
    * A logger that implements {@link ConfigDirectorLogger}. It defaults to the ConfigDirector console
    * logger set to 'warn' level.
@@ -207,6 +254,7 @@ type ClientHooks = {
   contextUpdated?: HookHandler<"contextUpdated"> | HookHandler<"contextUpdated">[];
   configEvaluated?: HookHandler<"configEvaluated"> | HookHandler<"configEvaluated">[];
   connectionError?: HookHandler<"connectionError"> | HookHandler<"connectionError">[];
+  cachedValuesLoaded?: HookHandler<"cachedValuesLoaded"> | HookHandler<"cachedValuesLoaded">[];
 };
 type ClientConnectAction = "initialization" | "context update" | "network resume";
 type HookHandler<TEvent extends keyof ClientEvents> = (payload: ClientEvents[TEvent]) => void;
@@ -227,6 +275,7 @@ type ClientEvents = {
   connectionError: {
     error: Error;
   };
+  cachedValuesLoaded: Record<string, never>;
 };
 type WatchHandler<T extends ConfigValueType> = (message: T) => void;
 /**
@@ -348,4 +397,4 @@ interface ConfigDirectorClient extends EventProvider<ClientEvents> {
   dispose(): void;
 }
 //#endregion
-export { OfflineValues as a, NativeValues as c, ConfigDirectorLogger as d, ConfigDirectorLoggingLevel as f, OfflineValue as i, ConfigDirectorContext as l, ConnectionMode as m, ConfigDirectorClient as n, NativeJsonValue as o, ConfigValueType as p, ConfigDirectorClientOptions as r, NativeValue as s, ClientHooks as t, ConfigDirectorLogMessageDecorator as u };
+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 };

package/package.json

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