Warn when using an async optimistic update handler (#37670)

`withOptimisticUpdate` takes an `OptimisticUpdate` (`(…) => void`) which is ran synchronously. But in TypeScript, `() => Promise<void>` is a valid subtype of it, so using an asynchronous handler won’t fail at compile time. When it runs, the behavior is very surprising as local store changes would suddenly start to be ignored as soon as the handler starts using `await` (even for awaiting a function that returns instantly).

It’s surprisingly difficult to fix that problem at compile time. Since functions that implicitly return `undefined` are typed as `() => void` and not `() => undefined`, changing `OptimisticUpdate` to be `() => undefined` doesn’t work.

The next best option is to add a runtime warning when the user returns a promise from an optimistic update handler, in order to help the developer identify what’s going wrong.

GitOrigin-RevId: 4f02221f153f482881163a3c1949ba45e62a1994

Author: Nicolapps

npm-packages/convex/src/browser/sync/client.ts

@@ -781,7 +781,15 @@ export class BaseConvexClient {
       const optimisticUpdate = options.optimisticUpdate;
       if (optimisticUpdate !== undefined) {
         const wrappedUpdate = (localQueryStore: OptimisticLocalStore) => {
-          optimisticUpdate(localQueryStore, mutationArgs);
+          const result: unknown = optimisticUpdate(
+            localQueryStore,
+            mutationArgs,
+          );
+          if (result instanceof Promise) {
+            this.logger.warn(
+              "Optimistic update handler returned a Promise. Optimistic updates should be synchronous.",
+            );
+          }
         };
 
         const changedQueryTokens =