@launchdarkly/js-sdk-common 2.20.0 → 2.21.0

package/dist/cjs/internal/fdv2/proto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proto.d.ts","sourceRoot":"","sources":["../../../src/internal/fdv2/proto.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,eAAe,GACf,YAAY,GACZ,eAAe,GACf,qBAAqB,GACrB,SAAS,GACT,OAAO,GACP,YAAY,CAAC;AACjB,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,MAAM,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5C,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EACA,gBAAgB,GAChB,SAAS,GACT,YAAY,GACZ,kBAAkB,GAClB,aAAa,GACb,WAAW,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,GAAG,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}
+{"version":3,"file":"proto.d.ts","sourceRoot":"","sources":["../../../src/internal/fdv2/proto.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,eAAe,GACf,YAAY,GACZ,eAAe,GACf,qBAAqB,GACrB,SAAS,GACT,OAAO,GACP,YAAY,CAAC;AAEjB,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,MAAM,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,IAAI,EACA,gBAAgB,GAChB,SAAS,GACT,YAAY,GACZ,kBAAkB,GAClB,aAAa,GACb,WAAW,GACX,OAAO,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,GAAG,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}

package/dist/cjs/internal/fdv2/protocolHandler.d.ts

@@ -0,0 +1,76 @@
+import { LDLogger } from '../../api';
+import { FDv2Event } from './proto';
+/**
+ * Defines object processing between deserialization and payload emission.
+ * Can be used to provide object sanitization logic per kind.
+ */
+export interface ObjProcessors {
+    [kind: string]: (object: any) => any;
+}
+export interface Update {
+    kind: string;
+    key: string;
+    version: number;
+    object?: any;
+    deleted?: boolean;
+}
+export type PayloadType = 'full' | 'partial' | 'none';
+/**
+ * A collection of updates from the FDv2 services.
+ *
+ * - `full`: the updates represent the complete state and replace everything.
+ * - `partial`: the updates are incremental changes to apply.
+ * - `none`: no changes are needed; the SDK is up-to-date.
+ */
+export interface Payload {
+    id: string;
+    version: number;
+    state?: string;
+    type: PayloadType;
+    updates: Update[];
+}
+export type PayloadListener = (payload: Payload) => void;
+/**
+ * - `inactive`: No server intent has been expressed (initial state).
+ * - `changes`: Currently receiving incremental changes.
+ * - `full`: Currently receiving a full transfer.
+ */
+export type ProtocolState = 'inactive' | 'changes' | 'full';
+export type ProtocolErrorKind = 'UNKNOWN_EVENT' | 'MISSING_PAYLOAD' | 'PROTOCOL_ERROR';
+/**
+ * - `none`: No special action should be taken.
+ * - `payload`: A changeset should be applied.
+ * - `error`: An internal protocol error was encountered.
+ * - `goodbye`: The server intends to disconnect.
+ * - `serverError`: A server-side application error was encountered.
+ */
+export type ProtocolAction = {
+    type: 'none';
+} | {
+    type: 'payload';
+    payload: Payload;
+} | {
+    type: 'error';
+    kind: ProtocolErrorKind;
+    message: string;
+} | {
+    type: 'goodbye';
+    reason: string;
+} | {
+    type: 'serverError';
+    id?: string;
+    reason: string;
+};
+/**
+ * Pure FDv2 protocol state machine. Processes a single event at a time and
+ * returns an action describing what the caller should do. Contains no I/O
+ * or callbacks.
+ */
+export interface ProtocolHandler {
+    readonly state: ProtocolState;
+    processEvent(event: FDv2Event): ProtocolAction;
+    /** Resets the handler to inactive. Should be called when a connection is reset. */
+    reset(): void;
+}
+export declare function createProtocolHandler(objProcessors: ObjProcessors, logger?: LDLogger): ProtocolHandler;
+//# sourceMappingURL=protocolHandler.d.ts.map

package/dist/cjs/internal/fdv2/protocolHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolHandler.d.ts","sourceRoot":"","sources":["../../../src/internal/fdv2/protocolHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAEL,SAAS,EAKV,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;CACtC;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIzD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CAAC;IAC/C,mFAAmF;IACnF,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,aAAa,EAC5B,MAAM,CAAC,EAAE,QAAQ,GAChB,eAAe,CAyMjB"}

package/dist/esm/index.mjs

@@ -3016,135 +3016,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);
@@ -3155,56 +3220,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?.(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 = [];
-    }
 }
 
 /**
@@ -3333,6 +3366,7 @@ var index = /*#__PURE__*/Object.freeze({
     PayloadProcessor: PayloadProcessor,
     PayloadStreamReader: PayloadStreamReader,
     canonicalize: canonicalize,
+    createProtocolHandler: createProtocolHandler,
     initMetadataFromHeaders: initMetadataFromHeaders,
     isLegacyUser: isLegacyUser,
     isMultiKind: isMultiKind,