Extend ConvexQueryCacheProvider with a "storer" object

[frozar]

This is not a bug report but rather a discussion of a potential feature regarding the ConvexQueryCacheProvider component.

I'm well aware that the cache provided by this component is not just about data, but rather about keeping the subscription to the central DB in sync with queries (as far as I understood).

My question is: Is it possible to add an optional argument to the ConvexQueryCacheProvider contructor to provide an object, storer for example, which would be able to read and to write from a storage?
The type of this storer object should be something like:

type Storer = {
  fnRead: (key: string) => Promise<any>;
  fnWrite: (key: string, value: any) => Promise<void>;
};

The fnRead function should be used when a query is done by the client application in case this query has no active subscription or the DB is unreachable.
The fnWrite function should be used when a query is done by the client application in case this query has an active subscription or the DB is reachable.

The purpose is to be able to provide data to the application in case of connection disability. This would be particularly interesting on a mobile phone when sometime, you're in place without internet connection. What interest me the most is to be able to have some data when my application opens up, even if I'm in a mall without internet connection.
Also, this management of the cache concerns only the read part of the interaction with the DB, so no headheck with optimistic write and resolution of the state of the DB when devices get back to an internet connection.

To me, it seems possible to do from ConvexQueryCacheProvider component and harmless. The optionality of this argument should not break existing code. And finally, with this interface, ConvexQueryCacheProvider is agnostic about the storage system eventually used by the application.

Does this request seem legit to you?
It is implementable without directly interacting with the BaseConvexClient component?

[ianmacartney]

Good suggestion, thanks for adding it. One nuance is that there's a sense of consistency *between* queries - e.g. if you have one query that got persisted and fell out of date, and another that kept updating, you might later load that older query and be seeing results from different versions of the data. e.g. a deleted item might be referenced, or other logical inconsistencies. Right now with the React client, every hook gets a version of the data from the same snapshot in the same React render cycle. So this would be a weakening of that guarantee. If it wrote only when the client was going away, and read only at startup when resuming subscriptions, there wouldn't be an issue - it would look like the client had frozen in the past, then caught up to a consistent view of the future when it got back online. One version of this is the Local Sync project, but unsure when that will ship. What about a local stale-while-revalidate cache that can be used alongside / in place of the subscription cache? e.g. `const valueOrCached = useCache(api.foo.bar, { ...args }, value)` that stored values into session storage / local storage / React Native storage, and when `value` is `undefined`, it returns any cached value for that function & args? It'd be two hooks instead of one, but would be explicit about which values were cached and which weren't?

…

On Sun, Jul 6, 2025 at 12:03 AM ROZAR Fabien ***@***.***> wrote: *frozar* created an issue (get-convex/convex-helpers#677) <#677> This is not a bug report but rather a discussion of a potential feature regarding the ConvexQueryCacheProvider component. I'm well aware that the cache provided by this component is not just about data, but rather about keeping the subscription to the central DB in sync with queries <https://youtu.be/ZgxDlSUGpfE?si=qOGuXXbDz8nLH9BV> (as far as I understood). My question is: Is it possible to add an optional argument to the ConvexQueryCacheProvider contructor to provide an object, storer for example, which would be able to read and to write from a storage? The type of this storer object should be something like: type Storer = { fnRead: (key: string) => Promise<any>; fnWrite: (key: string, value: any) => Promise<void>; }; The fnRead function should be used when a query is done by the client application in case this query has no active subscription or the DB is unreachable. The fnWrite function should be used when a query is done by the client application in case this query has an active subscription or the DB is reachable. The purpose is to be able to provide data to the application in case of connection disability. This would be particularly interesting on a mobile phone when sometime, you're in place without internet connection. What interest me the most is to be able to have some data when my application opens up, even if I'm in a mall without internet connection. Also, this management of the cache concerns only the read part of the interaction with the DB, so no headheck with optimistic write and resolution of the state of the DB when devices get back to an internet connection. To me, it seems possible to do from ConvexQueryCacheProvider component and harmless. The optionality of this argument should not break existing code. And finally, with this interface, ConvexQueryCacheProvider is agnostic about the storage system eventually used by the application. Does this request seem legit to you? It is implementable without directly interacting with the BaseConvexClient component? — Reply to this email directly, view it on GitHub <#677>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW5TLWRIVHFQIAT25ZD3HDC5RAVCNFSM6AAAAACA336ZP6VHI2DSMVQWIX3LMV43ASLTON2WKOZTGIYDMMRQHE4TQNQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[frozar]

Thank you for the answer, and we're right, I overlooked the topic about consistency (because I find it to hard for me, I must say). My hope was to focus only on the read part to try to avoid these issues, but in any case, the guarantee of consistency is necessary weakened or at the very least tydious to achieve.

I'm aware of the Sync Engine project but as this comment says, it seems to be deprioritized (for the moment (I guess it was in favor of Chef...)).

Maybe you're right, my current best option is to wrap calls of queries. Of course, if you have any news about the Sync Engine feature, please let me know by writting a comment here (I'll do the same 😉).

Should I close this issue? Or you can, up to you.