@launchdarkly/js-sdk-common 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@launchdarkly/js-sdk-common` will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [2.21.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.20.0...js-sdk-common-v2.21.0) (2026-02-25)
+
+
+### Features
+
+* Refactor FDV2 protocol handling. ([4570089](https://github.com/launchdarkly/js-core/commit/4570089cd478cc5811a9a1c207231a96fdb5b39a))
+
 ## [2.20.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.19.0...js-sdk-common-v2.20.0) (2025-12-05)
 
 

package/dist/cjs/index.cjs

@@ -3018,135 +3018,200 @@ function fdv1PayloadAdaptor(processor) {
     };
 }
 
-/**
- * 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 processor will continue to operate.
- */
-class PayloadProcessor {
-    /**
-     * Creates a PayloadProcessor
-     *
-     * @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(_objProcessors, _errorHandler, _logger) {
-        this._objProcessors = _objProcessors;
-        this._errorHandler = _errorHandler;
-        this._logger = _logger;
-        this._listeners = [];
-        this._tempId = undefined;
-        this._tempBasis = false;
-        this._tempUpdates = [];
-        this._processServerIntent = (data) => {
-            // clear state in prep for handling data
-            this._resetAll();
-            // if there's no payloads, return
-            if (!data.payloads.length) {
-                return;
-            }
-            // at the time of writing this, it was agreed upon that SDKs could assume exactly 1 element in this list.  In the future, a negotiation of protocol version will be required to remove this assumption.
-            const payload = data.payloads[0];
-            switch (payload?.intentCode) {
-                case 'xfer-full':
-                    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
-                    this._logger?.warn(`Unable to process intent code '${payload?.intentCode}'.`);
-                    return;
-            }
-            this._tempId = payload?.id;
-        };
-        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 received yet.
-                !data.kind ||
-                !data.key ||
-                !data.version ||
-                !data.object) {
-                return;
-            }
-            const obj = this._processObj(data.kind, data.object);
-            if (!obj) {
-                this._logger?.warn(`Unable to process object for kind: '${data.kind}'`);
-                // ignore unrecognized kinds
-                return;
-            }
-            this._tempUpdates.push({
-                kind: data.kind,
-                key: data.key,
-                version: data.version,
-                object: obj,
-                // intentionally omit deleted for this put
-            });
-        };
-        this._processDeleteObject = (data) => {
-            // if the following properties haven't been provided by now, we should ignore the event
-            if (!this._tempId || !data.kind || !data.key || !data.version) {
-                return;
-            }
-            this._tempUpdates.push({
-                kind: data.kind,
-                key: data.key,
-                version: data.version,
-                // intentionally omit object for this delete
-                deleted: true,
-            });
-        };
-        this._processIntentNone = (intent) => {
-            // if the following properties aren't present ignore the event
-            if (!intent.id || !intent.target) {
-                return;
-            }
-            const payload = {
+const ACTION_NONE = { type: 'none' };
+function createProtocolHandler(objProcessors, logger) {
+    let protocolState = 'inactive';
+    let tempId;
+    let tempType = 'partial';
+    let tempUpdates = [];
+    function processObj(kind, jsonObj) {
+        return objProcessors[kind]?.(jsonObj);
+    }
+    function resetAll() {
+        protocolState = 'inactive';
+        tempId = undefined;
+        tempType = 'partial';
+        tempUpdates = [];
+    }
+    function resetAfterEmission() {
+        protocolState = 'changes';
+        tempType = 'partial';
+        tempUpdates = [];
+    }
+    function resetAfterError() {
+        tempUpdates = [];
+    }
+    function processIntentNone(intent) {
+        if (!intent.id || !intent.target) {
+            return ACTION_NONE;
+        }
+        return {
+            type: 'payload',
+            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();
+                type: 'none',
+                updates: [],
+            },
         };
-        this._processPayloadTransferred = (data) => {
-            // if the following properties haven't been provided by now, we should reset
-            if (
-            // server intent hasn't been received yet.
-            !this._tempId ||
-                // selector can be an empty string if we are using a file data initilizer
-                data.state === null ||
-                data.state === undefined ||
-                !data.version) {
-                this._resetAll(); // a reset is best defensive action since payload transferred terminates a payload
-                return;
-            }
-            const payload = {
-                id: this._tempId,
+    }
+    function processServerIntent(data) {
+        if (!data.payloads?.length) {
+            return {
+                type: 'error',
+                kind: 'MISSING_PAYLOAD',
+                message: 'No payload present in server-intent',
+            };
+        }
+        // Per spec 3.4.2: SDK uses only the first payload.
+        const payload = data.payloads[0];
+        switch (payload?.intentCode) {
+            case 'xfer-full':
+                protocolState = 'full';
+                tempUpdates = [];
+                tempType = 'full';
+                tempId = payload.id;
+                return ACTION_NONE;
+            case 'xfer-changes':
+                protocolState = 'changes';
+                tempUpdates = [];
+                tempType = 'partial';
+                tempId = payload.id;
+                return ACTION_NONE;
+            case 'none':
+                protocolState = 'changes';
+                tempUpdates = [];
+                tempType = 'partial';
+                tempId = payload.id;
+                return processIntentNone(payload);
+            default:
+                logger?.warn(`Unable to process intent code '${payload?.intentCode}'.`);
+                return ACTION_NONE;
+        }
+    }
+    function processPutObject(data) {
+        if (protocolState === 'inactive' ||
+            !tempId ||
+            !data.kind ||
+            !data.key ||
+            !data.version ||
+            !data.object) {
+            return ACTION_NONE;
+        }
+        const obj = processObj(data.kind, data.object);
+        if (!obj) {
+            logger?.warn(`Unable to process object for kind: '${data.kind}'`);
+            return ACTION_NONE;
+        }
+        tempUpdates.push({
+            kind: data.kind,
+            key: data.key,
+            version: data.version,
+            object: obj,
+        });
+        return ACTION_NONE;
+    }
+    function processDeleteObject(data) {
+        if (protocolState === 'inactive' || !tempId || !data.kind || !data.key || !data.version) {
+            return ACTION_NONE;
+        }
+        tempUpdates.push({
+            kind: data.kind,
+            key: data.key,
+            version: data.version,
+            deleted: true,
+        });
+        return ACTION_NONE;
+    }
+    function processPayloadTransferred(data) {
+        if (protocolState === 'inactive') {
+            return {
+                type: 'error',
+                kind: 'PROTOCOL_ERROR',
+                message: 'A payload transferred has been received without an intent having been established.',
+            };
+        }
+        if (!tempId || data.state === null || data.state === undefined || !data.version) {
+            resetAll();
+            return ACTION_NONE;
+        }
+        const result = {
+            type: 'payload',
+            payload: {
+                id: tempId,
                 version: data.version,
                 state: data.state,
-                basis: this._tempBasis,
-                updates: this._tempUpdates,
-            };
-            this._listeners.forEach((it) => it(payload));
-            this._resetAfterEmission();
-        };
-        this._processGoodbye = (data) => {
-            this._logger?.info(`Goodbye was received from the LaunchDarkly connection with reason: ${data.reason}.`);
-            this._resetAll();
-        };
-        this._processError = (data) => {
-            this._logger?.info(`An issue was encountered receiving updates for payload ${this._tempId} with reason: ${data.reason}.`);
-            this._resetAfterError();
+                type: tempType,
+                updates: tempUpdates,
+            },
         };
+        resetAfterEmission();
+        return result;
+    }
+    function processGoodbye(data) {
+        logger?.info(`Goodbye was received from the LaunchDarkly connection with reason: ${data.reason}.`);
+        resetAll();
+        return { type: 'goodbye', reason: data.reason };
+    }
+    function processError(data) {
+        logger?.info(`An issue was encountered receiving updates for payload ${tempId} with reason: ${data.reason}.`);
+        resetAfterError();
+        return { type: 'serverError', id: data.payload_id, reason: data.reason };
+    }
+    return {
+        get state() {
+            return protocolState;
+        },
+        processEvent(event) {
+            switch (event.event) {
+                case 'server-intent':
+                    return processServerIntent(event.data);
+                case 'put-object':
+                    return processPutObject(event.data);
+                case 'delete-object':
+                    return processDeleteObject(event.data);
+                case 'payload-transferred':
+                    return processPayloadTransferred(event.data);
+                case 'goodbye':
+                    return processGoodbye(event.data);
+                case 'error':
+                    return processError(event.data);
+                case 'heart-beat':
+                    return ACTION_NONE;
+                default:
+                    return {
+                        type: 'error',
+                        kind: 'UNKNOWN_EVENT',
+                        message: `Received an unknown event of type '${event.event}'`,
+                    };
+            }
+        },
+        reset() {
+            resetAll();
+        },
+    };
+}
+
+/**
+ * Errors that indicate a problem with the data or protocol flow and should
+ * be reported to the error handler. Informational errors like UNKNOWN_EVENT
+ * are intentionally excluded to preserve forward compatibility — older SDKs
+ * should silently ignore new event types added to the protocol.
+ */
+function isActionableError(kind) {
+    return kind === 'MISSING_PAYLOAD' || kind === 'PROTOCOL_ERROR';
+}
+/**
+ * Parses payloads from a stream of FDv2 events by delegating to a protocol handler.
+ * Sends completed payloads to registered listeners.
+ * Invalid event sequences may be dropped silently, but the processor will continue to operate.
+ */
+class PayloadProcessor {
+    constructor(objProcessors, _errorHandler, _logger) {
+        this._errorHandler = _errorHandler;
+        this._logger = _logger;
+        this._listeners = [];
+        this._handler = createProtocolHandler(objProcessors, _logger);
     }
     addPayloadListener(listener) {
         this._listeners.push(listener);
@@ -3157,56 +3222,24 @@ class PayloadProcessor {
             this._listeners.splice(index, 1);
         }
     }
-    /**
-     * 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);
+            const action = this._handler.processEvent(event);
+            switch (action.type) {
+                case 'payload':
+                    this._listeners.forEach((it) => it(action.payload));
                     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);
+                case 'error':
+                    if (isActionableError(action.kind)) {
+                        this._errorHandler?.(exports.DataSourceErrorKind.InvalidData, action.message);
+                    }
+                    else {
+                        this._logger?.warn(action.message);
+                    }
                     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 = [];
-    }
 }
 
 /**
@@ -3335,6 +3368,7 @@ var index = /*#__PURE__*/Object.freeze({
     PayloadProcessor: PayloadProcessor,
     PayloadStreamReader: PayloadStreamReader,
     canonicalize: canonicalize,
+    createProtocolHandler: createProtocolHandler,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,