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

package/dist/cjs/index.cjs

@@ -289,35 +289,141 @@ 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 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;
+        },
+    };
+}
 
-// 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 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,
+};
+({
+    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),
+});
+({
+    type: dataSourceTypeValidator,
+    initialReconnectDelay: jsSdkCommon.TypeValidators.numberWithMin(1),
+    endpoints: validatorOf(endpointValidators),
+});
+
+const modeSwitchingValidators = {
+    lifecycle: jsSdkCommon.TypeValidators.Boolean,
+    network: jsSdkCommon.TypeValidators.Boolean,
+};
+const dataSystemValidators = {
+    initialConnectionMode: connectionModeValidator,
+    backgroundConnectionMode: connectionModeValidator,
+    automaticModeSwitching: anyOf(jsSdkCommon.TypeValidators.Boolean, validatorOf(modeSwitchingValidators)),
+};
+/**
+ * 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 +449,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 +466,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 +821,71 @@ 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');
+}
+
+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 +951,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;
@@ -813,35 +994,38 @@ class FlagPersistence {
      * {@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 +1047,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 +1076,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}`);
+        }
     }
 }
 
@@ -996,17 +1200,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)) {
@@ -1482,7 +1687,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 +2781,86 @@ 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' } },
+];
+
 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.browserFdv1Endpoints = browserFdv1Endpoints;
+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) {