Skip to content

feat(node-sdk): adopt collection values and Boolean-first reads - #790

Merged
roncohen merged 19 commits into
mainfrom
feature/node-sdk-v2
Nov 18, 2026
Merged

roncohen merged 19 commits into
mainfrom
feature/node-sdk-v2

Conversation

@roncohen

@roncohen roncohen commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

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 main through 1adfced without rewriting history. Companion server protocol/check ingestion: https://github.com/reflagcom/web/pull/3660.

reflag.getFlag(context, "release"); // boolean, implicit false
reflag.getFlag(context, "settings", { model: "Swift" }); // { model: string }
reflag.bindClient(context).getFlag("release");
  • 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.

Main reconciliation — 0809be2

  • Preserve main's stable evaluator metadata, evaluator runtime source, dependency/security changes, generated Management SDK, browser/framework fixes and standalone-example CI.
  • 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.

Integration and release boundaries

  • This updates feat(node-sdk): adopt collection values and Boolean-first reads #790 only, not main. Fresh remote CI/review must complete; passing local checks are not release approval.
  • feat: adopt v2 flag values in Browser, React, Vue and React Native SDKs #791 still needs to inherit this finalized Node/main reconciliation once. Its original worktree and pending Browser matched-rule patch were not changed.
  • 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.

Copilot AI balanced review requested due to automatic review settings November 4, 2026 08:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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.

3 open issues
What changed in this PR

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.
packages/​react-sdk/​dev/​nextjs-bootstrap-demo/​package.json Pins the demo to published Node SDK v1.
packages/​react-sdk/​dev/​nextjs-bootstrap-demo/​app/​client.ts Imports the v1 SDK alias.
packages/​openfeature-node-provider/​src/​index.ts Uses the v1 SDK alias.
packages/​openfeature-node-provider/​src/​index.test.ts Updates imports and mocks for the alias.
packages/​openfeature-node-provider/​package.json Pins the provider to published Node SDK v1.
packages/​node-sdk/​type-tests/​defaults.ts Tests default-based inference without declarations.
packages/​node-sdk/​type-tests/​augmented-defaults.ts Tests augmented keys and Boolean-first contracts.
packages/​node-sdk/​tsconfig.type-tests.json Isolates unaugmented type-contract checks.
packages/​node-sdk/​tsconfig.type-tests-augmented.json Isolates augmented type-contract checks.
packages/​node-sdk/​tsconfig.test.json Configures SDK and selected test typechecking.
packages/​node-sdk/​test/​flagsFallbackProvider.test.ts Covers v2 snapshots and storage namespaces.
packages/​node-sdk/​test/​flag-definitions.test.ts Tests collection validation and ownership.
packages/​node-sdk/​test/​fixtures.ts Adds shared v2 collection fixtures.
packages/​node-sdk/​test/​client-sync.test.ts Covers synchronization modes and option validation.
packages/​node-sdk/​src/​types.ts Defines direct values and v2 protocol contracts.
packages/​node-sdk/​src/​index.ts Updates public type exports.
packages/​node-sdk/​src/​flagsFallbackProvider.ts Adds v2 fallback envelopes and namespaces.
packages/​node-sdk/​src/​flags-cache.ts Stores complete collections and exposes an apply callback.
packages/​node-sdk/​src/​flag-definitions.ts Validates and prepares complete collections.
packages/​node-sdk/​src/​flag-defaults.ts Implements default validation and category matching.
packages/​node-sdk/​src/​config.ts Accepts direct JSON overrides.
packages/​node-sdk/​src/​client.ts Implements v2 reads, checks, bootstrap, and persistence.
packages/​node-sdk/​README.md Documents v2 usage and migration boundaries.
packages/​node-sdk/​package.json Sets the v2 prerelease and evaluator dependency.
packages/​node-sdk/​examples/​express/​reflag.ts Migrates declarations and overrides to direct values.
packages/​node-sdk/​examples/​express/​app.ts Uses direct reads and separate usage tracking.
packages/​flag-evaluation/​test/​release.test.ts Checks v2 adoption and v1 consumer isolation.
.changeset/​pin-legacy-node-evaluator.md Removes the superseded evaluator-pinning changeset.
.changeset/​node-sdk-collection-values.md Records breaking SDK changes and provider isolation.

Review effort: Balanced

Comment thread packages/node-sdk/src/client.ts Resolved
Comment thread packages/node-sdk/src/client.ts Resolved
Base automatically changed from feature/multivariate-evaluator-v2 to main November 4, 2026 18:40
Copilot AI balanced review requested due to automatic review settings November 5, 2026 14:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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.

3 open issues
1 previously missed issue

In code that hasn't changed since last review

Low severity 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.

Review effort: Balanced

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.
Copilot AI balanced review requested due to automatic review settings November 14, 2026 20:11

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

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.
Copilot AI balanced review requested due to automatic review settings November 16, 2026 18:36

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

@roncohen
roncohen added this pull request to stack #808 November 17, 2026 19:52

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: high

no actionable findings

Comment thread packages/node-sdk/src/client.ts Resolved
Comment thread packages/node-sdk/src/client.ts Resolved
Comment thread packages/node-sdk/test/client.test.ts Resolved
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 18, 2026
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@roncohen
roncohen removed this pull request from the merge queue due to a manual request Nov 18, 2026
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Nov 18, 2026

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: high

no actionable findings

Comment thread packages/node-sdk/src/client.ts Resolved
Comment thread packages/node-sdk/test/client.test.ts Resolved
@roncohen

Copy link
Copy Markdown
Contributor Author

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.

@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 18, 2026

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: high

no actionable findings

Comment thread packages/node-sdk/src/client.ts Resolved
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 18, 2026
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 18, 2026
@roncohen
roncohen added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit 521de2f Nov 18, 2026
9 checks passed
@roncohen
roncohen deleted the feature/node-sdk-v2 branch November 18, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants