refactor(mutation-flow): options-object signature for useMutationFlow

Replace positional `useMutationFlow(call, mutationFn, fallback?)` with
`useMutationFlow(call, { mutationFn, fallback? })`. Same two-overload
shape encodes the "fallback required iff mutationFn may be undefined"
invariant on the options object instead of on positional arity.

Docs (README, ADR-0014, CONTEXT.md, changeset) and tests updated to the
new shape. Bundle still within budgets (275 B / 353 B brotli).

Author: desko27

.changeset/feat-mutation-flow.md

@@ -2,7 +2,7 @@
 "react-call": minor
 ---
 
-- **New `react-call/mutation-flow` subpath entry** — `useMutationFlow(call, mutationFn, fallback?)` is an opt-in hook that wraps the canonical async-submission flow (click → run async → keep open on failure, end on success). The main `react-call` entry stays unchanged: bundle size and API surface of `createCallable` / `CallContext` are not affected. Consumers who never import the subpath pay zero.
+- **New `react-call/mutation-flow` subpath entry** — `useMutationFlow(call, { mutationFn, fallback? })` is an opt-in hook that wraps the canonical async-submission flow (click → run async → keep open on failure, end on success). The main `react-call` entry stays unchanged: bundle size and API surface of `createCallable` / `CallContext` are not affected. Consumers who never import the subpath pay zero.
 
   ```tsx
   import { createCallable } from 'react-call'
@@ -12,7 +12,7 @@
 
   export const Confirm = createCallable<Props, boolean>(
     ({ call, mutationFn }) => {
-      const submit = useMutationFlow(call, mutationFn)
+      const submit = useMutationFlow(call, { mutationFn })
       return (
         <button disabled={submit.pending} onClick={() => submit()}>
           Yes
@@ -33,6 +33,6 @@
   })
   ```
 
-  The `mutationFn` receives a narrow `MutationCall<Response>` view (`{ end }`) — no `RootProps` ever leaks into the handler's signature. Throws are swallowed by the trigger so the call stays open for retry; the handler decides when (if ever) to `call.end()`. A 2-arg overload applies when the `mutationFn` parameter is required; a 3-arg overload requires a `fallback` response when `mutationFn` may be undefined. See [ADR-0014](docs/adr/0014-mutation-flow-as-composition-hook.md) for the design rationale and the trade-off versus making this a primitive on `CallContext`.
+  The `mutationFn` receives a narrow `MutationCall<Response>` view (`{ end }`) — no `RootProps` ever leaks into the handler's signature. Throws are swallowed by the trigger so the call stays open for retry; the handler decides when (if ever) to `call.end()`. The options object has two overloads: `{ mutationFn }` when the parameter is required, and `{ mutationFn, fallback }` (with `fallback` required by the type system) when `mutationFn` may be undefined. See [ADR-0014](docs/adr/0014-mutation-flow-as-composition-hook.md) for the design rationale and the trade-off versus making this a primitive on `CallContext`.
 
 - **Exports**: `MutationFn`, `MutationCall`, `Trigger`, `useMutationFlow` from `react-call/mutation-flow`.

CONTEXT.md

@@ -81,7 +81,7 @@ _Avoid_: Submit, runner, dispatcher.
 
 **Fallback response**:
 The Response value used when `submit()` fires but no MutationFn was
-provided. Required as the 3rd argument to `useMutationFlow` exactly when
+provided. Required in `useMutationFlow`'s options object exactly when
 the MutationFn parameter is typed as possibly-undefined.
 _Avoid_: Default, no-op.
 

README.md

@@ -278,7 +278,7 @@ type Props = {
 
 export const Confirm = createCallable<Props, boolean>(
   ({ call, message, mutationFn }) => {
-    const submit = useMutationFlow(call, mutationFn)
+    const submit = useMutationFlow(call, { mutationFn })
     return (
       <div role="dialog">
         <p>{message}</p>
@@ -314,9 +314,9 @@ can retry. The `mutationFn` decides when (if ever) to call `call.end()`.
 
 If your component should still close cleanly when no `mutationFn` was
 provided (e.g. a plain "Are you sure?" without any side effect), type the
-prop as optional and pass a third `fallback` argument to the hook. The
-type system enforces this — the fallback is required exactly when the
-`mutationFn` parameter may be undefined.
+prop as optional and pass a `fallback` alongside it in the options
+object. The type system enforces this — `fallback` is required exactly
+when the `mutationFn` parameter may be undefined.
 
 ```tsx
 type Props = {
@@ -326,8 +326,8 @@ type Props = {
 
 export const Confirm = createCallable<Props, boolean>(
   ({ call, message, mutationFn }) => {
-    //                                            ↓ closes with `true` if no mutationFn
-    const submit = useMutationFlow(call, mutationFn, true)
+    //                                                       ↓ closes with `true` if no mutationFn
+    const submit = useMutationFlow(call, { mutationFn, fallback: true })
     return (
       <button disabled={submit.pending} onClick={() => submit()}>
         Yes
@@ -348,7 +348,7 @@ type Props = {
 }
 
 export const Picker = createCallable<Props, string>(({ call, mutationFn }) => {
-  const submit = useMutationFlow(call, mutationFn)
+  const submit = useMutationFlow(call, { mutationFn })
   return (
     <>
       <button onClick={() => submit({ choice: 'A' })}>A</button>

docs/adr/0014-mutation-flow-as-composition-hook.md

@@ -5,7 +5,7 @@ Issue #22 asks for a first-class answer to *click → run async → keep open on
 ## Considered options
 
 - **Primitive on `CallContext` (PR #81 shape).** `call.pending` and `call.mutate(payload)` exposed by the lib itself, with `mutationFn` living in a new `CallOptions` second-arg of `call()` / `upsert()` and `MutationPayload` inserted as the 3rd generic of `createCallable` (RootProps moves to 4th). Rejected: requires ~+159 LOC in `createCallable`, mutates a public type (`CallContext`), bumps the brotli budget 1 KB → 1.25 KB, and forces a BREAKING reorder of generics on consumers who already used `<Props, Response, RootProps>`. The functional win over the hook is marginal: HMR-preserved `pending` across saves and the option to wire `Callable.mutate(...)` from outside later — both rare. Not worth the lib-core surface area.
-- **Composition hook in a subpath (chosen).** `useMutationFlow(call, mutationFn, fallback?)` lives in `react-call/mutation-flow`. Pending is local `useState` inside the user component. The handler receives a narrow `MutationCall<Response>` view of the call (just `{ end }`) and decides when to close. Two TypeScript overloads encode the invariant "fallback is required iff `mutationFn` is possibly-undefined", so the wart of a dead-weight third arg is closed at compile time. Lib core: zero changes.
+- **Composition hook in a subpath (chosen).** `useMutationFlow(call, { mutationFn, fallback? })` lives in `react-call/mutation-flow`. Pending is local `useState` inside the user component. The handler receives a narrow `MutationCall<Response>` view of the call (just `{ end }`) and decides when to close. Two TypeScript overloads on the options object encode the invariant "fallback is required iff `mutationFn` is possibly-undefined", so the wart of a dead-weight optional field is closed at compile time. Lib core: zero changes.
 - **Pure docs / no helper.** Just document the orion-style pattern (`useState` + `try/finally` in the user component, `asyncAction` prop with explicit `close`). Rejected: leaves the boilerplate of `useState`/`finally`/no-mutationFn-fallback at every dialog. The user-mentioned `usePending` and "builder for mutationFn" framing made the "no helper" position too thin.
 - **Hook in the main entry instead of a subpath.** One import path, more discoverable, tree-shakeable in modern bundlers. Rejected: the hook is ~100–200 bytes brotli; budgeting it into the main entry would push it past the 1 KB limit and force a budget bump (1 KB → ~1.1 KB). Cheap to keep separate, costly to revisit later if subpath gets adopted and we want to fold it back in.
 
@@ -18,6 +18,6 @@ Issue #22 asks for a first-class answer to *click → run async → keep open on
 - **`Callable.mutate(...)` from caller scope is structurally absent**, not deferred. The trigger is local to the user component's render. Adding caller-scope triggering later would require a parallel lib-level channel — it is *not* an additive extension of this hook. PR #81 left this door open at the cost of the primitive-on-CallContext shape; we trade that door for the smaller lib core.
 - **HMR does not preserve `pending` across saves.** Pending lives in component `useState`; a Fast Refresh during an in-flight mutation resets the visible pending flag (the mutation itself continues in background). Acceptable: editing a dialog mid-mutation is exotic.
 - **`MutationCall<Response>` is the public name** of the handler's `call` argument. Chosen over `MutationContext` (which would falsely suggest a React `Context`) and over `Closer` (too narrow once we ever add `signal` / `ended` / etc.).
-- **The hook signature uses TypeScript overloads.** `mutationFn` required → 2-arg signature with no fallback; `mutationFn` possibly-undefined → 3-arg signature with fallback required. The dead-weight third arg from the original sketch is gone.
+- **The hook signature uses TypeScript overloads on the options object.** `mutationFn` required → `{ mutationFn }` (no fallback); `mutationFn` possibly-undefined → `{ mutationFn, fallback }` with fallback required. The dead-weight optional fallback field is gone in the required-handler case.
 - **`AbortSignal` on `MutationCall` and `submit.error` on the trigger are deferred**, same as PR #81. Additive without breaking change: extending `MutationCall<Response>` and adding an `error` field to the trigger is purely additive type-wise.
 - **The README needs a new section** documenting `react-call/mutation-flow`, distinct from the createCallable basics. The hook isn't part of the "Call your React components" first-impression API; it's an opt-in helper for a specific pattern, and the docs should frame it that way.

packages/react-call/src/__tests__/mutation-flow.test.tsx

@@ -7,8 +7,8 @@ import type * as ReactCall from '../types.public'
 import { withAct } from './shared/act'
 
 // Component fixtures cover the two consumer patterns: a Required-handler
-// dialog (the 2-arg overload, no fallback) and an Optional-handler dialog
-// (the 3-arg overload, fallback required by the type system).
+// dialog (no fallback) and an Optional-handler dialog (fallback required
+// by the type system because mutationFn may be undefined).
 
 type RequiredProps = { mutationFn: MutationFn<boolean> }
 
@@ -18,7 +18,7 @@ const RequiredComponent: ReactCall.UserComponent<
   {}
 > = ({ call, mutationFn }) => {
   const a11yId = useId()
-  const submit = useMutationFlow(call, mutationFn)
+  const submit = useMutationFlow(call, { mutationFn })
   return (
     <div role="dialog" aria-labelledby={a11yId}>
       <p id={a11yId}>Are you sure?</p>
@@ -47,7 +47,7 @@ const OptionalComponent: ReactCall.UserComponent<
   boolean,
   {}
 > = ({ call, mutationFn }) => {
-  const submit = useMutationFlow(call, mutationFn, true)
+  const submit = useMutationFlow(call, { mutationFn, fallback: true })
   return (
     <button
       type="button"
@@ -69,7 +69,7 @@ const PayloadComponent: ReactCall.UserComponent<PayloadProps, string, {}> = ({
   call,
   mutationFn,
 }) => {
-  const submit = useMutationFlow(call, mutationFn)
+  const submit = useMutationFlow(call, { mutationFn })
   return (
     <>
       <button type="button" onClick={() => submit({ choice: 'A' })}>
@@ -129,7 +129,7 @@ describe('useMutationFlow — pending lifecycle', () => {
   })
 })
 
-describe('useMutationFlow — fallback (3-arg overload)', () => {
+describe('useMutationFlow — fallback', () => {
   test('submit() without a mutationFn closes the call with the fallback response', async () => {
     render(<Optional />)
     const promise = withAct(() => Optional.call({}))

packages/react-call/src/mutation-flow/index.ts

@@ -31,23 +31,28 @@ export type Trigger<Payload> = ((payload: Payload) => void) & {
 
 // Overloads encode the invariant "fallback is required iff mutationFn
 // may be undefined". When the consumer types the prop as required, the
-// 2-arg form applies and no fallback is needed. When the prop is
-// possibly-undefined, TypeScript forces the 3-arg form. No third dead-
-// weight optional argument leaks into the required-handler case.
+// fallback-less options shape applies. When the prop is possibly-
+// undefined, TypeScript forces the shape that requires `fallback`. No
+// dead-weight optional field leaks into the required-handler case.
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  mutationFn: MutationFn<Response, Payload>,
+  options: { mutationFn: MutationFn<Response, Payload> },
 ): Trigger<Payload>
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  mutationFn: MutationFn<Response, Payload> | undefined,
-  fallback: Response,
+  options: {
+    mutationFn: MutationFn<Response, Payload> | undefined
+    fallback: Response
+  },
 ): Trigger<Payload>
 export function useMutationFlow<Response, Payload = void>(
   call: MutationCall<Response>,
-  mutationFn: MutationFn<Response, Payload> | undefined,
-  fallback?: Response,
+  options: {
+    mutationFn: MutationFn<Response, Payload> | undefined
+    fallback?: Response
+  },
 ): Trigger<Payload> {
+  const { mutationFn, fallback } = options
   const [pending, setPending] = useState(false)
   // Synchronous re-entry guard. `pending` state alone can't guard against
   // a second call dispatched programmatically inside the same event-loop