@launchdarkly/js-client-sdk-common 1.20.0 → 1.21.0

package/dist/cjs/datasource/fdv2/FDv2DataSource.d.ts

@@ -0,0 +1,52 @@
+import { internal, LDLogger } from '@launchdarkly/js-sdk-common';
+import { DataSourceStatusManager } from '../DataSourceStatusManager';
+import { InitializerFactory, SynchronizerSlot } from './SourceManager';
+/**
+ * Callback invoked when the orchestrator produces a changeSet payload.
+ */
+export type DataCallback = (payload: internal.Payload) => void;
+/**
+ * Configuration for the {@link FDv2DataSource} orchestrator.
+ */
+export interface FDv2DataSourceConfig {
+    /** Ordered list of initializer factories. */
+    initializerFactories: InitializerFactory[];
+    /** Ordered list of synchronizer slots with state. */
+    synchronizerSlots: SynchronizerSlot[];
+    /** Callback to deliver payloads to the consuming layer. */
+    dataCallback: DataCallback;
+    /** Status manager for reporting data source state transitions. */
+    statusManager: DataSourceStatusManager;
+    /**
+     * Getter for the current selector (basis) string. The selector is managed
+     * externally by the consuming layer — the orchestrator reads it via this
+     * getter and passes it through to source factories.
+     */
+    selectorGetter: () => string | undefined;
+    /** Optional logger. */
+    logger?: LDLogger;
+    /** Fallback condition timeout in ms (default 120s). */
+    fallbackTimeoutMs?: number;
+    /** Recovery condition timeout in ms (default 300s). */
+    recoveryTimeoutMs?: number;
+}
+/**
+ * The FDv2 data source orchestrator. Coordinates initializers and
+ * synchronizers to provide a resilient flag data pipeline.
+ */
+export interface FDv2DataSource {
+    /**
+     * Start the orchestration loop. Returns a promise that resolves when
+     * initialization is complete (first basis data received or all initializers
+     * exhausted with data). The orchestration loop continues running in the
+     * background after the promise resolves, driving synchronizers.
+     */
+    start(): Promise<void>;
+    /** Close the orchestrator. Stops all active sources. */
+    close(): void;
+}
+/**
+ * Creates an {@link FDv2DataSource} orchestrator.
+ */
+export declare function createFDv2DataSource(config: FDv2DataSourceConfig): FDv2DataSource;
+//# sourceMappingURL=FDv2DataSource.d.ts.map

package/dist/cjs/datasource/fdv2/FDv2DataSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FDv2DataSource.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/FDv2DataSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AASrE,OAAO,EAAuB,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE5F;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;IAE3C,qDAAqD;IACrD,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IAEtC,2DAA2D;IAC3D,YAAY,EAAE,YAAY,CAAC;IAE3B,kEAAkE;IAClE,aAAa,EAAE,uBAAuB,CAAC;IAEvC;;;;OAIG;IACH,cAAc,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAEzC,uBAAuB;IACvB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAElB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CA0QjF"}

package/dist/cjs/datasource/fdv2/FDv2Requestor.d.ts

@@ -0,0 +1,45 @@
+import { Encoding, LDHeaders, Requests, ServiceEndpoints } from '@launchdarkly/js-sdk-common';
+import { DataSourcePaths } from '../DataSourceConfig';
+/**
+ * Response from an FDv2 poll request, providing access to status code,
+ * headers, and body.
+ */
+export interface FDv2PollResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    body: string | null;
+}
+/**
+ * Makes HTTP requests to FDv2 polling endpoints and returns full response
+ * information including status code and headers.
+ */
+export interface FDv2Requestor {
+    /**
+     * Perform a poll request.
+     *
+     * @param basis Optional opaque state string from the most recent
+     *   `payload-transferred` event, enabling delta-based updates.
+     * @returns The full HTTP response.
+     */
+    poll(basis?: string): Promise<FDv2PollResponse>;
+}
+/**
+ * Creates an {@link FDv2Requestor} for client-side FDv2 polling.
+ *
+ * @param plainContextString The JSON-serialized evaluation context.
+ * @param serviceEndpoints Service endpoint configuration.
+ * @param paths FDv2 polling endpoint paths.
+ * @param requests Platform HTTP abstraction.
+ * @param encoding Platform encoding abstraction.
+ * @param baseHeaders Default HTTP headers (e.g. authorization).
+ * @param baseQueryParams Additional query parameters to include on every request.
+ * @param usePost If true, use POST with context in body instead of GET with
+ *   context in URL path.
+ */
+export declare function makeFDv2Requestor(plainContextString: string, serviceEndpoints: ServiceEndpoints, paths: DataSourcePaths, requests: Requests, encoding: Encoding, baseHeaders?: LDHeaders, baseQueryParams?: {
+    key: string;
+    value: string;
+}[], usePost?: boolean): FDv2Requestor;
+//# sourceMappingURL=FDv2Requestor.d.ts.map

package/dist/cjs/datasource/fdv2/FDv2Requestor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FDv2Requestor.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/FDv2Requestor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EAER,SAAS,EACT,QAAQ,EACR,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,MAAM,EAC1B,gBAAgB,EAAE,gBAAgB,EAClC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,WAAW,CAAC,EAAE,SAAS,EACvB,eAAe,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAClD,OAAO,CAAC,EAAE,OAAO,GAChB,aAAa,CA0Cf"}

package/dist/cjs/datasource/fdv2/FDv2SourceResult.d.ts

@@ -0,0 +1,82 @@
+import { internal } from '@launchdarkly/js-sdk-common';
+import DataSourceStatusErrorInfo from '../DataSourceStatusErrorInfo';
+/**
+ * Possible states for a status result from an FDv2 data source.
+ *
+ * - `interrupted`: Transient error; synchronizer will retry automatically.
+ * - `shutdown`: Graceful shutdown; no further results will be produced.
+ * - `terminal_error`: Unrecoverable error; no further results will be produced.
+ * - `goodbye`: Server-initiated disconnect; no further results will be produced.
+ */
+export type SourceState = 'interrupted' | 'shutdown' | 'terminal_error' | 'goodbye';
+/**
+ * A change set result containing a processed FDv2 payload.
+ */
+export interface ChangeSetResult {
+    type: 'changeSet';
+    payload: internal.Payload;
+    fdv1Fallback: boolean;
+    environmentId?: string;
+}
+/**
+ * A status result indicating a state transition (error, shutdown, goodbye).
+ */
+export interface StatusResult {
+    type: 'status';
+    state: SourceState;
+    errorInfo?: DataSourceStatusErrorInfo;
+    reason?: string;
+    fdv1Fallback: boolean;
+}
+/**
+ * The result type for FDv2 initializers and synchronizers.
+ *
+ * An initializer produces a single result, while a synchronizer produces a
+ * stream of results. Each result is either a change set (containing a payload
+ * of flag data) or a status (indicating a state transition like an error or
+ * shutdown).
+ */
+export type FDv2SourceResult = ChangeSetResult | StatusResult;
+/**
+ * Creates a change set result containing processed flag data.
+ */
+export declare function changeSet(payload: internal.Payload, fdv1Fallback: boolean, environmentId?: string): FDv2SourceResult;
+/**
+ * Creates an interrupted status result. Indicates a transient error; the
+ * synchronizer will attempt to recover automatically.
+ *
+ * When used with an initializer, this is still a terminal state.
+ */
+export declare function interrupted(errorInfo: DataSourceStatusErrorInfo, fdv1Fallback: boolean): FDv2SourceResult;
+/**
+ * Creates a shutdown status result. Indicates the data source was closed
+ * gracefully and will not produce any further results.
+ */
+export declare function shutdown(): FDv2SourceResult;
+/**
+ * Creates a terminal error status result. Indicates an unrecoverable error;
+ * the data source will not produce any further results.
+ */
+export declare function terminalError(errorInfo: DataSourceStatusErrorInfo, fdv1Fallback: boolean): FDv2SourceResult;
+/**
+ * Creates a goodbye status result. Indicates the server has instructed the
+ * client to disconnect.
+ */
+export declare function goodbye(reason: string, fdv1Fallback: boolean): FDv2SourceResult;
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from an HTTP status code.
+ */
+export declare function errorInfoFromHttpError(statusCode: number): DataSourceStatusErrorInfo;
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from a network error.
+ */
+export declare function errorInfoFromNetworkError(message: string): DataSourceStatusErrorInfo;
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} from invalid data.
+ */
+export declare function errorInfoFromInvalidData(message: string): DataSourceStatusErrorInfo;
+/**
+ * Helper to create a {@link DataSourceStatusErrorInfo} for unknown errors.
+ */
+export declare function errorInfoFromUnknown(message: string): DataSourceStatusErrorInfo;
+//# sourceMappingURL=FDv2SourceResult.d.ts.map

package/dist/cjs/datasource/fdv2/FDv2SourceResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FDv2SourceResult.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/FDv2SourceResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5E,OAAO,yBAAyB,MAAM,8BAA8B,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,YAAY,CAAC;AAE9D;;GAEG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,QAAQ,CAAC,OAAO,EACzB,YAAY,EAAE,OAAO,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,yBAAyB,EACpC,YAAY,EAAE,OAAO,GACpB,gBAAgB,CAElB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,gBAAgB,CAE3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,yBAAyB,EACpC,YAAY,EAAE,OAAO,GACpB,gBAAgB,CAElB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,gBAAgB,CAE/E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,yBAAyB,CAOpF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAMpF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAMnF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAM/E"}

package/dist/cjs/datasource/fdv2/Initializer.d.ts

@@ -0,0 +1,40 @@
+import { FDv2SourceResult } from './FDv2SourceResult';
+/**
+ * Interface for an asynchronous data source initializer.
+ *
+ * An initializer runs once and produces a single result. If successful, the
+ * result contains a change set with flag data. If it fails, the result
+ * contains a status describing the error.
+ *
+ * Once `run()` resolves, the initializer is complete and should not be
+ * called again. Use `close()` to cancel a pending run.
+ *
+ * ```
+ *     [START]
+ *        │
+ *        ▼
+ *   ┌─────────┐
+ *   │ RUNNING │──┐
+ *   └─────────┘  │
+ *    │  │  │  │  └──► SHUTDOWN ──► [END]
+ *    │  │  │  └─────► INTERRUPTED ──► [END]
+ *    │  │  └────────► CHANGESET ──► [END]
+ *    │  └───────────► TERMINAL_ERROR ──► [END]
+ *    └──────────────► GOODBYE ──► [END]
+ * ```
+ */
+export interface Initializer {
+    /**
+     * Run the initializer to completion.
+     *
+     * This method is intended to be called only a single time for an instance.
+     * @returns The result of the initializer.
+     */
+    run(): Promise<FDv2SourceResult>;
+    /**
+     * Close the initializer. If `run()` is in progress, it will resolve with
+     * a shutdown result.
+     */
+    close(): void;
+}
+//# sourceMappingURL=Initializer.d.ts.map

package/dist/cjs/datasource/fdv2/Initializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Initializer.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/Initializer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,GAAG,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEjC;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/cjs/datasource/fdv2/PollingBase.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PollingBase.d.ts.map

package/dist/cjs/datasource/fdv2/PollingBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PollingBase.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/PollingBase.ts"],"names":[],"mappings":""}

package/dist/cjs/datasource/fdv2/PollingInitializer.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PollingInitializer.d.ts.map

package/dist/cjs/datasource/fdv2/PollingInitializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PollingInitializer.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/PollingInitializer.ts"],"names":[],"mappings":""}

package/dist/cjs/datasource/fdv2/PollingSynchronizer.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PollingSynchronizer.d.ts.map

package/dist/cjs/datasource/fdv2/PollingSynchronizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PollingSynchronizer.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/PollingSynchronizer.ts"],"names":[],"mappings":""}

package/dist/cjs/datasource/fdv2/SourceManager.d.ts

@@ -0,0 +1,88 @@
+import { Initializer } from './Initializer';
+import { Synchronizer } from './Synchronizer';
+/**
+ * Factory function that creates an {@link Initializer} instance.
+ *
+ * @param selectorGetter Returns the current selector (basis) string, or
+ *   `undefined` if no selector is available.
+ */
+export type InitializerFactory = (selectorGetter: () => string | undefined) => Initializer;
+/**
+ * Factory function that creates a {@link Synchronizer} instance.
+ *
+ * @param selectorGetter Returns the current selector (basis) string, or
+ *   `undefined` if no selector is available.
+ */
+export type SynchronizerFactory = (selectorGetter: () => string | undefined) => Synchronizer;
+/**
+ * State of a synchronizer slot.
+ * - `'available'`: can be selected for use.
+ * - `'blocked'`: has been blocked (e.g., terminal error or not yet activated).
+ */
+export type SynchronizerSlotState = 'available' | 'blocked';
+/**
+ * A slot in the synchronizer list, wrapping a factory with state metadata.
+ */
+export interface SynchronizerSlot {
+    readonly factory: SynchronizerFactory;
+    readonly isFDv1Fallback: boolean;
+    state: SynchronizerSlotState;
+}
+/**
+ * Creates a {@link SynchronizerSlot}.
+ *
+ * @param factory The synchronizer factory function.
+ * @param options Optional configuration.
+ * @param options.isFDv1Fallback Whether this slot is the FDv1 fallback adapter.
+ *   FDv1 slots start `'blocked'` by default.
+ * @param options.initialState Override the initial state (defaults to
+ *   `'blocked'` for FDv1 slots, `'available'` otherwise).
+ */
+export declare function createSynchronizerSlot(factory: SynchronizerFactory, options?: {
+    isFDv1Fallback?: boolean;
+    initialState?: SynchronizerSlotState;
+}): SynchronizerSlot;
+/**
+ * Manages the state of initializers and synchronizers, tracks which source
+ * is active, and handles source transitions.
+ */
+export interface SourceManager {
+    /**
+     * Get the next initializer and set it as the active source.
+     * Closes the previous active source. Returns `undefined` when all
+     * initializers are exhausted.
+     */
+    getNextInitializerAndSetActive(): Initializer | undefined;
+    /**
+     * Get the next available (non-blocked) synchronizer and set it as the
+     * active source. Closes the previous active source. Returns `undefined`
+     * when all available synchronizers have been visited.
+     */
+    getNextAvailableSynchronizerAndSetActive(): Synchronizer | undefined;
+    /** Mark the current synchronizer as blocked (e.g., after terminal error). */
+    blockCurrentSynchronizer(): void;
+    /** Reset the synchronizer index to -1 so the next call starts from the beginning. */
+    resetSourceIndex(): void;
+    /** Block all non-FDv1 synchronizers and unblock FDv1 synchronizers. */
+    fdv1Fallback(): void;
+    /** True if the current synchronizer is the first available (primary). */
+    isPrimeSynchronizer(): boolean;
+    /** Count of synchronizers in `'available'` state. */
+    getAvailableSynchronizerCount(): number;
+    /** True if any synchronizer slot is marked as an FDv1 fallback. */
+    hasFDv1Fallback(): boolean;
+    /** Close the active source and mark the manager as shut down. */
+    close(): void;
+    /** True if {@link close} has been called. */
+    readonly isShutdown: boolean;
+}
+/**
+ * Creates a {@link SourceManager} that coordinates initializer and
+ * synchronizer lifecycle.
+ *
+ * @param initializerFactories Ordered list of initializer factories.
+ * @param synchronizerSlots Ordered list of synchronizer slots with state.
+ * @param selectorGetter Closure that returns the current selector string.
+ */
+export declare function createSourceManager(initializerFactories: InitializerFactory[], synchronizerSlots: SynchronizerSlot[], selectorGetter: () => string | undefined): SourceManager;
+//# sourceMappingURL=SourceManager.d.ts.map

package/dist/cjs/datasource/fdv2/SourceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceManager.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/SourceManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,cAAc,EAAE,MAAM,MAAM,GAAG,SAAS,KAAK,WAAW,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,cAAc,EAAE,MAAM,MAAM,GAAG,SAAS,KAAK,YAAY,CAAC;AAE7F;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,KAAK,EAAE,qBAAqB,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC,GACA,gBAAgB,CAIlB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,8BAA8B,IAAI,WAAW,GAAG,SAAS,CAAC;IAE1D;;;;OAIG;IACH,wCAAwC,IAAI,YAAY,GAAG,SAAS,CAAC;IAErE,6EAA6E;IAC7E,wBAAwB,IAAI,IAAI,CAAC;IAEjC,qFAAqF;IACrF,gBAAgB,IAAI,IAAI,CAAC;IAEzB,uEAAuE;IACvE,YAAY,IAAI,IAAI,CAAC;IAErB,yEAAyE;IACzE,mBAAmB,IAAI,OAAO,CAAC;IAE/B,qDAAqD;IACrD,6BAA6B,IAAI,MAAM,CAAC;IAExC,mEAAmE;IACnE,eAAe,IAAI,OAAO,CAAC;IAE3B,iEAAiE;IACjE,KAAK,IAAI,IAAI,CAAC;IAEd,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,oBAAoB,EAAE,kBAAkB,EAAE,EAC1C,iBAAiB,EAAE,gBAAgB,EAAE,EACrC,cAAc,EAAE,MAAM,MAAM,GAAG,SAAS,GACvC,aAAa,CAsGf"}

package/dist/cjs/datasource/fdv2/StreamingFDv2Base.d.ts

@@ -0,0 +1,11 @@
+import { FDv2SourceResult } from './FDv2SourceResult';
+/**
+ * Handler invoked when a legacy `"ping"` event is received on the stream.
+ * The implementation should perform an FDv2 poll request (e.g. via
+ * {@link poll} from PollingBase) and return the processed result.
+ */
+export interface PingHandler {
+    /** Perform a poll and return the processed result. */
+    handlePing(): Promise<FDv2SourceResult>;
+}
+//# sourceMappingURL=StreamingFDv2Base.d.ts.map

package/dist/cjs/datasource/fdv2/StreamingFDv2Base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingFDv2Base.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/StreamingFDv2Base.ts"],"names":[],"mappings":"AAeA,OAAO,EAML,gBAAgB,EAKjB,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACzC"}

package/dist/cjs/datasource/fdv2/StreamingInitializerFDv2.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StreamingInitializerFDv2.d.ts.map

package/dist/cjs/datasource/fdv2/StreamingInitializerFDv2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingInitializerFDv2.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/StreamingInitializerFDv2.ts"],"names":[],"mappings":""}

package/dist/cjs/datasource/fdv2/StreamingSynchronizerFDv2.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StreamingSynchronizerFDv2.d.ts.map

package/dist/cjs/datasource/fdv2/StreamingSynchronizerFDv2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingSynchronizerFDv2.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/StreamingSynchronizerFDv2.ts"],"names":[],"mappings":""}

package/dist/cjs/datasource/fdv2/Synchronizer.d.ts

@@ -0,0 +1,49 @@
+import { FDv2SourceResult } from './FDv2SourceResult';
+/**
+ * Interface for an asynchronous data source synchronizer.
+ *
+ * A synchronizer runs continuously and produces a stream of results via
+ * successive calls to `next()`. When it experiences a temporary failure,
+ * it emits an INTERRUPTED result while attempting to recover. When it
+ * receives data, it emits a CHANGESET result. When shut down gracefully,
+ * it emits a SHUTDOWN result.
+ *
+ * `next()` is intended to be driven by a single caller, with one outstanding
+ * call at a time. Once SHUTDOWN or TERMINAL_ERROR has been produced, no
+ * further calls to `next()` should be made.
+ *
+ * ```
+ *       [START]
+ *          │
+ *          ▼
+ *    ┌─────────┐
+ * ┌─►│ RUNNING │──┐
+ * │  └─────────┘  │
+ * │   │  │  │  │  └──► SHUTDOWN ──────► [END]
+ * │   │  │  │  └─────► TERMINAL_ERROR ► [END]
+ * │   │  │  └────────► GOODBYE ───────┐
+ * │   │  └───────────► CHANGESET ─────┤
+ * │   └──────────────► INTERRUPTED ───┤
+ * └───────────────────────────────────┘
+ * ```
+ */
+export interface Synchronizer {
+    /**
+     * Get the next result from the stream.
+     *
+     * This method is intended to be driven by a single caller, and for there
+     * to be a single outstanding call at any given time.
+     *
+     * Once SHUTDOWN or TERMINAL_ERROR has been produced, no further calls to
+     * `next()` should be made.
+     *
+     * @returns A promise that resolves when the next result is available.
+     */
+    next(): Promise<FDv2SourceResult>;
+    /**
+     * Close the synchronizer. The next call to `next()` will resolve with a
+     * shutdown result.
+     */
+    close(): void;
+}
+//# sourceMappingURL=Synchronizer.d.ts.map

package/dist/cjs/datasource/fdv2/Synchronizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;OAUG;IACH,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAElC;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/cjs/datasource/fdv2/index.d.ts

@@ -0,0 +1,16 @@
+export type { AsyncQueue } from './AsyncQueue';
+export { createAsyncQueue } from './AsyncQueue';
+export type { FDv2PollResponse, FDv2Requestor } from './FDv2Requestor';
+export { makeFDv2Requestor } from './FDv2Requestor';
+export type { ChangeSetResult, FDv2SourceResult, SourceState, StatusResult, } from './FDv2SourceResult';
+export { changeSet, errorInfoFromHttpError, errorInfoFromInvalidData, errorInfoFromNetworkError, errorInfoFromUnknown, goodbye, interrupted, shutdown, terminalError, } from './FDv2SourceResult';
+export type { Initializer } from './Initializer';
+export type { Synchronizer } from './Synchronizer';
+export { poll } from './PollingBase';
+export { createPollingInitializer } from './PollingInitializer';
+export { createPollingSynchronizer } from './PollingSynchronizer';
+export type { PingHandler, StreamingFDv2Base } from './StreamingFDv2Base';
+export { createStreamingBase } from './StreamingFDv2Base';
+export { createStreamingInitializer } from './StreamingInitializerFDv2';
+export { createStreamingSynchronizer } from './StreamingSynchronizerFDv2';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/datasource/fdv2/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/datasource/fdv2/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,OAAO,EACP,WAAW,EACX,QAAQ,EACR,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/cjs/index.cjs

@@ -222,6 +222,74 @@ function createAsyncTaskQueue(logger) {
     };
 }
 
+function isCompoundValidator(v) {
+    return 'validate' in v;
+}
+/**
+ * Validates an options object against a map of validators and defaults.
+ *
+ * If `input` is null, undefined, or not an object the defaults are returned
+ * (with a warning for non-nullish non-objects).
+ *
+ * Supports special validator types created by:
+ * - {@link validatorOf}: recursively validates nested objects
+ * - {@link arrayOf}: validates arrays with per-item validation
+ * - {@link anyOf}: accepts the first matching validator from a list
+ * - {@link recordOf}: validates objects with dynamic keys
+ */
+function validateOptions(input, validatorMap, defaults, logger, prefix) {
+    const result = { ...defaults };
+    if (jsSdkCommon.isNullish(input)) {
+        return result;
+    }
+    if (!jsSdkCommon.TypeValidators.Object.is(input)) {
+        logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(prefix ?? 'config', 'object', typeof input));
+        return result;
+    }
+    Object.entries(input).forEach(([key, value]) => {
+        const validator = validatorMap[key];
+        const name = prefix ? `${prefix}.${key}` : key;
+        if (!validator) {
+            logger?.warn(jsSdkCommon.OptionMessages.unknownOption(name));
+            return;
+        }
+        if (jsSdkCommon.isNullish(value)) {
+            return;
+        }
+        if (isCompoundValidator(validator)) {
+            const validated = validator.validate(value, name, logger, defaults[key]);
+            if (validated !== undefined) {
+                result[key] = validated.value;
+            }
+            return;
+        }
+        if (validator.is(value)) {
+            result[key] = value;
+            return;
+        }
+        // Validation failed — apply correction or fall back to default.
+        const validatorType = validator.getType();
+        if (validatorType === 'boolean') {
+            logger?.warn(jsSdkCommon.OptionMessages.wrongOptionTypeBoolean(name, typeof value));
+            result[key] = !!value;
+        }
+        else if (validatorType === 'boolean | undefined | null') {
+            logger?.warn(jsSdkCommon.OptionMessages.wrongOptionTypeBoolean(name, typeof value));
+            if (typeof value !== 'boolean' && typeof value !== 'undefined' && value !== null) {
+                result[key] = !!value;
+            }
+        }
+        else if (validator instanceof jsSdkCommon.NumberWithMinimum && jsSdkCommon.TypeValidators.Number.is(value)) {
+            logger?.warn(jsSdkCommon.OptionMessages.optionBelowMinimum(name, value, validator.min));
+            result[key] = validator.min;
+        }
+        else {
+            logger?.warn(jsSdkCommon.OptionMessages.wrongOptionType(name, validatorType, typeof value));
+        }
+    });
+    return result;
+}
+
 // eslint-disable-next-line max-classes-per-file
 const validators = {
     logger: jsSdkCommon.TypeValidators.Object,
@@ -291,8 +359,12 @@ class ConfigurationImpl {
         this.hooks = [];
         this.inspectors = [];
         this.logger = ensureSafeLogger(pristineOptions.logger);
-        const errors = this._validateTypesAndNames(pristineOptions);
-        errors.forEach((e) => this.logger.warn(e));
+        const validated = validateOptions(pristineOptions, validators, {}, this.logger);
+        Object.entries(validated).forEach(([k, v]) => {
+            if (k !== 'logger') {
+                this[k] = v;
+            }
+        });
         this.serviceEndpoints = new jsSdkCommon.ServiceEndpoints(this.streamUri, this.baseUri, this.eventsUri, internalOptions.analyticsEventPath, internalOptions.diagnosticEventPath, internalOptions.includeAuthorizationHeader, pristineOptions.payloadFilterKey);
         this.useReport = pristineOptions.useReport ?? false;
         this.tags = new jsSdkCommon.ApplicationTags({ application: this.applicationInfo, logger: this.logger });
@@ -301,44 +373,6 @@ class ConfigurationImpl {
         this.credentialType = internalOptions.credentialType;
         this.getImplementationHooks = internalOptions.getImplementationHooks;
     }
-    _validateTypesAndNames(pristineOptions) {
-        const errors = [];
-        Object.entries(pristineOptions).forEach(([k, v]) => {
-            const validator = validators[k];
-            if (validator) {
-                if (!validator.is(v)) {
-                    const validatorType = validator.getType();
-                    if (validatorType === 'boolean') {
-                        errors.push(jsSdkCommon.OptionMessages.wrongOptionTypeBoolean(k, typeof v));
-                        this[k] = !!v;
-                    }
-                    else if (validatorType === 'boolean | undefined | null') {
-                        errors.push(jsSdkCommon.OptionMessages.wrongOptionTypeBoolean(k, typeof v));
-                        if (typeof v !== 'boolean' && typeof v !== 'undefined' && v !== null) {
-                            this[k] = !!v;
-                        }
-                    }
-                    else if (validator instanceof jsSdkCommon.NumberWithMinimum && jsSdkCommon.TypeValidators.Number.is(v)) {
-                        const { min } = validator;
-                        errors.push(jsSdkCommon.OptionMessages.optionBelowMinimum(k, v, min));
-                        this[k] = min;
-                    }
-                    else {
-                        errors.push(jsSdkCommon.OptionMessages.wrongOptionType(k, validator.getType(), typeof v));
-                    }
-                }
-                else if (k === 'logger') ;
-                else {
-                    // if an option is explicitly null, coerce to undefined
-                    this[k] = v ?? undefined;
-                }
-            }
-            else {
-                errors.push(jsSdkCommon.OptionMessages.unknownOption(k));
-            }
-        });
-        return errors;
-    }
 }
 
 async function digest(hasher, encoding) {
@@ -2552,6 +2586,7 @@ exports.makeRequestor = makeRequestor;
 exports.mobileFdv1Endpoints = mobileFdv1Endpoints;
 exports.readFlagsFromBootstrap = readFlagsFromBootstrap;
 exports.safeRegisterDebugOverridePlugins = safeRegisterDebugOverridePlugins;
+exports.validateOptions = validateOptions;
 Object.keys(jsSdkCommon).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
         enumerable: true,