Updating objects and arrays

A box can hold any value: a number, a string, an object, an array. Numbers and strings can't be changed in place, only replaced, so a write is always a new value. Objects and arrays can be changed in place, and that's where it goes wrong: a box only knows about writes to .value, and a change made inside the object it already holds never goes through .value. This page shows how to update objects and arrays so the page follows, with weft's set to save the copying.

What counts as a change

A box hears about a change in one way: something assigns to .value. Then it compares the new value with the old using Object.is, and only if they differ does it tell its readers.

That works for this:

position.value = { x: 5, y: 0 }     // a new object: readers update

and not for this:

position.value.x = 5                // reads the box, then changes the object it holds: nobody is toldposition.value = position.value     // the same object again: Object.is says nothing changed

The second line reads position.value and then changes the object it got back. The object did change, but the box wasn't written, so nothing on the page that shows x updates. The third line writes, but writes the very same object, so the box sees no change either.

So treat any object or array in a box as read-only. To change it, make a new one and write that.

Copying objects with spread

To change one field, copy the object with the spread syntax and override that field:

person.value = { ...person.value, first: 'Barbara' }

{ ...person.value } copies every field of the old object into a new one, and first: 'Barbara', written after it, wins. The box gets a new object, so everything that reads it updates.

The first two fields use spread. The third uses set, covered next. Both give the box a new object.

One handler for many fields

With several fields, a handler per field gets repetitive. A computed key, [field], lets one handler update any of them:

import { state } from '@weft-js/core'import { Input } from '@weft-js/warp'type Person = { first: string; last: string; email: string }export function Form() {  const person = state<Person>({ first: 'Barbara', last: 'Hepworth', email: 'bhepworth@sculpture.com' })  const update = (field: keyof Person, value: string) => (person.value = { ...person.value, [field]: value })  return (    <form>      <Input label="First name" value={person.value.first} onInput={e => update('first', e.currentTarget.value)} />      <Input label="Last name" value={person.value.last} onInput={e => update('last', e.currentTarget.value)} />      <Input label="Email" value={person.value.email} onInput={e => update('email', e.currentTarget.value)} />    </form>  )}

set: change a copy

Spelling out the spread every time is noisy, and for arrays the spread forms can get long. Every box has a set method that does the copy for you:

person.set(draft => {  draft.first = 'Barbara'})

set makes a copy of the current value, hands it to your function as draft, and writes the copy back to the box when your function returns. You change the draft as if mutating were allowed, because it's a fresh object nobody else holds.

It's exactly the same as writing the spread yourself:

person.set(d => { d.first = 'Barbara' })               // these twoperson.value = { ...person.value, first: 'Barbara' }   // do the same thing

For an array, the draft is a copy of the array, so the array methods that mutate are fine on it:

todos.set(d => { d.push({ id: 4, title: 'Wash up', done: false }) })todos.set(d => { d.sort((a, b) => a.title.localeCompare(b.title)) })

React developers may know Immer, which tracks changes at any depth with a proxy. weft's set is deliberately smaller: a one-level copy, with no proxy and nothing to install. For the deeper levels, copy what you change.

Updating a nested object

Objects inside objects need a copy at each level you change. Here a piece of art holds an artist, and the city is inside the artist:

piece.value = {  ...piece.value,                                     // copy the piece  artist: { ...piece.value.artist, city: 'Paris' },   // with a copy of the artist, with a new city}

Two spreads, because two objects change: the artist gets a new city, and the piece gets a new artist. The title isn't copied in any meaningful sense: the new piece points at the same string, which is fine, since strings can't change.

With set, the top level is copied for you, and you replace the nested object yourself:

piece.set(d => { d.artist = { ...d.artist, city: 'Paris' } })

Updating arrays

Arrays work the same way: give the box a new array. JavaScript has methods for both styles, so pick the ones that return a new array:

Inside a set draft, the left column is fine: the draft is already a copy. On .value, use the right column.

The next three steps build a todo list, one operation at a time.

Adding an item

Spread the old array into a new one with the item at the end:

todos.value = [...todos.value, { id: nextId++, title: draft.value, done: false }]

Put the new item first, [item, ...todos.value], to add at the start. To insert in the middle, slice around the place:

const at = 1todos.value = [...todos.value.slice(0, at), item, ...todos.value.slice(at)]

Removing an item

filter makes a new array of the items that pass a test. To remove one todo, keep every todo that isn't it:

const remove = (id: number) => (todos.value = todos.value.filter(t => t.id !== id))

Changing an item

To change one item, map over the array and return a new object for the item you're changing and the same object for every other:

const toggle = (id: number) => (todos.value = todos.value.map(t => (t.id === id ? { ...t, done: !t.done } : t)))

Returning t unchanged for the other items matters. The list matches rows by key, and a row whose item is the same object has nothing to do. Ticking one todo updates one row.

Sorting and reversing

sort and reverse change the array they're called on. Copy first:

const sorted = [...todos.value].sort((a, b) => a.title.localeCompare(b.title))todos.value = sorted

or let set copy:

todos.set(d => { d.reverse() })

If you only need a sorted view and the original order should stay, don't write it back at all. Make it a derived:

const byTitle = derived(() => [...todos.value].sort((a, b) => a.title.localeCompare(b.title)))

Reading one entry of a big object

When a box holds a record keyed by id, such as stock levels or cart lines, every reader of box.value[id] depends on the whole record. Change one entry and every reader re-runs. box.get(id) reads one entry instead, and re-runs only when that entry is a new value:

{stock.get(fruit)}          // re-runs when stock[fruit] changes{stock.value[fruit]}        // re-runs when anything in stock changes

The updates are the same as on this page: stock.set(d => { d[fruit] = (d[fruit] ?? 0) + 1 }). Each entry is compared with Object.is, so this is another place where replacing beats mutating. Keyed state and entries covers get in full, with the W017 warning that suggests it.

Recap

• A box only hears writes to .value, and compares with Object.is. Changing an object it holds is invisible.
• Treat objects and arrays in boxes as read-only: make a new one and write it.
• { ...obj, field: value } copies an object with one field changed. Copy each level you change.
• box.set(draft => …) copies one level for you and writes the copy. Replace nested objects you change inside it.
• For arrays: spread to add, filter to remove, map to change, copy before sort or reverse.
• When changing one item, return the same object for every other item, so only one row updates (W014).
• box.get(key) reads one entry of a record, and re-runs only when that entry changes.

Try it