mixpanel-browser 2.77.0 → 2.79.0

package/src/flags/index.js

@@ -4,11 +4,13 @@ import { Config, TARGETING_GLOBAL_NAME } from '../config';
 import {
     getTargetingPromise
 } from '../targeting/loader';
+import { FeatureFlagPersistence, VariantLookupPolicy } from './flags-persistence';
 
 var logger = console_with_prefix('flags');
 var FLAGS_CONFIG_KEY = 'flags';
 
 var CONFIG_CONTEXT = 'context';
+var CONFIG_PERSISTENCE = 'persistence';
 var CONFIG_DEFAULTS = {};
 CONFIG_DEFAULTS[CONFIG_CONTEXT] = {};
 
@@ -31,6 +33,13 @@ var getFlagKeyFromPendingEventKey = function(eventKey) {
     return eventKey.split(':')[0];
 };
 
+var withFallbackSource = function(fallback) {
+    if (_.isObject(fallback)) {
+        return _.extend({}, fallback, {'variant_source': 'fallback'});
+    }
+    return {'value': fallback, 'variant_source': 'fallback'};
+};
+
 /**
  * FeatureFlagManager: support for Mixpanel's feature flagging product
  * @constructor
@@ -53,11 +62,63 @@ FeatureFlagManager.prototype.init = function() {
     }
 
     this.flags = null;
-    this.fetchFlags();
-
     this.trackedFeatures = new Set();
     this.pendingFirstTimeEvents = {};
     this.activatedFirstTimeEvents = {};
+    this._loadedPersistedAtMs = null;
+    this._loadedTtlMs = null;
+
+    this.persistence = new FeatureFlagPersistence(
+        this.getConfig(CONFIG_PERSISTENCE),
+        this.getMpConfig('token'),
+        _.bind(function() { return this.getMpConfig('disable_persistence'); }, this)
+    );
+
+    this.persistenceLoadedPromise = this.persistence.loadFlagsFromStorage(this._buildContext())
+        .then(_.bind(function(loaded) {
+            if (loaded) {
+                this.flags = loaded.flags;
+                this.pendingFirstTimeEvents = loaded.pendingFirstTimeEvents;
+                this._loadedPersistedAtMs = loaded.persistedAtMs;
+                this._loadedTtlMs = loaded.ttlMs;
+            }
+        }, this));
+
+    return this.persistenceLoadedPromise
+        .then(_.bind(function() {
+            return this.fetchFlags();
+        }, this))
+        .catch(function() {
+            logger.error('Error initializing feature flags');
+        });
+};
+
+FeatureFlagManager.prototype._buildContext = function() {
+    return _.extend(
+        {'distinct_id': this.getMpProperty('distinct_id'), 'device_id': this.getMpProperty('$device_id')},
+        this.getConfig(CONFIG_CONTEXT)
+    );
+};
+
+FeatureFlagManager.prototype.reset = function() {
+    if (!this.persistence) {
+        return Promise.resolve();
+    }
+
+    this.flags = null;
+    this.pendingFirstTimeEvents = {};
+    this.activatedFirstTimeEvents = {};
+    this.trackedFeatures = new Set();
+    this.fetchPromise = null;
+    this._fetchInProgressStartTime = null;
+    this._loadedPersistedAtMs = null;
+    this._loadedTtlMs = null;
+
+    return this.persistence.clear().then(_.bind(function() {
+        return this.fetchFlags();
+    }, this)).catch(function() {
+        logger.error('Error during flags reset');
+    });
 };
 
 FeatureFlagManager.prototype.getFullConfig = function() {
@@ -94,8 +155,12 @@ FeatureFlagManager.prototype.updateContext = function(newContext, options) {
     var oldContext = (options && options['replace']) ? {} : this.getConfig(CONFIG_CONTEXT);
     ffConfig[CONFIG_CONTEXT] = _.extend({}, oldContext, newContext);
 
-    this.setMpConfig(FLAGS_CONFIG_KEY, ffConfig);
-    return this.fetchFlags();
+    var configUpdate = {};
+    configUpdate[FLAGS_CONFIG_KEY] = ffConfig;
+    this.setMpConfig(configUpdate);
+    return this.fetchFlags().catch(function() {
+        logger.error('Error fetching flags during updateContext');
+    });
 };
 
 FeatureFlagManager.prototype.areFlagsReady = function() {
@@ -110,12 +175,11 @@ FeatureFlagManager.prototype.fetchFlags = function() {
         return Promise.resolve();
     }
 
-    var distinctId = this.getMpProperty('distinct_id');
-    var deviceId = this.getMpProperty('$device_id');
+    var context = this._buildContext();
+    var distinctId = context['distinct_id'];
     var traceparent = generateTraceparent();
     logger.log('Fetching flags for distinct ID: ' + distinctId);
 
-    var context = _.extend({'distinct_id': distinctId, 'device_id': deviceId}, this.getConfig(CONFIG_CONTEXT));
     var searchParams = new URLSearchParams();
     searchParams.set('context', JSON.stringify(context));
     searchParams.set('token', this.getMpConfig('token'));
@@ -132,96 +196,116 @@ FeatureFlagManager.prototype.fetchFlags = function() {
         }
     }).then(function(response) {
         this.markFetchComplete();
-        return response.json().then(function(responseBody) {
-            var responseFlags = responseBody['flags'];
-            if (!responseFlags) {
-                throw new Error('No flags in API response');
-            }
-            var flags = new Map();
-            var pendingFirstTimeEvents = {};
-
-            // Process flags from response
-            _.each(responseFlags, function(data, key) {
-                // Check if this flag has any activated first-time events this session
-                var hasActivatedEvent = false;
-                var prefix = key + ':';
-                _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
-                    if (eventKey.startsWith(prefix)) {
-                        hasActivatedEvent = true;
-                    }
-                });
+        return response.json();
+    }.bind(this)).then(function(responseBody) {
+        var responseFlags = responseBody['flags'];
+        if (!responseFlags) {
+            throw new Error('No flags in API response');
+        }
+        var flags = new Map();
+        var pendingFirstTimeEvents = {};
+
+        // Process flags from response
+        _.each(responseFlags, function(data, key) {
+            // Check if this flag has any activated first-time events this session
+            var hasActivatedEvent = false;
+            var prefix = key + ':';
+            _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
+                if (eventKey.startsWith(prefix)) {
+                    hasActivatedEvent = true;
+                }
+            });
 
-                if (hasActivatedEvent) {
-                    // Preserve the activated variant, don't overwrite with server's current variant
-                    var currentFlag = this.flags && this.flags.get(key);
-                    if (currentFlag) {
-                        flags.set(key, currentFlag);
-                    }
-                } else {
-                    // Use server's current variant
-                    flags.set(key, {
-                        'key': data['variant_key'],
-                        'value': data['variant_value'],
-                        'experiment_id': data['experiment_id'],
-                        'is_experiment_active': data['is_experiment_active'],
-                        'is_qa_tester': data['is_qa_tester']
-                    });
+            if (hasActivatedEvent) {
+                // Preserve the activated variant, don't overwrite with server's current variant
+                var currentFlag = this.flags && this.flags.get(key);
+                if (currentFlag) {
+                    flags.set(key, currentFlag);
                 }
+            } else {
+                // Use server's current variant
+                flags.set(key, {
+                    'key': data['variant_key'],
+                    'value': data['variant_value'],
+                    'experiment_id': data['experiment_id'],
+                    'is_experiment_active': data['is_experiment_active'],
+                    'is_qa_tester': data['is_qa_tester'],
+                    'variant_source': 'network'
+                });
+            }
+        }, this);
+
+        // Process top-level pending_first_time_events array
+        var topLevelDefinitions = responseBody['pending_first_time_events'];
+        if (topLevelDefinitions && topLevelDefinitions.length > 0) {
+            _.each(topLevelDefinitions, function(def) {
+                var flagKey = def['flag_key'];
+                var eventKey = getPendingEventKey(flagKey, def['first_time_event_hash']);
+
+                // Skip if this specific event has already been activated this session
+                if (this.activatedFirstTimeEvents[eventKey]) {
+                    return;
+                }
+
+                // Store pending event definition using composite key
+                pendingFirstTimeEvents[eventKey] = {
+                    'flag_key': flagKey,
+                    'flag_id': def['flag_id'],
+                    'project_id': def['project_id'],
+                    'first_time_event_hash': def['first_time_event_hash'],
+                    'event_name': def['event_name'],
+                    'property_filters': def['property_filters'],
+                    'pending_variant': def['pending_variant']
+                };
             }, this);
+        }
 
-            // Process top-level pending_first_time_events array
-            var topLevelDefinitions = responseBody['pending_first_time_events'];
-            if (topLevelDefinitions && topLevelDefinitions.length > 0) {
-                _.each(topLevelDefinitions, function(def) {
-                    var flagKey = def['flag_key'];
-                    var eventKey = getPendingEventKey(flagKey, def['first_time_event_hash']);
-
-                    // Skip if this specific event has already been activated this session
-                    if (this.activatedFirstTimeEvents[eventKey]) {
-                        return;
-                    }
-
-                    // Store pending event definition using composite key
-                    pendingFirstTimeEvents[eventKey] = {
-                        'flag_key': flagKey,
-                        'flag_id': def['flag_id'],
-                        'project_id': def['project_id'],
-                        'first_time_event_hash': def['first_time_event_hash'],
-                        'event_name': def['event_name'],
-                        'property_filters': def['property_filters'],
-                        'pending_variant': def['pending_variant']
-                    };
-                }, this);
-            }
+        // Preserve any activated orphaned flags (flags that were activated but are no longer in response)
+        if (this.activatedFirstTimeEvents) {
+            _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
+                var flagKey = getFlagKeyFromPendingEventKey(eventKey);
+                if (activated && !flags.has(flagKey) && this.flags && this.flags.has(flagKey)) {
+                    // Keep the activated flag even though it's not in the new response
+                    flags.set(flagKey, this.flags.get(flagKey));
+                }
+            }, this);
+        }
 
-            // Preserve any activated orphaned flags (flags that were activated but are no longer in response)
-            if (this.activatedFirstTimeEvents) {
-                _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
-                    var flagKey = getFlagKeyFromPendingEventKey(eventKey);
-                    if (activated && !flags.has(flagKey) && this.flags && this.flags.has(flagKey)) {
-                        // Keep the activated flag even though it's not in the new response
-                        flags.set(flagKey, this.flags.get(flagKey));
-                    }
-                }, this);
-            }
+        this.flags = flags;
+        this.trackedFeatures = new Set();
+        this.pendingFirstTimeEvents = pendingFirstTimeEvents;
+        this._loadedPersistedAtMs = null;
+        this._loadedTtlMs = null;
+        this._traceparent = traceparent;
 
-            this.flags = flags;
-            this.pendingFirstTimeEvents = pendingFirstTimeEvents;
-            this._traceparent = traceparent;
+        this._loadTargetingIfNeeded();
 
-            this._loadTargetingIfNeeded();
-        }.bind(this)).catch(function(error) {
-            this.markFetchComplete();
-            logger.error(error);
-        }.bind(this));
+        this.persistence.save(context, this.flags, this.pendingFirstTimeEvents);
     }.bind(this)).catch(function(error) {
-        this.markFetchComplete();
+        if (this._fetchInProgressStartTime) {
+            this.markFetchComplete();
+        }
         logger.error(error);
+        throw error;
     }.bind(this));
 
     return this.fetchPromise;
 };
 
+FeatureFlagManager.prototype.loadFlags = function() {
+    if (!this.isSystemEnabled()) {
+        return Promise.resolve();
+    }
+    if (!this.trackedFeatures) {
+        logger.error('loadFlags called before init');
+        return Promise.resolve();
+    }
+    if (this._fetchInProgressStartTime) {
+        return this.fetchPromise;
+    }
+    return this.fetchFlags();
+};
+
 FeatureFlagManager.prototype.markFetchComplete = function() {
     if (!this._fetchInProgressStartTime) {
         logger.error('Fetch in progress started time not set, cannot mark fetch complete');
@@ -356,6 +440,7 @@ FeatureFlagManager.prototype._processFirstTimeEventCheck = function(eventName, p
         };
 
         this.flags.set(flagKey, newVariant);
+        this.trackedFeatures.delete(flagKey);
         this.activatedFirstTimeEvents[eventKey] = true;
 
         this.recordFirstTimeEvent(
@@ -405,35 +490,106 @@ FeatureFlagManager.prototype.recordFirstTimeEvent = function(flagId, projectId,
 };
 
 FeatureFlagManager.prototype.getVariant = function(featureName, fallback) {
-    if (!this.fetchPromise) {
+    if (!this.persistenceLoadedPromise) {
         return new Promise(function(resolve) {
             logger.critical('Feature Flags not initialized');
-            resolve(fallback);
+            resolve(withFallbackSource(fallback));
         });
     }
 
-    return this.fetchPromise.then(function() {
-        return this.getVariantSync(featureName, fallback);
-    }.bind(this)).catch(function(error) {
-        logger.error(error);
-        return fallback;
-    });
+    var policy = this.persistence.getPolicy();
+
+    return this.persistenceLoadedPromise.then(_.bind(function() {
+        // Serve from persistence until the network completes a successful fetch. If a non-expired cached value is available, return it without waiting on the in-flight fetch.
+        if (policy === VariantLookupPolicy.PERSISTENCE_UNTIL_NETWORK_SUCCESS) {
+            if (this.areFlagsReady() && !this._loadedPersistenceIsStale()) {
+                return this.getVariantSync(featureName, fallback);
+            }
+            if (!this.fetchPromise) {
+                return withFallbackSource(fallback);
+            }
+            return this.fetchPromise.then(_.bind(function() {
+                return this.getVariantSync(featureName, fallback);
+            }, this)).catch(function(error) {
+                logger.error(error);
+                return withFallbackSource(fallback);
+            });
+        }
+
+        var serve = _.bind(function() { return this.getVariantSync(featureName, fallback); }, this);
+        if (!this.fetchPromise) {
+            return withFallbackSource(fallback);
+        }
+        return this.fetchPromise.then(serve).catch(serve);
+    }, this));
+};
+
+FeatureFlagManager.prototype._loadedPersistenceIsStale = function() {
+    if (!this._loadedPersistedAtMs || !this._loadedTtlMs) {
+        return false;
+    }
+    return Date.now() - this._loadedPersistedAtMs >= this._loadedTtlMs;
 };
 
 FeatureFlagManager.prototype.getVariantSync = function(featureName, fallback) {
+    if (this._loadedPersistenceIsStale()) {
+        logger.log('Loaded persisted variants are past TTL so returning fallback for "' + featureName + '"');
+        return withFallbackSource(fallback);
+    }
     if (!this.areFlagsReady()) {
         logger.log('Flags not loaded yet');
-        return fallback;
+        return withFallbackSource(fallback);
     }
     var feature = this.flags.get(featureName);
     if (!feature) {
         logger.log('No flag found: "' + featureName + '"');
-        return fallback;
+        return withFallbackSource(fallback);
     }
     this.trackFeatureCheck(featureName, feature);
     return feature;
 };
 
+FeatureFlagManager.prototype.getAllVariants = function() {
+    if (!this.persistenceLoadedPromise) {
+        logger.critical('Feature Flags not initialized');
+        return Promise.resolve(new Map());
+    }
+
+    var policy = this.persistence.getPolicy();
+
+    return this.persistenceLoadedPromise.then(_.bind(function() {
+        // Serve from persistence until the network completes a successful fetch. If a non-expired cached value is available, return it without waiting on the in-flight fetch.
+        if (policy === VariantLookupPolicy.PERSISTENCE_UNTIL_NETWORK_SUCCESS) {
+            if (this.areFlagsReady() && !this._loadedPersistenceIsStale()) {
+                return this.getAllVariantsSync();
+            }
+            if (!this.fetchPromise) {
+                return new Map();
+            }
+            return this.fetchPromise.then(_.bind(function() {
+                return this.getAllVariantsSync();
+            }, this)).catch(function(error) {
+                logger.error(error);
+                return new Map();
+            });
+        }
+
+        var serve = _.bind(this.getAllVariantsSync, this);
+        if (!this.fetchPromise) {
+            return new Map();
+        }
+        return this.fetchPromise.then(serve).catch(serve);
+    }, this));
+};
+
+FeatureFlagManager.prototype.getAllVariantsSync = function() {
+    if (this._loadedPersistenceIsStale()) {
+        logger.log('Loaded persisted variants are past TTL so returning empty Map');
+        return new Map();
+    }
+    return this.flags || new Map();
+};
+
 FeatureFlagManager.prototype.getVariantValue = function(featureName, fallbackValue) {
     return this.getVariant(featureName, {'value': fallbackValue}).then(function(feature) {
         return feature['value'];
@@ -472,6 +628,10 @@ FeatureFlagManager.prototype.isEnabledSync = function(featureName, fallbackValue
     return val;
 };
 
+function isPresent(v) {
+    return v !== undefined && v !== null;
+}
+
 FeatureFlagManager.prototype.trackFeatureCheck = function(featureName, feature) {
     if (this.trackedFeatures.has(featureName)) {
         return;
@@ -482,25 +642,41 @@ FeatureFlagManager.prototype.trackFeatureCheck = function(featureName, feature)
         'Experiment name': featureName,
         'Variant name': feature['key'],
         '$experiment_type': 'feature_flag',
-        'Variant fetch start time': new Date(this._fetchStartTime).toISOString(),
-        'Variant fetch complete time': new Date(this._fetchCompleteTime).toISOString(),
+        'Variant fetch start time': isPresent(this._fetchStartTime) ? new Date(this._fetchStartTime).toISOString() : null,
+        'Variant fetch complete time': isPresent(this._fetchCompleteTime) ? new Date(this._fetchCompleteTime).toISOString() : null,
         'Variant fetch latency (ms)': this._fetchLatency,
         'Variant fetch traceparent': this._traceparent,
     };
 
-    if (feature['experiment_id'] !== 'undefined') {
+    if (isPresent(feature['experiment_id'])) {
         trackingProperties['$experiment_id'] = feature['experiment_id'];
     }
-    if (feature['is_experiment_active'] !== 'undefined') {
+    if (isPresent(feature['is_experiment_active'])) {
         trackingProperties['$is_experiment_active'] = feature['is_experiment_active'];
     }
-    if (feature['is_qa_tester'] !== 'undefined') {
+    if (isPresent(feature['is_qa_tester'])) {
         trackingProperties['$is_qa_tester'] = feature['is_qa_tester'];
     }
+    if (isPresent(feature['variant_source'])) {
+        trackingProperties['$variant_source'] = feature['variant_source'];
+    }
+    if (isPresent(feature['persisted_at_in_ms'])) {
+        trackingProperties['$persisted_at_in_ms'] = feature['persisted_at_in_ms'];
+    }
+    if (isPresent(feature['ttl_in_ms'])) {
+        trackingProperties['$ttl_in_ms'] = feature['ttl_in_ms'];
+    }
 
     this.track('$experiment_started', trackingProperties);
 };
 
+FeatureFlagManager.prototype.whenReady = function() {
+    if (this.fetchPromise) {
+        return this.fetchPromise;
+    }
+    return Promise.resolve();
+};
+
 FeatureFlagManager.prototype.minApisSupported = function() {
     return !!this.fetch &&
       typeof Promise !== 'undefined' &&
@@ -513,11 +689,15 @@ safewrapClass(FeatureFlagManager);
 FeatureFlagManager.prototype['are_flags_ready'] = FeatureFlagManager.prototype.areFlagsReady;
 FeatureFlagManager.prototype['get_variant'] = FeatureFlagManager.prototype.getVariant;
 FeatureFlagManager.prototype['get_variant_sync'] = FeatureFlagManager.prototype.getVariantSync;
+FeatureFlagManager.prototype['get_all_variants'] = FeatureFlagManager.prototype.getAllVariants;
+FeatureFlagManager.prototype['get_all_variants_sync'] = FeatureFlagManager.prototype.getAllVariantsSync;
 FeatureFlagManager.prototype['get_variant_value'] = FeatureFlagManager.prototype.getVariantValue;
 FeatureFlagManager.prototype['get_variant_value_sync'] = FeatureFlagManager.prototype.getVariantValueSync;
 FeatureFlagManager.prototype['is_enabled'] = FeatureFlagManager.prototype.isEnabled;
 FeatureFlagManager.prototype['is_enabled_sync'] = FeatureFlagManager.prototype.isEnabledSync;
+FeatureFlagManager.prototype['load_flags'] = FeatureFlagManager.prototype.loadFlags;
 FeatureFlagManager.prototype['update_context'] = FeatureFlagManager.prototype.updateContext;
+FeatureFlagManager.prototype['when_ready'] = FeatureFlagManager.prototype.whenReady;
 
 // Deprecated method
 FeatureFlagManager.prototype['get_feature_data'] = FeatureFlagManager.prototype.getFeatureData;

package/src/index.d.ts

@@ -165,8 +165,47 @@ export interface AutocaptureConfig {
   block_element_callback?: (element: Element, event: Event) => boolean;
 }
 
+/**
+ * Network-only variant lookup - no persistence. Default behavior.
+ */
+export interface NetworkOnlyFlagsPolicy {
+  variantLookupPolicy: "networkOnly";
+}
+
+/**
+ * Network-first variant lookup - prioritizes freshness.
+ * Attempts network fetch first, falls back to persisted variants on failure.
+ */
+export interface NetworkFirstFlagsPolicy {
+  variantLookupPolicy: "networkFirst";
+  /**
+   * Time-to-live in milliseconds. Persisted variants older than this are discarded.
+   * Defaults to 24 hours.
+   */
+  persistenceTtlMs?: number;
+}
+
+/**
+ * Serves persisted variants immediately while a network fetch runs in the background.
+ * Once the fetch succeeds, its result replaces the cached variants for the rest of the session.
+ */
+export interface PersistenceUntilNetworkSuccessFlagsPolicy {
+  variantLookupPolicy: "persistenceUntilNetworkSuccess";
+  /**
+   * Time-to-live in milliseconds. Persisted variants older than this are discarded.
+   * Defaults to 24 hours.
+   */
+  persistenceTtlMs?: number;
+}
+
+export type FlagsPersistencePolicy =
+  | NetworkOnlyFlagsPolicy
+  | NetworkFirstFlagsPolicy
+  | PersistenceUntilNetworkSuccessFlagsPolicy;
+
 export interface FlagsConfig {
-  context: Dict;
+  context?: Dict;
+  persistence?: FlagsPersistencePolicy;
 }
 
 export interface BeforeSendHookPayload {
@@ -349,6 +388,8 @@ export interface FlagsVariant {
   experiment_id?: string;
   is_experiment_active?: boolean;
   is_qa_tester?: boolean;
+  variant_source?: string;
+  persisted_at_in_ms?: number;
 }
 
 export interface FlagsUpdateContextOptions {
@@ -357,6 +398,7 @@ export interface FlagsUpdateContextOptions {
 
 export interface FlagsManager {
   are_flags_ready(): boolean;
+  load_flags(): Promise<void>;
   get_variant(
     featureName: string,
     fallback: FlagsVariant
@@ -364,12 +406,15 @@ export interface FlagsManager {
   get_variant_sync(featureName: string, fallback: FlagsVariant): FlagsVariant;
   get_variant_value(featureName: string, fallbackValue: any): Promise<any>;
   get_variant_value_sync(featureName: string, fallbackValue: any): any;
+  get_all_variants(): Promise<Map<string, FlagsVariant>>;
+  get_all_variants_sync(): Map<string, FlagsVariant>;
   is_enabled(featureName: string, fallbackValue?: boolean): Promise<boolean>;
   is_enabled_sync(featureName: string, fallbackValue?: boolean): boolean;
   update_context(
     context: Dict,
     options?: FlagsUpdateContextOptions
   ): Promise<void>;
+  when_ready(): Promise<void>;
 }
 
 export interface Mixpanel {