fix: FDv2 initializer readiness

[joker23]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Describe the solution you've provided

This PR will:

1. Make it so that a client in FDv2 will only report intialized when it gets a basis + valid selector. This will align the behavior better with the FDv2 initializer specs.
2. Updated the docs for the custom datasystem options with an example for clarity

---

Note

Gate FDv2 basis readiness to only trigger when a non-empty state is present; update tests accordingly and add @experimental docs plus example for custom data source options.

• Data sources:
  • In src/data_sources/createPayloadListenerFDv2.ts, wrap the applyChanges readiness callback to invoke basisReceived() only when payload.state is non-empty, aligning initializer readiness with valid selector presence.
• Tests:
  • Update __tests__/data_sources/createPayloadListenersFDv2.test.ts to use toHaveBeenCalledWith and expect the third applyChanges arg as expect.any(Function); adjust logger expectations.
• Docs/Types:
  • In src/api/options/LDDataSystemOptions.ts, mark CustomDataSourceOptions as @experimental and add a concise example demonstrating initializers and synchronizers configuration.

^{Written by Cursor Bugbot for commit 935b994. 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: 22101 bytes
Compressed size limit: 25000
Uncompressed size: 76263 bytes

[kinyoklion]

Would the FDv2 fallback also not have a selector? I may just not know how that part works.

[joker23]

From my understanding here, the basis can be consumed without a selector, however that would not be considered a successful initialization from this particular initializer. I think this function might not be named correctly here as from the invocation it is simply a success callback (

js-core/packages/shared/sdk-server/src/LDClientImpl.ts

Line 459 in 8113122

payloadListener = createPayloadListener(dataSourceUpdates, logger, initSuccess);

). @tanderson-ld thoughts?

[cursor]

Bug: New conditional logic in callback lacks test coverage

The tests were changed from verifying that basisReceived is passed directly to applyChanges to using expect.any(Function), but there's no test that verifies the new conditional behavior. The key new logic (if (payload.state !== '') determines whether basisReceived() is called) is not covered by any test. The tests don't verify that basisReceived is actually invoked when state is non-empty, nor that it's skipped when state is empty (for file data initializer scenarios). This means the core fix described in the PR could regress without test detection.

Additional Locations (1)

• packages/shared/sdk-server/__tests__/data_sources/createPayloadListenersFDv2.test.ts#L170-L171