firestore: improve documentation about CRUD promises and when they resolve #8887
Conversation
… clearly document that the returned Promise does not resolve/reject until the write is attempted against the remote Firestore backend, which could be an indefinite amount of time in the future.
|
Size Report 1Affected ProductsNo changes between base commit (c8cbfff) and merge commit (780df1a).Test Logs |
Size Analysis Report 1Affected ProductsNo changes between base commit (c8cbfff) and merge commit (780df1a).Test Logs |
| * time, for example until the client has gone back online. That being said, | ||
| * the given data _will_ be immediately saved to the local cache and will be | ||
| * incorporated into future "get" operations as if it had been successfully | ||
| * written to the remote Firestore server. The data will _eventually_ be written |
There was a problem hiding this comment.
You could reference this behavior as latency compensation. We do use this term in public documentation, so giving it a name here may make it easier to search for.
There was a problem hiding this comment.
Please update the documentation at https://firebase.google.com/docs/firestore/manage-data/add-data and https://firebase.google.com/docs/firestore/manage-data/enable-offline as well.
| * rejected until the remote Firestore backend reports an error saving the given | ||
| * data. So if the client cannot reach the backend, for example due to being | ||
| * offline, then the returned `Promise` will not resolve for a potentially-long | ||
| * time, for example until the client has gone back online. That being said, |
There was a problem hiding this comment.
Duplicate "for example" clauses in the language here.
| * rejected until the remote Firestore backend reports an error saving the given | ||
| * data. So if the client cannot reach the backend, for example due to being | ||
| * offline, then the returned `Promise` will not resolve for a potentially-long | ||
| * time, for example until the client has gone back online. That being said, |
There was a problem hiding this comment.
It might be worth also emphasizing, somewhere, that if the client is offline (for example via await disableNetwork(db);) attempting to await in test automation will cause the process to immediately exit because there is no pending network operation or timer to attempt the retry.
That's probably not suitable for this page, but it might be worth a highlight somewhere.
Firestore: Improve documentation for setDoc, updateDoc, deleteDoc, and addDoc to clearly document that the returned Promise does not resolve/reject until the write is attempted against the remote Firestore backend, which could be an indefinite amount of time in the future.
Fixes: #8862