@launchdarkly/js-client-sdk-common 1.24.0 → 1.26.0

package/dist/esm/index.mjs

@@ -680,13 +680,28 @@ async function digest(hasher, encoding) {
  * @param storageKey keyed storage location where the generated key should live.  See {@link namespaceForGeneratedContextKey}
  * for related exmaples of generating a storage key and usage.
  * @param platform crypto and storage implementations for necessary operations
+ * @param legacyStorageKey optional legacy storage key to migrate from. If the key is not found
+ * under {@link storageKey} but exists under this legacy key, it will be migrated to the new
+ * location and the legacy key will be cleared.
  * @returns the generated key
  */
-const getOrGenerateKey = async (storageKey, { crypto, storage }) => {
+const getOrGenerateKey = async (storageKey, { crypto, storage }, legacyStorageKey) => {
     let generatedKey = await storage?.get(storageKey);
-    if (!generatedKey) {
-        generatedKey = crypto.randomUUID();
-        await storage?.set(storageKey, generatedKey);
+    if (generatedKey == null) {
+        if (legacyStorageKey) {
+            generatedKey = await storage?.get(legacyStorageKey);
+            if (generatedKey != null) {
+                await storage?.set(storageKey, generatedKey);
+                const verified = await storage?.get(storageKey);
+                if (verified != null) {
+                    await storage?.clear(legacyStorageKey);
+                }
+            }
+        }
+        if (generatedKey == null) {
+            generatedKey = crypto.randomUUID();
+            await storage?.set(storageKey, generatedKey);
+        }
     }
     return generatedKey;
 };
@@ -709,12 +724,9 @@ async function namespaceForEnvironment(crypto, sdkKey) {
     ]);
 }
 /**
- * @deprecated prefer {@link namespaceForGeneratedContextKey}. At one time we only generated keys for
- * anonymous contexts and they were namespaced in LaunchDarkly_AnonymousKeys.  Eventually we started
- * generating context keys for non-anonymous contexts such as for the Auto Environment Attributes
- * feature and those were namespaced in LaunchDarkly_ContextKeys.  This function can be removed
- * when the data under the LaunchDarkly_AnonymousKeys namespace is merged with data under the
- * LaunchDarkly_ContextKeys namespace.
+ * @deprecated Used only for migration in ensureKey. Data stored under LaunchDarkly_AnonymousKeys
+ * is now migrated to LaunchDarkly_ContextKeys on first access. This function can be removed once
+ * all clients have had the chance to run the migration.
  */
 async function namespaceForAnonymousGeneratedContextKey(kind) {
     return concatNamespacesAndValues([
@@ -897,10 +909,11 @@ const { isLegacyUser, isMultiKind, isSingleKind } = internal;
 const ensureKeyCommon = async (kind, c, platform) => {
     const { anonymous, key } = c;
     if (anonymous && !key) {
-        const storageKey = await namespaceForAnonymousGeneratedContextKey(kind);
+        const storageKey = await namespaceForGeneratedContextKey(kind);
+        const legacyStorageKey = await namespaceForAnonymousGeneratedContextKey(kind);
         // This mutates a cloned copy of the original context from ensureyKey so this is safe.
         // eslint-disable-next-line no-param-reassign
-        c.key = await getOrGenerateKey(storageKey, platform);
+        c.key = await getOrGenerateKey(storageKey, platform, legacyStorageKey);
     }
 };
 const ensureKeySingle = async (c, platform) => {
@@ -999,6 +1012,46 @@ class EventFactory extends internal.EventFactoryBase {
     }
 }
 
+function readFlagsFromBootstrap(logger, data) {
+    // If the bootstrap data came from an older server-side SDK, we'll have just a map of keys to values.
+    // Newer SDKs that have an allFlagsState method will provide an extra "$flagsState" key that contains
+    // the rest of the metadata we want. We do it this way for backward compatibility with older JS SDKs.
+    const keys = Object.keys(data);
+    const metadataKey = '$flagsState';
+    const validKey = '$valid';
+    const metadata = data[metadataKey];
+    if (!metadata && keys.length) {
+        logger.warn('LaunchDarkly client was initialized with bootstrap data that did not include flag' +
+            ' metadata. Events may not be sent correctly.');
+    }
+    if (data[validKey] === false) {
+        logger.warn('LaunchDarkly bootstrap data is not available because the back end could not read the flags.');
+    }
+    const ret = {};
+    keys.forEach((key) => {
+        if (key !== metadataKey && key !== validKey) {
+            let flag;
+            if (metadata && metadata[key]) {
+                flag = {
+                    value: data[key],
+                    ...metadata[key],
+                };
+            }
+            else {
+                flag = {
+                    value: data[key],
+                    version: 0,
+                };
+            }
+            ret[key] = {
+                version: flag.version,
+                flag,
+            };
+        }
+    });
+    return ret;
+}
+
 /**
  * Suffix appended to context storage keys to form the freshness storage key.
  */
@@ -1927,6 +1980,10 @@ class LDClientImpl {
         this._eventFactoryWithReasons = new EventFactory(true);
         this._eventSendingEnabled = false;
         this._identifyQueue = createAsyncTaskQueue();
+        // NOTE: this is used to ease the transition to the new initialization pattern.
+        // All client SDKs should set this to true with the exception of React Native which is
+        // still using the deprecated construct + identify pattern.
+        this._requiresStart = false;
         if (!sdkKey) {
             throw new Error('You must configure the client with a client-side SDK key');
         }
@@ -1935,6 +1992,8 @@ class LDClientImpl {
         }
         this._config = new ConfigurationImpl(options, internalOptions);
         this.logger = this._config.logger;
+        this._requiresStart = internalOptions?.requiresStart ?? false;
+        this.initialContext = internalOptions?.initialContext;
         this._baseHeaders = 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.disableCache ?? false, this._config.logger);
         this._diagnosticsManager = createDiagnosticsManager(sdkKey, this._config, platform);
@@ -1952,6 +2011,8 @@ class LDClientImpl {
             });
         });
         this.dataManager = dataManagerFactory(this._flagManager, this._config, this._baseHeaders, this.emitter, this._diagnosticsManager);
+        this.isFDv2 = !!this._config.dataSystem;
+        this.dataSystemConfig = this._config.dataSystem;
         const hooks = [...this._config.hooks];
         this.environmentMetadata = createPluginEnvironmentMetadata(this.sdkKey, this.platform, this._config);
         this._config.getImplementationHooks(this.environmentMetadata).forEach((hook) => {
@@ -2029,6 +2090,57 @@ class LDClientImpl {
     presetFlags(newFlags) {
         this._flagManager.presetFlags(newFlags);
     }
+    /**
+     * Starts the client and returns a promise that resolves to the initialization result.
+     *
+     * This method is idempotent - calling it multiple times returns the same promise.
+     *
+     * @param options Optional configuration. See {@link LDStartOptions}.
+     * @returns A promise that resolves to the initialization result.
+     */
+    start(options) {
+        if (this.initializeResult) {
+            return Promise.resolve(this.initializeResult);
+        }
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+        if (!this.initialContext) {
+            this.logger.error('Initial context not set');
+            return Promise.resolve({ status: 'failed', error: new Error('Initial context not set') });
+        }
+        const identifyOptions = {
+            ...(options?.identifyOptions ?? {}),
+            // Initial identify operations are not sheddable.
+            sheddable: false,
+        };
+        // If the bootstrap data is provided in the start options, and the identify options do not
+        // have bootstrap data, then use the bootstrap data from the start options.
+        if (options?.bootstrap && !identifyOptions.bootstrap) {
+            identifyOptions.bootstrap = options.bootstrap;
+        }
+        if (identifyOptions.bootstrap) {
+            try {
+                if (!identifyOptions.bootstrapParsed) {
+                    identifyOptions.bootstrapParsed = readFlagsFromBootstrap(this.logger, identifyOptions.bootstrap);
+                }
+                if (identifyOptions.bootstrapParsed) {
+                    this.presetFlags(identifyOptions.bootstrapParsed);
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to bootstrap data', error);
+            }
+        }
+        if (!this.initializedPromise) {
+            this.initializedPromise = new Promise((resolve) => {
+                this.initResolve = resolve;
+            });
+        }
+        this.startPromise = this._promiseWithTimeout(this.initializedPromise, options?.timeout ?? 5, 'start');
+        this.identifyResult(this.initialContext, identifyOptions);
+        return this.startPromise;
+    }
     /**
      * Identifies a context to LaunchDarkly. See {@link LDClient.identify}.
      *
@@ -2066,6 +2178,10 @@ class LDClientImpl {
         // If completed or shed, then we are done.
     }
     async identifyResult(pristineContext, identifyOptions) {
+        if (this._requiresStart && !this.startPromise) {
+            this.logger.error('The client must be started before a context can be identified. Call start() prior to identifying a context.');
+            return { status: 'error', error: new Error('Identify called before start') };
+        }
         const identifyTimeout = identifyOptions?.timeout ?? DEFAULT_IDENTIFY_TIMEOUT_SECONDS;
         const noTimeout = identifyOptions?.timeout === undefined && identifyOptions?.noTimeout === true;
         // When noTimeout is specified, and a timeout is not specified, then this condition cannot
@@ -2175,7 +2291,7 @@ class LDClientImpl {
         // 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);
+            return this._promiseWithTimeout(this.initializedPromise, timeout);
         }
         // Create a new promise for tracking initialization
         if (!this.initializedPromise) {
@@ -2183,22 +2299,18 @@ class LDClientImpl {
                 this.initResolve = resolve;
             });
         }
-        return this.promiseWithTimeout(this.initializedPromise, timeout);
+        return this._promiseWithTimeout(this.initializedPromise, timeout);
     }
     /**
-     * Apply a timeout promise to a base promise. This is for use with waitForInitialization.
+     * Apply a timeout promise to a base promise. This is for use with waitForInitialization
+     * and start.
      *
      * @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 = cancelableTimedPromise(timeout, 'waitForInitialization');
+    _promiseWithTimeout(basePromise, timeout, label = 'waitForInitialization') {
+        const cancelableTimeout = cancelableTimedPromise(timeout, label);
         return Promise.race([
             basePromise.then((res) => {
                 cancelableTimeout.cancel();
@@ -2428,46 +2540,6 @@ function safeRegisterDebugOverridePlugins(logger, debugOverride, plugins) {
     });
 }
 
-function readFlagsFromBootstrap(logger, data) {
-    // If the bootstrap data came from an older server-side SDK, we'll have just a map of keys to values.
-    // Newer SDKs that have an allFlagsState method will provide an extra "$flagsState" key that contains
-    // the rest of the metadata we want. We do it this way for backward compatibility with older JS SDKs.
-    const keys = Object.keys(data);
-    const metadataKey = '$flagsState';
-    const validKey = '$valid';
-    const metadata = data[metadataKey];
-    if (!metadata && keys.length) {
-        logger.warn('LaunchDarkly client was initialized with bootstrap data that did not include flag' +
-            ' metadata. Events may not be sent correctly.');
-    }
-    if (data[validKey] === false) {
-        logger.warn('LaunchDarkly bootstrap data is not available because the back end could not read the flags.');
-    }
-    const ret = {};
-    keys.forEach((key) => {
-        if (key !== metadataKey && key !== validKey) {
-            let flag;
-            if (metadata && metadata[key]) {
-                flag = {
-                    value: data[key],
-                    ...metadata[key],
-                };
-            }
-            else {
-                flag = {
-                    value: data[key],
-                    version: 0,
-                };
-            }
-            ret[key] = {
-                version: flag.version,
-                flag,
-            };
-        }
-    });
-    return ret;
-}
-
 /**
  * Creates endpoint paths for browser (client-side ID) FDv1 evaluation.
  *
@@ -3190,12 +3262,12 @@ 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);
+        return changeSet({ version: 0, type: 'none', updates: [] }, false);
     }
     const cached = await loadCachedFlags(storage, crypto, environmentNamespace, context, logger);
     if (!cached) {
         logger?.debug('Cache miss for context');
-        return interrupted(errorInfoFromUnknown('Cache miss'), false);
+        return changeSet({ version: 0, type: 'none', updates: [] }, false);
     }
     const updates = Object.entries(cached.flags).map(([key, flag]) => ({
         kind: 'flag-eval',
@@ -3228,21 +3300,24 @@ async function loadFromCache(config) {
  * @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;
-            },
-        };
+    return {
+        isCache: true,
+        // The selectorGetter is ignored -- cache data has no selector.
+        create(_selectorGetter) {
+            let shutdownResolve;
+            const shutdownPromise = new Promise((resolve) => {
+                shutdownResolve = resolve;
+            });
+            return {
+                async run() {
+                    return Promise.race([shutdownPromise, loadFromCache(config)]);
+                },
+                close() {
+                    shutdownResolve?.(shutdown());
+                    shutdownResolve = undefined;
+                },
+            };
+        },
     };
 }
 
@@ -3710,7 +3785,7 @@ function createSourceManager(initializerFactories, synchronizerSlots, selectorGe
                 return undefined;
             }
             closeActiveSource();
-            const initializer = initializerFactories[initializerIndex](selectorGetter);
+            const initializer = initializerFactories[initializerIndex].create(selectorGetter);
             activeSource = initializer;
             return initializer;
         },
@@ -3730,7 +3805,7 @@ function createSourceManager(initializerFactories, synchronizerSlots, selectorGe
                 const candidate = synchronizerSlots[synchronizerIndex];
                 if (candidate.state === 'available') {
                     closeActiveSource();
-                    const synchronizer = candidate.factory(selectorGetter);
+                    const synchronizer = candidate.factory.create(selectorGetter);
                     activeSource = synchronizer;
                     return synchronizer;
                 }
@@ -4120,10 +4195,14 @@ function createDefaultSourceFactoryProvider() {
             switch (entry.type) {
                 case 'polling': {
                     const requestor = resolvePollingRequestor(ctx, entry.endpoints);
-                    return (sg) => createPollingInitializer(requestor, ctx.logger, sg);
+                    return {
+                        create: (sg) => createPollingInitializer(requestor, ctx.logger, sg),
+                    };
                 }
                 case 'streaming':
-                    return (sg) => createStreamingInitializer(buildStreamingBase(entry, ctx, sg));
+                    return {
+                        create: (sg) => createStreamingInitializer(buildStreamingBase(entry, ctx, sg)),
+                    };
                 case 'cache':
                     return createCacheInitializerFactory({
                         storage: ctx.storage,
@@ -4141,13 +4220,14 @@ function createDefaultSourceFactoryProvider() {
                 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);
+                    return createSynchronizerSlot({
+                        create: (sg) => createPollingSynchronizer(requestor, ctx.logger, sg, intervalMs),
+                    });
                 }
+                case 'streaming':
+                    return createSynchronizerSlot({
+                        create: (sg) => createStreamingSynchronizer(buildStreamingBase(entry, ctx, sg)),
+                    });
                 default:
                     return undefined;
             }
@@ -4418,6 +4498,15 @@ function createFDv2DataSource(config) {
     let dataReceived = false;
     let initResolve;
     let initReject;
+    // When every initializer is a cache initializer and there are no
+    // synchronizers, the cache is the only possible data source. A cache miss
+    // in that configuration must not fail initialization -- there is nowhere
+    // else for data to come from, and reporting an error would be meaningless.
+    // Mirrors the Android SDK's InitializerFromCache / hasAvailableSources
+    // behavior.
+    const cacheOnlyDataSystem = initializerFactories.length > 0 &&
+        initializerFactories.every((f) => f.isCache === true) &&
+        synchronizerSlots.length === 0;
     const sourceManager = createSourceManager(initializerFactories, synchronizerSlots, selectorGetter);
     function markInitialized() {
         if (!initialized) {
@@ -4447,6 +4536,10 @@ function createFDv2DataSource(config) {
     // The orchestration loops intentionally use await-in-loop for sequential
     // state machine processing — one result at a time.
     async function runInitializers() {
+        // Tracks whether any initializer reported interrupted/terminal_error.
+        // Used below so the cache-only exhaustion branch does not overwrite
+        // that error status with VALID.
+        let errorReportedDuringInit = false;
         while (!closed) {
             const initializer = sourceManager.getNextInitializerAndSetActive();
             if (initializer === undefined) {
@@ -4456,16 +4549,16 @@ function createFDv2DataSource(config) {
             if (closed) {
                 return;
             }
-            if (result.type === 'changeSet') {
+            if (result.type === 'changeSet' && result.payload.type !== 'none') {
                 applyChangeSet(result);
                 if (handleFdv1Fallback(result)) {
-                    // FDv1 fallback triggered during initialization — data was received
+                    // FDv1 fallback triggered during initialization -- data was received
                     // but we should move to synchronizers where the FDv1 adapter will run.
                     dataReceived = true;
                     break;
                 }
                 if (result.payload.state) {
-                    // Got basis data with a selector — initialization is complete.
+                    // Got basis data with a selector -- initialization is complete.
                     markInitialized();
                     return;
                 }
@@ -4479,6 +4572,7 @@ function createFDv2DataSource(config) {
                     case 'terminal_error':
                         logger?.warn(`Initializer failed: ${result.errorInfo?.message ?? 'unknown error'}`);
                         reportStatusError(result);
+                        errorReportedDuringInit = true;
                         break;
                     case 'shutdown':
                         return;
@@ -4486,8 +4580,30 @@ function createFDv2DataSource(config) {
                 handleFdv1Fallback(result);
             }
         }
+        // close() between the last loop iteration and the exhaustion branch.
+        // Exit without marking initialized or emitting a spurious VALID; the
+        // start() promise will be rejected by the post-orchestration handler
+        // with "closed before initialization completed."
+        if (closed) {
+            return;
+        }
         // All initializers exhausted.
-        if (dataReceived) {
+        if (cacheOnlyDataSystem) {
+            // Cache-only data system with no synchronizer to produce a VALID
+            // status on its own. On a cache miss with no errors, nothing else
+            // has asserted VALID yet, so do it here. Skip the update if:
+            //   - dataReceived (cache hit): applyChangeSet already asserted VALID.
+            //   - errorReportedDuringInit: reportError set an error status that
+            //     must not be silently overwritten.
+            if (!dataReceived && !errorReportedDuringInit) {
+                statusManager.requestStateUpdate('VALID');
+            }
+            markInitialized();
+        }
+        else if (dataReceived) {
+            // At least one initializer delivered data. Do not overwrite any
+            // error status that a subsequent failed initializer may have
+            // reported -- the status will be driven by the synchronizers.
             markInitialized();
         }
     }
@@ -4718,6 +4834,13 @@ function createFDv2DataManagerBase(baseConfig) {
     let bootstrapped = false;
     let closed = false;
     let flushCallback;
+    /**
+     * The minimum data availability required before the identify promise
+     * resolves. Maps from the public `waitForNetworkResults` option:
+     * - `'cached'` -- resolve as soon as any data (e.g. from cache) is delivered
+     * - `'fresh'`  -- wait for network data with a selector (REFRESHED state)
+     */
+    let minimumDataAvailability = 'fresh';
     // Explicit connection mode override — bypasses transition table entirely.
     let connectionModeOverride;
     // Forced/automatic streaming state for browser listener-driven streaming.
@@ -4820,7 +4943,9 @@ function createFDv2DataManagerBase(baseConfig) {
                 ? new ServiceEndpoints(fallbackConfig.endpoints.streamingBaseUri ?? ctx.serviceEndpoints.streaming, fallbackConfig.endpoints.pollingBaseUri ?? ctx.serviceEndpoints.polling, ctx.serviceEndpoints.events, ctx.serviceEndpoints.analyticsEventPath, ctx.serviceEndpoints.diagnosticEventPath, ctx.serviceEndpoints.includeAuthorizationHeader, ctx.serviceEndpoints.payloadFilterKey)
                 : ctx.serviceEndpoints;
             const fdv1RequestorFactory = () => makeRequestor(ctx.plainContextString, fallbackServiceEndpoints, fdv1Endpoints.polling(), ctx.requests, ctx.encoding, ctx.baseHeaders, ctx.queryParams, config.withReasons, config.useReport);
-            const fdv1SyncFactory = () => createFDv1PollingSynchronizer(fdv1RequestorFactory(), fallbackPollIntervalMs, logger);
+            const fdv1SyncFactory = {
+                create: () => createFDv1PollingSynchronizer(fdv1RequestorFactory(), fallbackPollIntervalMs, logger),
+            };
             synchronizerSlots.push(createSynchronizerSlot(fdv1SyncFactory, { isFDv1Fallback: true }));
         }
         return { initializerFactories, synchronizerSlots };
@@ -4839,11 +4964,21 @@ function createFDv2DataManagerBase(baseConfig) {
         }
         const descriptors = flagEvalPayloadToItemDescriptors(payload.updates ?? []);
         // Flag updates and change events happen synchronously inside applyChanges.
-        // The returned promise is only for async cache persistence — we intentionally
+        // The returned promise is only for async cache persistence -- we intentionally
         // do not await it so the data source pipeline is not blocked by storage I/O.
         flagManager.applyChanges(context, descriptors, payload.type).catch((e) => {
             logger.warn(`${logTag} Failed to persist flag cache: ${e}`);
         });
+        // When the minimum data availability is 'cached', resolve the identify
+        // promise as soon as any data (e.g. from cache) has been delivered. The
+        // data source continues its initialization pipeline normally --
+        // subsequent changesets update flags and fire change events.
+        if (minimumDataAvailability === 'cached' && !initialized && pendingIdentifyResolve) {
+            initialized = true;
+            pendingIdentifyResolve();
+            pendingIdentifyResolve = undefined;
+            pendingIdentifyReject = undefined;
+        }
     }
     /**
      * Create and start a new FDv2DataSource for the given mode.
@@ -4950,6 +5085,7 @@ function createFDv2DataManagerBase(baseConfig) {
             selector = undefined;
             initialized = false;
             bootstrapped = false;
+            minimumDataAvailability = identifyOptions?.waitForNetworkResults ? 'fresh' : 'cached';
             identifiedContext = context;
             pendingIdentifyResolve = identifyResolve;
             pendingIdentifyReject = identifyReject;