feat(codec): Dual marshal preserve RawJSON

[Cobalt0s]

Description

This PR introduces codec.RawJSON[T any].

Key changes

• codec.RawJSON[T any]
  A generic wrapper for JSON marshalling/unmarshalling that preserves data in two forms:
  • the original, unmodified map[string]any
  • the parsed concrete type T
    This enables lossless handling of responses. It’s particularly useful when multiple representations are possible—for example, when parsing provider responses where T represents a success model, but failures require access to the raw payload (e.g. to construct common.NewHTTPError).

• JSON comparison utilities
  Adds mockutils.JSONComparator, a lightweight helper for comparing Go values against JSON string representations (commonly used in tests).

  • Equals compares single values
  • ListsEqual compares slices

  This simplifies assertions where expected data is expressed as JSON literals.

Live Tests

[Cobalt0s]

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

• feat(codec): Dual marshal preserve RawJSON #2276 : 2 dependent PRs (#2277 , #2945 ) 👈 (View in Graphite)
• feat(testroutines): Subscribe and ReadByIds #3009 : 1 other dependent PR (#3014 )
• feat(subscriptions): Scripts for consuming events #2948
• feat(components): Subscription interfaces #2876
• main

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

[anushat05]

The build is failing for this should we address that first?

[Cobalt0s]

@anushat05 The original reason to include the utility is gone with Salesforce using new create method. However, the utility could still come in handy. I think it should replace some of the jsonquery package in favour of concrete Golang data types and still have the raw map[string]any alongside. The concrete data type doesn't have to be exhaustive. All the "extra" fields not unmarshalled into concrete golang struct will still be in Raw.

[Cobalt0s]

@anushat05 the PR is still relevant and was useful in the Microsoft Susbcribe implementation.

[Cobalt0s]

@jlimatampersand
The util is already used by Salesforce it enhances it a bit.

codec.RawJSON[YourType] allows to deal with Raw representation of data map[string]any alongside the concrete Struct Type.

• Conrete Type allows easy access to fields.
• The Raw map will always contain all data so nothing is "wasted". Useful when you want the original data before Marshalling happened into the struct.

[jlimatampersand]

I see what this util is trying to achieve, but is this a necessary util?

I guess the win is there when you edit records in such a way that you are strictly adding items and fields, but if this wrapper is used when removing or deleting for a purpose, this is going to be very buggy and will introduce friction.

You will understand this utility, but many others will easily use it incorrectly unless they actually read this logic fully themselves, which will not be the case. Most likeley 90% of the contributors won't read the description as carefully as the logic itself.

[jlimatampersand]

Convince me or fix the logic so I can approve. I am open to suggestions.

[Cobalt0s]

I understand that it can be misused. Probably it should be more dedicated, or some features stripped away towards more immutable design. I started small, then got some code generated and thought it fits the concept.

(1)
For Microsoft Batch I need Dual Unmarshal -- therefore, it will be part of that Microsoft impl and not a utility:

Usage:

(2)
I changed the code and added tests for DecoratedRecord which has only one responsibility and that won't be growing.

Summary:

• The existing DecoratedRecord is used by Salesforce. The mock test validates that Salesforce write operation sends correct payload..
• The "DecoratedRecord" is doing only one thing -- enhancing any map with "sidecar data" to produce JSON for payload:
  • map[string]any + your extension,decoration struct => JSON
    Example:

PS: There are many write payloads that are "decorated", so this idea of DecoratedRecord makes payload construction automatic without any map[string]any assertions, key checks, etc -- it just combines 2 JSON representations. Let me know if it is an overkill 😅 .