feat: async mutation primitive (call.pending + call.mutate)

[desko27]

Summary

Closes #22 (open since Dec 2024) with a first-class answer to the canonical async-submission flow: click → run async op → disable while loading → keep open on failure / end on success.

Two additions to CallContext:

• call.pending: boolean — true while an in-flight mutation hasn't settled.
• call.mutate(payload) — managed-pending trigger that invokes the caller-provided mutationFn, swallows throws, and lets the mutationFn decide when to call.end().

The mutationFn lives in a new optional CallOptions slot — the second arg of call() / upsert() — not in Props. Naming follows TanStack Query (mutate / mutationFn / pending) for free familiarity; the one deviation is payload instead of variables (the mutationFn closes over half its inputs in caller scope, so what flows through call.mutate(...) is the modal's contribution only — not "all variables").

type Props = { message: string }
type Payload = { id: string }

export const Confirm = createCallable<Props, boolean, Payload>(({ call, message }) => (
  <div role="dialog">
    <p>{message}</p>
    <button disabled={call.pending} onClick={() => call.mutate({ id: 'abc' })}>Delete</button>
    <button onClick={() => call.end(false)}>Cancel</button>
  </div>
))

Confirm.call(
  { message: 'Delete?' },
  {
    mutationFn: async (call, { id }) => {
      try {
        await api.delete(id)
        call.end(true)
        toast.success('Deleted')
      } catch (err) {
        toast.error(err)
        // no end → dialog stays open, pending clears, user can retry
      }
    },
  },
)

Full design rationale + considered alternatives in ADR-0014. Grilling session that produced the design is captured in CONTEXT.md.

⚠️ BREAKING — generic reorder

createCallable's signature reorders to <Props, Response, MutationPayload = void, RootProps = {}>. RootProps moves from 3rd to 4th position. Mechanical migration:

// before
createCallable<Props, Response, RootProps>(Component)
// after
createCallable<Props, Response, void, RootProps>(Component)

The (small) set of consumers using the 3rd generic for RootProps insert void in the new 3rd slot. Bundle budget raised from 1 KB → 1.25 KB brotli to fit the new primitive honestly (alternative was crunching dev warnings the consumer's bundler strips for prod anyway).

Commits

1. 65abf28 docs(adr): design decision + CONTEXT.md
2. 8846e66 feat(react-call): implementation + types + tests + readme + changeset
3. 26a6b09 chore(react-call): silence two biome warnings

Out of scope (deliberate, additive later if real demand)

• Callable.mutate(...) from outside
• AbortSignal on MutationContext
• call.error on CallContext

ADR-0014 documents why each was deferred.

Test plan

• pnpm vitest run — 94/94 pass (17 new in mutate.test.tsx)
• pnpm check:types — clean
• pnpm lint — clean (2 prior warnings silenced via biome-ignore with reasons)
• pnpm --filter react-call run build + pnpm size — within new 1.25 KB brotli budget
• Manual smoke in apps/vite / apps/nextjs (not done — these apps don't exercise the mutation path; would be a follow-up if you want a apps/* demo of the pattern)
• Demo scene in sites/demo (also not done — happy to add a YourMutation.tsx scene in a follow-up)

Do NOT merge

Per request, leaving for manual merge.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-call	Ready	Preview, Comment	May 23, 2026 9:12pm

[desko27]

Close in favor of #82