@launchdarkly/js-sdk-common 2.19.0 → 2.21.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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)
+
+
+### Features
+
+* add FDv2 FileDataSource initializer ([#1010](https://github.com/launchdarkly/js-core/issues/1010)) ([99931f0](https://github.com/launchdarkly/js-core/commit/99931f0706c0202390e3b68e3701ba0fb8aba124))
+
 ## [2.19.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.18.0...js-sdk-common-v2.19.0) (2025-07-23)
 
 

package/dist/cjs/index.cjs

@@ -2956,131 +2956,262 @@ class EventFactoryBase {
     }
 }
 
-/**
- * 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
+const PAYLOAD_ID = 'FDv1Fallback';
+function fdv1PayloadAdaptor(processor) {
+    return {
+        _processor: processor,
+        _selector: '',
+        useSelector(selector) {
+            this._selector = selector;
+            return this;
+        },
+        processFullTransfer(data) {
+            const events = [
+                {
+                    event: 'server-intent',
+                    data: {
+                        payloads: [
+                            {
+                                id: PAYLOAD_ID,
+                                target: 1,
+                                intentCode: 'xfer-full',
+                                reason: 'payload-missing',
+                            },
+                        ],
+                    },
+                },
+            ];
+            Object.entries(data?.flags || []).forEach(([key, flag]) => {
+                events.push({
+                    event: 'put-object',
+                    data: {
+                        kind: 'flag',
+                        key,
+                        version: flag.version || 1,
+                        object: flag,
+                    },
+                });
             });
-        };
-        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,
+            Object.entries(data?.segments || []).forEach(([key, segment]) => {
+                events.push({
+                    event: 'put-object',
+                    data: {
+                        kind: 'segment',
+                        key,
+                        version: segment.version || 1,
+                        object: segment,
+                    },
+                });
             });
-        };
-        this._processIntentNone = (intent) => {
-            // if the following properties aren't present ignore the event
-            if (!intent.id || !intent.target) {
-                return;
-            }
-            const payload = {
+            events.push({
+                event: 'payload-transferred',
+                data: {
+                    // IMPORTANT: the selector MUST be empty or "live" data synchronizers
+                    // will not work as it would try to resume from a bogus state.
+                    state: this._selector,
+                    version: 1,
+                    id: PAYLOAD_ID,
+                },
+            });
+            this._processor.processEvents(events);
+        },
+    };
+}
+
+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 (!this._tempId || // server intent hasn't been received yet.
-                !data.state ||
-                !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);
@@ -3091,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);
-                    break;
-                }
-                case 'delete-object': {
-                    this._processDeleteObject(event.data);
-                    break;
-                }
-                case 'payload-transferred': {
-                    this._processPayloadTransferred(event.data);
+            const action = this._handler.processEvent(event);
+            switch (action.type) {
+                case 'payload':
+                    this._listeners.forEach((it) => it(action.payload));
                     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 = [];
-    }
 }
 
 /**
@@ -3261,6 +3360,7 @@ var index = /*#__PURE__*/Object.freeze({
     ErrorKinds: ErrorKinds$1,
     EventFactoryBase: EventFactoryBase,
     EventProcessor: EventProcessor,
+    FDv1PayloadAdaptor: fdv1PayloadAdaptor,
     InputCustomEvent: InputCustomEvent,
     InputEvalEvent: InputEvalEvent,
     InputIdentifyEvent: InputIdentifyEvent,
@@ -3268,6 +3368,7 @@ var index = /*#__PURE__*/Object.freeze({
     PayloadProcessor: PayloadProcessor,
     PayloadStreamReader: PayloadStreamReader,
     canonicalize: canonicalize,
+    createProtocolHandler: createProtocolHandler,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,