@launchdarkly/js-client-sdk-common 1.21.0 → 1.23.0

package/dist/cjs/index.cjs

@@ -289,35 +289,290 @@ function validateOptions(input, validatorMap, defaults, logger, prefix) {
     });
     return result;
 }
+/**
+ * Creates a validator for nested objects. When used in a validator map,
+ * `validateOptions` will recursively validate the nested object's properties.
+ * Defaults for nested fields are passed through from the parent.
+ */
+function validatorOf(validators, builtInDefaults) {
+    return {
+        is: (u) => jsSdkCommon.TypeValidators.Object.is(u),
+        getType: () => 'object',
+        validate(value, name, logger, defaults) {
+            if (!jsSdkCommon.TypeValidators.Object.is(value)) {
+                logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, 'object', typeof value));
+                return undefined;
+            }
+            const nestedDefaults = builtInDefaults ??
+                (jsSdkCommon.TypeValidators.Object.is(defaults) ? defaults : {});
+            const nested = validateOptions(value, validators, nestedDefaults, logger, name);
+            return Object.keys(nested).length > 0 ? { value: nested } : undefined;
+        },
+    };
+}
+/**
+ * Creates a validator for arrays of discriminated objects. Each item in the
+ * array must be an object containing a `discriminant` field whose value
+ * selects which validator map to apply. The valid discriminant values are
+ * the keys of `validatorsByType`. Items that are not objects, or whose
+ * discriminant value is missing or unrecognized, are filtered out with a
+ * warning.
+ *
+ * @param discriminant - The field name used to determine each item's type.
+ * @param validatorsByType - A mapping from discriminant values to the
+ *   validator maps used to validate items of that type. Each validator map
+ *   should include a validator for the discriminant field itself.
+ *
+ * @example
+ * ```ts
+ * // Validates an array like:
+ * //   [{ type: 'polling', pollInterval: 60 }, { type: 'cache' }]
+ *
+ * const validator = arrayOf('type', {
+ *   cache: { type: TypeValidators.String },
+ *   polling: { type: TypeValidators.String, pollInterval: TypeValidators.numberWithMin(30) },
+ *   streaming: { type: TypeValidators.String, initialReconnectDelay: TypeValidators.numberWithMin(1) },
+ * });
+ * ```
+ */
+function arrayOf(discriminant, validatorsByType) {
+    return {
+        is: (u) => Array.isArray(u),
+        getType: () => 'array',
+        validate(value, name, logger) {
+            if (!Array.isArray(value)) {
+                logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, 'array', typeof value));
+                return undefined;
+            }
+            const results = [];
+            value.forEach((item, i) => {
+                const itemPath = `${name}[${i}]`;
+                if (jsSdkCommon.isNullish(item) || !jsSdkCommon.TypeValidators.Object.is(item)) {
+                    logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(itemPath, 'object', typeof item));
+                    return;
+                }
+                const obj = item;
+                const typeValue = obj[discriminant];
+                const validators = typeof typeValue === 'string' ? validatorsByType[typeValue] : undefined;
+                if (!validators) {
+                    const expected = Object.keys(validatorsByType).join(' | ');
+                    const received = typeof typeValue === 'string' ? typeValue : typeof typeValue;
+                    logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(`${itemPath}.${discriminant}`, expected, received));
+                    return;
+                }
+                results.push(validateOptions(obj, validators, {}, logger, itemPath));
+            });
+            return { value: results };
+        },
+    };
+}
+/**
+ * Creates a validator that tries each provided validator in order and uses the
+ * first one whose `is()` check passes. For compound validators the value is
+ * processed through `validate()`; for simple validators the value is accepted
+ * as-is. If no validator matches, a warning is logged and the default is
+ * preserved.
+ *
+ * @example
+ * ```ts
+ * // Accepts either a boolean or a nested object with specific fields:
+ * anyOf(TypeValidators.Boolean, validatorOf({ lifecycle: TypeValidators.Boolean }))
+ * ```
+ */
+function anyOf(...validators) {
+    return {
+        is: (u) => validators.some((v) => v.is(u)),
+        getType: () => validators.map((v) => v.getType()).join(' | '),
+        validate(value, name, logger, defaults) {
+            const match = validators.find((v) => v.is(value));
+            if (match) {
+                return isCompoundValidator(match)
+                    ? match.validate(value, name, logger, defaults)
+                    : { value };
+            }
+            logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, this.getType(), typeof value));
+            return undefined;
+        },
+    };
+}
+/**
+ * Creates a validator for objects with dynamic keys. Each key in the input
+ * object is checked against `keyValidator`; unrecognized keys produce a
+ * warning. Each value is validated by `valueValidator`. Defaults for
+ * individual entries are passed through from the parent so partial overrides
+ * preserve non-overridden entries.
+ *
+ * @param keyValidator - Validates that each key is an allowed value.
+ * @param valueValidator - Validates each value in the record.
+ *
+ * @example
+ * ```ts
+ * // Validates a record like { streaming: { ... }, polling: { ... } }
+ * // where keys must be valid connection modes:
+ * recordOf(
+ *   TypeValidators.oneOf('streaming', 'polling', 'offline'),
+ *   validatorOf({ initializers: arrayValidator, synchronizers: arrayValidator }),
+ * )
+ * ```
+ */
+function recordOf(keyValidator, valueValidator) {
+    return {
+        is: (u) => jsSdkCommon.TypeValidators.Object.is(u),
+        getType: () => 'object',
+        validate(value, name, logger, defaults) {
+            if (jsSdkCommon.isNullish(value)) {
+                return undefined;
+            }
+            if (!jsSdkCommon.TypeValidators.Object.is(value)) {
+                logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, 'object', typeof value));
+                return undefined;
+            }
+            // Filter invalid keys, then delegate to validateOptions.
+            const obj = value;
+            const filtered = {};
+            const validatorMap = {};
+            Object.keys(obj).forEach((key) => {
+                if (keyValidator.is(key)) {
+                    filtered[key] = obj[key];
+                    validatorMap[key] = valueValidator;
+                }
+                else {
+                    logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, keyValidator.getType(), key));
+                }
+            });
+            const recordDefaults = jsSdkCommon.TypeValidators.Object.is(defaults)
+                ? defaults
+                : {};
+            return { value: validateOptions(filtered, validatorMap, recordDefaults, logger, name) };
+        },
+    };
+}
 
-// eslint-disable-next-line max-classes-per-file
-const validators = {
-    logger: jsSdkCommon.TypeValidators.Object,
-    maxCachedContexts: jsSdkCommon.TypeValidators.numberWithMin(0),
-    baseUri: jsSdkCommon.TypeValidators.String,
-    streamUri: jsSdkCommon.TypeValidators.String,
-    eventsUri: jsSdkCommon.TypeValidators.String,
-    capacity: jsSdkCommon.TypeValidators.numberWithMin(1),
-    diagnosticRecordingInterval: jsSdkCommon.TypeValidators.numberWithMin(2),
-    flushInterval: jsSdkCommon.TypeValidators.numberWithMin(2),
-    streamInitialReconnectDelay: jsSdkCommon.TypeValidators.numberWithMin(0),
-    allAttributesPrivate: jsSdkCommon.TypeValidators.Boolean,
-    debug: jsSdkCommon.TypeValidators.Boolean,
-    diagnosticOptOut: jsSdkCommon.TypeValidators.Boolean,
-    withReasons: jsSdkCommon.TypeValidators.Boolean,
-    sendEvents: jsSdkCommon.TypeValidators.Boolean,
+const BACKGROUND_POLL_INTERVAL_SECONDS = 3600;
+const dataSourceTypeValidator = jsSdkCommon.TypeValidators.oneOf('cache', 'polling', 'streaming');
+const connectionModeValidator = jsSdkCommon.TypeValidators.oneOf('streaming', 'polling', 'offline', 'one-shot', 'background');
+const endpointValidators = {
+    pollingBaseUri: jsSdkCommon.TypeValidators.String,
+    streamingBaseUri: jsSdkCommon.TypeValidators.String,
+};
+const cacheEntryValidators = {
+    type: dataSourceTypeValidator,
+};
+const pollingEntryValidators = {
+    type: dataSourceTypeValidator,
     pollInterval: jsSdkCommon.TypeValidators.numberWithMin(30),
-    useReport: jsSdkCommon.TypeValidators.Boolean,
-    privateAttributes: jsSdkCommon.TypeValidators.StringArray,
-    applicationInfo: jsSdkCommon.TypeValidators.Object,
-    wrapperName: jsSdkCommon.TypeValidators.String,
-    wrapperVersion: jsSdkCommon.TypeValidators.String,
-    payloadFilterKey: jsSdkCommon.TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
-    hooks: jsSdkCommon.TypeValidators.createTypeArray('Hook[]', {}),
-    inspectors: jsSdkCommon.TypeValidators.createTypeArray('LDInspection', {}),
-    cleanOldPersistentData: jsSdkCommon.TypeValidators.Boolean,
+    endpoints: validatorOf(endpointValidators),
+};
+const streamingEntryValidators = {
+    type: dataSourceTypeValidator,
+    initialReconnectDelay: jsSdkCommon.TypeValidators.numberWithMin(1),
+    endpoints: validatorOf(endpointValidators),
+};
+const initializerEntryArrayValidator = arrayOf('type', {
+    cache: cacheEntryValidators,
+    polling: pollingEntryValidators,
+    streaming: streamingEntryValidators,
+});
+const synchronizerEntryArrayValidator = arrayOf('type', {
+    polling: pollingEntryValidators,
+    streaming: streamingEntryValidators,
+});
+const modeDefinitionValidators = {
+    initializers: initializerEntryArrayValidator,
+    synchronizers: synchronizerEntryArrayValidator,
+};
+const connectionModesValidator = recordOf(connectionModeValidator, validatorOf(modeDefinitionValidators));
+const MODE_TABLE = {
+    streaming: {
+        initializers: [{ type: 'cache' }, { type: 'polling' }],
+        synchronizers: [{ type: 'streaming' }, { type: 'polling' }],
+    },
+    polling: {
+        initializers: [{ type: 'cache' }],
+        synchronizers: [{ type: 'polling' }],
+    },
+    offline: {
+        initializers: [{ type: 'cache' }],
+        synchronizers: [],
+    },
+    'one-shot': {
+        initializers: [{ type: 'cache' }, { type: 'polling' }, { type: 'streaming' }],
+        synchronizers: [],
+    },
+    background: {
+        initializers: [{ type: 'cache' }],
+        synchronizers: [{ type: 'polling', pollInterval: BACKGROUND_POLL_INTERVAL_SECONDS }],
+    },
 };
 
+const modeSwitchingValidators = {
+    lifecycle: jsSdkCommon.TypeValidators.Boolean,
+    network: jsSdkCommon.TypeValidators.Boolean,
+};
+const dataSystemValidators = {
+    initialConnectionMode: connectionModeValidator,
+    backgroundConnectionMode: connectionModeValidator,
+    automaticModeSwitching: anyOf(jsSdkCommon.TypeValidators.Boolean, validatorOf(modeSwitchingValidators)),
+    connectionModes: connectionModesValidator,
+};
+/**
+ * Default FDv2 data system configuration for browser SDKs.
+ */
+const BROWSER_DATA_SYSTEM_DEFAULTS = {
+    initialConnectionMode: 'one-shot',
+    backgroundConnectionMode: undefined,
+    automaticModeSwitching: false,
+};
+/**
+ * Default FDv2 data system configuration for mobile (React Native) SDKs.
+ */
+const MOBILE_DATA_SYSTEM_DEFAULTS = {
+    initialConnectionMode: 'streaming',
+    backgroundConnectionMode: 'background',
+    automaticModeSwitching: true,
+};
+/**
+ * Default FDv2 data system configuration for desktop SDKs (Electron, etc.).
+ */
+const DESKTOP_DATA_SYSTEM_DEFAULTS = {
+    initialConnectionMode: 'streaming',
+    backgroundConnectionMode: undefined,
+    automaticModeSwitching: false,
+};
+
+function createValidators(options) {
+    return {
+        logger: jsSdkCommon.TypeValidators.Object,
+        maxCachedContexts: jsSdkCommon.TypeValidators.numberWithMin(0),
+        baseUri: jsSdkCommon.TypeValidators.String,
+        streamUri: jsSdkCommon.TypeValidators.String,
+        eventsUri: jsSdkCommon.TypeValidators.String,
+        capacity: jsSdkCommon.TypeValidators.numberWithMin(1),
+        diagnosticRecordingInterval: jsSdkCommon.TypeValidators.numberWithMin(2),
+        flushInterval: jsSdkCommon.TypeValidators.numberWithMin(2),
+        streamInitialReconnectDelay: jsSdkCommon.TypeValidators.numberWithMin(0),
+        allAttributesPrivate: jsSdkCommon.TypeValidators.Boolean,
+        debug: jsSdkCommon.TypeValidators.Boolean,
+        diagnosticOptOut: jsSdkCommon.TypeValidators.Boolean,
+        withReasons: jsSdkCommon.TypeValidators.Boolean,
+        sendEvents: jsSdkCommon.TypeValidators.Boolean,
+        pollInterval: jsSdkCommon.TypeValidators.numberWithMin(30),
+        useReport: jsSdkCommon.TypeValidators.Boolean,
+        privateAttributes: jsSdkCommon.TypeValidators.StringArray,
+        disableCache: jsSdkCommon.TypeValidators.Boolean,
+        applicationInfo: jsSdkCommon.TypeValidators.Object,
+        wrapperName: jsSdkCommon.TypeValidators.String,
+        wrapperVersion: jsSdkCommon.TypeValidators.String,
+        payloadFilterKey: jsSdkCommon.TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
+        hooks: jsSdkCommon.TypeValidators.createTypeArray('Hook[]', {}),
+        inspectors: jsSdkCommon.TypeValidators.createTypeArray('LDInspection', {}),
+        cleanOldPersistentData: jsSdkCommon.TypeValidators.Boolean,
+        dataSystem: options?.dataSystemDefaults
+            ? validatorOf(dataSystemValidators, options.dataSystemDefaults)
+            : jsSdkCommon.TypeValidators.Object,
+    };
+}
+
 const DEFAULT_POLLING_INTERVAL = 60 * 5;
 const DEFAULT_POLLING = 'https://clientsdk.launchdarkly.com';
 const DEFAULT_STREAM = 'https://clientstream.launchdarkly.com';
@@ -343,6 +598,7 @@ class ConfigurationImpl {
         // eslint-disable-next-line @typescript-eslint/naming-convention
         this.streamUri = DEFAULT_STREAM;
         this.maxCachedContexts = 5;
+        this.disableCache = false;
         this.capacity = 100;
         this.diagnosticRecordingInterval = 900;
         this.flushInterval = 30;
@@ -359,6 +615,9 @@ class ConfigurationImpl {
         this.hooks = [];
         this.inspectors = [];
         this.logger = ensureSafeLogger(pristineOptions.logger);
+        const validators = createValidators({
+            dataSystemDefaults: internalOptions.dataSystemDefaults,
+        });
         const validated = validateOptions(pristineOptions, validators, {}, this.logger);
         Object.entries(validated).forEach(([k, v]) => {
             if (k !== 'logger') {
@@ -711,6 +970,98 @@ class EventFactory extends jsSdkCommon.internal.EventFactoryBase {
     }
 }
 
+/**
+ * Suffix appended to context storage keys to form the freshness storage key.
+ */
+const FRESHNESS_SUFFIX = '_freshness';
+/**
+ * Computes a SHA-256 hash of the context's full canonical JSON.
+ * Returns `undefined` if the context cannot be serialized.
+ */
+async function hashContext(crypto, context) {
+    const json = context.canonicalUnfilteredJson();
+    if (!json) {
+        return undefined;
+    }
+    return digest(crypto.createHash('sha256').update(json), 'base64');
+}
+/**
+ * Reads the freshness timestamp from storage for the given context.
+ *
+ * Returns `undefined` if no freshness record exists, the data is corrupt,
+ * or the context attributes have changed since the freshness was recorded.
+ */
+async function readFreshness(storage, crypto, environmentNamespace, context, logger) {
+    const contextStorageKey = await namespaceForContextData(crypto, environmentNamespace, context);
+    const json = await storage.get(`${contextStorageKey}${FRESHNESS_SUFFIX}`);
+    if (json === null || json === undefined) {
+        return undefined;
+    }
+    try {
+        const record = JSON.parse(json);
+        const currentHash = await hashContext(crypto, context);
+        if (currentHash === undefined || record.contextHash !== currentHash) {
+            return undefined;
+        }
+        return typeof record.timestamp === 'number' && !Number.isNaN(record.timestamp)
+            ? record.timestamp
+            : undefined;
+    }
+    catch (e) {
+        logger?.warn(`Could not read freshness data from persistent storage: ${e.message}`);
+        return undefined;
+    }
+}
+
+function isValidFlag(value) {
+    return value !== null && typeof value === 'object' && typeof value.version === 'number';
+}
+/**
+ * Loads cached flag data from storage for the given context.
+ *
+ * Checks the current storage key first, then falls back to the legacy
+ * canonical key location (pre-10.3.1). Does NOT perform migration — the
+ * caller is responsible for migrating data if {@link CachedFlagData.fromLegacyKey}
+ * is true.
+ *
+ * @returns The cached flag data, or `undefined` on cache miss or parse error.
+ */
+async function loadCachedFlags(storage, crypto, environmentNamespace, context, logger) {
+    const storageKey = await namespaceForContextData(crypto, environmentNamespace, context);
+    let flagsJson = await storage.get(storageKey);
+    let fromLegacyKey = false;
+    if (flagsJson === null || flagsJson === undefined) {
+        // Fallback: in version <10.3.1 flag data was stored under the canonical key.
+        flagsJson = await storage.get(context.canonicalKey);
+        if (flagsJson === null || flagsJson === undefined) {
+            return undefined;
+        }
+        fromLegacyKey = true;
+    }
+    try {
+        const parsed = JSON.parse(flagsJson);
+        if (parsed === null || typeof parsed !== 'object') {
+            logger?.warn('Cached flag data is not a valid object');
+            return undefined;
+        }
+        const entries = Object.entries(parsed);
+        const invalidKey = entries.find(([, value]) => !isValidFlag(value));
+        if (invalidKey) {
+            logger?.warn(`Discarding cached flags due to invalid entry: ${invalidKey[0]}`);
+            return undefined;
+        }
+        const flags = entries.reduce((acc, [key, value]) => {
+            acc[key] = value;
+            return acc;
+        }, {});
+        return { flags, storageKey, fromLegacyKey };
+    }
+    catch (e) {
+        logger?.warn(`Could not parse cached flag evaluations from persistent storage: ${e.message}`);
+        return undefined;
+    }
+}
+
 /**
  * An index for tracking the most recently used contexts by timestamp with the ability to
  * update entry timestamps and prune out least used contexts above a max capacity provided.
@@ -776,12 +1127,18 @@ class ContextIndex {
  * This class handles persisting and loading flag values from a persistent
  * store. It intercepts updates and forwards them to the flag updater and
  * then persists changes after the updater has completed.
+ *
+ * Freshness metadata (timestamp + context attribute hash) is stored in a
+ * separate storage key (`{contextKey}_freshness`) alongside the flag data.
+ * Both keys are managed together — when a context is evicted, both the flag
+ * data and freshness record are cleared.
  */
 class FlagPersistence {
-    constructor(_platform, _environmentNamespace, _maxCachedContexts, _flagStore, _flagUpdater, _logger, _timeStamper = () => Date.now()) {
+    constructor(_platform, _environmentNamespace, _maxCachedContexts, _disableCache, _flagStore, _flagUpdater, _logger, _timeStamper = () => Date.now()) {
         this._platform = _platform;
         this._environmentNamespace = _environmentNamespace;
         this._maxCachedContexts = _maxCachedContexts;
+        this._disableCache = _disableCache;
         this._flagStore = _flagStore;
         this._flagUpdater = _flagUpdater;
         this._logger = _logger;
@@ -808,40 +1165,56 @@ class FlagPersistence {
         }
         return false;
     }
+    /**
+     * Applies a changeset to the flag store.
+     * - `'full'`: replaces all flags via {@link FlagUpdater.init}.
+     * - `'partial'`: upserts individual flags via {@link FlagUpdater.upsert}.
+     * - `'none'`: no flag changes, only persists cache to update freshness.
+     *
+     * Always persists to cache afterwards, which updates the freshness timestamp
+     * even when no flags change (e.g., transfer-none).
+     */
+    async applyChanges(context, updates, type) {
+        this._flagUpdater.applyChanges(context, updates, type);
+        await this._storeCache(context);
+    }
     /**
      * Loads the flags from persistence for the provided context and gives those to the
      * {@link FlagUpdater} this {@link FlagPersistence} was constructed with.
      */
     async loadCached(context) {
-        const storageKey = await namespaceForContextData(this._platform.crypto, this._environmentNamespace, context);
-        let flagsJson = await this._platform.storage?.get(storageKey);
-        if (flagsJson === null || flagsJson === undefined) {
-            // Fallback: in version <10.3.1 flag data was stored under the canonical key, check
-            // to see if data is present and migrate the data if present.
-            flagsJson = await this._platform.storage?.get(context.canonicalKey);
-            if (flagsJson === null || flagsJson === undefined) {
-                // return false indicating cache did not load if flag json is still absent
-                return false;
-            }
-            // migrate data from version <10.3.1 and cleanup data that was under canonical key
-            await this._platform.storage?.set(storageKey, flagsJson);
-            await this._platform.storage?.clear(context.canonicalKey);
+        if (this._disableCache || this._maxCachedContexts <= 0) {
+            return false;
         }
-        try {
-            const flags = JSON.parse(flagsJson);
-            // mapping flags to item descriptors
-            const descriptors = Object.entries(flags).reduce((acc, [key, flag]) => {
-                acc[key] = { version: flag.version, flag };
-                return acc;
-            }, {});
-            this._flagUpdater.initCached(context, descriptors);
-            this._logger.debug('Loaded cached flag evaluations from persistent storage');
-            return true;
+        if (!this._platform.storage) {
+            return false;
         }
-        catch (e) {
-            this._logger.warn(`Could not load cached flag evaluations from persistent storage: ${e.message}`);
+        const cached = await loadCachedFlags(this._platform.storage, this._platform.crypto, this._environmentNamespace, context, this._logger);
+        if (!cached) {
             return false;
         }
+        // Migrate data from version <10.3.1 stored under the canonical key
+        if (cached.fromLegacyKey) {
+            await this._platform.storage.set(cached.storageKey, JSON.stringify(cached.flags));
+            await this._platform.storage.clear(context.canonicalKey);
+        }
+        // mapping flags to item descriptors
+        const descriptors = Object.entries(cached.flags).reduce((acc, [key, flag]) => {
+            acc[key] = { version: flag.version, flag };
+            return acc;
+        }, {});
+        this._flagUpdater.initCached(context, descriptors);
+        this._logger.debug('Loaded cached flag evaluations from persistent storage');
+        return true;
+    }
+    async _storeFreshness(contextStorageKey, context, timestamp) {
+        const contextHash = await hashContext(this._platform.crypto, context);
+        if (contextHash === undefined) {
+            this._logger.error('Could not serialize context for freshness tracking');
+            return;
+        }
+        const record = { timestamp, contextHash };
+        await this._platform.storage?.set(`${contextStorageKey}${FRESHNESS_SUFFIX}`, JSON.stringify(record));
     }
     async _loadIndex() {
         if (this._contextIndex !== undefined) {
@@ -863,13 +1236,26 @@ class FlagPersistence {
         return this._contextIndex;
     }
     async _storeCache(context) {
+        if (this._disableCache) {
+            return;
+        }
+        const now = this._timeStamper();
         const index = await this._loadIndex();
         const storageKey = await namespaceForContextData(this._platform.crypto, this._environmentNamespace, context);
-        index.notice(storageKey, this._timeStamper());
+        if (this._maxCachedContexts > 0) {
+            index.notice(storageKey, now);
+        }
         const pruned = index.prune(this._maxCachedContexts);
-        await Promise.all(pruned.map(async (it) => this._platform.storage?.clear(it.id)));
-        // store index
+        // If maxCachedContexts <= 0, current context was never added, so always skip flag write
+        const currentContextWasPruned = this._maxCachedContexts <= 0 || pruned.some((it) => it.id === storageKey);
+        await Promise.all(pruned.flatMap((it) => [
+            this._platform.storage?.clear(it.id),
+            this._platform.storage?.clear(`${it.id}${FRESHNESS_SUFFIX}`),
+        ]));
         await this._platform.storage?.set(await this._indexKeyPromise, index.toJson());
+        if (currentContextWasPruned) {
+            return;
+        }
         const allFlags = this._flagStore.getAll();
         // mapping item descriptors to flags
         const flags = Object.entries(allFlags).reduce((acc, [key, descriptor]) => {
@@ -879,8 +1265,15 @@ class FlagPersistence {
             return acc;
         }, {});
         const jsonAll = JSON.stringify(flags);
-        // store flag data
+        // store flag data first, so freshness is never newer than the flags it describes
         await this._platform.storage?.set(storageKey, jsonAll);
+        // store freshness — best-effort, must not block flag persistence
+        try {
+            await this._storeFreshness(storageKey, context, now);
+        }
+        catch (e) {
+            this._logger.warn(`Failed to store freshness data: ${e.message}`);
+        }
     }
 }
 
@@ -908,6 +1301,16 @@ function createDefaultFlagStore() {
         getAll() {
             return flags;
         },
+        applyChanges(updates, type) {
+            if (type === 'full') {
+                this.init(updates);
+            }
+            else if (type === 'partial') {
+                Object.entries(updates).forEach(([key, descriptor]) => {
+                    flags[key] = descriptor;
+                });
+            }
+        },
     };
 }
 
@@ -965,6 +1368,24 @@ function createFlagUpdater(_flagStore, _logger) {
             }
             this.init(context, newFlags);
         },
+        applyChanges(context, updates, type) {
+            activeContext = context;
+            const oldFlags = flagStore.getAll();
+            flagStore.applyChanges(updates, type);
+            if (type === 'full') {
+                const changed = calculateChangedKeys(oldFlags, updates);
+                if (changed.length > 0) {
+                    this.handleFlagChanges(changed, 'init');
+                }
+            }
+            else if (type === 'partial') {
+                const keys = Object.keys(updates);
+                if (keys.length > 0) {
+                    this.handleFlagChanges(keys, 'patch');
+                }
+            }
+            // 'none' — no flag changes, caller handles freshness.
+        },
         upsert(context, key, item) {
             if (activeContext?.canonicalKey !== context.canonicalKey) {
                 logger.warn('Received an update for an inactive context.');
@@ -996,17 +1417,18 @@ class DefaultFlagManager {
      * @param platform implementation of various platform provided functionality
      * @param sdkKey that will be used to distinguish different environments
      * @param maxCachedContexts that specifies the max number of contexts that will be cached in persistence
+     * @param disableCache set to true to completely disable the persistent flag cache
      * @param logger used for logging various messages
      * @param timeStamper exists for testing purposes
      */
-    constructor(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
+    constructor(platform, sdkKey, maxCachedContexts, disableCache, logger, timeStamper = () => Date.now()) {
         this._flagStore = createDefaultFlagStore();
         this._flagUpdater = createFlagUpdater(this._flagStore, logger);
-        this._flagPersistencePromise = this._initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper);
+        this._flagPersistencePromise = this._initPersistence(platform, sdkKey, maxCachedContexts, disableCache, logger, timeStamper);
     }
-    async _initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
+    async _initPersistence(platform, sdkKey, maxCachedContexts, disableCache, logger, timeStamper = () => Date.now()) {
         const environmentNamespace = await namespaceForEnvironment(platform.crypto, sdkKey);
-        return new FlagPersistence(platform, environmentNamespace, maxCachedContexts, this._flagStore, this._flagUpdater, logger, timeStamper);
+        return new FlagPersistence(platform, environmentNamespace, maxCachedContexts, disableCache, this._flagStore, this._flagUpdater, logger, timeStamper);
     }
     get(key) {
         if (this._overrides && Object.prototype.hasOwnProperty.call(this._overrides, key)) {
@@ -1043,6 +1465,9 @@ class DefaultFlagManager {
     async loadCached(context) {
         return (await this._flagPersistencePromise).loadCached(context);
     }
+    async applyChanges(context, updates, type) {
+        return (await this._flagPersistencePromise).applyChanges(context, updates, type);
+    }
     on(callback) {
         this._flagUpdater.on(callback);
     }
@@ -1482,7 +1907,7 @@ class LDClientImpl {
         this._config = new ConfigurationImpl(options, internalOptions);
         this.logger = this._config.logger;
         this._baseHeaders = jsSdkCommon.defaultHeaders(this.sdkKey, this.platform.info, this._config.tags, this._config.serviceEndpoints.includeAuthorizationHeader, this._config.userAgentHeaderName);
-        this._flagManager = new DefaultFlagManager(this.platform, sdkKey, this._config.maxCachedContexts, this._config.logger);
+        this._flagManager = new DefaultFlagManager(this.platform, sdkKey, this._config.maxCachedContexts, this._config.disableCache ?? false, this._config.logger);
         this._diagnosticsManager = createDiagnosticsManager(sdkKey, this._config, platform);
         this._eventProcessor = createEventProcessor(sdkKey, this._config, platform, this._baseHeaders, this._diagnosticsManager);
         this.emitter = new LDEmitter();
@@ -2576,15 +3001,993 @@ class BaseDataManager {
     }
 }
 
+function allConditionsMatch(conditions, input) {
+    return Object.entries(conditions).every(([key, value]) => value === undefined || input[key] === value);
+}
+/**
+ * Given a mode resolution table and the current input state, returns the
+ * resolved FDv2 connection mode.
+ *
+ * Iterates entries in order. The first entry whose conditions all match the
+ * input wins. If no entry matches (should not happen when the table ends with
+ * a catch-all), falls back to `input.foregroundMode`.
+ */
+const CONFIGURED_MODE_MAP = {
+    foreground: 'foregroundMode',
+    background: 'backgroundMode',
+};
+function resolveConnectionMode(table, input) {
+    const match = table.find((entry) => allConditionsMatch(entry.conditions, input));
+    if (match) {
+        const { mode } = match;
+        if (typeof mode === 'object') {
+            return input[CONFIGURED_MODE_MAP[mode.configured]];
+        }
+        return mode;
+    }
+    return input.foregroundMode;
+}
+/**
+ * Mode resolution table for mobile platforms (React Native, etc.).
+ *
+ * - No network → offline.
+ * - Background → configured background mode.
+ * - Foreground → configured foreground mode.
+ */
+const MOBILE_TRANSITION_TABLE = [
+    { conditions: { networkAvailable: false }, mode: 'offline' },
+    { conditions: { lifecycle: 'background' }, mode: { configured: 'background' } },
+    { conditions: { lifecycle: 'foreground' }, mode: { configured: 'foreground' } },
+];
+/**
+ * Mode resolution table for browser platforms.
+ *
+ * - No network → offline.
+ * - Otherwise → configured foreground mode.
+ *
+ * Browser listener-driven streaming (auto-promotion to streaming when change
+ * listeners are registered) is handled externally by the caller modifying
+ * `foregroundMode` before consulting this table.
+ */
+const BROWSER_TRANSITION_TABLE = [
+    { conditions: { networkAvailable: false }, mode: 'offline' },
+    { conditions: {}, mode: { configured: 'foreground' } },
+];
+/**
+ * Mode resolution table for desktop platforms (Electron, etc.).
+ *
+ * - No network → offline.
+ * - Otherwise → configured foreground mode.
+ */
+const DESKTOP_TRANSITION_TABLE = [
+    { conditions: { networkAvailable: false }, mode: 'offline' },
+    { conditions: {}, mode: { configured: 'foreground' } },
+];
+
+/**
+ * Creates a change set result containing processed flag data.
+ */
+function changeSet(payload, fdv1Fallback, environmentId, freshness) {
+    return { type: 'changeSet', payload, fdv1Fallback, environmentId, freshness };
+}
+/**
+ * Creates an interrupted status result. Indicates a transient error; the
+ * synchronizer will attempt to recover automatically.
+ *
+ * When used with an initializer, this is still a terminal state.
+ */
+function interrupted(errorInfo, fdv1Fallback) {
+    return { type: 'status', state: 'interrupted', errorInfo, fdv1Fallback };
+}
+/**
+ * Creates a shutdown status result. Indicates the data source was closed
+ * gracefully and will not produce any further results.
+ */
+function shutdown() {
+    return { type: 'status', state: 'shutdown', fdv1Fallback: false };
+}
+/**
+ * Creates a terminal error status result. Indicates an unrecoverable error;
+ * the data source will not produce any further results.
+ */
+function terminalError(errorInfo, fdv1Fallback) {
+    return { type: 'status', state: 'terminal_error', errorInfo, fdv1Fallback };
+}
+/**
+ * Creates a goodbye status result. Indicates the server has instructed the
+ * client to disconnect.
+ */
+function goodbye(reason, fdv1Fallback) {
+    return { type: 'status', state: 'goodbye', reason, fdv1Fallback };
+}
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from an HTTP status code.
+ */
+function errorInfoFromHttpError(statusCode) {
+    return {
+        kind: jsSdkCommon.DataSourceErrorKind.ErrorResponse,
+        message: `Unexpected status code: ${statusCode}`,
+        statusCode,
+        time: Date.now(),
+    };
+}
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from a network error.
+ */
+function errorInfoFromNetworkError(message) {
+    return {
+        kind: jsSdkCommon.DataSourceErrorKind.NetworkError,
+        message,
+        time: Date.now(),
+    };
+}
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from invalid data.
+ */
+function errorInfoFromInvalidData(message) {
+    return {
+        kind: jsSdkCommon.DataSourceErrorKind.InvalidData,
+        message,
+        time: Date.now(),
+    };
+}
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} for unknown errors.
+ */
+function errorInfoFromUnknown(message) {
+    return {
+        kind: jsSdkCommon.DataSourceErrorKind.Unknown,
+        message,
+        time: Date.now(),
+    };
+}
+
+/**
+ * Strips the `version` field from a stored {@link Flag} to produce the
+ * `FlagEvaluationResult` shape expected in an FDv2 `Update.object`.
+ *
+ * The version is carried on the `Update` envelope, not on the object itself.
+ */
+function flagToEvaluationResult(flag) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { version, ...evalResult } = flag;
+    return evalResult;
+}
+/**
+ * Reads cached flag data and freshness from platform storage and returns
+ * them as an {@link FDv2SourceResult}.
+ */
+async function loadFromCache(config) {
+    const { storage, crypto, environmentNamespace, context, logger } = config;
+    if (!storage) {
+        logger?.debug('No storage available for cache initializer');
+        return interrupted(errorInfoFromUnknown('No storage available'), false);
+    }
+    const cached = await loadCachedFlags(storage, crypto, environmentNamespace, context, logger);
+    if (!cached) {
+        logger?.debug('Cache miss for context');
+        return interrupted(errorInfoFromUnknown('Cache miss'), false);
+    }
+    const updates = Object.entries(cached.flags).map(([key, flag]) => ({
+        kind: 'flag-eval',
+        key,
+        version: flag.version,
+        object: flagToEvaluationResult(flag),
+    }));
+    const payload = {
+        id: 'cache',
+        version: 0,
+        // No `state` field. The orchestrator sees a changeSet without a selector,
+        // records dataReceived=true, and continues to the next initializer.
+        type: 'full',
+        updates,
+    };
+    const freshness = await readFreshness(storage, crypto, environmentNamespace, context, logger);
+    logger?.debug('Loaded cached flag evaluations via cache initializer');
+    return changeSet(payload, false, undefined, freshness);
+}
+/**
+ * Creates an {@link InitializerFactory} that produces cache initializers.
+ *
+ * The cache initializer reads flag data and freshness from persistent storage
+ * for the given context and returns them as a changeSet without a selector.
+ * This allows the orchestrator to provide cached data immediately while
+ * continuing to the next initializer for network-verified data.
+ *
+ * Per spec Requirement 4.1.2, the payload has `persist=false` semantics
+ * (no selector) so the consuming layer should not re-persist it.
+ *
+ * @internal
+ */
+function createCacheInitializerFactory(config) {
+    // The selectorGetter is ignored — cache data has no selector.
+    return (_selectorGetter) => {
+        let shutdownResolve;
+        const shutdownPromise = new Promise((resolve) => {
+            shutdownResolve = resolve;
+        });
+        return {
+            async run() {
+                return Promise.race([shutdownPromise, loadFromCache(config)]);
+            },
+            close() {
+                shutdownResolve?.(shutdown());
+                shutdownResolve = undefined;
+            },
+        };
+    };
+}
+
+/**
+ * Creates an {@link FDv2Requestor} for client-side FDv2 polling.
+ *
+ * @param plainContextString The JSON-serialized evaluation context.
+ * @param serviceEndpoints Service endpoint configuration.
+ * @param paths FDv2 polling endpoint paths.
+ * @param requests Platform HTTP abstraction.
+ * @param encoding Platform encoding abstraction.
+ * @param baseHeaders Default HTTP headers (e.g. authorization).
+ * @param baseQueryParams Additional query parameters to include on every request.
+ * @param usePost If true, use POST with context in body instead of GET with
+ *   context in URL path.
+ */
+function makeFDv2Requestor(plainContextString, serviceEndpoints, paths, requests, encoding, baseHeaders, baseQueryParams, usePost) {
+    const headers = { ...baseHeaders };
+    let body;
+    let method = 'GET';
+    let path;
+    if (usePost) {
+        method = 'POST';
+        headers['content-type'] = 'application/json';
+        body = plainContextString;
+        path = paths.pathPost(encoding, plainContextString);
+    }
+    else {
+        path = paths.pathGet(encoding, plainContextString);
+    }
+    return {
+        async poll(basis) {
+            const parameters = [...(baseQueryParams ?? [])];
+            // Intentionally falsy check: an empty string basis must not be sent as
+            // a query parameter, since it does not represent a valid selector.
+            if (basis) {
+                parameters.push({ key: 'basis', value: basis });
+            }
+            const uri = jsSdkCommon.getPollingUri(serviceEndpoints, path, parameters);
+            const res = await requests.fetch(uri, {
+                method,
+                headers,
+                body,
+            });
+            const responseBody = res.status === 304 ? null : await res.text();
+            return {
+                status: res.status,
+                headers: res.headers,
+                body: responseBody,
+            };
+        },
+    };
+}
+
+/**
+ * ObjProcessor for the `flag-eval` object kind. Used by the protocol handler to
+ * process objects received in `put-object` events.
+ *
+ * Client-side evaluation results are already in their final form (pre-evaluated
+ * by the server), so no transformation is needed — this is a passthrough.
+ */
+function processFlagEval(object) {
+    return object;
+}
+
+function getFallback(headers) {
+    const value = headers.get('x-ld-fd-fallback');
+    return value !== null && value.toLowerCase() === 'true';
+}
+function getEnvironmentId(headers) {
+    return headers.get('x-ld-envid') ?? undefined;
+}
+/**
+ * Process FDv2 events using the protocol handler directly.
+ *
+ * We use `createProtocolHandler` rather than `PayloadProcessor` because
+ * the PayloadProcessor does not surface goodbye/serverError actions —
+ * it only forwards payloads and actionable errors. For polling results,
+ * we need full control over all protocol action types.
+ */
+function processEvents(events, oneShot, fdv1Fallback, environmentId, logger) {
+    const handler = jsSdkCommon.internal.createProtocolHandler({
+        'flag-eval': processFlagEval,
+    }, logger);
+    let earlyResult;
+    events.forEach((event) => {
+        if (earlyResult) {
+            return;
+        }
+        const action = handler.processEvent(event);
+        switch (action.type) {
+            case 'payload':
+                earlyResult = changeSet(action.payload, fdv1Fallback, environmentId);
+                break;
+            case 'goodbye':
+                earlyResult = goodbye(action.reason, fdv1Fallback);
+                break;
+            case 'serverError': {
+                const errorInfo = errorInfoFromUnknown(action.reason);
+                logger?.error(`Server error during polling: ${action.reason}`);
+                earlyResult = oneShot
+                    ? terminalError(errorInfo, fdv1Fallback)
+                    : interrupted(errorInfo, fdv1Fallback);
+                break;
+            }
+            case 'error': {
+                // Actionable protocol errors (MISSING_PAYLOAD, PROTOCOL_ERROR)
+                if (action.kind === 'MISSING_PAYLOAD' || action.kind === 'PROTOCOL_ERROR') {
+                    const errorInfo = errorInfoFromInvalidData(action.message);
+                    logger?.warn(`Protocol error during polling: ${action.message}`);
+                    earlyResult = oneShot
+                        ? terminalError(errorInfo, fdv1Fallback)
+                        : interrupted(errorInfo, fdv1Fallback);
+                }
+                else {
+                    // Non-actionable errors (UNKNOWN_EVENT) are logged but don't stop processing
+                    logger?.warn(action.message);
+                }
+                break;
+            }
+        }
+    });
+    if (earlyResult) {
+        return earlyResult;
+    }
+    // Events didn't produce a result
+    const errorInfo = errorInfoFromUnknown('Unexpected end of polling response');
+    logger?.error('Unexpected end of polling response');
+    return oneShot ? terminalError(errorInfo, fdv1Fallback) : interrupted(errorInfo, fdv1Fallback);
+}
+/**
+ * Performs a single FDv2 poll request, processes the protocol response, and
+ * returns an {@link FDv2SourceResult}.
+ *
+ * The `oneShot` parameter controls error handling: when true (initializer),
+ * all errors are terminal; when false (synchronizer), recoverable errors
+ * produce interrupted results.
+ *
+ * @internal
+ */
+async function poll(requestor, basis, oneShot, logger) {
+    let fdv1Fallback = false;
+    let environmentId;
+    try {
+        const response = await requestor.poll(basis);
+        fdv1Fallback = getFallback(response.headers);
+        environmentId = getEnvironmentId(response.headers);
+        // 304 Not Modified: treat as server-intent with intentCode 'none'
+        // (Spec Requirement 10.1.2)
+        if (response.status === 304) {
+            const nonePayload = {
+                id: '',
+                version: 0,
+                type: 'none',
+                updates: [],
+            };
+            return changeSet(nonePayload, fdv1Fallback, environmentId);
+        }
+        // Non-success HTTP status
+        if (response.status < 200 || response.status >= 300) {
+            const errorInfo = errorInfoFromHttpError(response.status);
+            logger?.error(`Polling request failed with HTTP error: ${response.status}`);
+            if (oneShot) {
+                return terminalError(errorInfo, fdv1Fallback);
+            }
+            const recoverable = response.status <= 0 || jsSdkCommon.isHttpRecoverable(response.status);
+            return recoverable
+                ? interrupted(errorInfo, fdv1Fallback)
+                : terminalError(errorInfo, fdv1Fallback);
+        }
+        // Successful response — process FDv2 events
+        if (!response.body) {
+            const errorInfo = errorInfoFromInvalidData('Empty response body');
+            logger?.error('Polling request received empty response body');
+            return oneShot
+                ? terminalError(errorInfo, fdv1Fallback)
+                : interrupted(errorInfo, fdv1Fallback);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch {
+            const errorInfo = errorInfoFromInvalidData('Malformed JSON data in polling response');
+            logger?.error('Polling request received malformed data');
+            return oneShot
+                ? terminalError(errorInfo, fdv1Fallback)
+                : interrupted(errorInfo, fdv1Fallback);
+        }
+        if (!Array.isArray(parsed.events)) {
+            const errorInfo = errorInfoFromInvalidData('Invalid polling response: missing or invalid events array');
+            logger?.error('Polling response does not contain a valid events array');
+            return oneShot
+                ? terminalError(errorInfo, fdv1Fallback)
+                : interrupted(errorInfo, fdv1Fallback);
+        }
+        return processEvents(parsed.events, oneShot, fdv1Fallback, environmentId, logger);
+    }
+    catch (err) {
+        // Network or other I/O error from the fetch itself
+        const message = err?.message ?? String(err);
+        logger?.error(`Polling request failed with network error: ${message}`);
+        const errorInfo = errorInfoFromNetworkError(message);
+        return oneShot ? terminalError(errorInfo, fdv1Fallback) : interrupted(errorInfo, fdv1Fallback);
+    }
+}
+
+/**
+ * Creates a one-shot polling initializer that performs a single FDv2 poll
+ * request and returns the result.
+ *
+ * All errors are treated as terminal (oneShot=true). If `close()` is called
+ * before the poll completes, the result will be a shutdown status.
+ *
+ * @internal
+ */
+function createPollingInitializer(requestor, logger, selectorGetter) {
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+    return {
+        async run() {
+            const pollResult = poll(requestor, selectorGetter(), true, logger);
+            // Race the poll against the shutdown signal
+            return Promise.race([shutdownPromise, pollResult]);
+        },
+        close() {
+            shutdownResolve?.(shutdown());
+            shutdownResolve = undefined;
+        },
+    };
+}
+
+/**
+ * Creates a new {@link AsyncQueue}.
+ *
+ * @internal
+ */
+function createAsyncQueue() {
+    const items = [];
+    const waiters = [];
+    return {
+        put(item) {
+            const waiter = waiters.shift();
+            if (waiter) {
+                waiter(item);
+            }
+            else {
+                items.push(item);
+            }
+        },
+        take() {
+            if (items.length > 0) {
+                return Promise.resolve(items.shift());
+            }
+            return new Promise((resolve) => {
+                waiters.push(resolve);
+            });
+        },
+    };
+}
+
+/**
+ * Creates a continuous polling synchronizer that periodically polls for FDv2
+ * data and yields results via successive calls to `next()`.
+ *
+ * The first poll fires immediately. Subsequent polls are scheduled using
+ * `setTimeout` after each poll completes, ensuring sequential execution and
+ * preventing overlapping requests on slow networks.
+ *
+ * Results are buffered in an async queue. On terminal errors, polling stops
+ * and the shutdown future is resolved. On `close()`, polling stops and the
+ * next `next()` call returns a shutdown result.
+ *
+ * @internal
+ */
+function createPollingSynchronizer(requestor, logger, selectorGetter, pollIntervalMs) {
+    const resultQueue = createAsyncQueue();
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+    let timeoutHandle;
+    let stopped = false;
+    async function doPoll() {
+        if (stopped) {
+            return;
+        }
+        const startTime = Date.now();
+        try {
+            const result = await poll(requestor, selectorGetter(), false, logger);
+            if (stopped) {
+                return;
+            }
+            let shouldShutdown = false;
+            if (result.type === 'status') {
+                switch (result.state) {
+                    case 'terminal_error':
+                        stopped = true;
+                        shouldShutdown = true;
+                        break;
+                    case 'interrupted':
+                    case 'goodbye':
+                        // Continue polling on transient errors and goodbyes
+                        break;
+                    case 'shutdown':
+                        // The base poll function doesn't emit shutdown; we handle it
+                        // at this level via close().
+                        break;
+                    default:
+                        break;
+                }
+            }
+            if (shouldShutdown) {
+                shutdownResolve?.(result);
+                shutdownResolve = undefined;
+            }
+            else {
+                resultQueue.put(result);
+            }
+        }
+        catch (err) {
+            logger?.debug(`Polling error: ${err}`);
+        }
+        // Schedule next poll after completion, accounting for elapsed time.
+        // This ensures sequential execution — no overlapping requests.
+        if (!stopped) {
+            const elapsed = Date.now() - startTime;
+            const sleepFor = Math.min(Math.max(pollIntervalMs - elapsed, 0), pollIntervalMs);
+            timeoutHandle = setTimeout(() => {
+                doPoll();
+            }, sleepFor);
+        }
+    }
+    // Start polling immediately
+    doPoll();
+    return {
+        async next() {
+            return Promise.race([shutdownPromise, resultQueue.take()]);
+        },
+        close() {
+            stopped = true;
+            if (timeoutHandle !== undefined) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = undefined;
+            }
+            shutdownResolve?.(shutdown());
+            shutdownResolve = undefined;
+        },
+    };
+}
+
+/**
+ * Creates a {@link SynchronizerSlot}.
+ *
+ * @param factory The synchronizer factory function.
+ * @param options Optional configuration.
+ * @param options.isFDv1Fallback Whether this slot is the FDv1 fallback adapter.
+ *   FDv1 slots start `'blocked'` by default.
+ * @param options.initialState Override the initial state (defaults to
+ *   `'blocked'` for FDv1 slots, `'available'` otherwise).
+ */
+function createSynchronizerSlot(factory, options) {
+    const isFDv1Fallback = options?.isFDv1Fallback ?? false;
+    const state = options?.initialState ?? (isFDv1Fallback ? 'blocked' : 'available');
+    return { factory, isFDv1Fallback, state };
+}
+
+/**
+ * FDv2 event names to listen for on the EventSource. This must stay in sync
+ * with the `EventType` union defined in `@launchdarkly/js-sdk-common`'s
+ * `internal/fdv2/proto.ts`.
+ */
+const FDV2_EVENT_NAMES = [
+    'server-intent',
+    'put-object',
+    'delete-object',
+    'payload-transferred',
+    'goodbye',
+    'error',
+    'heart-beat',
+];
+/**
+ * Creates the core streaming base for FDv2 client-side data sources.
+ *
+ * Manages an EventSource connection, processes FDv2 protocol events using
+ * a protocol handler from the common package, detects FDv1 fallback signals,
+ * handles legacy ping events, and queues results for consumption by
+ * {@link createStreamingInitializer} or {@link createStreamingSynchronizer}.
+ *
+ * @internal
+ */
+function createStreamingBase(config) {
+    const resultQueue = createAsyncQueue();
+    const protocolHandler = jsSdkCommon.internal.createProtocolHandler({ 'flag-eval': processFlagEval }, config.logger);
+    const headers = { ...config.headers };
+    function buildStreamUri() {
+        const params = [...config.parameters];
+        const basis = config.selectorGetter?.();
+        if (basis) {
+            params.push({ key: 'basis', value: encodeURIComponent(basis) });
+        }
+        return jsSdkCommon.getStreamingUri(config.serviceEndpoints, config.streamUriPath, params);
+    }
+    let eventSource;
+    let connectionAttemptStartTime;
+    let fdv1Fallback = false;
+    let started = false;
+    let stopped = false;
+    function logConnectionAttempt() {
+        connectionAttemptStartTime = Date.now();
+    }
+    function logConnectionResult(success) {
+        if (connectionAttemptStartTime && config.diagnosticsManager) {
+            config.diagnosticsManager.recordStreamInit(connectionAttemptStartTime, !success, Date.now() - connectionAttemptStartTime);
+        }
+        connectionAttemptStartTime = undefined;
+    }
+    function handleAction(action) {
+        switch (action.type) {
+            case 'payload':
+                logConnectionResult(true);
+                resultQueue.put(changeSet(action.payload, fdv1Fallback));
+                break;
+            case 'goodbye':
+                resultQueue.put(goodbye(action.reason, fdv1Fallback));
+                break;
+            case 'serverError':
+                resultQueue.put(interrupted(errorInfoFromUnknown(action.reason), fdv1Fallback));
+                break;
+            case 'error':
+                // Only actionable errors are queued; informational ones (UNKNOWN_EVENT)
+                // are logged by the protocol handler.
+                if (action.kind === 'MISSING_PAYLOAD' || action.kind === 'PROTOCOL_ERROR') {
+                    resultQueue.put(interrupted(errorInfoFromInvalidData(action.message), fdv1Fallback));
+                }
+                break;
+        }
+    }
+    function handleError(err) {
+        // Check for FDv1 fallback header.
+        if (err.headers?.['x-ld-fd-fallback'] === 'true') {
+            fdv1Fallback = true;
+            logConnectionResult(false);
+            resultQueue.put(terminalError(errorInfoFromHttpError(err.status ?? 0), true));
+            return false;
+        }
+        if (!jsSdkCommon.shouldRetry(err)) {
+            config.logger?.error(jsSdkCommon.httpErrorMessage(err, 'streaming request'));
+            logConnectionResult(false);
+            resultQueue.put(terminalError(errorInfoFromHttpError(err.status ?? 0), fdv1Fallback));
+            return false;
+        }
+        config.logger?.warn(jsSdkCommon.httpErrorMessage(err, 'streaming request', 'will retry'));
+        logConnectionResult(false);
+        logConnectionAttempt();
+        resultQueue.put(interrupted(errorInfoFromHttpError(err.status ?? 0), fdv1Fallback));
+        return true;
+    }
+    function attachFDv2Listeners(es) {
+        FDV2_EVENT_NAMES.forEach((eventName) => {
+            es.addEventListener(eventName, (event) => {
+                if (stopped) {
+                    config.logger?.debug(`Received ${eventName} event after processor was closed. Skipping.`);
+                    return;
+                }
+                if (!event?.data) {
+                    // Some events (e.g. 'error') may legitimately arrive without a body.
+                    if (eventName !== 'error') {
+                        config.logger?.warn(`Event from EventStream missing data for "${eventName}".`);
+                    }
+                    return;
+                }
+                config.logger?.debug(`Received ${eventName} event`);
+                let parsed;
+                try {
+                    parsed = JSON.parse(event.data);
+                }
+                catch {
+                    config.logger?.error(`Stream received data that was unable to be parsed in "${eventName}" message`);
+                    config.logger?.debug(`Data follows: ${event.data}`);
+                    resultQueue.put(interrupted(errorInfoFromInvalidData('Malformed JSON in EventStream'), fdv1Fallback));
+                    return;
+                }
+                const action = protocolHandler.processEvent({ event: eventName, data: parsed });
+                handleAction(action);
+            });
+        });
+    }
+    function attachPingListener(es) {
+        es.addEventListener('ping', async () => {
+            if (stopped) {
+                config.logger?.debug('Ping received after processor was closed. Skipping.');
+                return;
+            }
+            config.logger?.debug('Got PING, going to poll LaunchDarkly for feature flag updates');
+            if (!config.pingHandler) {
+                config.logger?.warn('Ping event received but no ping handler configured.');
+                return;
+            }
+            try {
+                const result = await config.pingHandler.handlePing();
+                if (stopped) {
+                    config.logger?.debug('Ping completed after processor was closed. Skipping processing.');
+                    return;
+                }
+                resultQueue.put(result);
+            }
+            catch (err) {
+                if (stopped) {
+                    return;
+                }
+                config.logger?.error(`Error handling ping: ${err?.message ?? err}`);
+                resultQueue.put(interrupted(errorInfoFromNetworkError(err?.message ?? 'Error during ping poll'), fdv1Fallback));
+            }
+        });
+    }
+    return {
+        start() {
+            if (started || stopped) {
+                return;
+            }
+            started = true;
+            logConnectionAttempt();
+            const es = config.requests.createEventSource(buildStreamUri(), {
+                headers,
+                errorFilter: (error) => handleError(error),
+                initialRetryDelayMillis: config.initialRetryDelayMillis,
+                readTimeoutMillis: 5 * 60 * 1000,
+                retryResetIntervalMillis: 60 * 1000,
+            });
+            eventSource = es;
+            attachFDv2Listeners(es);
+            attachPingListener(es);
+            es.onclose = () => {
+                config.logger?.info('Closed LaunchDarkly stream connection');
+            };
+            es.onerror = (err) => {
+                if (stopped) {
+                    return;
+                }
+                if (err && typeof err.status === 'number') {
+                    // This condition will be handled by the error filter.
+                    return;
+                }
+                resultQueue.put(interrupted(errorInfoFromNetworkError(err?.message ?? 'IO Error'), fdv1Fallback));
+            };
+            es.onopen = () => {
+                config.logger?.info('Opened LaunchDarkly stream connection');
+                protocolHandler.reset();
+            };
+            es.onretrying = (e) => {
+                config.logger?.info(`Will retry stream connection in ${e.delayMillis} milliseconds`);
+            };
+        },
+        close() {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            eventSource?.close();
+            eventSource = undefined;
+            resultQueue.put(shutdown());
+        },
+        takeResult() {
+            return resultQueue.take();
+        },
+    };
+}
+
+/**
+ * Creates a one-shot streaming initializer for FDv2.
+ *
+ * Connects to the FDv2 streaming endpoint, waits for the first result
+ * (a change set or an error status), then disconnects. Used in browser
+ * `one-shot` mode where a persistent connection is not desired.
+ *
+ * If `close()` is called before a result arrives, the returned promise
+ * resolves with a shutdown result.
+ *
+ * @param base - The streaming base that manages the EventSource connection.
+ * @internal
+ */
+function createStreamingInitializer(base) {
+    let closed = false;
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+    return {
+        run() {
+            if (closed) {
+                return Promise.resolve(shutdown());
+            }
+            base.start();
+            return Promise.race([
+                base.takeResult().then((result) => {
+                    // Got our first result — close the connection.
+                    base.close();
+                    return result;
+                }),
+                shutdownPromise,
+            ]);
+        },
+        close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            base.close();
+            shutdownResolve?.(shutdown());
+            shutdownResolve = undefined;
+        },
+    };
+}
+
+/**
+ * Creates a long-lived streaming synchronizer for FDv2.
+ *
+ * Maintains a persistent EventSource connection to the FDv2 streaming
+ * endpoint and produces a stream of results via the pull-based `next()`
+ * method. Used in streaming connection mode.
+ *
+ * The connection is started lazily on the first call to `next()`.
+ * On `close()`, the next call to `next()` returns a shutdown result.
+ *
+ * @param base - The streaming base that manages the EventSource connection.
+ * @internal
+ */
+function createStreamingSynchronizer(base) {
+    let started = false;
+    let closed = false;
+    let shutdownResolve;
+    const shutdownPromise = new Promise((resolve) => {
+        shutdownResolve = resolve;
+    });
+    return {
+        next() {
+            if (closed) {
+                return Promise.resolve(shutdown());
+            }
+            if (!started) {
+                started = true;
+                base.start();
+            }
+            return Promise.race([base.takeResult(), shutdownPromise]);
+        },
+        close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            base.close();
+            shutdownResolve?.(shutdown());
+            shutdownResolve = undefined;
+        },
+    };
+}
+
+function createPingHandler(requestor, selectorGetter, logger) {
+    return {
+        handlePing: () => poll(requestor, selectorGetter(), false, logger),
+    };
+}
+/**
+ * Create a {@link ServiceEndpoints} with per-entry endpoint overrides applied.
+ * Returns the original endpoints if no overrides are specified.
+ */
+function resolveEndpoints(ctx, endpoints) {
+    if (!endpoints?.pollingBaseUri && !endpoints?.streamingBaseUri) {
+        return ctx.serviceEndpoints;
+    }
+    return new jsSdkCommon.ServiceEndpoints(endpoints.streamingBaseUri ?? ctx.serviceEndpoints.streaming, endpoints.pollingBaseUri ?? ctx.serviceEndpoints.polling, ctx.serviceEndpoints.events, ctx.serviceEndpoints.analyticsEventPath, ctx.serviceEndpoints.diagnosticEventPath, ctx.serviceEndpoints.includeAuthorizationHeader, ctx.serviceEndpoints.payloadFilterKey);
+}
+/**
+ * Get the FDv2 requestor for a polling entry. If the entry has custom
+ * endpoints, creates a new requestor targeting those endpoints. Otherwise
+ * returns the shared requestor from the context.
+ */
+function resolvePollingRequestor(ctx, endpoints) {
+    if (!endpoints?.pollingBaseUri) {
+        return ctx.requestor;
+    }
+    const overriddenEndpoints = resolveEndpoints(ctx, endpoints);
+    return makeFDv2Requestor(ctx.plainContextString, overriddenEndpoints, ctx.polling.paths, ctx.requests, ctx.encoding, ctx.baseHeaders, ctx.queryParams);
+}
+/**
+ * Build a streaming base instance using per-entry config with context defaults
+ * as fallbacks. The `sg` selector getter is the canonical source of truth for
+ * the current selector — both the stream and its ping handler use it.
+ */
+function buildStreamingBase(entry, ctx, sg) {
+    const entryEndpoints = resolveEndpoints(ctx, entry.endpoints);
+    const requestor = resolvePollingRequestor(ctx, entry.endpoints);
+    const streamUriPath = ctx.streaming.paths.pathGet(ctx.encoding, ctx.plainContextString);
+    return createStreamingBase({
+        requests: ctx.requests,
+        serviceEndpoints: entryEndpoints,
+        streamUriPath,
+        parameters: ctx.queryParams,
+        selectorGetter: sg,
+        headers: ctx.baseHeaders,
+        initialRetryDelayMillis: (entry.initialReconnectDelay ?? ctx.streaming.initialReconnectDelaySeconds) * 1000,
+        logger: ctx.logger,
+        pingHandler: createPingHandler(requestor, sg, ctx.logger),
+    });
+}
+/**
+ * Creates a {@link SourceFactoryProvider} that handles `cache`, `polling`,
+ * and `streaming` data source entries.
+ */
+function createDefaultSourceFactoryProvider() {
+    return {
+        createInitializerFactory(entry, ctx) {
+            switch (entry.type) {
+                case 'polling': {
+                    const requestor = resolvePollingRequestor(ctx, entry.endpoints);
+                    return (sg) => createPollingInitializer(requestor, ctx.logger, sg);
+                }
+                case 'streaming':
+                    return (sg) => createStreamingInitializer(buildStreamingBase(entry, ctx, sg));
+                case 'cache':
+                    return createCacheInitializerFactory({
+                        storage: ctx.storage,
+                        crypto: ctx.crypto,
+                        environmentNamespace: ctx.environmentNamespace,
+                        context: ctx.context,
+                        logger: ctx.logger,
+                    });
+                default:
+                    return undefined;
+            }
+        },
+        createSynchronizerSlot(entry, ctx) {
+            switch (entry.type) {
+                case 'polling': {
+                    const intervalMs = (entry.pollInterval ?? ctx.polling.intervalSeconds) * 1000;
+                    const requestor = resolvePollingRequestor(ctx, entry.endpoints);
+                    const factory = (sg) => createPollingSynchronizer(requestor, ctx.logger, sg, intervalMs);
+                    return createSynchronizerSlot(factory);
+                }
+                case 'streaming': {
+                    const factory = (sg) => createStreamingSynchronizer(buildStreamingBase(entry, ctx, sg));
+                    return createSynchronizerSlot(factory);
+                }
+                default:
+                    return undefined;
+            }
+        },
+    };
+}
+
 exports.platform = jsSdkCommon__namespace;
+exports.BROWSER_DATA_SYSTEM_DEFAULTS = BROWSER_DATA_SYSTEM_DEFAULTS;
+exports.BROWSER_TRANSITION_TABLE = BROWSER_TRANSITION_TABLE;
 exports.BaseDataManager = BaseDataManager;
+exports.DESKTOP_DATA_SYSTEM_DEFAULTS = DESKTOP_DATA_SYSTEM_DEFAULTS;
+exports.DESKTOP_TRANSITION_TABLE = DESKTOP_TRANSITION_TABLE;
 exports.DataSourceState = DataSourceState;
 exports.LDClientImpl = LDClientImpl;
+exports.MOBILE_DATA_SYSTEM_DEFAULTS = MOBILE_DATA_SYSTEM_DEFAULTS;
+exports.MOBILE_TRANSITION_TABLE = MOBILE_TRANSITION_TABLE;
+exports.MODE_TABLE = MODE_TABLE;
 exports.browserFdv1Endpoints = browserFdv1Endpoints;
+exports.createDataSourceStatusManager = createDataSourceStatusManager;
+exports.createDefaultSourceFactoryProvider = createDefaultSourceFactoryProvider;
+exports.dataSystemValidators = dataSystemValidators;
 exports.fdv2Endpoints = fdv2Endpoints;
 exports.makeRequestor = makeRequestor;
 exports.mobileFdv1Endpoints = mobileFdv1Endpoints;
 exports.readFlagsFromBootstrap = readFlagsFromBootstrap;
+exports.resolveConnectionMode = resolveConnectionMode;
 exports.safeRegisterDebugOverridePlugins = safeRegisterDebugOverridePlugins;
 exports.validateOptions = validateOptions;
 Object.keys(jsSdkCommon).forEach(function (k) {