@confect/react 9.0.1 → 9.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@confect/react",
   "description": "Client-side bindings for React apps",
-  "version": "9.0.1",
+  "version": "9.1.0",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
@@ -57,7 +57,7 @@
     "convex": "^1.32.0",
     "effect": "^3.21.2",
     "react": "^18.0.0 || ^19.0.0",
-    "@confect/core": "^9.0.1"
+    "@confect/core": "^9.1.0"
   },
   "repository": {
     "type": "git",

package/src/OptimisticLocalStore.ts

@@ -0,0 +1,70 @@
+import { Ref } from "@confect/core";
+import type { OptimisticLocalStore as ConvexOptimisticLocalStore } from "convex/browser";
+import * as Option from "effect/Option";
+
+/**
+ * The Confect counterpart to Convex's `OptimisticLocalStore`.
+ *
+ * Its methods accept Confect query `Ref`s and operate on decoded (Effect
+ * Schema) values rather than the encoded values stored by Convex. Query values
+ * are wrapped in `Option`: `Option.none()` represents a query that is not
+ * present in the store, and `Option.some(value)` carries the decoded value.
+ */
+export interface OptimisticLocalStore {
+  getQuery<Query extends Ref.AnyPublicQuery>(
+    queryRef: Query,
+    ...args: Ref.OptionalArgs<Query>
+  ): Option.Option<Ref.Returns<Query>>;
+
+  getAllQueries<Query extends Ref.AnyPublicQuery>(
+    queryRef: Query,
+  ): Array<{
+    args: Ref.Args<Query>;
+    value: Option.Option<Ref.Returns<Query>>;
+  }>;
+
+  setQuery<Query extends Ref.AnyPublicQuery>(
+    queryRef: Query,
+    args: Ref.Args<Query>,
+    value: Option.Option<Ref.Returns<Query>>,
+  ): void;
+}
+
+/**
+ * Wraps Convex's `OptimisticLocalStore` so that it accepts Confect query `Ref`s
+ * and decoded values, handling the encoding/decoding against Convex's store.
+ */
+export const make = (
+  convexLocalStore: ConvexOptimisticLocalStore,
+): OptimisticLocalStore => ({
+  getQuery: (queryRef, ...rest) => {
+    const functionReference = Ref.getFunctionReference(queryRef);
+    const args = (rest[0] ?? {}) as Ref.Args<typeof queryRef>;
+    const encodedArgs = Ref.encodeArgsSync(queryRef, args);
+    const encoded = convexLocalStore.getQuery(functionReference, encodedArgs);
+    return encoded === undefined
+      ? Option.none()
+      : Option.some(Ref.decodeReturnsSync(queryRef, encoded));
+  },
+  getAllQueries: (queryRef) => {
+    const functionReference = Ref.getFunctionReference(queryRef);
+    return convexLocalStore
+      .getAllQueries(functionReference)
+      .map(({ args, value }) => ({
+        args: Ref.decodeArgsSync(queryRef, args),
+        value:
+          value === undefined
+            ? Option.none()
+            : Option.some(Ref.decodeReturnsSync(queryRef, value)),
+      }));
+  },
+  setQuery: (queryRef, args, value) => {
+    const functionReference = Ref.getFunctionReference(queryRef);
+    const encodedArgs = Ref.encodeArgsSync(queryRef, args);
+    const encodedValue = Option.match(value, {
+      onNone: () => undefined,
+      onSome: (decoded) => Ref.encodeReturnsSync(queryRef, decoded),
+    });
+    convexLocalStore.setQuery(functionReference, encodedArgs, encodedValue);
+  },
+});

package/src/index.ts

@@ -1,9 +1,13 @@
 import { Ref } from "@confect/core";
+import type { OptimisticUpdate as ConvexOptimisticUpdate } from "convex/browser";
 import {
   useAction as useConvexAction,
   useMutation as useConvexMutation,
   useQuery as useConvexQuery,
+  type ReactMutation as ConvexReactMutation,
 } from "convex/react";
+import type { FunctionReference } from "convex/server";
+import type { Value } from "convex/values";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Either from "effect/Either";
@@ -11,9 +15,10 @@ import * as Exit from "effect/Exit";
 import * as Option from "effect/Option";
 import { useCallback, useMemo } from "react";
 
+import * as OptimisticLocalStore from "./OptimisticLocalStore";
 import * as QueryResult from "./QueryResult";
 
-export { QueryResult };
+export { OptimisticLocalStore, QueryResult };
 
 export type InvokeReturn<Ref_ extends Ref.Any> = [Ref.Error<Ref_>] extends [
   never,
@@ -76,7 +81,69 @@ export const useQuery = <Query extends Ref.AnyPublicQuery>(
 };
 
 /**
- * Returns a function that invokes the provided `Ref`'s mutation.
+ * An optimistic update for a Confect mutation. Mirrors Convex's
+ * `OptimisticUpdate`, but receives a Confect {@link OptimisticLocalStore} and
+ * the decoded mutation `args`.
+ */
+export type OptimisticUpdate<Mutation extends Ref.AnyPublicMutation> = (
+  localStore: OptimisticLocalStore.OptimisticLocalStore,
+  args: Ref.Args<Mutation>,
+) => void;
+
+/**
+ * The handle returned by {@link useMutation}. It is callable like the function
+ * returned by Convex's `useMutation`, and additionally exposes
+ * `withOptimisticUpdate` for attaching an optimistic update. Mirrors the
+ * `ReactMutation` type from `convex/react`.
+ */
+export interface ReactMutation<Mutation extends Ref.AnyPublicMutation> {
+  (...args: Ref.OptionalArgs<Mutation>): InvokeReturn<Mutation>;
+  withOptimisticUpdate(
+    optimisticUpdate: OptimisticUpdate<Mutation>,
+  ): ReactMutation<Mutation>;
+}
+
+const makeReactMutation = <Mutation extends Ref.AnyPublicMutation>(
+  ref: Mutation,
+  convexReactMutation: ConvexReactMutation<
+    Ref.FunctionReference<Mutation> & FunctionReference<"mutation">
+  >,
+): ReactMutation<Mutation> => {
+  const callable = ((...args: Ref.OptionalArgs<Mutation>) =>
+    invokeAsEither(
+      ref,
+      (_, encodedArgs) => convexReactMutation(encodedArgs as never),
+      args,
+    ).then((either) =>
+      Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),
+    )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>;
+
+  const withOptimisticUpdate = (
+    optimisticUpdate: OptimisticUpdate<Mutation>,
+  ): ReactMutation<Mutation> => {
+    const wrappedUpdate: ConvexOptimisticUpdate<Record<string, Value>> = (
+      convexLocalStore,
+      encodedArgs,
+    ) => {
+      const decodedArgs = Ref.decodeArgsSync(ref, encodedArgs);
+      optimisticUpdate(
+        OptimisticLocalStore.make(convexLocalStore),
+        decodedArgs,
+      );
+    };
+    const nextConvexReactMutation =
+      convexReactMutation.withOptimisticUpdate(wrappedUpdate);
+    return makeReactMutation(ref, nextConvexReactMutation);
+  };
+
+  return Object.assign(callable, { withOptimisticUpdate });
+};
+
+/**
+ * Returns a {@link ReactMutation} handle for the provided `Ref`'s mutation. The
+ * handle is callable to invoke the mutation, and exposes `withOptimisticUpdate`
+ * for attaching an optimistic update, mirroring `useMutation` from
+ * `convex/react`.
  *
  * If the `Ref` declares an `error` schema, the returned promise resolves to an
  * `Either` with the decoded `returns` value on the right and the decoded error
@@ -90,20 +157,19 @@ export const useQuery = <Query extends Ref.AnyPublicQuery>(
  */
 export const useMutation = <Mutation extends Ref.AnyPublicMutation>(
   ref: Mutation,
-): ((...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>) => {
+): ReactMutation<Mutation> => {
   const functionReference = Ref.getFunctionReference(ref);
-  const actualMutation = useConvexMutation(functionReference);
+  const convexReactMutation = useConvexMutation(functionReference);
 
-  return useCallback(
-    ((...args: Ref.OptionalArgs<Mutation>) =>
-      invokeAsEither(
+  return useMemo(
+    () =>
+      makeReactMutation(
         ref,
-        (_, encodedArgs) => actualMutation(encodedArgs),
-        args,
-      ).then((either) =>
-        Ref.hasErrorSchema(ref) ? either : Either.getOrThrow(either),
-      )) as (...args: Ref.OptionalArgs<Mutation>) => InvokeReturn<Mutation>,
-    [ref, actualMutation],
+        convexReactMutation as ConvexReactMutation<
+          Ref.FunctionReference<Mutation> & FunctionReference<"mutation">
+        >,
+      ),
+    [ref, convexReactMutation],
   );
 };