Support immutable Models

[jthegedus]

I have been using Immer to manage my data as immutable structures. It achieves this by using Object.freeze(someObject) internally, with a specific API to mutate these Immer-tracked objects. This is a more robust solution than relying on TypeScript types like readonly as attempted modification to a frozen object throws a JS runtime error (Uncaught TypeError: Cannot assign to read only property of 'value' of object '#<Object>').

I have noticed that the elmish update will replace the Model object and thus remove the frozen object that was previously used. I believe this is the place where this happens:

react-elmish/src/ElmComponent.ts

Lines 115 to 118 in fe4193f

	if (modelHasChanged(this.currentModel, { ...deferredModel, ...model })) {
	this.currentModel = { ...this.currentModel, ...deferredModel, ...model };
	modified = true;
	}

It may be possible to achieve what I want with the current APIs, but I cannot figure it out myself if there is.

Reproduction

(click to expand)

// counter.model.ts
import {produce} from "immer";
import type {InitResult,UpdateReturnType} from "react-elmish";

type Message = {name:increment}|{name:decrement};
interface Model = {count:number;}; // using `readonly count: number` only errors in editor or build time thanks to TSC
interface Props = {initialCount: number;};

function init(props: Props): InitResult<Model,Message> {
  return [produce({count:props.initialCount}, (draft) => { return draft; })]; // this returns the immutable version of the provided model.
}

function update(mode: Model, msg: Message, props: Props): UpdateReturnType<Model, Message> {
  console.log({ updateModelFrozen: Object.isFrozen(model)}); // is always false;
  switch(msg.name) {
    case "increment": { return [produce(model, (draft) => {draft.count +=1})]; }
    case "decrement": { return [produce(model, (draft) => {draft.count -=1})]; }
  }
}

export {init, update, Msg, type Model, type Props};

// counter.tsx
import {useElmish} from "react-elmish";
import {type Props, init, update} from "./counter.model.ts";

function Counter(props: Props) {
  const [model, dispatch] = useElmish({props,init,update,name:"counter"});
  
  console.log({frozenModel: Object.isFrozen(model)}); // this will initially be true until a Message is dispatched and the update function runs.

  return (
    <div>
      <button type="button" onClick={() => dispatch({name: "increment"})}>+</button>
      <button type="button" onClick={() => dispatch({name: "decrement"})}>-</button>
      <p>count: {model.count}</p>
      <button type="button" onClick={() => {
        model.count = 99; // This errors with TSC but is valid JS unless the object is frozen, in which case it throws a runtime error.
      }}>
        set outside of elmish update
      </button>
    </div>
  );
}

export {Counter};

// App.tsx - use whatever bundler/tooling React index/entrypoint
import {Counter} from "counter";

function App() {
  return (
    <div>
      <Counter initialCount={10} />
    </div>
  );
}

NOTE: I haven't tried to use the Immer produce() function on the UpdateReturnType array tuple, though my assumption would be that it would still produce a new tuple and the Immer object lineage would be lost.

Proposed Solutions

IdeallY I would like to see immutability become the default behaviour. However that would be a big change. A new API (react-elmish/immutable or something) that had an immutable implementation would be ideal. It could either:

• internally use Immer (or similar alternative, or manually implement Object.freeze()) to enforce immutability of the Model object and provide a "draftable" version of the Model in the Update function.
• provide some API for allowing users to specify how they wish to manage the freezing/unfreezing of the Model. Perhaps similar to the logger API.

Each has their pros and cons.

I would opt for a library with immutability by default, especially since those adopting a library like this are trying to get a handle on their data's mutability through the TEA model, but in a non-statically typed environment.

Thanks for the React v19 peerDep update.

[jthegedus]

I have hacked together a useImmutableElmish() hook for use in the meantime. It simply wraps useElmish() and returns a frozen model. This allows me to write tests ensuring that models cannot be modified erroneously once returned by the use hook in components. It does nothing for enforcing immutability within the model implementation or testing.

// utilities/immutable-react-elmish.tsx
import {produce} from "immer";
import {useElmish} from "react-elmish";

function useImmutableElmish(options) {
	const [model, dispatch] = useElmish(options);
	const immutableModel = produce(model, (draft) => {
		return draft;
	});

	return [immutableModel, dispatch];
}

export { useImmutableElmish };

A set of APIs in this library with immutable implementations would still be preferred. The test APIs and update are still all opt-in. Even if you do try to use immutability libs like Immer in the update function, as I did, the desired behaviour is unknowingly circumvented.

[atheck]

Hi, this is a good idea. I would also prefer to have an immutable model by default. So maybe I'll introduce a breaking change and provide the mutable API when importing from react-elmish/mutable. Or I add a new configuration option. But I will have to look into this closer first.

Using "immer" would be handy, but on the other side I'd like to keep zero dependencies.

I will release this as beta versions and keep you updated, so you can try this early on and provide feedback.

[jthegedus]

I also like zero dependencies. I only really want the Model object to be frozen in any context except in update/updateMap. So to enforce this, I imagine this library would have to provide an update/updateMap function instead of just the TS types for a user-defined function. And somehow enforce this as the only valid update to pass to useElmish... 🤷

Immutable libraries, while having many more features, often compare their performance against a "vanilla" solution, so it is likely they document common pitfalls of a "vanilla" implementation. Perhaps worth a read of their vanilla comparison code:

• Mutative: https://github.com/unadlib/mutative
• Immer: https://github.com/immerjs/immer

Redux Toolkit uses Immer and people are complaining about it's performance, as Immer has slowed over releases+time, so immutable by default with a separate specific mutable API is probably worth the extra effort.

[atheck]

Thank you for your feedback.

I could imagine something like this in an update function:

return [(draft) => {
  draft.count++;
}, ...];

So instead of returning a partial model, the only valid value is a produce-like function. Everywhere else the model is immutable (and also use the type Immutable<Model>).

Because this is a big change, I think it would be better to follow your suggestion and provide this via a "react-elmish/immutable" import.

For a proof-of-concept I will use "immer" as dependency for now. This way I can replace it anytime with an alternative package or my own implementation.

[atheck]

Hi @jthegedus, I released version 10.0.0-beta.2 including immutable versions of useElmish and ElmComponent. To use them, import everything from "react-elmish/immutable".

This is a new major release, because I changed the import path of the testing API from "react-elmish/dist/Testing" to "react-elmish/testing".

Testing of the immutable APIs is not supported in this beta release.

Feel free to test it and provide feedback.

[jthegedus]

I will give it a try, thank you!

[jthegedus]

It works as expected, thanks! Testing funcs would be welcome 🙇

It seems since the update() func provides the draft object, the user doesn't need to utilise the Model param. Would it make sense to remove that or are there other reasons I am not thinking or aware of for it to persist?

[atheck]

Very good. Test functionalities are coming soon and will be available via import from "react-elmish/immutable/testing".

Indeed I'm contemplating changing the update function signature again. The update function itself can be a draft function. So, the model parameter would be of type Draft<Model>. Then, we would not need a draft function as return value. But I'm not completly sure about this yet.

[github-actions]

🎉 This issue has been resolved in version 10.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀