Svelte 5: decide on behaviour of `$state.frozen`

[Rich-Harris]

Describe the problem

The discussion in #12413 revealed some differences of opinion around $state.frozen. As of that PR, it will error if passed existing reactive state, which eliminates one source of confusion. But others remain:

• in dev, the input will be frozen with Object.freeze, but in prod it won't (for perf reasons). As such, the name is a bit of a misnomer
• Object.freeze is so-called for a reason — it freezes the object passed in; it has a side-effect. frozen implies that it returns a frozen object, rather than freezing its argument as a side-effect. Which isn't to say that $state.freeze would be a better name, since that implies that it freezes existing state proxies
• It's shallow — it doesn't affect state inside the object, including in classes

Describe the proposed solution

Together, these observations suggest (to me at least) we should change the name and the behaviour. Taking a cue from MobX, perhaps $state.ref would be a better name. $state.raw is another option. Doubtless there are others.

This would have similar semantics to $state.frozen today — in other words only reassigning (not mutating) will cause updates (or in implementation terms: it creates a source but not a proxy) — but without the dev-time Object.freeze.

Of course, by doing this we lose the opportunity to tell people that they're incorrectly mutating an object. If we want to keep that but also have consistency between dev and prod, then the alternative is to always use Object.freeze, perf implications be damned.

Importance

nice to have

[brunnerh]

The Object.freeze call struck me as a bit odd from the start. If someone really wants their objects frozen, that can always be done manually. Types can also be an avenue for indicating that things are read-only.

ref sounds a bit unspecific and could maybe be misinterpreted as creating a { value } box.

[RyanYANG52]

I would suggest keep this api as close as Svelte 3/4's behaviour (no proxy only source), and not treat dev and prod differently (as @brunnerh suggested leave freeze to user land). It's a perf enhance / advanced api, user who pick this over $state() normally would read the doc and know what they were doing. Plus, for user who used Svelte 3/4 would be easy to understand and easy to migrate their existing code;

In my current codebase, I use a lot of object as a complex immutable value type, for instance {text: string, value/action: T, class?: string} as options which would never change separately

[dummdidumm]

My thoughts:

• remove freeze in dev
• remove the symbol and any checks. In other words, nothing is done to the object (but you're also responsible for not accidentally mixing it with proxied state)
• possibly/maybe: make foo = foo always trigger an update, not just when the values aren't equal. Satisfies demands of people who want to wrap some third party stuff and want to trigger reruns by doing this, and also reflects the "your on your own"-style of this feature
• name it $state.raw, as in "nothing is done with this" (frozen doesn't reflect that anymore, ref is too similar to other similar-but-different concepts in other frameworks)

[trueadm]

remove the symbol and any checks. In other words, nothing is done to the object (but you're also responsible for not accidentally mixing it with proxied state)

I don't think we can do that. If you remember that's what original $state.raw did in my PR that I never landed – because the chances of accidentally proxying it are huge. For example you create some frozen state and then push it into an array, or assigning a property on some object to be the value.

[trueadm]

Personally, I'm in favour of keeping $state.frozen as is and separately introducing $state.raw and seeing how that goes.

[Rich-Harris]

That feels like the worst of all options honestly — extra surface area, and it would be very hard to articulate when to use which.

To the best of my understand/recollection (which may not be fully accurate) the reason we added the symbol was to deal with this scenario:

let object = $state.frozen({ x: 1 });
let array = $state([object]); // oops, `array[0]` is now a proxy, we didn't want that

Svelte doesn't proxify objects with the symbol, meaning $state.frozen avoids that issue. But maybe we were thinking about this backwards. Nothing about object itself changes when array[0] is proxified; that array[0].x is reactive is a fact about array, not a fact about object. So we should adjust the array declaration accordingly.

Currently though, we don't have a way to express 'this thing is reactive — we can do array.push(...) and so on — but its children shouldn't inherit that reactiveness'. That's the missing piece that led us down this path. So here's what I propose:

let object = $state.raw({ x: 1 }); // reassigning (but not mutating) `object` will cause updates
let array = $state.shallow([object]); // we can push/pop/etc, but the members of the array are untouched

// or...
let array = $state.shallow([{ x: 1 }]);

array[0].x += 1; // triggers no updates (should probably yield a warning, on a best-effort basis)

[ryanatkn]

This is maybe offtopic and I'm not requesting the rationale, just offering a thought expressed by others in various forms - is deep reactivity the best default? With limited experience I think I'd prefer $state() proxying nothing as the default raw form, and then also having $state.shallow() and $state.deep(), if it makes sense.

It would feel like less of a surprise/risk if .deep() is visible. The caveats around deep state, including the boundary at reactive builtin collections, make deep state uncommon in my current patterns, but I'm still adapting to thinking in those terms. (I was using immutable: true)

There's also the idea switching to the less elegant SvelteArray and object/record that could be returned by runes to make accidental mutation mistakes less of a problem via types.

[dummdidumm]

$state.shallow sounds a bit like scenario-solving to me - I imagine it only really being useful for arrays, because you don't want to lose the "push/pop/etc triggers reactivity" niceness. For objects it's less useful, and it's also very inflexible because what if I want reactivity two levels deep instead?

If it's really "only" about arrays, there are other solutions I think would be better:

• $state.raw gets some tiny additional code that's like "if this is an array, patch the mutating methods to trigger reactivity"
• import { SvelteArray } from 'svelte/reactivity'

[peterreeves]

...what if I want reactivity two levels deep instead?

Wouldn't that just be this?

let position = { x: 1, y: 1 };
let transform = $state.shallow({ position });
let obj = $state.shallow({ transform });

[Rich-Harris]

Gah, GitHub didn't show me more recent replies. Editing:

is deep reactivity the best default?

There's definitely room for debate on this topic, but so far when we've had that discussion we've landed on deep reactivity being the right default — the idea being that by using the $state rune you're already declaring your intent. It's a more robust version of how Svelte 4 already works (foo.bar += 1 invalidating foo), and mirrors the choice made by other systems (Vue's ref, MobX's observable).

I suspect that for many people, the question arises precisely because we don't have an opt-out mechanism at present. It's clearly a gap in the API (and one that the aforementioned systems cover with shallowRef and observable.shallow respectively).

Wouldn't that just be this?

It's definitely solvable, yeah. But I think 'I want reactivity two levels deep' is a real edge case anyway

[peterreeves]

Thinking about it more, do you need a $state.shallow(...) rune? Could you just get away with only a $state.raw(...) and prevent it's contents from being proxied if it was included inside another $state?
e.g.

let obj = $state({
    transform: {
        position: $state.raw({
            x: 0,
        })
    },
    material: {
        colour: {
            r: 1,
        },
    }
});

// ...elsewhere
obj.transform.position.x = 2; // Does NOT trigger reactivity, as reactivity "stops" at `position`
obj.material.colour.r = 0.5; // Does trigger reactivity

If so that seems like a pretty clear way to carve up which bits of an object should be reactive, and which bits shouldn't. Just wrap things you don't want to be reactive in $state.raw(...). If you want it to be immutable, use $state.raw(Object.freeze(...)).

[trueadm]

I'm more leaning towards $state.frozen to be deeply frozen in DEV too. I feel one of the nice things about $state being deeply reactive is that it means that Svelte can track the values of all the nested properties. This enables us to enable future work where we might suspend or fork the current state tree and do nice things with immutability for free. If $state.frozen was deep, then you'd also get this nice guarantee too. However, when I think of $state.raw, it seems that the benefit is that you can now mutate state without it applying to the UI – and this also means that we no longer track these values, meaning the above benefits now are no longer viable to us.

[Rich-Harris]

Could you just get away with only a $state.raw(...) and prevent it's contents from being proxied if it was included inside another $state?

I don't think so. For one thing, you'd need to add a symbol to the position object to create a boundary, which isn't a dealbreaker but is something that would be nice to avoid.

But the larger issue is that you would need to use it on every assignment...

obj.transform = {
  position: $state.raw({
    x: 1
  })
};

...otherwise position would be proxified at that point. To me that feels like an abstraction leak. For what it's worth you can essentially do that today in userland, by virtue of the fact that classes are treated as 'boundaries':

class Raw {
  constructor(properties) {
    Object.assign(this, properties);
  }
}

let obj = $state({
  transform: {
    position: new Raw({
      x: 0,
    })
  },
  material: {
    colour: {
      r: 1,
    },
  }
});

It's also much more annoying to do this...

const swatch = $state([
  $state.raw(createColour('red')),
  $state.raw(createColour('orange')),
  $state.raw(createColour('yellow')),
  $state.raw(createColour('green')),
  $state.raw(createColour('blue')),
  $state.raw(createColour('indigo')),
  $state.raw(createColour('violet'))
]);

...than this:

const swatch = $state.shallow([
  createColour('red'),
  createColour('orange'),
  createColour('yellow'),
  createColour('green'),
  createColour('blue'),
  createColour('indigo'),
  createColour('violet')
]);

I'm more leaning towards $state.frozen to be deeply frozen in DEV too

I thought we were leaning towards getting rid of the dev/prod discrepancy? The main reason to use this thing — whatever form it takes — is that you have a large blob of data that you don't plan to mutate, and so you're opting out of deep anything.

when I think of $state.raw, it seems that the benefit is that you can now mutate state without it applying to the UI

I don't think that's right. You're not declaring something with $state.raw so that you're free to mutate it, you're declaring something with $state.raw because you don't intend to mutate it.