improve store docs #770
improve store docs #770
Conversation
|
|
✅ Deploy Preview for solid-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| }) | ||
|
|
||
| return ( | ||
| <div> | ||
| <h1>Hello, {store.users[0].username}</h1> | ||
| <p>User count: {store.userCount}</p> | ||
| <button onClick={addUser}>Add user</button> | ||
| <button onClick={addUser}>Add user</button> | ||
| </div> | ||
| ) | ||
| } | ||
| ``` | ||
|
|
||
| ## Modifying store values |
There was a problem hiding this comment.
This part has been reorganized to try and provide an overall picture of how updating the store works before diving into the details of all the different possible update methods and utilities, so people have context for what those techniques do and why they're useful.
| ```jsx | ||
| setStore({ from: 1, to: store.length }, "loggedIn", false) | ||
| ``` | ||
| ### Updating multiple elements by index |
There was a problem hiding this comment.
I thought about combining this and the previous section into just "Updating elements by index" and showing both the individual index and array of indices as examples. It seems a little wordy to have two sections for the same basic idea, but they are two different pieces of valid path syntax...
src/routes/concepts/stores.mdx
Outdated
| These functions receive the old value as an argument, allowing you to compute the new value based on the existing one. | ||
| This dynamic approach is particularly useful for complex transformations. | ||
| You can provide an object with `from` and `to` keys to update every element in that range of indices. | ||
| Note that the range is **inclusive** of both `from` and `to`. |
There was a problem hiding this comment.
This API decision surprised me, since most of the JS APIs I can think of are start inclusive, end exclusive, like Array.slice. { from: 3, to: 7 } updates 3, 4, 5, 6, and 7, whereas something like .slice(3, 7) would take 3, 4, 5, and 6.
Does anyone know why this API is the way it is? If so, is it worth explaining in the doc?
| (user) => ({ | ||
| username: "newUsername"; | ||
| location: "newLocation"; | ||
| })); | ||
|
|
||
| // with produce |
There was a problem hiding this comment.
I think something explaining why this utility is better/more flexible/useful in different cases than
(prevUser) => {
const newUser = { ...oldValue }
newUser.username = "newUsername";
newUser.location = "newLocation";
return newValue
}
would be great to have in the doc, but of course I myself have no idea. Is it just a convenience? Does it have something to do with how values nested inside the target are treated?
| `reconcile` will determine the differences between new and existing data and initiate updates only when there are _changed_ values, thereby avoiding unnecessary updates. | ||
| The `reconcile` utility can be useful when you need to merge new data into a store. | ||
| It determines the differences between the existing data and the incoming data and modifies only the _changed_ values, avoiding unnecessary updates. | ||
| In this example, only `'koala'`, the new addition, will cause an update: |
There was a problem hiding this comment.
Does all this boil down to the fact that normally, objects are shallow merged, but reconcile somehow deep merges them?
| const newData = { | ||
| animals: ['cat', 'dog', 'bird', 'gorilla', 'koala'] | ||
| } | ||
| setStore('animals', reconcile(newData)) |
There was a problem hiding this comment.
I know this example is bad because the DOM behaves exactly the same way whether you use reconcile or not in this case. Only koala is added and no other nodes rerender whether you use reconcile or not. You can watch the DOM tree in the devtools on the playground site for confirmation, see https://playground.solidjs.com/anonymous/c37c2d5d-d820-4507-859c-5a19ca73edbf
But I don't know enough to come up with an example that would actually demonstrate the difference.
There was a problem hiding this comment.
@SpencerWhitehead7 I modified your example a little to make it actually show the difference. Since solid compares the values it doesn't re-execute the original items when switching to the new string array because the values match, but by switching to objects which will have different refs it will re-execute unless you use reconcile. You have to use a console log to see that it re-executes because the result is the same either way https://playground.solidjs.com/anonymous/4ee128da-0098-4b3f-84ea-da447f94b81e
There was a problem hiding this comment.
Ah, thank you so much, I checked it out and I can see it working.
If this PR/issue is ever reopened I will definitely update it with your example.
| ``` | ||
|
|
||
| To learn more about how to use Stores in practice, visit the [guide on complex state management](/guides/complex-state-management). | ||
| To learn more about how to use Stores in practice, visit the [complex state management guide](/guides/complex-state-management). |
There was a problem hiding this comment.
I read this page too and a lot of the content there is duplicative of the content on this page. I think some of the examples there might also be a little misleading because they demonstrate synchronizing state instead of deriving it, which I understand is not recommended in Solid.
If this PR goes OK, I'd love to try something similar (maybe less ambitious) for that page.
SpencerWhitehead7
force-pushed
the
store-page-reorganization-and-editing
branch
from
3aa18cc to
d8ecafa
Compare
|
Thank you for your pull request! We appreciate your effort and contributions to the project. However, as mentioned in our contributor guidelines we ask that contributors file an issue before submitting a PR. This helps us discuss the proposed changes and ensure they align with the project’s direction. Please file an issue so we can have a conversation about your suggestions. For now, I’ll close this PR, but we look forward to your ideas and collaborating on them. Thank you again! |
Thank you, issue created #774 ! |
This is an, um, unsolicited rewrite of the
storedocs page.I wanted to just copy edit some things and fix a couple factual inaccuracies, but it rapidly spiraled out of control. I'm sorry it's so long, but please read it with an open mind.
I have some self review comments on it and I am happy to talk about any of the editorial choices or changes in content.