docs: add docs on state_unsafe_mutation error

[dummdidumm]

closes #14752

[changeset-bot]

⚠️ No Changeset found

Latest commit: 77434b2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Rich-Harris]

preview: https://svelte-dev-git-preview-svelte-14932-svelte.vercel.app/

this is an automated message

[github-actions]

Playground

pnpm add https://pkg.pr.new/svelte@14932

[Rich-Harris]

I think it would be helpful to use an example where the mutated state is independent of the derived — it's easy to look at the current example and think 'well of course you can't update the thing the result depends on', when actually it's nothing to do with the cyclicality.

I'd guess that most people are encountering a non-cyclical version of this problem (i.e. treating the derived as a convenient place to update some independent state). Ideally the example would reflect real cases — @MathiasWP do you recall what sort of things led to you encountering this error?

[MathiasWP]

I think it would be helpful to use an example where the mutated state is independent of the derived — it's easy to look at the current example and think 'well of course you can't update the thing the result depends on', when actually it's nothing to do with the cyclicality.

I'd guess that most people are encountering a non-cyclical version of this problem (i.e. treating the derived as a convenient place to update some independent state). Ideally the example would reflect real cases — @MathiasWP do you recall what sort of things led to you encountering this error?

I've gone on a scavenge hunt to try and find the code that caused this, but with no luck (it was quite difficult to find in the first place when it happened) :/

[dummdidumm]

In the absence of a better real world example, I'd like to merge this. Any objections?

[MathiasWP]

I've figured out an example of why this happened with us, and essentially it is the same as documented here, but a lot more hidden. We have repositories that fetch external data based on the parameters passed into a get method. Our repositories use a cache-pattern where we check if it has been cached, and if it has been cached then we immediately return the cached state.

It's intuitive to use the repository in a derived method to make it fetch new data when state updates, but one of the services used in the repository may trigger update of a rune in another class, which isn't always that easy to spot. We've managed to fix this case, but it's an example of where it's a little bit hidden that a state rune actually was updated by a method used in a derived rune.

So we've had to figure out why runes and stores behaves different (when it essentially feels like the same thing), which in result has made us scratch our heads when migrating to Svelte 5.