@launchdarkly/js-client-sdk-common 1.16.0 → 1.17.1

package/dist/cjs/index.cjs

@@ -260,6 +260,7 @@ const validators = {
     payloadFilterKey: jsSdkCommon.TypeValidators.stringMatchingRegex(/^[a-zA-Z0-9](\w|\.|-)*$/),
     hooks: jsSdkCommon.TypeValidators.createTypeArray('Hook[]', {}),
     inspectors: jsSdkCommon.TypeValidators.createTypeArray('LDInspection', {}),
+    cleanOldPersistentData: jsSdkCommon.TypeValidators.Boolean,
 };
 
 const DEFAULT_POLLING_INTERVAL = 60 * 5;
@@ -863,30 +864,30 @@ class FlagPersistence {
 }
 
 /**
- * In memory flag store.
+ * Creates the default implementation of the flag store.
  */
-class DefaultFlagStore {
-    constructor() {
-        this._flags = {};
-    }
-    init(newFlags) {
-        this._flags = Object.entries(newFlags).reduce((acc, [key, flag]) => {
-            acc[key] = flag;
-            return acc;
-        }, {});
-    }
-    insertOrUpdate(key, update) {
-        this._flags[key] = update;
-    }
-    get(key) {
-        if (Object.prototype.hasOwnProperty.call(this._flags, key)) {
-            return this._flags[key];
-        }
-        return undefined;
-    }
-    getAll() {
-        return this._flags;
-    }
+function createDefaultFlagStore() {
+    let flags = {};
+    return {
+        init(newFlags) {
+            flags = Object.entries(newFlags).reduce((acc, [key, flag]) => {
+                acc[key] = flag;
+                return acc;
+            }, {});
+        },
+        insertOrUpdate(key, update) {
+            flags[key] = update;
+        },
+        get(key) {
+            if (Object.prototype.hasOwnProperty.call(flags, key)) {
+                return flags[key];
+            }
+            return undefined;
+        },
+        getAll() {
+            return flags;
+        },
+    };
 }
 
 function calculateChangedKeys(existingObject, newObject) {
@@ -907,70 +908,66 @@ function calculateChangedKeys(existingObject, newObject) {
     return changedKeys;
 }
 
-/**
- * The flag updater handles logic required during the flag update process.
- * It handles versions checking to handle out of order flag updates and
- * also handles flag comparisons for change notification.
- */
-class FlagUpdater {
-    constructor(flagStore, logger) {
-        this._changeCallbacks = new Array();
-        this._flagStore = flagStore;
-        this._logger = logger;
-    }
-    handleFlagChanges(keys, type) {
-        if (this._activeContext) {
-            this._changeCallbacks.forEach((callback) => {
-                try {
-                    callback(this._activeContext, keys, type);
-                }
-                catch (err) {
-                    /* intentionally empty */
-                }
-            });
-        }
-        else {
-            this._logger.warn('Received a change event without an active context. Changes will not be propagated.');
-        }
-    }
-    init(context, newFlags) {
-        this._activeContext = context;
-        const oldFlags = this._flagStore.getAll();
-        this._flagStore.init(newFlags);
-        const changed = calculateChangedKeys(oldFlags, newFlags);
-        if (changed.length > 0) {
-            this.handleFlagChanges(changed, 'init');
-        }
-    }
-    initCached(context, newFlags) {
-        if (this._activeContext?.canonicalKey === context.canonicalKey) {
-            return;
-        }
-        this.init(context, newFlags);
-    }
-    upsert(context, key, item) {
-        if (this._activeContext?.canonicalKey !== context.canonicalKey) {
-            this._logger.warn('Received an update for an inactive context.');
-            return false;
-        }
-        const currentValue = this._flagStore.get(key);
-        if (currentValue !== undefined && currentValue.version >= item.version) {
-            // this is an out of order update that can be ignored
-            return false;
-        }
-        this._flagStore.insertOrUpdate(key, item);
-        this.handleFlagChanges([key], 'patch');
-        return true;
-    }
-    on(callback) {
-        this._changeCallbacks.push(callback);
-    }
-    off(callback) {
-        const index = this._changeCallbacks.indexOf(callback);
-        if (index > -1) {
-            this._changeCallbacks.splice(index, 1);
-        }
-    }
+function createFlagUpdater(_flagStore, _logger) {
+    const flagStore = _flagStore;
+    const logger = _logger;
+    let activeContext;
+    const changeCallbacks = new Array();
+    return {
+        handleFlagChanges(keys, type) {
+            if (activeContext) {
+                changeCallbacks.forEach((callback) => {
+                    try {
+                        callback(activeContext, keys, type);
+                    }
+                    catch (err) {
+                        /* intentionally empty */
+                    }
+                });
+            }
+            else {
+                logger.warn('Received a change event without an active context. Changes will not be propagated.');
+            }
+        },
+        init(context, newFlags) {
+            activeContext = context;
+            const oldFlags = flagStore.getAll();
+            flagStore.init(newFlags);
+            const changed = calculateChangedKeys(oldFlags, newFlags);
+            if (changed.length > 0) {
+                this.handleFlagChanges(changed, 'init');
+            }
+        },
+        initCached(context, newFlags) {
+            if (activeContext?.canonicalKey === context.canonicalKey) {
+                return;
+            }
+            this.init(context, newFlags);
+        },
+        upsert(context, key, item) {
+            if (activeContext?.canonicalKey !== context.canonicalKey) {
+                logger.warn('Received an update for an inactive context.');
+                return false;
+            }
+            const currentValue = flagStore.get(key);
+            if (currentValue !== undefined && currentValue.version >= item.version) {
+                // this is an out of order update that can be ignored
+                return false;
+            }
+            flagStore.insertOrUpdate(key, item);
+            this.handleFlagChanges([key], 'patch');
+            return true;
+        },
+        on(callback) {
+            changeCallbacks.push(callback);
+        },
+        off(callback) {
+            const index = changeCallbacks.indexOf(callback);
+            if (index > -1) {
+                changeCallbacks.splice(index, 1);
+            }
+        },
+    };
 }
 
 class DefaultFlagManager {
@@ -982,8 +979,8 @@ class DefaultFlagManager {
      * @param timeStamper exists for testing purposes
      */
     constructor(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
-        this._flagStore = new DefaultFlagStore();
-        this._flagUpdater = new FlagUpdater(this._flagStore, logger);
+        this._flagStore = createDefaultFlagStore();
+        this._flagUpdater = createFlagUpdater(this._flagStore, logger);
         this._flagPersistencePromise = this._initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper);
     }
     async _initPersistence(platform, sdkKey, maxCachedContexts, logger, timeStamper = () => Date.now()) {
@@ -1486,6 +1483,24 @@ class LDClientImpl {
         if (this._inspectorManager.hasInspectors()) {
             this._hookRunner.addHook(getInspectorHook(this._inspectorManager));
         }
+        if (options.cleanOldPersistentData &&
+            internalOptions?.getLegacyStorageKeys &&
+            this.platform.storage) {
+            // NOTE: we are letting this fail silently because it's not critical and we don't want to block the client from initializing.
+            try {
+                this.logger.debug('Cleaning old persistent data.');
+                Promise.all(internalOptions.getLegacyStorageKeys().map((key) => this.platform.storage?.clear(key)))
+                    .catch((error) => {
+                    this.logger.error(`Error cleaning old persistent data: ${error}`);
+                })
+                    .finally(() => {
+                    this.logger.debug('Cleaned old persistent data.');
+                });
+            }
+            catch (error) {
+                this.logger.error(`Error cleaning old persistent data: ${error}`);
+            }
+        }
     }
     allFlags() {
         // extracting all flag values
@@ -1630,13 +1645,18 @@ class LDClientImpl {
         }, identifyOptions?.sheddable ?? false)
             .then((res) => {
             if (res.status === 'error') {
-                return { status: 'error', error: res.error };
+                const errorResult = { status: 'error', error: res.error };
+                // Track initialization state for waitForInitialization
+                this.maybeSetInitializationResult({ status: 'failed', error: res.error });
+                return errorResult;
             }
             if (res.status === 'shed') {
                 return { status: 'shed' };
             }
-            this.emitter.emit('initialized');
-            return { status: 'completed' };
+            const successResult = { status: 'completed' };
+            // Track initialization state for waitForInitialization
+            this.maybeSetInitializationResult({ status: 'complete' });
+            return successResult;
         });
         if (noTimeout) {
             return callSitePromise;
@@ -1648,6 +1668,74 @@ class LDClientImpl {
         });
         return Promise.race([callSitePromise, timeoutPromise]);
     }
+    /**
+     * Sets the initialization result and resolves any pending waitForInitialization promises.
+     * This method is idempotent and will only be set by the initialization flow. Subsequent calls
+     * should not do anything.
+     * @param result The initialization result.
+     */
+    maybeSetInitializationResult(result) {
+        if (this.initializeResult === undefined) {
+            this.initializeResult = result;
+            this.emitter.emit('ready');
+            if (result.status === 'complete') {
+                this.emitter.emit('initialized');
+            }
+            if (this.initResolve) {
+                this.initResolve(result);
+                this.initResolve = undefined;
+            }
+        }
+    }
+    waitForInitialization(options) {
+        const timeout = options?.timeout ?? 5;
+        // If initialization has already completed (successfully or failed), return the result immediately.
+        if (this.initializeResult) {
+            return Promise.resolve(this.initializeResult);
+        }
+        // If waitForInitialization was previously called, then return the promise with a timeout.
+        // This condition should only be triggered if waitForInitialization was called multiple times.
+        if (this.initializedPromise) {
+            return this.promiseWithTimeout(this.initializedPromise, timeout);
+        }
+        // Create a new promise for tracking initialization
+        if (!this.initializedPromise) {
+            this.initializedPromise = new Promise((resolve) => {
+                this.initResolve = resolve;
+            });
+        }
+        return this.promiseWithTimeout(this.initializedPromise, timeout);
+    }
+    /**
+     * Apply a timeout promise to a base promise. This is for use with waitForInitialization.
+     *
+     * @param basePromise The promise to race against a timeout.
+     * @param timeout The timeout in seconds.
+     * @returns A promise that resolves to the initialization result or timeout.
+     *
+     * @privateRemarks
+     * This method is protected because it is used by the browser SDK's `start` method.
+     * Eventually, the start method will be moved to this common implementation and this method will
+     * be made private.
+     */
+    promiseWithTimeout(basePromise, timeout) {
+        const cancelableTimeout = jsSdkCommon.cancelableTimedPromise(timeout, 'waitForInitialization');
+        return Promise.race([
+            basePromise.then((res) => {
+                cancelableTimeout.cancel();
+                return res;
+            }),
+            cancelableTimeout.promise
+                // If the promise resolves without error, then the initialization completed successfully.
+                // NOTE: this should never return as the resolution would only be triggered by the basePromise
+                // being resolved.
+                .then(() => ({ status: 'complete' }))
+                .catch(() => ({ status: 'timeout' })),
+        ]).catch((reason) => {
+            this.logger?.error(reason.message);
+            return { status: 'failed', error: reason };
+        });
+    }
     on(eventName, listener) {
         this.emitter.on(eventName, listener);
     }
@@ -1686,8 +1774,7 @@ class LDClientImpl {
         const foundItem = this._flagManager.get(flagKey);
         if (foundItem === undefined || foundItem.flag.deleted) {
             const defVal = defaultValue ?? null;
-            const error = new jsSdkCommon.LDClientError(`Unknown feature flag "${flagKey}"; returning default value ${defVal}.`);
-            this.emitter.emit('error', this._activeContextTracker.getUnwrappedContext(), error);
+            this.logger?.warn(`Unknown feature flag "${flagKey}"; returning default value ${defVal}.`);
             if (hasContext) {
                 this._eventProcessor?.sendEvent(this._eventFactoryDefault.unknownFlagEvent(flagKey, defVal, evalContext));
             }
@@ -1833,6 +1920,9 @@ class LDClientImpl {
                 };
             }
         });
+        // NOTE: we are not tracking "override" changes because, at the time of writing,
+        // these changes are only used for debugging purposes and are not persisted. This
+        // may change in the future.
         if (type === 'init') {
             this._inspectorManager.onFlagsChanged(details);
         }