feat: add FDv2 FileDataSource initializer

[joker23]

This PR will introduce file data source initializer for FDv2 that could be specified by adding in an optional intializerOption to the FDv2 datasource option. If this option is not specified then the behavior should not change from before this change.

Additionally:

• I've added some more type definitions to align better with FDv2 as well as a change set builder to convert FDv1 scheme to FDv2.
• added a new custom data source options mode that allows users to specify the ordering of their initializers and synchronizers

NOTE: will need to look into a problem where while the initializers are running in expected order, the client initialized event seems to be prematurely firing. Example with the following config:

const ldClient = init(sdkKey, {
  dataSystem: {
    dataSource: {
      dataSourceOptionsType: 'custom',
      initializers: [
      {
        type: 'file',
        paths: [path.resolve(__dirname, 'flagdatav1.json')]
      },
      {
        type: 'polling'
      },
    ],
      synchronizers: [
        {
          type: 'streaming',
          streamInitialReconnectDelay: 1
        }
      ],
    }
  }
});

STDOUT with the sample-feature flag set to false in LD:

fs start
fs stop
polling started
*** SDK successfully initialized!
*** The 'sample-feature' feature flag evaluates to true.
        ██
          ██
      ████████
         ███████
██ LAUNCHDARKLY █
         ███████
      ████████
          ██
        ██

*** Event triggered: update:sample-feature
polling stopped
*** The 'sample-feature' feature flag evaluates to false.
info: [LaunchDarkly] Opened LaunchDarkly stream connection

In the above run, we have the correct ordering where the fs initializer got data, but since it does not report a valid basis, the polling initializer is also being ran. But as you can see, the client reported initialized before the polling initializer was able to update the data to the real thing (but further down we can see that the flag value is being set correctly before the streaming synchronizer runs)

I think this issue could be addressed in a separate change.

---

Note

Introduces a file-based FDv2 initializer and configurable custom data source pipeline, adds an adaptor to convert FDv1 payloads to FDv2 events, tightens FDv2 proto/types, and wires everything into LDClient with tests.

• FDv2 data flow:
  • New FDv1PayloadAdaptor (packages/shared/common/src/internal/fdv2/FDv1PayloadAdaptor.ts): converts FDv1 flags/segments into FDv2 event sequences; exported via internal/fdv2/index.
  • PollingProcessorFDv2: replaces inline FDv1 conversion with FDv1PayloadAdaptor and sets selector; unchanged FDv2 path.
  • payloadProcessor: relaxes payload-transferred validation to allow empty state and makes checks null/undefined-safe.
  • proto: adds strict EventType, ObjectKind, GoodbyeObject, ErrorObject; refines event data union; makes PayloadTransferred.id optional.
• SDK server – data source composition:
  • Custom mode in LDDataSystemOptions: new custom option with ordered initializers (file|polling) and synchronizers (streaming|polling).
  • LDClientImpl: builds CompositeDataSource from custom configs; supports file initializer, streaming/polling synchronizers, and FDv1 fallback polling; exports DEFAULT_STREAM_RECONNECT_DELAY.
  • Configuration: validates custom data source options; exports DEFAULT_STREAM_RECONNECT_DELAY.
  • New FileDataInitializerFDv2: loads JSON/YAML from disk, merges multiple files, emits FDv2 payload via FDv1PayloadAdaptor; no auto-update; error handling for invalid/missing FS.
• Tests:
  • Add unit tests for FDv1PayloadAdaptor.
  • Extend CompositeDataSource tests for multi-initializer fallback/short-circuit.
  • Add comprehensive tests for FileDataInitializerFDv2 (JSON/YAML parsing, multi-file merge/overwrite, errors).

^{Written by Cursor Bugbot for commit c42e4f4. This will update automatically on new commits. Configure here.}

[github-actions]

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 169118 bytes
Compressed size limit: 200000
Uncompressed size: 789399 bytes

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 25394 bytes
Compressed size limit: 26000
Uncompressed size: 124693 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 17636 bytes
Compressed size limit: 20000
Uncompressed size: 90259 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 22096 bytes
Compressed size limit: 25000
Uncompressed size: 76263 bytes

[tanderson-ld]

If new values are added to the protocol, is the code well behaved? Same for nearby types.

[joker23]

yea payload changes will potentially break this, but that is probably true even if we didn't declare these types?

[tanderson-ld]

Double check logic in the processFDv1FlagsAndSegments in PollingProcessorFDv2 matches this and/or consider commonizing.

[joker23]

ah yea the logic is the same! Let me think of a way to merge the logic.

Now that I am thinking about this more, I don't think sdk-common is the right place to create this builder? I am not sure how FDv2 is going to show up for client side implementations so probably move this out to sdk-server then, if we find out that client implementation is similar, move it back out to sdk-common? @abarker-launchdarkly @kinyoklion thoughts?

Otherwise, I think the plan will be change this to a FDv1PayloadAdaptor instead of a builder.

[kinyoklion]

If the data inside the objects is opaque, then the the code itself would likely be the same for both of them.

I am fine with it not being common until we need it though.

A note specifically for internal/common code, but code we intend to use client-side we likely want to avoid classes and do this with functions, as generally speaking they end up smaller when minified. (Or old school function that returns object).

[tanderson-ld]

Should a customer be able to configure to use only a file data source? @kinyoklion thoughts?

I think they should be able to configure just the file data source with polling and streaming disabled, but you'll have to confirm with others on team as I haven't dealt with file data source implementations.

[kinyoklion]

I think we discussed sync, but yeah it should be possible. This would be a typical use case with FDv1. Often times people use file data sources for testing purposes.

[joker23]

Okay I think we can have a separate story to handle file synchronizer? I think it would be a fairly trivial implementation on top of this PR.