feat: Add the file-based override source

[kinyoklion]

Summary

This PR is based on the events branch because it completes the feature that the earlier branches build up, and it should merge after them.

This change adds the file-based override source described by the OVERRIDE specification to the Node.js server SDK. It is configured as { type: 'file', paths: [...] } in the overrides property of the data system options, alongside the source object and factory forms that the earlier change added.

The source reads one or more JSON or YAML files in the file data source document format, with optional flags, flagValues, and segments members, and combines their entries in the configured order. Duplicate keys across files fail the reload by default, or keep the first file's entry with the ignore handling. Change detection is one of two modes. Polling, the default, examines the files once per second, with a one second minimum, and works on every filesystem. Watching reacts to change notifications for the directories that contain the files. Change detection is in place before the initial load, so a change made between the two is not missed.

A configured file that does not exist contributes no overrides, so a file can be created later and deleting a file removes its overrides. A file that exists but cannot be read or parsed fails that whole reload: the last good overrides stay in effect, the failure is logged once, and the source retries after one second. Every applied change is logged at Info level with the overrides in effect and what each file supplied, and an unchanged reload logs nothing. The initial load completes before the client evaluates anything, so an override present at startup takes effect from the first evaluation.

An invalid configuration fails client construction, the way an invalid file initializer does: no file paths, an unrecognized change detection mode, or a platform without filesystem support. An unrecognized duplicate keys handling is logged and replaced by its default. A polling interval below the minimum is logged and raised to one second, and one that is not a finite number or exceeds 2147483 seconds is logged and replaced by the default.

The specification requires YAML support without extra configuration. The Node.js SDK package gains a dependency on the yaml package (2.9.1, already present in the lockfile as a transitive dependency of other workspaces) and supplies its parser to the shared code as a platform default. A configured yamlParser takes precedence. The shared server package has no new dependency.

The existing file data sources keep their current behavior. The override source has its own document handling (format detection by file extension, validation of the document shape, entries keyed by their map key, value expansion to a flag that is on and serves the value by fallthrough, missing-file handling, retry) and none of it applies to the FDv1 FileDataSource or the FDv2 file data initializer.

The tests mirror the Go file source tests over a mock filesystem: initial load, YAML, ordered merge, duplicate handling, missing files that appear and disappear, the Info log on each change, quiet watching of an absent file, reloads in both modes, retention across a malformed edit with recovery through the retry, and close. A server-node test drives the source through the client on real files, including the built-in YAML parser.

SDK-3247

---

Note

Overview
Adds a file-based override source for experimental flag overrides via dataSystem.overrides: { type: 'file', paths: [...] }. Local JSON/YAML files (same shape as file data sources: flags, flagValues, segments) are merged in path order, hot-reloaded via polling (default, 1s) or filesystem watching, and pushed into the existing override layer so evaluations can win over LaunchDarkly data with overrideAffected: true.

Shared server code introduces FileOverrideSource, override-specific document parsing/validation, and expanded createOverrideSource wiring (path validation, duplicate-key fail/ignore, poll interval bounds). Missing files contribute nothing; bad reloads keep the last good snapshot with retry/logging. The Node server SDK adds the yaml dependency and registers a default yamlParser on the platform (overridable per config).

Coverage is mostly new unit/integration tests over mock and real filesystems; TestLogger gains getMessages for log assertions.

^{Reviewed by Cursor Bugbot for commit a908d4b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 27281 bytes
Compressed size limit: 29000
Uncompressed size: 132642 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 32691 bytes
Compressed size limit: 34000
Uncompressed size: 117095 bytes

[github-actions]

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

[kinyoklion]

bugbot review

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a908d4b. Configure here.}

[cursor]

Override layer ignores document map keys

Medium Severity

The file source merges and de-duplicates flags and segments by map key, but apply forwards each item as written and the overlay stores it under item.key. When those differ, the override is served for the wrong key, and two map keys that share one key property silently overwrite each other instead of failing the reload.

Additional Locations (2)

• packages/shared/sdk-server/src/overrides/FileOverrideSource.ts#L126-L127
• packages/shared/sdk-server/src/overrides/overrideDocument.ts#L27-L30

 

^{Reviewed by Cursor Bugbot for commit a908d4b. Configure here.}