Skip to content
Source
Sign inSign up
TanStack/form

fix(form-core): support value types with a custom equals() method in deep equality #2261

OpenFrancoKaddour(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromrefs/pull/2261/headopened

Closes #2195

Problem

evaluate (the deep-equality helper used for dirty-checking) reports two equal value-type instances as unequal. Value types like Temporal.PlainDate, Luxon DateTime, etc. expose their state through private fields/getters, so they have no own enumerable keys and a non-plain prototype — which hits the no-enumerable-keys guard added in #2140 and returns false. A field backed by such a value is then considered dirty even after it's reset to its original value.

Fix

Before that guard, delegate to a custom equals() method when both operands share a constructor that exposes one. This covers Temporal types, Luxon DateTime, Immutable collections, and any value type following the equals() convention, while leaving plain objects/arrays and the existing Date/Map/Set cases untouched.

Tests

Added a form-core unit test using a value type with a private field and an equals() method (mirroring Temporal's shape — no own enumerable keys). Reverting the fix fails it; the full form-core suite passes, plus typecheck and lint.

Summary by CodeRabbit

  • Bug Fixes
    • Improved form value comparisons for objects with custom equals() methods.
    • Added support for value types such as Temporal and Luxon DateTime instances, including objects with private state.
    • Ensured equal instances compare correctly while differing instances remain distinct.
    1. Review Change Stack

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro Plus

      Run ID: 364ea4e4-49c0-4609-a420-4ee4bf3e58c2

      📥 Commits

      Reviewing files that changed from the base of the PR and between 7ed7642626cc92c966801a4a252457fec3ed87d3 and c424ccaea39bd4b1c72057bea351e5f268c45154.

      📒 Files selected for processing (2)
      • packages/form-core/src/utils.ts
      • packages/form-core/tests/utils.spec.ts
      🚧 Files skipped from review as they are similar to previous changes (2)
      • packages/form-core/src/utils.ts
      • packages/form-core/tests/utils.spec.ts

      📝 Walkthrough

      Walkthrough

      evaluate now uses callable equals() methods when both objects share a constructor. Tests cover equal and different PlainDate instances and one-sided equals() properties. A patch changeset documents support for custom value types.

      Changes

      Custom equality support

      Layer / File(s)Summary
      Custom equality evaluation
      packages/form-core/src/utils.ts, packages/form-core/tests/utils.spec.ts, .changeset/evaluate-custom-equals.md
      evaluate invokes a callable equals() method before enumerable-key comparison when constructors match. Tests cover matching, nonmatching, and one-sided equals() cases. The changeset documents the patch release.

      Estimated code review effort: 2 (Simple) | ~10 minutes

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely describes the main change: support for custom equals methods in form-core deep equality.
      Description check✅ PassedThe description explains the problem, fix, tests, and linked issue, but omits the template checklist and release-impact sections.
      Linked Issues check✅ PassedThe implementation and tests satisfy issue #2195 by using equals() for same-constructor value types, including Temporal-like instances.
      Out of Scope Changes check✅ PassedThe changeset, implementation, and regression tests are directly related to the linked issue and stated pull request objectives.
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. Actionable comments posted: 1

      🤖 Prompt for all review comments with AI agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      Inline comments:
      In `@packages/form-core/src/utils.ts`:
      - Around line 522-528: Update the constructor-based equality branch in evaluate
      to require both objA.equals and objB.equals to be callable before delegating to
      objA.equals(objB). Add a test in utils.spec.ts covering an object with equals()
      compared against an object without it, asserting they are not considered equal.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro Plus

      Run ID: 4939f6b5-c10a-44c7-8ff0-7d0e3d405dff

      📥 Commits

      Reviewing files that changed from the base of the PR and between 5d1128141a705ebb24ade1275b3117bb4c8b1bdc and 7ed7642626cc92c966801a4a252457fec3ed87d3.

      📒 Files selected for processing (3)
      • .changeset/evaluate-custom-equals.md
      • packages/form-core/src/utils.ts
      • packages/form-core/tests/utils.spec.ts
      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    3. View your CI Pipeline Execution ↗ for commit c424ccaea39bd4b1c72057bea351e5f268c45154

      CommandStatusDurationResult
      nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded3m 24sView ↗
      nx run-many --target=build --exclude=examples/**✅ Succeeded38sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-08-08 08:13:39 UTC

    4. More templates

      @tanstack/angular-form

      npm i https://pkg.pr.new/@tanstack/angular-form@2261

      @tanstack/form-core

      npm i https://pkg.pr.new/@tanstack/form-core@2261

      @tanstack/form-devtools

      npm i https://pkg.pr.new/@tanstack/form-devtools@2261

      @tanstack/lit-form

      npm i https://pkg.pr.new/@tanstack/lit-form@2261

      @tanstack/preact-form

      npm i https://pkg.pr.new/@tanstack/preact-form@2261

      @tanstack/react-form

      npm i https://pkg.pr.new/@tanstack/react-form@2261

      @tanstack/react-form-devtools

      npm i https://pkg.pr.new/@tanstack/react-form-devtools@2261

      @tanstack/react-form-nextjs

      npm i https://pkg.pr.new/@tanstack/react-form-nextjs@2261

      @tanstack/react-form-remix

      npm i https://pkg.pr.new/@tanstack/react-form-remix@2261

      @tanstack/react-form-start

      npm i https://pkg.pr.new/@tanstack/react-form-start@2261

      @tanstack/solid-form

      npm i https://pkg.pr.new/@tanstack/solid-form@2261

      @tanstack/solid-form-devtools

      npm i https://pkg.pr.new/@tanstack/solid-form-devtools@2261

      @tanstack/svelte-form

      npm i https://pkg.pr.new/@tanstack/svelte-form@2261

      @tanstack/vue-form

      npm i https://pkg.pr.new/@tanstack/vue-form@2261

      commit: c424cca

    5. :warning: Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

      Codecov Report

      :white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 89.79%. Comparing base (6892ed0) to head (c424cca). :warning: Report is 264 commits behind head on main. :exclamation: Your organization needs to install the Codecov GitHub app to enable full functionality.

      Additional details and impacted files
      @@            Coverage Diff             @@
      ##             main    #2261      +/-   ##
      ==========================================
      - Coverage   90.35%   89.79%   -0.56%     
      ==========================================
        Files          38       66      +28     
        Lines        1752     3235    +1483     
        Branches      444      814     +370     
      ==========================================
      + Hits         1583     2905    +1322     
      - Misses        149      296     +147     
      - Partials       20       34      +14     

      :umbrella: View full report in Codecov by Harness. :loudspeaker: Have feedback on the report? Share it here.

      :rocket: New features to boost your workflow:

      • :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
      • :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
  • Pulled the current evaluate() from main to check the guard ordering, since that's what actually determines whether this fixes #2195 or not. The zero-own-keys guard a few lines below (keysA.length === 0 && ... prototype !== Object.prototype) is exactly what was returning false for two equal Temporal/Luxon instances before this patch, they expose state through private fields and getters so Object.keys() is empty on both, and that guard was written assuming empty keys on a non-plain object means "can't compare, treat as unequal." Putting the equals() delegation above that guard is the only place it can go for the fix to matter, since by the time you reach the empty-keys check it's already too late. Confirmed that's where it landed.

    I see CodeRabbit's earlier comment about requiring both objA.equals and objB.equals to be callable before delegating, that's already handled in the version I'm looking at, both are checked with typeof ... === 'function', and there's a dedicated test for the one-sided case now ({ equals: () => true } vs {} in both directions). Good that it's covered both ways since plain objects share the Object constructor, so the constructor check alone wouldn't have caught a lopsided equals.

    Requiring objA.constructor === objB.constructor in addition to both having equals is the right conservative choice, it avoids letting an equals() from one class accidentally get called with an incompatible instance of a different class that happens to also define equals with different semantics.

    The test class using a private field (#iso) rather than a plain property is a good choice too, it's what actually reproduces the "no own enumerable keys" condition instead of just simulating it, so the test would have caught a regression in the old code path honestly rather than by coincidence.

  • Thanks for the careful trace @MILLERMARRU — you're right that the equals() delegation only works above the empty-keys guard, and that requiring both operands' equals plus the matching constructor is what keeps it conservative. Appreciate the second set of eyes.

  • Sign in to join this conversation.