Merge PR #45: Add updateOnPristine option

[erikras-dinesh-agent]

This PR resolves the merge conflicts in #45 and brings the updateOnPristine feature to the current TypeScript codebase.

Summary

Adds an optional updateOnPristine flag to the Calculation type (defaults to true for backward compatibility). When set to false, calculations will not run on pristine (initial/unchanged) field values.

Problem Solved

Fixes data corruption issue when loading form data from a database - calculations would overwrite DB values on initial render. See #26 for detailed discussion.

Changes

• src/decorator.ts: Added pristine check logic with updateOnPristine parameter
• src/types.ts: Added updateOnPristine?: boolean to Calculation type
• src/index.d.ts: Added updateOnPristine?: boolean to type definition
• src/types.js.flow: Removed (replaced by TypeScript in v2.0.0)

Backward Compatibility

✅ No breaking changes - updateOnPristine defaults to true, preserving current behavior.

Example Usage

createDecorator({
  field: 'foo',
  updateOnPristine: false,  // Don't run on initial values
  updates: {
    bar: (fooValue) => `${fooValue}bar`
  }
})

Testing

• Existing tests should pass (validates backward compatibility)
• Original PR Adds Option To Ignore Updates On InitialValues #45 included comprehensive tests for the feature

Related

• Closes Adds Option To Ignore Updates On InitialValues #45
• Addresses Update gets triggered on render with initialValues #26

Author

Merge conflicts resolved by @erikras-dinesh-agent
Original feature by community contributor (PR #45, Dec 2020)

Summary by CodeRabbit

• New Features

  • Added an optional updateOnPristine setting for calculations to control whether derived updates run on initial pristine fields (defaults to true for compatibility).

• Tests

  • Added tests verifying updateOnPristine behavior across single fields, arrays of fields, and regex field matchers.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an optional updateOnPristine flag to Calculation and modifies decorator logic so updates can be skipped for pristine initial field values when updateOnPristine is false. New tests verify behavior for string, array, and RegExp field matchers.

Changes

Cohort / File(s)	Summary
Type Definitions src/index.d.ts, src/types.ts	Added optional updateOnPristine?: boolean to the Calculation type to allow per-calculation control over whether updates run for pristine initial values.
Decorator Implementation src/decorator.ts	Gated update execution with updateOnPristine — for string, array, and RegExp field matchers, updates only run if updateOnPristine is true or the matched field(s) are not pristine. Adjusted calculation iteration signature to destructure updateOnPristine.
Test Coverage src/decorator.test.ts	Added three tests asserting that when updateOnPristine: false, initial pristine values do not trigger updates. Tests cover single field ('foo'), array matcher, and RegExp matcher (/^foo$/).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble code where changes lie,
A flag to skip the newborn try,
Pristine fields rest, untouched at start,
Updates wait till they play their part,
Hoppity hops—stable forms, smart. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and concisely describes the main change: adding the updateOnPristine option to the codebase.
Linked Issues check	✅ Passed	The PR implements all coding requirements from issue #45: adds optional updateOnPristine property to Calculation type, implements pristine field checking in decorator logic, and maintains backward compatibility by defaulting to true.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the updateOnPristine feature across type definitions and decorator logic, with new tests validating the feature's behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch merge-pr45-updateOnPristine

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@src/decorator.test.ts`:
- Around line 53-98: Add a new spec mirroring the existing "array of field
names" test but using a regex for the field matcher: call createForm and
createDecorator with field: /^foo$/ and updateOnPristine: false,
subscribe/register the same spies (spy, foo, bar), assert the initial
subscription is called once with initialValues unchanged, then call
form.change('foo', 'baz') and assert the decorator computes bar to 'bazbar' and
subscription calls reflect the intermediate and final values; place this test
alongside the existing it(...) block and use the same helpers createForm,
createDecorator, form.registerField and form.change to match the pattern in the
diff.

In `@src/decorator.ts`:
- Around line 62-68: Replace the bitwise NOT trick in the matches initializer
with a clearer existence check: in the Array.isArray(field) branch (the matches
function defined using field and name), change the "~field.indexOf(name)"
expression to a readable check such as "field.indexOf(name) !== -1" or use
"field.includes(name)" for exact string matches, keeping the existing
findIndex(RegExp) fallback intact so RegExp elements are still tested via f
instanceof RegExp and (f as RegExp).test(name).

In `@src/types.ts`:
- Around line 14-19: The Calculation type's property order is inconsistent with
src/index.d.ts; update the Calculation type definition so properties appear in
the same order as in index.d.ts: field, updates, updateOnPristine, isEqual
(preserve existing types and optionality for isEqual and updateOnPristine) to
keep type declarations consistent across the codebase.

[erikras-dinesh-agent]

✅ All CodeRabbit comments addressed

Per the updated review policy, I've addressed all three requested changes:

1. src/types.ts (line 14-19): ✅ Reordered Calculation properties to match index.d.ts order: field, updates, updateOnPristine, isEqual

2. src/decorator.ts (line 62-68): ✅ Replaced bitwise NOT trick (~field.indexOf(name)) with clearer check (field.indexOf(name) !== -1)

3. src/decorator.test.ts (line 53-98): ✅ Added regex test case for updateOnPristine: false using field: /^foo$/ matcher

Changes pushed to merge-pr45-updateOnPristine branch. Waiting for CI to re-run.