feat(openfeature): DatadogOfflineOpenFeatureProvider [PR3] (FFL-2689, FFL-2690)

[btthomas]

Offline feature flags — related PRs

• Plan: Offline precomputed feature flags for the React Native SDK #1326
• Parse & decode ConfigurationWire: feat(flags): ConfigurationWire parse + precomputed decode [PR1] (FFL-2686, FFL-2687) #1330
• Core offline API (FlagsClient.setConfiguration): feat(flags): FlagsClient.setConfiguration + context matching [PR2] (FFL-2688) #1331
• Offline OpenFeature provider: feat(openfeature): DatadogOfflineOpenFeatureProvider [PR3] (FFL-2689, FFL-2690) #1332 ← you are here

---

Summary

Adds DatadogOfflineOpenFeatureProvider — a never-fetch OpenFeature provider for offline initialization — and the public exports for the offline API.

The offline provider evaluates flags and reports exposures/RUM exactly like DatadogOpenFeatureProvider, but never fetches configuration from the network: initialize/onContextChange set the evaluation context without a request, and the configuration is supplied via setConfiguration. A precomputed configuration carries the context it was computed for, so no separate OpenFeature.setContext call is needed.

• Both providers share an internal DatadogCoreOpenFeatureProvider base that owns the flag client, event emitter, and flag evaluation; only the context-sourcing (initialize/onContextChange) differs.
• Public exports — core: configurationFromString, configurationToString, ParsedFlagsConfiguration. OpenFeature: DatadogOfflineOpenFeatureProvider and a re-exported configurationFromString. The README documents offline usage.

No native changes: the offline path uses the existing native enable + exposure tracking and skips the native fetch; evaluation is all JS.

const provider = new DatadogOfflineOpenFeatureProvider();
provider.setConfiguration(configurationFromString(wire)); // no network
await OpenFeature.setProviderAndWait(provider);

const enabled = OpenFeature.getClient().getBooleanValue('new-feature', false);

Context handling: a mismatch is an error state

A precomputed configuration is a single-subject snapshot served against the context it was computed for. A runtime context that does not match that embedded context (compared after normalization) cannot be served, so the provider enters the OpenFeature ERROR state and evaluations fall back to the app's coded defaults (this replaces the earlier "ignore the mismatch and keep serving" behavior). See #1331 for the core model and error codes.

• Lifecycle (context path): onContextChange is synchronous and throws the precise OpenFeature error (InvalidContextError / ProviderNotReadyError / GeneralError) on a non-servable context, so the Web SDK transitions straight to ERROR with no async race (a resolving handler would be unconditionally set back to READY). A matching context — or a cleared/empty one — returns normally and the SDK recovers to READY. initialize likewise throws unless the provider can serve, so registering before any configuration starts in ERROR and recovers when a valid config loads.
• setConfiguration (outside the lifecycle): emits PROVIDER_ERROR (with the spec's top-level errorCode) when the configuration cannot be served, and emits PROVIDER_READY then PROVIDER_CONFIGURATION_CHANGED when recovering from an error; a healthy (re)load emits only PROVIDER_CONFIGURATION_CHANGED.
• Empty context = no external override: clearContext() / setContext({}) re-adopt the embedded context (order-independent), so they recover rather than error — subject to the effective-context caveat below.
• Requires @openfeature/web-sdk ^1.8.0, whose static-context lifecycle it relies on: the SDK owns the PROVIDER_RECONCILING / PROVIDER_CONTEXT_CHANGED events, and (a documented SDK limitation) drops the error code from the lifecycle-generated PROVIDER_ERROR event — the thrown error type is still correct for direct callers.

Recommended setup (documented in the README): bind the offline provider to a dedicated OpenFeature domain, give that domain an explicit empty context, and use a unique Datadog clientName (separate domains otherwise share DdFlags.getClient('default')). Note that clearContext(domain) falls back to the global context (which may be non-empty and mismatching, keeping the provider in ERROR), and the context split: OpenFeature hooks see the OpenFeature context ({} when unset) while Datadog exposure tracking uses the embedded context.

Intentional limitation: the offline configuration is applied only in the JS layer and is not propagated to the native SDKs. Native propagation is out of scope for this iteration, so hybrid apps that also read flags natively will have inconsistent configuration between JS and native. The example app therefore does not call OpenFeature.setContext, and its online/offline toggle uses distinct clientNames so the two providers don't share a FlagsClient.

Tests

react-native-openfeature (27 tests) covers both providers — the offline provider never fetches, serves against the configuration's embedded context, throws synchronously to enter ERROR on a mismatch (recovering on a matching/cleared context), and emits PROVIDER_ERROR with a top-level error code and PROVIDER_READY + PROVIDER_CONFIGURATION_CHANGED on recovery; the online provider still fetches on context. A real-FlagsClient, OpenFeature-bound integration test asserts the SDK provider status through ERROR/READY transitions (mismatch, clearContext, provider-first, setConfiguration recovery) plus domain/global-context isolation. The core flags/ suite passes. Lint and tsc are clean on both packages.

Example App

iOS

Android

[Copilot]

Pull request overview

This PR adds an offline OpenFeature provider for the React Native Datadog SDK, enabling feature-flag evaluation from a precomputed configuration supplied by the app (no network fetch), while keeping evaluation + exposure/RUM tracking aligned with the existing online provider.

Changes:

• Introduces DatadogOfflineOpenFeatureProvider and refactors shared logic into DatadogCoreOpenFeatureProvider.
• Adds offline configuration plumbing/events (context set without fetch; emit ConfigurationChanged / Error / Ready as appropriate).
• Publicly exports offline configuration helpers/types from core (configurationFromString, configurationToString, ParsedFlagsConfiguration) and re-exports configurationFromString from the OpenFeature package; updates docs + adds tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/react-native-openfeature/src/provider.ts	Refactors online provider to extend shared core provider; keeps fetch-on-context behavior.
packages/react-native-openfeature/src/offlineProvider.ts	Adds offline provider that never fetches; supports setConfiguration + event mapping.
packages/react-native-openfeature/src/mappers.ts	Extracts OF → Datadog context conversion + empty-context detection helper.
packages/react-native-openfeature/src/index.ts	Exports offline provider and re-exports configurationFromString.
packages/react-native-openfeature/src/coreProvider.ts	Adds shared base provider owning FlagsClient, event emitter, and evaluations.
packages/react-native-openfeature/src/tests/provider.test.ts	Adds unit coverage for online provider behavior after refactor.
packages/react-native-openfeature/src/tests/offlineProvider.test.ts	Adds unit coverage for offline provider no-fetch behavior + events.
packages/react-native-openfeature/src/tests/offlineProvider.integration.test.ts	Adds integration coverage using real FlagsClient for offline flow edge cases.
packages/react-native-openfeature/README.md	Documents offline initialization flow and usage.
packages/core/src/index.tsx	Exposes configuration parse/serialize utilities and parsed config type publicly.
packages/core/src/flags/FlagsClient.ts	Returns configuration outcome status from offline context/config APIs for provider event mapping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sbarrio]

This is a good point, we should not mutate the user provided options parameter.

[leoromanovsky]

nit: no network request is expected here, that was going to be at setProviderAndAwait

[leoromanovsky]

good note

[btthomas]

I actually decided this doesn't make sense in the OfflineProvider when setConfiguration is called with precomputed variants. So instead, if the customer calls setContext with a mismatch, we'll keep serving the precomputed but emit a warning.

[leoromanovsky]

In the readme below you mention an error is thrown if the user provides their own context; is that modeled here or elsewhere?

[btthomas]

We changed the design: a mismatched context is no longer an error. The README has been updated.

[btthomas]

And now I need to walk all of that back from yesterday's conversation.

[evazorro]

One nit, but approving from now!

[sbarrio]

Perhaps replacing the return with an else would look a bit cleaner.

[sbarrio]

Suggested change

	private emitConfigurationOutcome(outcome: ConfigurationOutcome): void {
	if (outcome === 'ready') {
	if (this.hasEmittedError) {
	// Recover from a prior error state: emit READY to clear the provider status
	// (a bare CONFIGURATION_CHANGED would not clear it).
	this.hasEmittedError = false;
	this.events.emit(ProviderEvents.Ready);
	} else {
	// The provider is already READY from initialize; a (re)loaded configuration is
	// signalled as a configuration change.
	this.events.emit(ProviderEvents.ConfigurationChanged);
	}
	} else if (outcome === 'invalid') {
	this.hasEmittedError = true;
	this.events.emit(ProviderEvents.Error, {
	message:
	'The Datadog offline provider cannot serve the loaded configuration (invalid).'
	});
	}
	// 'none' — no configuration engaged yet; nothing to signal. A runtime context that
	// does not match a precomputed snapshot is not an error: the client ignores it
	// (serving the snapshot for its embedded context) and warns.
	}
	}
	private emitConfigurationOutcome(outcome: ConfigurationOutcome): void {
	if (outcome === 'none') return;
	if (outcome === 'invalid') {
	this.hasEmittedError = true;
	this.events.emit(ProviderEvents.Error, {
	message: 'The Datadog offline provider cannot serve the loaded configuration (invalid).'
	});
	return;
	}
	// outcome === 'ready'
	if (this.hasEmittedError) {
	// Recover from a prior error: emit READY to clear provider status
	// (a bare CONFIGURATION_CHANGED would not clear it).
	this.hasEmittedError = false;
	this.events.emit(ProviderEvents.Ready);
	} else {
	this.events.emit(ProviderEvents.ConfigurationChanged);
	}
	}