test: add local patch application for verification

[ricokahler]

This PR enhances the test suite by introducing a local patch application mechanism. This allows us to verify the correctness of the generated patches by applying them to the source document and comparing the result against the expected target document, all without needing to hit a live Sanity backend.

Key Changes:

• New Test Helpers:
  • test/helpers/patchOperations.ts:
    • This new file contains a set of functions (set, unset, insert, diffMatchPatch, ifRevisionID) that simulate the application of Sanity patch operations to a JavaScript object.
    • These operations are based on logic adapted from the @sanity/sdk (specifically core/src/document/patchOperations.ts) to ensure consistency with how Sanity itself processes patches.
    • Includes jsonMatch and related path parsing utilities (also adapted from @sanity/sdk) to correctly target values within the document based on Sanity path expressions.
    • The KeyedSanityObject type and isKeyedObject utility were moved from src/diffPatch.ts to src/paths.ts to be accessible by these helpers and the main library code.
  • test/helpers/applyPatches.ts:
    • Introduces an applyPatches(source: DocumentStub, patches: SanityPatchMutation[]): DocumentStub helper function.
    • This function iterates through an array of SanityPatchMutation objects and uses the operations from patchOperations.ts to apply them sequentially to a source document.
• Test Suite Integration:
  • All existing unit tests (*.test.ts files) have been updated to use applyPatches.
  • After generating patches with diffPatch, the tests now also call expect(applyPatches(source, patches)).toEqual(target) to ensure the patches transform the source into the target correctly.
• Integration Test Modification:
  • The integration.test.ts file, which previously relied solely on dryRun commits to a Sanity backend, can now also leverage the local applyPatches if Sanity client configuration is missing. This makes the integration tests more robust and runnable in environments without backend access.
• Fixture Update:
  • The test/fixtures/set-and-unset.ts fixture (b.arr) was updated to use null instead of undefined to align with the new undefined-to-null conversion behavior and ensure tests pass with the local patch application.

Rationale:

• Improved Test Confidence: Directly verifying that the generated patches produce the expected outcome locally provides a much stronger guarantee of correctness than just snapshotting the patches themselves.
• Faster Feedback Loop: Local patch application is significantly faster than relying on dryRun commits to a backend, speeding up the test suite.
• Offline Testing: Enables more comprehensive testing even without a configured Sanity client, which is beneficial for CI environments and local development.
• Foundation for Future Testing: These helpers provide a solid base for writing more complex tests involving patch application and merging.

Note: While this PR adds significant value to the test suite, the introduction of the patch application logic (adapted from the SDK) does add a considerable amount of code to the test helpers. If this is deemed too complex or adds too much maintenance overhead for a testing utility within this specific library, this PR could potentially be omitted, and we could continue to rely on integration tests with a backend for end-to-end verification. However, the benefits of local verification are substantial for development speed and confidence.

[ricokahler]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• test: add local patch application for verification #40 👈 (View in Graphite)
• refactor: preserve order in patch serialization #42 : 1 other dependent PR (#41 )
• feat!: replace diffItem with diffValue #39
• feat!: remove undefined-to-null conversion warnings and simplify internal APIs #38
• refactor: simplify array unset logic by removing revision lock check #37
• feat!: replace configurable DMP with perf-based heuristics #36
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[rexxars]

I feel like this is testing the SDK patch application more than this module 😅
Can we make the integration suite run both the SDK tests and the actual API integration tests? I feel strongly that we should be testing both

[ricokahler]

I feel like this is testing the SDK patch application more than this module 😅

you know, i caught a few bugs while i threw this in there and there was some motivation to see what our compliance is like 😅. in the future, i'd like to move this file into its own repo (maybe @sanity/patch-operations?) and then have integration tests similar to how they're set up here. for now, i think i'll drop this PR and remove the code. will remove this from the stack and restack.