@configdirector/react-native-sdk 1.5.0 → 1.6.0

package/README.md

@@ -32,6 +32,49 @@ function Home() {
 
 Full details are in the [official documentation](https://docs.configdirector.com/sdks/mobile/react-native).
 
+## Test your code
+
+`@configdirector/react-native-sdk/testing` creates a real client connected to an in-memory server that
+your test controls. Render the production `ConfigDirectorProvider` with its `client` prop, or install
+the test client for components that render their own provider, such as `App`.
+
+```tsx
+import { act, render } from "@testing-library/react-native";
+import { ConfigDirectorProvider } from "@configdirector/react-native-sdk";
+import { createTestClient, installTestClient } from "@configdirector/react-native-sdk/testing";
+
+const testClient = createTestClient({ values: { "dark-mode": true } });
+
+const view = await render(
+  <ConfigDirectorProvider client={testClient.client}>
+    <Home />
+  </ConfigDirectorProvider>,
+);
+await view.findByText("dark-mode: true");
+
+await act(() => testClient.setValue("dark-mode", false));
+view.getByText("dark-mode: false");
+
+const uninstall = installTestClient(testClient);
+await render(<App />);
+uninstall();
+```
+
+The provider renders its children before initialization completes, so the first assertion uses
+`findBy…`. Wrap `setValue`, `removeValue`, and `replaceValues` in `act()`. React Native Testing
+Library 14 made `render`, `fireEvent`, and `act` asynchronous, so the example awaits them; the same
+code works with version 13. The test client also holds
+or fails `initialize` and `updateContext`, and records every context in `contextUpdates`. A provider
+never disposes a client it was given, removes its handlers and its `AppState` and NetInfo
+subscriptions when it unmounts, and does not initialize a client that is ready or initializing.
+Under the React Native Jest preset, `AppState.addEventListener` never calls its listener, so the
+provider never pauses on its own; a test that calls the listener runs the production pause and
+resume against the test client. The package and its dependency `@noble/hashes` are ESM, and the
+package's files are `.mjs` files, which the `jest-expo` and `@react-native/jest-preset` presets do not
+transform, so a Jest setup must let `transformIgnorePatterns` transform both packages and add a
+`transform` entry for `.mjs` files; the documentation shows the configuration for both presets.
+`jest-expo` requires `@react-native/jest-preset` as a peer dependency, so install it in either case.
+
 ## Documentation
 
 Refer to the [official documentation for the React Native SDK](https://docs.configdirector.com/sdks/mobile/react-native).

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

@@ -0,0 +1,157 @@
+import { i as ConfigDirectorContext, n as ConfigDirectorClient, o as ConfigDirectorLogger } from "./types-fcPMBgiX.mjs";
+
+//#region ../shared/src/errors.d.ts
+declare class ConfigDirectorConnectionError extends Error {
+  readonly name: string;
+  readonly status?: number;
+  constructor(message: string, status?: number);
+}
+declare class ConfigDirectorValidationError extends Error {
+  readonly name: string;
+  constructor(message: string);
+}
+//#endregion
+//#region ../shared/src/testing/values.d.ts
+type TestJsonValue = boolean | number | string | null | TestJsonValue[] | {
+  [key: string]: TestJsonValue;
+};
+type TestValue = boolean | number | string | TestJsonValue[] | {
+  [key: string]: TestJsonValue;
+};
+type TestValues = Record<string, TestValue>;
+//#endregion
+//#region ../js-client-core/src/testing/TestClient.d.ts
+/**
+ * Options for {@link createTestClient}. Every option is optional.
+ */
+type TestClientOptions = {
+  /**
+   * The config values the test client serves once its client connects, keyed by config key. The
+   * config type follows from each value: a boolean, an integral number (`integer`), any other
+   * number (`float`), a string, or a plain object or array (`json`).
+   */
+  values?: TestValues;
+  /**
+   * The connection timeout of the SDK client, in milliseconds. It bounds how long a held
+   * `initialize` or `updateContext` waits. Defaults to the SDK's production timeout.
+   */
+  timeout?: number;
+  /**
+   * The logger the SDK client uses. Defaults to the SDK's console logger at `warn` level.
+   */
+  logger?: ConfigDirectorLogger;
+};
+/**
+ * A real ConfigDirector client connected to an in-memory server that the test controls.
+ *
+ * The client under {@link TestClient.client} is the SDK's production client: value parsing, watchers,
+ * events, and readiness behave as they do against ConfigDirector. Only the network connection and
+ * telemetry are replaced, so no request is ever made and nothing is left running after the client is
+ * disposed.
+ */
+interface TestClient {
+  /**
+   * The SDK client to hand to the code under test. It starts uninitialized, like a production
+   * client; `initialize` completes at once with the seeded values unless initialization is held.
+   */
+  readonly client: ConfigDirectorClient;
+  /**
+   * Stores `value` under `key` and, when the client is connected, delivers it as an update, so
+   * reads, watchers, and `configsUpdated` handlers see it.
+   */
+  setValue(key: string, value: TestValue): void;
+  /**
+   * Removes `key` and, when the client is connected, delivers a full update without it, so reads
+   * fall back to the in-code default value and watchers of `key` receive that default.
+   */
+  removeValue(key: string): void;
+  /**
+   * Replaces every stored value with `values`, disarms any armed hold or failure, and, when the
+   * client is connected, delivers the new values as a full update.
+   */
+  replaceValues(values: TestValues): void;
+  /**
+   * Makes the next `initialize` wait until {@link completeInitialization} or
+   * {@link failInitialization} is called, or until the client's timeout elapses.
+   */
+  holdInitialization(): void;
+  /**
+   * Delivers the stored values to a held `initialize`, so it completes with the client ready. When
+   * a hold is armed but no `initialize` has started, it disarms the hold instead.
+   */
+  completeInitialization(): void;
+  /**
+   * Fails a held `initialize` with an unrecoverable connection error, or arms the next `initialize`
+   * to fail. `initialize` completes promptly with the client not ready and `connectionError` fires.
+   */
+  failInitialization(): void;
+  /**
+   * Makes the next `updateContext` wait until {@link completeContextUpdate} or
+   * {@link failContextUpdate} is called, or until the client's timeout elapses.
+   */
+  holdContextUpdate(): void;
+  /**
+   * Delivers the stored values to a held `updateContext`, or disarms an armed hold that no
+   * `updateContext` has picked up.
+   */
+  completeContextUpdate(): void;
+  /**
+   * Fails a held `updateContext` with an unrecoverable connection error, or arms the next
+   * `updateContext` to fail.
+   */
+  failContextUpdate(): void;
+  /**
+   * The context of every `initialize` and `updateContext` call, in call order. `initialize` without
+   * a context records an empty context. Resumes are not recorded.
+   */
+  readonly contextUpdates: ConfigDirectorContext[];
+}
+//#endregion
+//#region ../js-client-core/src/testing/installTestClient.d.ts
+/**
+ * Makes every `ConfigDirectorProvider` mounted without a `client` prop, and every client
+ * `withProvider` would build, use `testClient.client` instead of building a client, until the
+ * returned function uninstalls it. Construction props such as `sdkKey` are ignored while installed;
+ * `context` and `hooks` apply to the installed client as they do for a `client` prop. A provider
+ * reads the installed client when it is constructed, so install before rendering.
+ *
+ * Installing again replaces the installed test client. Each uninstall function restores the test
+ * client that was installed when it was created, so nested installs are uninstalled in reverse order.
+ *
+ * @param testClient The test client whose `client` providers should use
+ * @returns A function that uninstalls it
+ *
+ * @example
+ * let uninstallTestClient: () => void;
+ * beforeEach(() => {
+ *   testClient = createTestClient({ values: { "new-checkout": true } });
+ *   uninstallTestClient = installTestClient(testClient);
+ * });
+ * afterEach(() => uninstallTestClient());
+ */
+declare const installTestClient: (testClient: TestClient) => (() => void);
+//#endregion
+//#region src/testing.d.ts
+/**
+ * Creates a {@link TestClient}: a real `ConfigDirectorClient` connected to an in-memory server
+ * that the test controls. No network connection is opened and no telemetry is sent. Render with
+ * `<ConfigDirectorProvider client={testClient.client}>`, or install it with `installTestClient` for
+ * components that render their own provider.
+ *
+ * @param options {@link TestClientOptions}: the initial values, the client's timeout, and its logger
+ * @returns A {@link TestClient} whose `client` is passed to the code under test
+ *
+ * @example
+ * import { createTestClient } from "@configdirector/react-native-sdk/testing";
+ *
+ * const testClient = createTestClient({ values: { "new-checkout": true } });
+ * const view = render(
+ *   <ConfigDirectorProvider client={testClient.client}>
+ *     <Home />
+ *   </ConfigDirectorProvider>,
+ * );
+ * act(() => testClient.setValue("new-checkout", false));
+ */
+declare const createTestClient: (options?: TestClientOptions) => TestClient;
+//#endregion
+export { ConfigDirectorConnectionError, ConfigDirectorValidationError, type TestClient, type TestClientOptions, type TestJsonValue, type TestValue, type TestValues, createTestClient, installTestClient };

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

@@ -0,0 +1,398 @@
+import { c as ConfigDirectorConnectionError, d as _defineProperty, l as ConfigDirectorValidationError, o as createDefaultLogger, r as DefaultConfigDirectorClient, t as INSTALLED_TEST_CLIENT_SLOT, u as Emitter } from "./installedTestClient-CxGEAMOE.mjs";
+//#region ../shared/src/testing/values.ts
+const encodeTestValue$1 = (key, value) => {
+	if (key.trim().length == 0) throw new ConfigDirectorValidationError("Invalid config key. The key of a test value cannot be empty.");
+	return encode(key, value);
+};
+const encode = (key, value) => {
+	switch (typeof value) {
+		case "boolean": return {
+			type: "boolean",
+			value: value ? "true" : "false"
+		};
+		case "number": return encodeNumber(key, value);
+		case "string": return {
+			type: "string",
+			value
+		};
+		case "object": if (value !== null) {
+			assertJsonContents(key, value, "");
+			return {
+				type: "json",
+				value: JSON.stringify(value)
+			};
+		}
+	}
+	throw new ConfigDirectorValidationError(`Invalid test value for '${key}': ${describe(value)}. Use a boolean, a number, a string, a plain object, or an array.`);
+};
+const encodeNumber = (key, value) => {
+	if (!Number.isFinite(value)) throw new ConfigDirectorValidationError(`Invalid test value for '${key}': ${describe(value)} is not a finite number.`);
+	if (Number.isInteger(value)) {
+		if (!Number.isSafeInteger(value)) throw new ConfigDirectorValidationError(`Invalid test value for '${key}': ${value} is not a safe integer, so the SDK could not read it back exactly.`);
+		return {
+			type: "integer",
+			value: String(value)
+		};
+	}
+	return {
+		type: "float",
+		value: toPlainDecimal(value)
+	};
+};
+const toPlainDecimal = (value) => {
+	const text = String(value);
+	const exponentIndex = text.indexOf("e-");
+	if (exponentIndex < 0) return text;
+	const sign = text.startsWith("-") ? "-" : "";
+	const [integerDigits = "", fractionDigits = ""] = text.slice(sign.length, exponentIndex).split(".");
+	const leadingZeros = Number(text.slice(exponentIndex + 2)) - integerDigits.length;
+	return `${sign}0.${"0".repeat(leadingZeros)}${integerDigits}${fractionDigits}`;
+};
+const assertJsonContents = (key, value, path) => {
+	if (value === null || typeof value === "boolean" || typeof value === "string") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw invalidJsonContents(key, path, `${describe(value)} is not a finite number`);
+		return;
+	}
+	if (Array.isArray(value)) {
+		value.forEach((item, index) => assertJsonContents(key, item, `${path}[${index}]`));
+		return;
+	}
+	if (isPlainObject(value)) {
+		for (const [property, item] of Object.entries(value)) assertJsonContents(key, item, path ? `${path}.${property}` : property);
+		return;
+	}
+	throw invalidJsonContents(key, path, `${describe(value)} cannot be encoded as JSON`);
+};
+const invalidJsonContents = (key, path, problem) => new ConfigDirectorValidationError(`Invalid test value for '${key}'${path ? ` at '${path}'` : ""}: ${problem}. JSON contents can hold booleans, finite numbers, strings, null, arrays, and plain objects.`);
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const describe = (value) => {
+	if (value === null) return "null";
+	if (typeof value === "function") return "a function";
+	if (typeof value === "object") {
+		var _value$constructor$na, _value$constructor;
+		return `a ${(_value$constructor$na = (_value$constructor = value.constructor) === null || _value$constructor === void 0 ? void 0 : _value$constructor.name) !== null && _value$constructor$na !== void 0 ? _value$constructor$na : "object"} instance`;
+	}
+	if (typeof value === "symbol") return "a symbol";
+	return String(value);
+};
+//#endregion
+//#region ../js-client-core/src/testing/values.ts
+const encodeTestValue = (key, value, revision) => {
+	const encoded = encodeTestValue$1(key, value);
+	return {
+		id: `test-config:${key}`,
+		key,
+		type: encoded.type,
+		value: encoded.value,
+		valueId: `test-value:${key}:${revision}`
+	};
+};
+//#endregion
+//#region ../js-client-core/src/testing/InMemoryConnection.ts
+const TEST_ENVIRONMENT = {
+	environmentId: "test-environment",
+	projectId: "test-project"
+};
+const controlledAttemptFor = (reason) => {
+	switch (reason) {
+		case "initialization": return "initialize";
+		case "context update": return "updateContext";
+		default: return;
+	}
+};
+var InMemoryConnection = class {
+	constructor(logger, values) {
+		this.logger = logger;
+		_defineProperty(this, "emitter", new Emitter());
+		_defineProperty(this, "configs", /* @__PURE__ */ new Map());
+		_defineProperty(this, "recordedContexts", []);
+		_defineProperty(this, "pendingDeliveries", []);
+		_defineProperty(this, "armed", {
+			initialize: "nothing",
+			updateContext: "nothing"
+		});
+		_defineProperty(this, "pendingHold", void 0);
+		_defineProperty(this, "connected", false);
+		_defineProperty(this, "delivering", false);
+		_defineProperty(this, "revision", 0);
+		_defineProperty(this, "attemptGeneration", 0);
+		_defineProperty(this, "on", (name, handler) => this.emitter.on(name, handler));
+		_defineProperty(this, "off", (name, handler) => this.emitter.off(name, handler));
+		this.store(values);
+	}
+	get contextUpdates() {
+		return [...this.recordedContexts];
+	}
+	setValue(key, value) {
+		const configState = encodeTestValue(key, value, ++this.revision);
+		this.configs.set(key, configState);
+		this.deliverIfConnected({
+			...TEST_ENVIRONMENT,
+			kind: "delta",
+			configs: { [key]: configState }
+		});
+	}
+	removeValue(key) {
+		this.configs.delete(key);
+		this.deliverIfConnected(this.fullUpdate());
+	}
+	replaceValues(values) {
+		const encoded = this.encodeAll(values);
+		this.configs.clear();
+		encoded.forEach((configState, key) => this.configs.set(key, configState));
+		this.armed.initialize = "nothing";
+		this.armed.updateContext = "nothing";
+		this.deliverIfConnected(this.fullUpdate());
+	}
+	hold(attempt) {
+		this.armed[attempt] = "hold";
+	}
+	complete(attempt) {
+		var _this$pendingHold;
+		if (((_this$pendingHold = this.pendingHold) === null || _this$pendingHold === void 0 ? void 0 : _this$pendingHold.attempt) === attempt) this.pendingHold.complete();
+		else if (this.armed[attempt] === "hold") this.armed[attempt] = "nothing";
+	}
+	fail(attempt) {
+		var _this$pendingHold2;
+		if (((_this$pendingHold2 = this.pendingHold) === null || _this$pendingHold2 === void 0 ? void 0 : _this$pendingHold2.attempt) === attempt) this.pendingHold.fail();
+		else this.armed[attempt] = "failure";
+	}
+	connect(context, timeout, reason) {
+		this.endAttempt();
+		const attempt = controlledAttemptFor(reason);
+		if (!attempt) return this.connectNow();
+		this.recordedContexts.push(context);
+		const armed = this.armed[attempt];
+		this.armed[attempt] = "nothing";
+		switch (armed) {
+			case "failure": return this.failNow(reason);
+			case "hold": return this.holdNow(attempt, reason, timeout);
+			default: return this.connectNow();
+		}
+	}
+	clear() {
+		this.emitter.clear();
+	}
+	close() {
+		this.endAttempt();
+	}
+	dispose() {
+		this.close();
+		this.clear();
+	}
+	endAttempt() {
+		var _this$pendingHold3;
+		this.attemptGeneration++;
+		this.connected = false;
+		(_this$pendingHold3 = this.pendingHold) === null || _this$pendingHold3 === void 0 || _this$pendingHold3.end();
+	}
+	connectNow() {
+		const connected = Promise.resolve(this);
+		this.scheduleFirstDelivery();
+		return connected;
+	}
+	holdNow(attempt, reason, timeout) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				var _this$pendingHold4;
+				return (_this$pendingHold4 = this.pendingHold) === null || _this$pendingHold4 === void 0 ? void 0 : _this$pendingHold4.end();
+			}, timeout);
+			const release = () => {
+				clearTimeout(timer);
+				this.pendingHold = void 0;
+			};
+			this.pendingHold = {
+				attempt,
+				end: () => {
+					release();
+					resolve(this);
+				},
+				complete: () => {
+					release();
+					resolve(this);
+					this.scheduleFirstDelivery();
+				},
+				fail: () => {
+					release();
+					const error = this.fatalError(reason);
+					this.emitter.emit("connectionError", error);
+					reject(error);
+				}
+			};
+		});
+	}
+	failNow(reason) {
+		const error = this.fatalError(reason);
+		this.emitter.emit("connectionError", error);
+		return Promise.reject(error);
+	}
+	fatalError(reason) {
+		return new ConfigDirectorConnectionError(`Connection failed with status: 401. Error: the test client failed this ${reason}. This is an unrecoverable error, will not attempt to reconnect.`, 401);
+	}
+	scheduleFirstDelivery() {
+		const generation = this.attemptGeneration;
+		Promise.resolve().then(() => {}).then(() => {
+			if (generation !== this.attemptGeneration) return;
+			this.connected = true;
+			this.deliver(this.fullUpdate());
+		});
+	}
+	deliverIfConnected(configSet) {
+		if (this.connected) this.deliver(configSet);
+	}
+	deliver(configSet) {
+		this.pendingDeliveries.push(configSet);
+		if (this.delivering) return;
+		this.delivering = true;
+		try {
+			let next = this.pendingDeliveries.shift();
+			while (next) {
+				this.emitCaught(next);
+				next = this.pendingDeliveries.shift();
+			}
+		} finally {
+			this.delivering = false;
+		}
+	}
+	emitCaught(configSet) {
+		try {
+			this.emitter.emit("configSetReceived", configSet);
+		} catch (error) {
+			this.logger.error("[InMemoryConnection] Error dispatching a config update from the test client: ", error);
+		}
+	}
+	fullUpdate() {
+		return {
+			...TEST_ENVIRONMENT,
+			kind: "full",
+			configs: Object.fromEntries(this.configs)
+		};
+	}
+	store(values) {
+		this.encodeAll(values).forEach((configState, key) => this.configs.set(key, configState));
+	}
+	encodeAll(values) {
+		const encoded = /* @__PURE__ */ new Map();
+		for (const [key, value] of Object.entries(values)) encoded.set(key, encodeTestValue(key, value, ++this.revision));
+		return encoded;
+	}
+};
+//#endregion
+//#region ../js-client-core/src/testing/TestClient.ts
+const TEST_CLIENT_SDK_KEY = "test-client";
+const noopTelemetryClient = {
+	updateContext: async () => {},
+	evaluatedConfig: () => {},
+	close: async () => {}
+};
+var InMemoryTestClient = class {
+	constructor(client, connection) {
+		this.client = client;
+		this.connection = connection;
+	}
+	setValue(key, value) {
+		this.connection.setValue(key, value);
+	}
+	removeValue(key) {
+		this.connection.removeValue(key);
+	}
+	replaceValues(values) {
+		this.connection.replaceValues(values);
+	}
+	holdInitialization() {
+		this.connection.hold("initialize");
+	}
+	completeInitialization() {
+		this.connection.complete("initialize");
+	}
+	failInitialization() {
+		this.connection.fail("initialize");
+	}
+	holdContextUpdate() {
+		this.connection.hold("updateContext");
+	}
+	completeContextUpdate() {
+		this.connection.complete("updateContext");
+	}
+	failContextUpdate() {
+		this.connection.fail("updateContext");
+	}
+	get contextUpdates() {
+		return this.connection.contextUpdates;
+	}
+};
+const createTestClient$1 = (sdkOptions, options) => {
+	var _options$logger, _options$values;
+	const logger = (_options$logger = options === null || options === void 0 ? void 0 : options.logger) !== null && _options$logger !== void 0 ? _options$logger : createDefaultLogger();
+	const connection = new InMemoryConnection(logger, (_options$values = options === null || options === void 0 ? void 0 : options.values) !== null && _options$values !== void 0 ? _options$values : {});
+	return new InMemoryTestClient(new DefaultConfigDirectorClient(noopTelemetryClient, TEST_CLIENT_SDK_KEY, sdkOptions, {
+		logger,
+		connection: { timeout: options === null || options === void 0 ? void 0 : options.timeout }
+	}, { transport: connection }), connection);
+};
+//#endregion
+//#region ../js-client-core/src/testing/installTestClient.ts
+/**
+* Makes every `ConfigDirectorProvider` mounted without a `client` prop, and every client
+* `withProvider` would build, use `testClient.client` instead of building a client, until the
+* returned function uninstalls it. Construction props such as `sdkKey` are ignored while installed;
+* `context` and `hooks` apply to the installed client as they do for a `client` prop. A provider
+* reads the installed client when it is constructed, so install before rendering.
+*
+* Installing again replaces the installed test client. Each uninstall function restores the test
+* client that was installed when it was created, so nested installs are uninstalled in reverse order.
+*
+* @param testClient The test client whose `client` providers should use
+* @returns A function that uninstalls it
+*
+* @example
+* let uninstallTestClient: () => void;
+* beforeEach(() => {
+*   testClient = createTestClient({ values: { "new-checkout": true } });
+*   uninstallTestClient = installTestClient(testClient);
+* });
+* afterEach(() => uninstallTestClient());
+*/
+const installTestClient = (testClient) => {
+	const slot = globalThis;
+	const previous = slot[INSTALLED_TEST_CLIENT_SLOT];
+	slot[INSTALLED_TEST_CLIENT_SLOT] = testClient.client;
+	return () => {
+		slot[INSTALLED_TEST_CLIENT_SLOT] = previous;
+	};
+};
+//#endregion
+//#region src/testing.ts
+/**
+* Creates a {@link TestClient}: a real `ConfigDirectorClient` connected to an in-memory server
+* that the test controls. No network connection is opened and no telemetry is sent. Render with
+* `<ConfigDirectorProvider client={testClient.client}>`, or install it with `installTestClient` for
+* components that render their own provider.
+*
+* @param options {@link TestClientOptions}: the initial values, the client's timeout, and its logger
+* @returns A {@link TestClient} whose `client` is passed to the code under test
+*
+* @example
+* import { createTestClient } from "@configdirector/react-native-sdk/testing";
+*
+* const testClient = createTestClient({ values: { "new-checkout": true } });
+* const view = render(
+*   <ConfigDirectorProvider client={testClient.client}>
+*     <Home />
+*   </ConfigDirectorProvider>,
+* );
+* act(() => testClient.setValue("new-checkout", false));
+*/
+const createTestClient = (options) => {
+	return createTestClient$1({
+		sdkName: "react-native-sdk",
+		sdkVersion: "1.6.0"
+	}, options);
+};
+//#endregion
+export { ConfigDirectorConnectionError, ConfigDirectorValidationError, createTestClient, installTestClient };