You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(node-sdk): adopt collection values and Boolean-first reads - #790
Breaking Node SDK v2 using the already-published collection evaluator 2.0.0. #744 and release #793 landed the evaluator and v1 compatibility—not Node SDK v2. This PR now merges current main through 1adfced without rewriting history. Companion server protocol/check ingestion: https://github.com/reflagcom/web/pull/3660.
Consume and atomically prepare complete protocol-v2 { flags, segments } snapshots. Evaluate only requested roots/dependencies, without dependency-result caching.
Return direct values with Boolean-first reads and positional defaults, preserving valid falsy values. Runtime non-null defaults enforce top-level JSON categories, not nested selected-value schemas. Explicit null accepts arbitrary/nullable JSON.
Register requested-root checks immediately with buffered, identity-aware delivery. Dependencies, diagnostic reads and bootstrap serialization do not emit extra checks.
Persist isolated v2 fallback snapshots and serialize accepted live saves. Preserve synchronization modes, ordinary tracking, bound contexts and post-evaluation overrides.
Keep OpenFeature and the v1 React bootstrap demo on published Node 1.8.3, not the v2 workspace. The Node v2 source manifest retains its prerelease version to avoid Yarn transparently linking the legacy alias to this workspace; Changesets plans Node 2.0.0. This is not prerelease-publication authorization.
Remove the evaluator Changeset already consumed by its stable release. The evaluator runtime is unchanged against current main; the old evaluator commits remain visible only because feat: add protocol-v2 multivariate flag evaluation #744 was squash-merged and this update deliberately does not rewrite history.
Port main's ETag refresh behavior to complete /flags graphs: snapshot-owned validators, bodyless 304 freshness, unconditional cold/fallback/version-targeted requests, bounded unexpected-304 recovery, ordered background persistence, and isolation from rejected snapshots or late saves. Preserve default/custom HTTP transport coverage.
Preserve application-owned process shutdown: no SDK signal handlers or forced exits; automatic flushing is only on natural beforeExit.
Preserve evaluation diagnostics, including CLIENT_NOT_INITIALIZED captured at local-read time. Remote-only reads do not require local initialization and do not get that diagnostic.
Address all three existing review threads with regressions: accept thousandth-percent allocations using integer units; restore guarded context synchronization for track-only/remote-only and chained bindings with logged async failures; retain the bound company for an undefined override while accepting numeric zero.
Adapt the incoming Express/Cloudflare example assertions to direct values.
Registered-default follow-up
3cc369b checks non-null defaults against each registered key's schema for root/bound, local/remote singular getters. Named-interface and readonly defaults work without dictionary index signatures.
Bare/explicit-undefined reads remain Boolean; explicit null remains arbitrary JSON. Singular results still infer/widen from the supplied default, not the registered schema. Runtime JSON validation/copying and top-level category checking are unchanged.
Augmented/unaugmented compiler regressions retain generic forwarding and opaque arbitrary-JSON registrations to avoid recursive-instantiation failures.
595758d keeps the readonly mapper and existing log-level constant intentionally private in package-scoped TypeDoc settings, without public-export workarounds or a global validation disable. The docs anchor condition is POSIX-compatible.
Breaking changes
Remove flag wrappers: .value, .isEnabled, .config, and flag .track(). Client tracking remains separate.
Bare singular reads are Boolean with implicit false; supply positional defaults for other types. Batch APIs retain raw JSON/undefined records.
Remote signature: getFlagRemote(key, defaultValue, userId?, companyId?, context?). Use undefined for a Boolean read with explicit IDs.
V1 fallback/browser bootstrap formats and legacy CLI wrapper declarations are incompatible with v2.
Fresh local verification
965 workspace tests passed: evaluator 302, Node 271, Browser 208, React 65, Vue 13, OpenFeature Node 32/Browser 27, CLI 36, Management 7, Express 4. This checkout deliberately still has the v1 Browser/framework packages from main.
48 existing browser E2E cases passed, across Chromium, Firefox and WebKit with mocked transport—not deployed v2 acceptance.
Both standalone-example immutable installs/builds/tests pass: Cloudflare Worker 2 tests and OpenFeature Node 4 tests. Wrangler was dry-run only.
Evaluator, Node, Browser, React, Vue, React Native, both OpenFeature providers and CLI builds pass. Node/React/Vue type programs, Express typecheck, both Next.js example typechecks, immutable root install, docs build and 3 docs-transform tests pass.
Full Management regeneration/full root yarn build was not run locally because Java is absent. The existing checked-in Management generated source is byte-identical to main and its TypeScript build passes.
Repository formatting passes; changed-source lint has zero warnings/errors. Full lint has zero errors and one pre-existing main warning in generated Next.js environment declarations. Normal commit hooks passed, and the committed tree matches the verified prepared tree.
Node's pending matched-rule patch and LAN demo remain untouched outside this PR. Separate CLI v2 work remains local/uncommitted, with no CLI-v2 implementation in this PR.
Historical generated-consumer checks passed on the earlier typing stack; the separate CLI-v2 generator was not rerun or made mandatory CI here. Versioned/packed generated-consumer acceptance remains a release gate.
No package publication, deployment, saved-snapshot rebuild, persistent restart or shared-data mutation occurred. Compatible server readers/check ingestion, stored-predicate preflight, approved snapshots, deployed acceptance and publication holds remain necessary. Do not republish the already-released evaluator from its historical prerelease plan.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Valid fractional allocations are rejected, potentially blocking all flag refreshes, while bound clients lose context synchronization and can drop company associations from events.
Migrates the Node SDK to the collection evaluator introduced in #744, adding a breaking v2 direct-value API while keeping existing OpenFeature and React bootstrap consumers on published v1.
Changes:
Introduces Boolean-first reads, positional defaults, and immediate, identity-aware check registration.
Validates complete flag/segment collections and persists isolated v2 fallback snapshots with ordered saves.
Updates documentation, type contracts, tests, and the Express example; pins unmigrated consumers to v1.
File
Description
yarn.lock
Resolves the v2 evaluator and published v1 SDK alias.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Integer-only validation rejects valid three-decimal variant distributions, causing an entire live or fallback flag snapshot to be discarded and leaving flags stale or on caller defaults.
Correct Node SDK version guidance in migration guide
packages/flag-evaluation/README.md:101
The migration guide still says the Node SDK uses the published v1 evaluator, but this PR switches packages/node-sdk/package.json to the v2 workspace evaluator. This gives integrators the opposite compatibility guidance for the new collection protocol. Update this paragraph to distinguish Node SDK v2 from the OpenFeature provider and bootstrap demo, which remain isolated on published Node SDK v1.
Keep published evaluator 2.0.0 and main's dependency updates, port ETag revalidation and initialization diagnostics to complete collections, preserve application-owned shutdown, and address the three Node migration review regressions. Keep OpenFeature and the v1 bootstrap demo isolated on published Node 1.8.3.
Focus the protocol-v2 Changeset on developer-facing API and migration changes. Fold registered-default typing into the major release note and remove the separate patch Changeset.
Addressed both remaining open review threads in 956f266 (retry-argument cleanup and inferred event-mock types), with regression coverage for configured retries on collection and remote reads. Also corrected the still-relevant migration-guide issue from the earlier review: packages/flag-evaluation/README.md now distinguishes Node SDK v2’s collection evaluator from the OpenFeature provider and v1 React bootstrap demo, which remain on published Node SDK 1.8.3 and its v1 evaluator.
Validation: 273 Node SDK tests and 302 evaluator tests pass; both Node public type-contract programs, test-source typechecking, evaluator/Node builds, changed-file formatting, zero-warning scoped lint, and normal commit hooks pass. No lockfile or dependency changes. Fresh remote CI is pending; no merge or publication performed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Breaking Node SDK v2 using the already-published collection evaluator 2.0.0. #744 and release #793 landed the evaluator and v1 compatibility—not Node SDK v2. This PR now merges current
mainthrough1adfcedwithout rewriting history. Companion server protocol/check ingestion: https://github.com/reflagcom/web/pull/3660.{ flags, segments }snapshots. Evaluate only requested roots/dependencies, without dependency-result caching.nullaccepts arbitrary/nullable JSON.Main reconciliation —
0809be2/flagsgraphs: snapshot-owned validators, bodyless 304 freshness, unconditional cold/fallback/version-targeted requests, bounded unexpected-304 recovery, ordered background persistence, and isolation from rejected snapshots or late saves. Preserve default/custom HTTP transport coverage.beforeExit.CLIENT_NOT_INITIALIZEDcaptured at local-read time. Remote-only reads do not require local initialization and do not get that diagnostic.Registered-default follow-up
undefinedreads remain Boolean; explicitnullremains arbitrary JSON. Singular results still infer/widen from the supplied default, not the registered schema. Runtime JSON validation/copying and top-level category checking are unchanged.Breaking changes
.value,.isEnabled,.config, and flag.track(). Client tracking remains separate.false; supply positional defaults for other types. Batch APIs retain raw JSON/undefinedrecords.getFlagRemote(key, defaultValue, userId?, companyId?, context?). Useundefinedfor a Boolean read with explicit IDs.Fresh local verification
yarn buildwas not run locally because Java is absent. The existing checked-in Management generated source is byte-identical to main and its TypeScript build passes.Integration and release boundaries