Custom replacer/reviver functions for data serialisation/deserialization

[cairin]

The problem

There are various places that Inertia needs to serialize/deserialize data in order to send it over the network, or save it to history state.

In the latest version (v1.2.0 at the time of writing) Inertia does nothing to data being pushed to state. This has since been improved with the cloneserializable function, but this is unreleased.

For the sake of this discussion I'll reference moneyphp to illustrate my dilemma. This is essentially an immutable value object used to make working with money simpler.

If we return a Money instance from a controller using return Inertia::render('Home', [ 'balance' => Money::ZAR(350) ]);, balance will be serialized as '{"amount":"350","currency":"ZAR"}'.

This works fine, except I now need to convert cents -> whole currency units in javascript. Ideally we would like to have a corresponding immutable money value object to work with in React.

Note: Our Money object in typescript is read only - so works fine with React's reactivity.

The current solution

To have a full end-to-end solution, we need to:

• be able to automatically instantiate a Money object when receiving data from
  the network.
• work with Money objects in Forms.
• correctly store and rehydrate Money objects in history state.

In order to achieve this we currently need to wrap the relevant inertia hooks:

/**
 * Wraps `usePage` to automatically insert a `Money` instance when `\Money\Money` is returned from a controller.
 */
export function useMoneyPage<
  TPageProps extends PageProps = PageProps
>(): Page<TPageProps> {
  const page = usePage<TPageProps>()

  // Recursively parse page props to ensure anything `Money` like gets instantiated as `Money`.
  const deserializedProps = deserialize<TPageProps>(page.props)

  return { ...page, props: deserializedProps } as Page<TPageProps>
}

Similarly, we would need to wrap the useForm and useRemember hooks. However, these two hooks are currently very unwieldy to work with, as the object is deep cloned when adding it to the history state. This makes deserialization more tricky. Although this should be fixed when the cloneserializable is released, as the serialisation will use Money.toJSON().

Proposed improvements

Being able to pass custom replacer/reviver functions to cloneserializable would remove the need to wrap the useForm and useRemember hooks.

const cloneSerializable = <T>(
  obj: T,
  replacer?: Parameters<JSON['stringify']>[1],
  reviver?: Parameters<JSON['parse']>[1]
): T => JSON.parse(JSON.stringify(obj, replacer), reviver)

I'm not sure if this would necessarily fix how usePage props deserialization works, but I assume the same reviver function could be used for that too.

I am happy to try figure it out, and submit a PR. But thought I'd ask here first in case something similar is already in the works for v2 or if it's even likely to be included in Inertia.