@launchdarkly/js-sdk-common 2.16.0 → 2.18.0

package/dist/esm/index.mjs

@@ -115,6 +115,9 @@ class AttributeReference {
         return (this.depth === other.depth &&
             this._components.every((value, index) => value === other.getComponent(index)));
     }
+    get components() {
+        return [...this._components];
+    }
 }
 /**
  * For use as invalid references when deserializing Flag/Segment data.
@@ -314,6 +317,41 @@ function isLegacyUser(context) {
     return !('kind' in context) || context.kind === null || context.kind === undefined;
 }
 
+/**
+ * Given some object to serialize product a canonicalized JSON string.
+ * https://www.rfc-editor.org/rfc/rfc8785.html
+ *
+ * We do not support custom toJSON methods on objects. Objects should be limited to basic types.
+ *
+ * @param object The object to serialize.
+ */
+function canonicalize(object, visited = []) {
+    // For JavaScript the default JSON serialization will produce canonicalized output for basic types.
+    if (object === null || typeof object !== 'object') {
+        return JSON.stringify(object);
+    }
+    if (visited.includes(object)) {
+        throw new Error('Cycle detected');
+    }
+    if (Array.isArray(object)) {
+        const values = object
+            .map((item) => canonicalize(item, [...visited, object]))
+            .map((item) => (item === undefined ? 'null' : item));
+        return `[${values.join(',')}]`;
+    }
+    const values = Object.keys(object)
+        .sort()
+        .map((key) => {
+        const value = canonicalize(object[key], [...visited, object]);
+        if (value !== undefined) {
+            return `${JSON.stringify(key)}:${value}`;
+        }
+        return undefined;
+    })
+        .filter((item) => item !== undefined);
+    return `{${values.join(',')}}`;
+}
+
 // The general strategy for the context is to transform the passed in context
 // as little as possible. We do convert the legacy users to a single kind
 // context, but we do not translate all passed contexts into a rigid structure.
@@ -688,6 +726,28 @@ class Context {
     get legacy() {
         return this._wasLegacy;
     }
+    /**
+     * Get the serialized canonical JSON for this context. This is not filtered for use in events.
+     *
+     * This method will cache the result.
+     *
+     * @returns The serialized canonical JSON or undefined if it cannot be serialized.
+     */
+    canonicalUnfilteredJson() {
+        if (!this.valid) {
+            return undefined;
+        }
+        if (this._cachedCanonicalJson) {
+            return this._cachedCanonicalJson;
+        }
+        try {
+            this._cachedCanonicalJson = canonicalize(Context.toLDContext(this));
+        }
+        catch {
+            // Indicated by undefined being returned.
+        }
+        return this._cachedCanonicalJson;
+    }
 }
 Context.UserKind = DEFAULT_KIND;
 
@@ -811,6 +871,482 @@ class ContextFilter {
     }
 }
 
+const MAX_RETRY_DELAY = 30 * 1000; // Maximum retry delay 30 seconds.
+const JITTER_RATIO = 0.5; // Delay should be 50%-100% of calculated time.
+/**
+ * Implements exponential backoff and jitter. This class tracks successful connections and failures
+ * and produces a retry delay.
+ *
+ * It does not start any timers or directly control a connection.
+ *
+ * The backoff follows an exponential backoff scheme with 50% jitter starting at
+ * initialRetryDelayMillis and capping at MAX_RETRY_DELAY.  If RESET_INTERVAL has elapsed after a
+ * success, without an intervening faulure, then the backoff is reset to initialRetryDelayMillis.
+ */
+class DefaultBackoff {
+    constructor(initialRetryDelayMillis, _retryResetIntervalMillis, _random = Math.random) {
+        this._retryResetIntervalMillis = _retryResetIntervalMillis;
+        this._random = _random;
+        this._retryCount = 0;
+        // Initial retry delay cannot be 0.
+        this._initialRetryDelayMillis = Math.max(1, initialRetryDelayMillis);
+        this._maxExponent = Math.ceil(Math.log2(MAX_RETRY_DELAY / this._initialRetryDelayMillis));
+    }
+    _backoff() {
+        const exponent = Math.min(this._retryCount, this._maxExponent);
+        const delay = this._initialRetryDelayMillis * 2 ** exponent;
+        return Math.min(delay, MAX_RETRY_DELAY);
+    }
+    _jitter(computedDelayMillis) {
+        return computedDelayMillis - Math.trunc(this._random() * JITTER_RATIO * computedDelayMillis);
+    }
+    /**
+     * This function should be called when a connection attempt is successful.
+     *
+     * @param timeStampMs The time of the success. Used primarily for testing, when not provided
+     * the current time is used.
+     */
+    success(timeStampMs = Date.now()) {
+        this._activeSince = timeStampMs;
+    }
+    /**
+     * This function should be called when a connection fails. It returns the a delay, in
+     * milliseconds, after which a reconnection attempt should be made.
+     *
+     * @param timeStampMs The time of the success. Used primarily for testing, when not provided
+     * the current time is used.
+     * @returns The delay before the next connection attempt.
+     */
+    fail(timeStampMs = Date.now()) {
+        // If the last successful connection was active for more than the RESET_INTERVAL, then we
+        // return to the initial retry delay.
+        if (this._activeSince !== undefined &&
+            timeStampMs - this._activeSince > this._retryResetIntervalMillis) {
+            this._retryCount = 0;
+        }
+        this._activeSince = undefined;
+        const delay = this._jitter(this._backoff());
+        this._retryCount += 1;
+        return delay;
+    }
+}
+
+/**
+ * Handler that connects the current {@link DataSource} to the {@link CompositeDataSource}.  A single
+ * {@link CallbackHandler} should only be given to one {@link DataSource}.  Use {@link disable()} to
+ * prevent additional callback events.
+ */
+class CallbackHandler {
+    constructor(_dataCallback, _statusCallback) {
+        this._dataCallback = _dataCallback;
+        this._statusCallback = _statusCallback;
+        this._disabled = false;
+    }
+    disable() {
+        this._disabled = true;
+    }
+    async dataHandler(basis, data) {
+        if (this._disabled) {
+            return;
+        }
+        // TODO: SDK-1044 track selector for future synchronizer to use
+        // report data up
+        this._dataCallback(basis, data);
+    }
+    async statusHandler(status, err) {
+        if (this._disabled) {
+            return;
+        }
+        this._statusCallback(status, err);
+    }
+}
+
+// TODO: refactor client-sdk to use this enum
+var DataSourceState;
+(function (DataSourceState) {
+    // Positive confirmation of connection/data receipt
+    DataSourceState[DataSourceState["Valid"] = 0] = "Valid";
+    // Spinning up to make first connection attempt
+    DataSourceState[DataSourceState["Initializing"] = 1] = "Initializing";
+    // Transient issue, automatic retry is expected
+    DataSourceState[DataSourceState["Interrupted"] = 2] = "Interrupted";
+    // Data source was closed and will not retry automatically.
+    DataSourceState[DataSourceState["Closed"] = 3] = "Closed";
+})(DataSourceState || (DataSourceState = {}));
+
+/**
+ * Helper class for {@link CompositeDataSource} to manage iterating on data sources and removing them on the fly.
+ */
+class DataSourceList {
+    /**
+     * @param circular whether to loop off the end of the list back to the start
+     * @param initialList of content
+     */
+    constructor(circular, initialList) {
+        this._list = initialList ? [...initialList] : [];
+        this._circular = circular;
+        this._pos = 0;
+    }
+    /**
+     * Returns the current head and then iterates.
+     */
+    next() {
+        if (this._list.length <= 0 || this._pos >= this._list.length) {
+            return undefined;
+        }
+        const result = this._list[this._pos];
+        if (this._circular) {
+            this._pos = (this._pos + 1) % this._list.length;
+        }
+        else {
+            this._pos += 1;
+        }
+        return result;
+    }
+    /**
+     * Replaces all elements with the provided list and resets the position of head to the start.
+     *
+     * @param input that will replace existing list
+     */
+    replace(input) {
+        this._list = [...input];
+        this._pos = 0;
+    }
+    /**
+     * Removes the provided element from the list. If the removed element was the head, head moves to next. Consider head may be undefined if list is empty after removal.
+     *
+     * @param element to remove
+     * @returns true if element was removed
+     */
+    remove(element) {
+        const index = this._list.indexOf(element);
+        if (index < 0) {
+            return false;
+        }
+        this._list.splice(index, 1);
+        if (this._list.length > 0) {
+            // if removed item was before head, adjust head
+            if (index < this._pos) {
+                this._pos -= 1;
+            }
+            if (this._circular && this._pos > this._list.length - 1) {
+                this._pos = 0;
+            }
+        }
+        return true;
+    }
+    /**
+     * Reset the head position to the start of the list.
+     */
+    reset() {
+        this._pos = 0;
+    }
+    /**
+     * @returns the current head position in the list, 0 indexed.
+     */
+    pos() {
+        return this._pos;
+    }
+    /**
+     * @returns the current length of the list
+     */
+    length() {
+        return this._list.length;
+    }
+    /**
+     * Clears the list and resets head.
+     */
+    clear() {
+        this._list = [];
+        this._pos = 0;
+    }
+}
+
+const DEFAULT_FALLBACK_TIME_MS = 2 * 60 * 1000;
+const DEFAULT_RECOVERY_TIME_MS = 5 * 60 * 1000;
+/**
+ * The {@link CompositeDataSource} can combine a number of {@link DataSystemInitializer}s and {@link DataSystemSynchronizer}s
+ * into a single {@link DataSource}, implementing fallback and recovery logic internally to choose where data is sourced from.
+ */
+class CompositeDataSource {
+    /**
+     * @param initializers factories to create {@link DataSystemInitializer}s, in priority order.
+     * @param synchronizers factories to create  {@link DataSystemSynchronizer}s, in priority order.
+     */
+    constructor(initializers, synchronizers, _logger, _transitionConditions = {
+        [DataSourceState.Valid]: {
+            durationMS: DEFAULT_RECOVERY_TIME_MS,
+            transition: 'recover',
+        },
+        [DataSourceState.Interrupted]: {
+            durationMS: DEFAULT_FALLBACK_TIME_MS,
+            transition: 'fallback',
+        },
+    }, _backoff = new DefaultBackoff(1000, 30000)) {
+        this._logger = _logger;
+        this._transitionConditions = _transitionConditions;
+        this._backoff = _backoff;
+        this._stopped = true;
+        this._cancelTokens = [];
+        this._cancellableDelay = (delayMS) => {
+            let timeout;
+            const promise = new Promise((res, _) => {
+                timeout = setTimeout(res, delayMS);
+            });
+            return {
+                promise,
+                cancel() {
+                    if (timeout) {
+                        clearTimeout(timeout);
+                        timeout = undefined;
+                    }
+                },
+            };
+        };
+        this._externalTransitionPromise = new Promise((resolveTransition) => {
+            this._externalTransitionResolve = resolveTransition;
+        });
+        this._initPhaseActive = initializers.length > 0; // init phase if we have initializers
+        this._initFactories = new DataSourceList(false, initializers);
+        this._syncFactories = new DataSourceList(true, synchronizers);
+    }
+    async start(dataCallback, statusCallback) {
+        if (!this._stopped) {
+            // don't allow multiple simultaneous runs
+            this._logger?.info('CompositeDataSource already running. Ignoring call to start.');
+            return;
+        }
+        this._stopped = false;
+        this._logger?.debug(`CompositeDataSource starting with (${this._initFactories.length()} initializers, ${this._syncFactories.length()} synchronizers).`);
+        // this wrapper turns status updates from underlying data sources into a valid series of status updates for the consumer of this
+        // composite data source
+        const sanitizedStatusCallback = this._wrapStatusCallbackWithSanitizer(statusCallback);
+        sanitizedStatusCallback(DataSourceState.Initializing);
+        let lastTransition;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { dataSource: currentDS, isPrimary, cullDSFactory, } = this._pickDataSource(lastTransition);
+            const internalTransitionPromise = new Promise((transitionResolve) => {
+                if (currentDS) {
+                    // these local variables are used for handling automatic transition related to data source status (ex: recovering to primary after
+                    // secondary has been valid for N many seconds)
+                    let lastState;
+                    let cancelScheduledTransition = () => { };
+                    // this callback handler can be disabled and ensures only one transition request occurs
+                    const callbackHandler = new CallbackHandler((basis, data) => {
+                        this._backoff.success();
+                        dataCallback(basis, data);
+                        if (basis && this._initPhaseActive) {
+                            // transition to sync if we get basis during init
+                            callbackHandler.disable();
+                            this._consumeCancelToken(cancelScheduledTransition);
+                            sanitizedStatusCallback(DataSourceState.Interrupted);
+                            transitionResolve({ transition: 'switchToSync' });
+                        }
+                    }, (state, err) => {
+                        // When we get a status update, we want to fallback if it is an error.  We also want to schedule a transition for some
+                        // time in the future if this status remains for some duration (ex: Recover to primary synchronizer after the secondary
+                        // synchronizer has been Valid for some time).  These scheduled transitions are configurable in the constructor.
+                        this._logger?.debug(`CompositeDataSource received state ${state} from underlying data source.`);
+                        if (err || state === DataSourceState.Closed) {
+                            callbackHandler.disable();
+                            if (err.recoverable === false) {
+                                // don't use this datasource's factory again
+                                cullDSFactory?.();
+                            }
+                            sanitizedStatusCallback(state, err);
+                            this._consumeCancelToken(cancelScheduledTransition);
+                            transitionResolve({ transition: 'fallback', err }); // unrecoverable error has occurred, so fallback
+                        }
+                        else {
+                            sanitizedStatusCallback(state);
+                            if (state !== lastState) {
+                                lastState = state;
+                                this._consumeCancelToken(cancelScheduledTransition); // cancel previously scheduled status transition if one was scheduled
+                                // primary source cannot recover to itself, so exclude it
+                                const condition = this._lookupTransitionCondition(state, isPrimary);
+                                if (condition) {
+                                    const { promise, cancel } = this._cancellableDelay(condition.durationMS);
+                                    cancelScheduledTransition = cancel;
+                                    this._cancelTokens.push(cancelScheduledTransition);
+                                    promise.then(() => {
+                                        this._consumeCancelToken(cancel);
+                                        callbackHandler.disable();
+                                        sanitizedStatusCallback(DataSourceState.Interrupted);
+                                        transitionResolve({ transition: condition.transition });
+                                    });
+                                }
+                            }
+                        }
+                    });
+                    currentDS.start((basis, data) => callbackHandler.dataHandler(basis, data), (status, err) => callbackHandler.statusHandler(status, err));
+                }
+                else {
+                    // we don't have a data source to use!
+                    transitionResolve({
+                        transition: 'stop',
+                        err: {
+                            name: 'ExhaustedDataSources',
+                            message: `CompositeDataSource has exhausted all configured initializers and synchronizers.`,
+                        },
+                    });
+                }
+            });
+            // await transition triggered by internal data source or an external stop request
+            let transitionRequest = await Promise.race([
+                internalTransitionPromise,
+                this._externalTransitionPromise,
+            ]);
+            // stop the underlying datasource before transitioning to next state
+            currentDS?.stop();
+            if (transitionRequest.err && transitionRequest.transition !== 'stop') {
+                // if the transition was due to an error, throttle the transition
+                const delay = this._backoff.fail();
+                const { promise, cancel: cancelDelay } = this._cancellableDelay(delay);
+                this._cancelTokens.push(cancelDelay);
+                const delayedTransition = promise.then(() => {
+                    this._consumeCancelToken(cancelDelay);
+                    return transitionRequest;
+                });
+                // race the delayed transition and external transition requests to be responsive
+                transitionRequest = await Promise.race([
+                    delayedTransition,
+                    this._externalTransitionPromise,
+                ]);
+                // consume the delay cancel token (even if it resolved, need to stop tracking its token)
+                this._consumeCancelToken(cancelDelay);
+            }
+            lastTransition = transitionRequest.transition;
+            if (transitionRequest.transition === 'stop') {
+                // exit the loop, this is intentionally not the sanitized status callback
+                statusCallback(DataSourceState.Closed, transitionRequest.err);
+                break;
+            }
+        }
+        // reset so that run can be called again in the future
+        this._reset();
+    }
+    async stop() {
+        this._cancelTokens.forEach((cancel) => cancel());
+        this._cancelTokens = [];
+        this._externalTransitionResolve?.({ transition: 'stop' });
+    }
+    _reset() {
+        this._stopped = true;
+        this._initPhaseActive = this._initFactories.length() > 0; // init phase if we have initializers;
+        this._initFactories.reset();
+        this._syncFactories.reset();
+        this._externalTransitionPromise = new Promise((tr) => {
+            this._externalTransitionResolve = tr;
+        });
+        // intentionally not resetting the backoff to avoid a code path that could circumvent throttling
+    }
+    /**
+     * Determines the next datasource and returns that datasource as well as a closure to cull the
+     * datasource from the datasource lists. One example where the cull closure is invoked is if the
+     * datasource has an unrecoverable error.
+     */
+    _pickDataSource(transition) {
+        let factory;
+        let isPrimary;
+        switch (transition) {
+            case 'switchToSync':
+                this._initPhaseActive = false; // one way toggle to false, unless this class is reset()
+                this._syncFactories.reset();
+                isPrimary = this._syncFactories.pos() === 0;
+                factory = this._syncFactories.next();
+                break;
+            case 'recover':
+                if (this._initPhaseActive) {
+                    this._initFactories.reset();
+                    isPrimary = this._initFactories.pos() === 0;
+                    factory = this._initFactories.next();
+                }
+                else {
+                    this._syncFactories.reset();
+                    isPrimary = this._syncFactories.pos() === 0;
+                    factory = this._syncFactories.next();
+                }
+                break;
+            case 'fallback':
+            default:
+                if (this._initPhaseActive) {
+                    isPrimary = this._initFactories.pos() === 0;
+                    factory = this._initFactories.next();
+                }
+                else {
+                    isPrimary = this._syncFactories.pos() === 0;
+                    factory = this._syncFactories.next();
+                }
+                break;
+        }
+        if (!factory) {
+            return { dataSource: undefined, isPrimary, cullDSFactory: undefined };
+        }
+        return {
+            dataSource: factory(),
+            isPrimary,
+            cullDSFactory: () => {
+                if (factory) {
+                    this._syncFactories.remove(factory);
+                }
+            },
+        };
+    }
+    /**
+     * @returns the transition condition for the provided data source state or undefined
+     * if there is no transition condition
+     */
+    _lookupTransitionCondition(state, excludeRecover) {
+        const condition = this._transitionConditions[state];
+        // exclude recovery can happen for certain initializers/synchronizers (ex: the primary synchronizer shouldn't recover to itself)
+        if (excludeRecover && condition?.transition === 'recover') {
+            return undefined;
+        }
+        return condition;
+    }
+    _consumeCancelToken(cancel) {
+        cancel();
+        const index = this._cancelTokens.indexOf(cancel, 0);
+        if (index > -1) {
+            this._cancelTokens.splice(index, 1);
+        }
+    }
+    /**
+     * This wrapper will ensure the following:
+     *
+     * Don't report DataSourceState.Initializing except as first status callback.
+     * Map underlying DataSourceState.Closed to interrupted.
+     * Don't report the same status and error twice in a row.
+     */
+    _wrapStatusCallbackWithSanitizer(statusCallback) {
+        let alreadyReportedInitializing = false;
+        let lastStatus;
+        let lastErr;
+        return (status, err) => {
+            let sanitized = status;
+            // underlying errors, closed state, or off are masked as interrupted while we transition
+            if (status === DataSourceState.Closed) {
+                sanitized = DataSourceState.Interrupted;
+            }
+            // don't report the same combination of values twice in a row
+            if (sanitized === lastStatus && err === lastErr) {
+                return;
+            }
+            if (sanitized === DataSourceState.Initializing) {
+                // don't report initializing again if that has already been reported
+                if (alreadyReportedInitializing) {
+                    return;
+                }
+                alreadyReportedInitializing = true;
+            }
+            lastStatus = sanitized;
+            lastErr = err;
+            statusCallback(sanitized, err);
+        };
+    }
+}
+
 var DataSourceErrorKind;
 (function (DataSourceErrorKind) {
     /// An unexpected error, such as an uncaught exception, further
@@ -879,6 +1415,7 @@ var LDDeliveryStatus;
 
 var index$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
+    get DataSourceState () { return DataSourceState; },
     get LDDeliveryStatus () { return LDDeliveryStatus; },
     get LDEventType () { return LDEventType; }
 });
@@ -1874,7 +2411,9 @@ function counterKey(event) {
  * @internal
  */
 class EventSummarizer {
-    constructor() {
+    constructor(_singleContext = false, _contextFilter) {
+        this._singleContext = _singleContext;
+        this._contextFilter = _contextFilter;
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -1882,6 +2421,9 @@ class EventSummarizer {
     }
     summarizeEvent(event) {
         if (isFeature(event) && !event.excludeFromSummaries) {
+            if (!this._context) {
+                this._context = event.context;
+            }
             const countKey = counterKey(event);
             const counter = this._counters[countKey];
             let kinds = this._contextKinds[event.key];
@@ -1931,14 +2473,19 @@ class EventSummarizer {
             flagSummary.counters.push(counterOut);
             return acc;
         }, {});
-        return {
+        const event = {
             startDate: this._startDate,
             endDate: this._endDate,
             features,
             kind: 'summary',
+            context: this._context !== undefined && this._singleContext
+                ? this._contextFilter?.filter(this._context)
+                : undefined,
         };
+        this._clearSummary();
+        return event;
     }
-    clearSummary() {
+    _clearSummary() {
         this._startDate = 0;
         this._endDate = 0;
         this._counters = {};
@@ -1953,6 +2500,38 @@ class LDInvalidSDKKeyError extends Error {
     }
 }
 
+class MultiEventSummarizer {
+    constructor(_contextFilter, _logger) {
+        this._contextFilter = _contextFilter;
+        this._logger = _logger;
+        this._summarizers = {};
+    }
+    summarizeEvent(event) {
+        if (isFeature(event)) {
+            const key = event.context.canonicalUnfilteredJson();
+            if (!key) {
+                if (event.context.valid) {
+                    // The context appeared valid, but it could not be hashed.
+                    // This is likely because of a cycle in the data.
+                    this._logger?.error('Unable to serialize context, likely the context contains a cycle.');
+                }
+                return;
+            }
+            let summarizer = this._summarizers[key];
+            if (!summarizer) {
+                this._summarizers[key] = new EventSummarizer(true, this._contextFilter);
+                summarizer = this._summarizers[key];
+            }
+            summarizer.summarizeEvent(event);
+        }
+    }
+    getSummaries() {
+        const summarizersToFlush = this._summarizers;
+        this._summarizers = {};
+        return Object.values(summarizersToFlush).map((summarizer) => summarizer.getSummary());
+    }
+}
+
 /**
  * The contents of this file are for event sampling. They are not used for
  * any purpose requiring cryptographic security.
@@ -1973,12 +2552,14 @@ function shouldSample(ratio) {
     return Math.floor(Math.random() * truncated) === 0;
 }
 
+function isMultiEventSummarizer(summarizer) {
+    return summarizer.getSummaries !== undefined;
+}
 class EventProcessor {
-    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true) {
+    constructor(_config, clientContext, baseHeaders, _contextDeduplicator, _diagnosticsManager, start = true, summariesPerContext = false) {
         this._config = _config;
         this._contextDeduplicator = _contextDeduplicator;
         this._diagnosticsManager = _diagnosticsManager;
-        this._summarizer = new EventSummarizer();
         this._queue = [];
         this._lastKnownPastTime = 0;
         this._droppedEvents = 0;
@@ -1991,6 +2572,12 @@ class EventProcessor {
         this._logger = clientContext.basicConfiguration.logger;
         this._eventSender = new EventSender(clientContext, baseHeaders);
         this._contextFilter = new ContextFilter(_config.allAttributesPrivate, _config.privateAttributes.map((ref) => new AttributeReference(ref)));
+        if (summariesPerContext) {
+            this._summarizer = new MultiEventSummarizer(this._contextFilter, this._logger);
+        }
+        else {
+            this._summarizer = new EventSummarizer();
+        }
         if (start) {
             this.start();
         }
@@ -2042,10 +2629,19 @@ class EventProcessor {
         }
         const eventsToFlush = this._queue;
         this._queue = [];
-        const summary = this._summarizer.getSummary();
-        this._summarizer.clearSummary();
-        if (Object.keys(summary.features).length) {
-            eventsToFlush.push(summary);
+        if (isMultiEventSummarizer(this._summarizer)) {
+            const summaries = this._summarizer.getSummaries();
+            summaries.forEach((summary) => {
+                if (Object.keys(summary.features).length) {
+                    eventsToFlush.push(summary);
+                }
+            });
+        }
+        else {
+            const summary = this._summarizer.getSummary();
+            if (Object.keys(summary.features).length) {
+                eventsToFlush.push(summary);
+            }
         }
         if (!eventsToFlush.length) {
             return;
@@ -2327,30 +2923,29 @@ class EventFactoryBase {
 }
 
 /**
- * A FDv2 PayloadReader can be used to parse payloads from a stream of FDv2 events. It will send payloads
+ * A FDv2 PayloadProcessor can be used to parse payloads from a stream of FDv2 events. It will send payloads
  * to the PayloadListeners as the payloads are received. Invalid series of events may be dropped silently,
- * but the payload reader will continue to operate.
+ * but the payload processor will continue to operate.
  */
-class PayloadReader {
+class PayloadProcessor {
     /**
-     * Creates a PayloadReader
+     * Creates a PayloadProcessor
      *
-     * @param eventStream event stream of FDv2 events
      * @param _objProcessors defines object processors for each object kind.
-     * @param _errorHandler that will be called with errors as they are encountered
+     * @param _errorHandler that will be called with parsing errors as they are encountered
      * @param _logger for logging
      */
-    constructor(eventStream, _objProcessors, _errorHandler, _logger) {
+    constructor(_objProcessors, _errorHandler, _logger) {
         this._objProcessors = _objProcessors;
         this._errorHandler = _errorHandler;
         this._logger = _logger;
         this._listeners = [];
         this._tempId = undefined;
-        this._tempBasis = undefined;
+        this._tempBasis = false;
         this._tempUpdates = [];
         this._processServerIntent = (data) => {
             // clear state in prep for handling data
-            this._resetState();
+            this._resetAll();
             // if there's no payloads, return
             if (!data.payloads.length) {
                 return;
@@ -2362,8 +2957,11 @@ class PayloadReader {
                     this._tempBasis = true;
                     break;
                 case 'xfer-changes':
+                    this._tempBasis = false;
+                    break;
                 case 'none':
                     this._tempBasis = false;
+                    this._processIntentNone(payload);
                     break;
                 default:
                     // unrecognized intent code, return
@@ -2373,7 +2971,7 @@ class PayloadReader {
         };
         this._processPutObject = (data) => {
             // if the following properties haven't been provided by now, we should ignore the event
-            if (!this._tempId || // server intent hasn't been recieved yet.
+            if (!this._tempId || // server intent hasn't been received yet.
                 !data.kind ||
                 !data.key ||
                 !data.version ||
@@ -2382,7 +2980,7 @@ class PayloadReader {
             }
             const obj = this._processObj(data.kind, data.object);
             if (!obj) {
-                this._logger?.warn(`Unable to prcoess object for kind: '${data.kind}'`);
+                this._logger?.warn(`Unable to process object for kind: '${data.kind}'`);
                 // ignore unrecognized kinds
                 return;
             }
@@ -2407,13 +3005,27 @@ class PayloadReader {
                 deleted: true,
             });
         };
+        this._processIntentNone = (intent) => {
+            // if the following properties aren't present ignore the event
+            if (!intent.id || !intent.target) {
+                return;
+            }
+            const payload = {
+                id: intent.id,
+                version: intent.target,
+                basis: false,
+                updates: [], // payload with no updates to hide the intent none concept from the consumer
+                // note: state is absent here as that only appears in payload transferred events
+            };
+            this._listeners.forEach((it) => it(payload));
+            this._resetAfterEmission();
+        };
         this._processPayloadTransferred = (data) => {
             // if the following properties haven't been provided by now, we should reset
-            if (!this._tempId || // server intent hasn't been recieved yet.
+            if (!this._tempId || // server intent hasn't been received yet.
                 !data.state ||
-                !data.version ||
-                this._tempBasis === undefined) {
-                this._resetState(); // a reset is best defensive action since payload transferred terminates a payload
+                !data.version) {
+                this._resetAll(); // a reset is best defensive action since payload transferred terminates a payload
                 return;
             }
             const payload = {
@@ -2424,22 +3036,16 @@ class PayloadReader {
                 updates: this._tempUpdates,
             };
             this._listeners.forEach((it) => it(payload));
-            this._resetState();
+            this._resetAfterEmission();
         };
         this._processGoodbye = (data) => {
             this._logger?.info(`Goodbye was received from the LaunchDarkly connection with reason: ${data.reason}.`);
-            this._resetState();
+            this._resetAll();
         };
         this._processError = (data) => {
-            this._logger?.info(`An issue was encountered receiving updates for payload ${this._tempId} with reason: ${data.reason}. Automatic retry will occur.`);
-            this._resetState();
+            this._logger?.info(`An issue was encountered receiving updates for payload ${this._tempId} with reason: ${data.reason}.`);
+            this._resetAfterError();
         };
-        this._attachHandler(eventStream, 'server-intent', this._processServerIntent);
-        this._attachHandler(eventStream, 'put-object', this._processPutObject);
-        this._attachHandler(eventStream, 'delete-object', this._processDeleteObject);
-        this._attachHandler(eventStream, 'payload-transferred', this._processPayloadTransferred);
-        this._attachHandler(eventStream, 'goodbye', this._processGoodbye);
-        this._attachHandler(eventStream, 'error', this._processError);
     }
     addPayloadListener(listener) {
         this._listeners.push(listener);
@@ -2450,32 +3056,108 @@ class PayloadReader {
             this._listeners.splice(index, 1);
         }
     }
-    _attachHandler(stream, eventName, processor) {
+    /**
+     * Gives the {@link PayloadProcessor} a series of events that it will statefully, incrementally process.
+     * This may lead to listeners being invoked as necessary.
+     * @param events to be processed (can be a single element)
+     */
+    processEvents(events) {
+        events.forEach((event) => {
+            switch (event.event) {
+                case 'server-intent': {
+                    this._processServerIntent(event.data);
+                    break;
+                }
+                case 'put-object': {
+                    this._processPutObject(event.data);
+                    break;
+                }
+                case 'delete-object': {
+                    this._processDeleteObject(event.data);
+                    break;
+                }
+                case 'payload-transferred': {
+                    this._processPayloadTransferred(event.data);
+                    break;
+                }
+                case 'goodbye': {
+                    this._processGoodbye(event.data);
+                    break;
+                }
+                case 'error': {
+                    this._processError(event.data);
+                    break;
+                }
+            }
+        });
+    }
+    _processObj(kind, jsonObj) {
+        return this._objProcessors[kind]?.(jsonObj);
+    }
+    _resetAfterEmission() {
+        this._tempBasis = false;
+        this._tempUpdates = [];
+    }
+    _resetAfterError() {
+        this._tempUpdates = [];
+    }
+    _resetAll() {
+        this._tempId = undefined;
+        this._tempBasis = false;
+        this._tempUpdates = [];
+    }
+}
+
+/**
+ * A FDv2 PayloadStreamReader can be used to parse payloads from a stream of FDv2 events.  See {@link PayloadProcessor}
+ * for more details.
+ */
+class PayloadStreamReader {
+    /**
+     * Creates a PayloadStreamReader
+     *
+     * @param eventStream event stream of FDv2 events
+     * @param _objProcessors defines object processors for each object kind.
+     * @param _errorHandler that will be called with parsing errors as they are encountered
+     * @param _logger for logging
+     */
+    constructor(eventStream, _objProcessors, _errorHandler, _logger) {
+        this._errorHandler = _errorHandler;
+        this._logger = _logger;
+        this._attachHandler(eventStream, 'server-intent');
+        this._attachHandler(eventStream, 'put-object');
+        this._attachHandler(eventStream, 'delete-object');
+        this._attachHandler(eventStream, 'payload-transferred');
+        this._attachHandler(eventStream, 'goodbye');
+        this._attachHandler(eventStream, 'error');
+        this._payloadProcessor = new PayloadProcessor(_objProcessors, _errorHandler, _logger);
+    }
+    addPayloadListener(listener) {
+        this._payloadProcessor.addPayloadListener(listener);
+    }
+    removePayloadListener(listener) {
+        this._payloadProcessor.removePayloadListener(listener);
+    }
+    _attachHandler(stream, eventName) {
         stream.addEventListener(eventName, async (event) => {
             if (event?.data) {
                 this._logger?.debug(`Received ${eventName} event.  Data is ${event.data}`);
                 try {
-                    processor(JSON.parse(event.data));
+                    this._payloadProcessor.processEvents([
+                        { event: eventName, data: JSON.parse(event.data) },
+                    ]);
                 }
                 catch {
                     this._logger?.error(`Stream received data that was unable to be processed in "${eventName}" message`);
                     this._logger?.debug(`Data follows: ${event.data}`);
-                    this._errorHandler?.(DataSourceErrorKind.InvalidData, 'Malformed data in event stream');
+                    this._errorHandler?.(DataSourceErrorKind.InvalidData, 'Malformed data in EventStream.');
                 }
             }
             else {
-                this._errorHandler?.(DataSourceErrorKind.Unknown, 'Unexpected message from event stream');
+                this._errorHandler?.(DataSourceErrorKind.Unknown, 'Event from EventStream missing data.');
             }
         });
     }
-    _processObj(kind, jsonObj) {
-        return this._objProcessors[kind]?.(jsonObj);
-    }
-    _resetState() {
-        this._tempId = undefined;
-        this._tempBasis = undefined;
-        this._tempUpdates = [];
-    }
 }
 
 /**
@@ -2496,6 +3178,47 @@ function initMetadataFromHeaders(initHeaders) {
     return undefined;
 }
 
+const UNKNOWN_PLUGIN_NAME = 'unknown plugin';
+function safeGetName(logger, plugin) {
+    try {
+        return plugin.getMetadata().name || UNKNOWN_PLUGIN_NAME;
+    }
+    catch {
+        logger.error(`Exception thrown getting metadata for plugin. Unable to get plugin name.`);
+        return UNKNOWN_PLUGIN_NAME;
+    }
+}
+
+function safeGetHooks(logger, environmentMetadata, plugins) {
+    const hooks = [];
+    plugins.forEach((plugin) => {
+        try {
+            const pluginHooks = plugin.getHooks?.(environmentMetadata);
+            if (pluginHooks === undefined) {
+                logger.error(`Plugin ${safeGetName(logger, plugin)} returned undefined from getHooks.`);
+            }
+            else if (pluginHooks && pluginHooks.length > 0) {
+                hooks.push(...pluginHooks);
+            }
+        }
+        catch (error) {
+            logger.error(`Exception thrown getting hooks for plugin ${safeGetName(logger, plugin)}. Unable to get hooks.`);
+        }
+    });
+    return hooks;
+}
+
+function safeRegisterPlugins(logger, environmentMetadata, client, plugins) {
+    plugins.forEach((plugin) => {
+        try {
+            plugin.register(client, environmentMetadata);
+        }
+        catch (error) {
+            logger.error(`Exception thrown registering plugin ${safeGetName(logger, plugin)}.`);
+        }
+    });
+}
+
 var index = /*#__PURE__*/Object.freeze({
     __proto__: null,
     ClientMessages: ClientMessages,
@@ -2507,13 +3230,18 @@ var index = /*#__PURE__*/Object.freeze({
     InputEvalEvent: InputEvalEvent,
     InputIdentifyEvent: InputIdentifyEvent,
     NullEventProcessor: NullEventProcessor,
-    PayloadReader: PayloadReader,
+    PayloadProcessor: PayloadProcessor,
+    PayloadStreamReader: PayloadStreamReader,
+    canonicalize: canonicalize,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,
     isSingleKind: isSingleKind,
+    safeGetHooks: safeGetHooks,
+    safeGetName: safeGetName,
+    safeRegisterPlugins: safeRegisterPlugins,
     shouldSample: shouldSample
 });
 
-export { ApplicationTags, AttributeReference, AutoEnvAttributes, BasicLogger, ClientContext, Context, ContextFilter, DataSourceErrorKind, DateValidator, FactoryOrInstance, Function, KindValidator, LDClientError, LDFileDataSourceError, LDPollingError, LDStreamingError, LDTimeoutError, LDUnexpectedResponseError, NullableBoolean, NumberWithMinimum, OptionMessages, SafeLogger, ServiceEndpoints, StringMatchingRegex, Type, TypeArray, TypeValidators, base64UrlEncode, cancelableTimedPromise, clone, createSafeLogger, debounce, deepCompact, defaultHeaders, fastDeepEqual, getEventsUri, getPollingUri, getStreamingUri, httpErrorMessage, index as internal, isHttpLocallyRecoverable, isHttpRecoverable, noop, secondsToMillis, shouldRetry, sleep, index$1 as subsystem, timedPromise };
+export { ApplicationTags, AttributeReference, AutoEnvAttributes, BasicLogger, ClientContext, CompositeDataSource, Context, ContextFilter, DataSourceErrorKind, DateValidator, DefaultBackoff, FactoryOrInstance, Function, KindValidator, LDClientError, LDFileDataSourceError, LDPollingError, LDStreamingError, LDTimeoutError, LDUnexpectedResponseError, NullableBoolean, NumberWithMinimum, OptionMessages, SafeLogger, ServiceEndpoints, StringMatchingRegex, Type, TypeArray, TypeValidators, base64UrlEncode, cancelableTimedPromise, clone, createSafeLogger, debounce, deepCompact, defaultHeaders, fastDeepEqual, getEventsUri, getPollingUri, getStreamingUri, httpErrorMessage, index as internal, isHttpLocallyRecoverable, isHttpRecoverable, noop, secondsToMillis, shouldRetry, sleep, index$1 as subsystem, timedPromise };
 //# sourceMappingURL=index.mjs.map