Additional documentation for managing local state

[bignimbus]

Fixes #10176

Checklist:

• If this PR is a new feature, please reference an issue where a consensus about the design was reached (not necessary for small changes)
• Make sure all of the significant new logic is covered by tests

[jerelmiller]

I tend to think of an async read function as something that would return a promise and the wording in the sentence above would lead me to believe I'd see something like an async read(...) in here. Based on this example, it looks like this read function is still synchronous, just with the a side-effect that the storage variable is updated sometime after the first read function is kicked off.

Should this truly be an async function (e.g. async read()), or should we tweak the language above to better reflect the behavior in the example? I'm not sure of the intent on the comment about async reads.

[bignimbus]

Thanks for pointing this out. It looks like an async function would be the ideal outcome of a future feature. This workaround, though, doesn't use a promise. I tried wordsmithing the above a bit. How's this?

diff --git a/docs/source/local-state/managing-state-with-field-policies.mdx b/docs/source/local-state/managing-state-with-field-policies.mdx
index ae6da0682..91131ac08 100644
--- a/docs/source/local-state/managing-state-with-field-policies.mdx
+++ b/docs/source/local-state/managing-state-with-field-policies.mdx
@@ -62,7 +62,7 @@ You can use `read` functions to perform any sort of logic you want, including:
 
 ### Reads are synchronous by design
 
-Many UI frameworks like React (without `Suspense`) have synchronous rendering pipelines so it's important for UI components to have immediate access to any existing data.  So all `read` functions are synchronous, as are the cache's `readQuery` and `readFragment` methods.  It is possible, however, to leverage reactive variables and `options.storage` to roll your own asynchronous `read` function:
+Many UI frameworks like React have synchronous rendering pipelines, therefore it's important for UI components to have immediate access to any existing data.  This is why all `read` functions are synchronous, as are the cache's `readQuery` and `readFragment` methods.  It is possible, however, to leverage reactive variables and `options.storage` to compose a `read` function that behaves in a manner that resembles an asynchronous action:
 
 <ExpansionPanel title="See example">
 

[jerelmiller]

I like that much better!

[bignimbus]

Updated - thanks!

[jerelmiller]

🎉