Typesafe useFetcher like utility

[dadamssg]

tl;dr

let handler = useRouteHandler({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

<handler.Form /> // does not accept 'action' and 'method' props

handler.submit({ data: formData })

handler.data // typed to the above route's action return type

Background

useFetcher has no way to be typesafe because the data changes based on what you do with it. You can theoretically use the same fetcher instance for both a load() and submit() in the same component so unless your route's action and loader have the same return type, the types will lying to you if you typehint the useFetcher. Example:

let fetcher = useFetcher<typeof action>();
fetcher.load()

Here, fetcher.data would be the loader's return data but it's typed as if the action will be called.

Abstraction

For this to work, the intent of the request needs to be established at fetcher initialization.

let fetcher = useFetcher({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

However, if this were done to useFetcher, the methods make less sense:

let postFetcher = useFetcher({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})
postFetcher.load() // ??? only submit() makes sense

let getFetcher = useFetcher({
  method: 'get',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

getFetcher.submit(null, { method: 'post'}) 
// ^ method change negates what was established earlier

I believe this warrants a new utility.

Proposal

A new, useRouteHandler hook that would be configured just enough before use to be typesafe.

let handler = useRouteHandler({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

<handler.Form />

handler.submit({ data: formData })

// ^ both do not accept 'method' and 'action' props

We should be able to use fetchers under the hood. Something like this. (useMemo's removed for clarity)

type HandlerFormProps = Omit<FetcherFormProps, "method" | "action">;
type HandlerSubmitOptions = Omit<FetcherSubmitOptions, "method" | "action">;

function useRouteHandler<R extends RouteInput>(route: R) {
  type Resolved = ResolveRoute<R>;
  type Data = Resolved["data"];

  let fetcher = useFetcher<Data>();
  let action = href(route.routeId, route.params)

  if (route.method === "GET") {
    // discard submit
    let { load, submit, Form, ...fetcherParts } = fetcher;
    return {
      ...fetcherParts,
      load: (options?: { flushSync: boolean }) => {
        return load(action, options);
      },
      Form: (props: HandlerFormProps) => (
        <Form
          {...props}
          method="get"
          action={action}
        />
      ),
    };
  }

  // discard load
  let { load, submit, Form, ...fetcherParts } = fetcher;

  return {
    ...fetcherParts,
    submit: (target: SubmitTarget, options?: HandlerSubmitOptions) => {
      return submit(target, {
        ...options,
        method: route.method,
        action,
      });
    },
    Form: (props: HandlerFormProps) => (
      <Form
        {...props}
        method={route.method}
        action={action}
      />
    ),
  };
}

This version still has distinct methods for calling an action(submit) vs a loader(load) but they're mutually exclusive.

Considerations

I know some people prefer the distinction at the callsite but it could probably be normalized into a common function who's arg type changes based on how it's configured.

let postHandler = useRouteHandler({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

postHandler.fetch({ data: formData })

let getHandler = useRouteHandler({
  method: 'get',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

getHandler.fetch()

The fetch function could also be named submit since that makes sense for all verbs considering you can submit a get request with a fetcher now.

searchParams

Kinda goofy since they can be part of the action and also become the payload for GET submissions. I'm not sure the best way to handle them.

let handler = useRouteHandler({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
  searchParams: new URLSearchParams({returnTo: '/some/path'})
})

<handler.Form  /> // searchParms embedded in the rendered action

It might make sense to separate them out at the callsite(if we want to support them there) and adjust the body type.

let postHandler = useRouteHandler({
  method: 'post',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

postHandler.fetch({
  // body allowed because method != get
  body: formData,
  searchParams: new URLSearchParams({returnTo: '/some/path'})
})

let getHandler = useRouteHandler({
  method: 'get',
  routeId: 'routes/some.route.$id',
  params: { id: '1' },
})

getHandler.fetch({
  // no body allowed because method = get! 
  body: new URLSearchParams({page: '7'}),
  searchParams: new URLSearchParams({page: '7'})
})

Having a dedicated place to put searchParams for both requests might make more sense from a consistency standpoint. Also matches better with builtin fetch() since bodies are ignored with GET requests.

Something like this.

Alternative

One alternative would be to try to enhance useFetcher and add loaderData and actionData to its return.

let fetcher = useFetcher({ 
  routeId: 'routes/api.users.$id', 
  params: { id: '1' }
});

// No path accepted - always loads /api/users/1
fetcher.load()
fetcher.loaderData // strongly typed

// No action accepted - always submits to /api/users/1
fetcher.submit(data, { method: 'post' })
fetcher.actionData // strongly typed

However, with this approach i think we'd want typesafey on existing methods

fetcher.load() // not allowed for routes that only have an action
fetcher.submit(null, {method: 'get'}) // not allowed for routes that only have an action
fetcher.submit(null, {method: 'post'}) // not allowed for routes that only have a loader

[dadamssg]

Or...

RR8 ditches fetcher.load, fetcher.submit, and fetcher.data. It introduces fetcher.fetch and its arg type changes based on the routeId's capabilities: does it have an action? a loader?

let fetcher useFetcher({
  routeId: 'routes/api.users.$id' // only routes with actions and/or loaders
})

fetcher.fetch({ params: { id: 'abc' }}) // GET
fetcher.fetch({ method: 'post', params: { id: 'abc' } }) // POST

fetcher.loaderData
fetcher.actionData

• method becomes required if route only has action. it cannot be get
• method can only be get if supplied and route only has loader

Although, a GET would need some sort of revalidation opt out flag for it to behave like a GET submit() and retain the auto-revalidation like load().

[dadamssg]

Here's an attempt at reusing useFetcher under the hood with two new hooks: useLoaderFetcher and useActionFetcher. It's missing memo'ing things and the params aren't right. i'm not sure how to get those from a routeId. https://tsplay.dev/N5nv5m

[dadamssg]

And here's a version that uses path instead of routeId: https://tsplay.dev/N94z7w

[brophdawg11]

We talked about this in the steering committee meeting today and think we landed a on a nice API that simplifies this a bit and leans into modern react features.

These days, React has useTransition for pending state and async actions and useOptimistic for optimistic state. We should be leaning more into them where possible, so if we're talking about a new typesafe hook it would be a mistake to overlook it's compatibility with those.

Here's what we came up with:

let [post, updatePost] = useRouteAction({ pattern: '/blog/:slug' })
//   ^     ^ both strongly typed to the /blog/:slug route action

let [isPending, startTransition] = useTransition();
let [optimisticPost, setOptimistic] = useOptimistic(post);

// Use your own transition/optimistic state for pending/optimistic UI
startTransition(() => {
  setOptimistic({ ...post, text: updatedText });
  return updatePost({ text: updatedText }, { method: 'put' });
})

This eliminates a bunch of fetcher.* fields that exist today:

• fetcher.state replaced with isPending
• fetcher.form*/fetcher.json/fetcher.text, etc. replaced with useOptimistic
• fetcher.load eliminated because this is useRouteAction
• fetcher.Form eliminated because you could wire this into a React client-side form action easily
• fetcher.data/fetcher.submit surfaced via the tuple, very React-y

BUT WHAT ABOUT fetcher.reset BROPHDAWG?

let [data, submit, reset] = useRouteAction({ pattern })

It's a less-commonly used thing so many folks will never bother to even destructure it off, but it's available for those that do.

useRouteLoader would be basically the same without the need for useOptimistic.

These would all still be fetchers under the hood so they'd still get all the cancellation/interruption/revalidation behavior of useFetcher

[DimaAmega]

You should take a look at my implementation for type safe fetchers

First of all - one route has multiple actions (yes!)
For actions i have export const actions = {} in route like:

// route: /some/:slug

export const actions = {
    'action-one': (args: ActionArgs<{ data: SomeDataShapeActionOne }>) => {
        // returns Promise<ActionOneReturnType> inferred
        return clientAPI.POST('/api/some/path', { body: args.data }) 
    },
    'action-two': (args: ActionArgs<{ data: SomeDataShapeActionTwo }>) => {
        // returns Promise<ActionTwoReturnType> inferred
        return clientAPI.POST('/api/some/path/two', { body: args.data }) 
    },
}

And i use useSubmitFetcher for it like:

// Some compoent inside some route

const fetcher = useSubmitFetcher({
    path: '/some/:slug', // type safe
    action: 'action-one' // type safe
})

fetcher.data // type safe -> ActionOneReturnType | undefined

fetcher.state // type safe -> 'idle' | 'submitting'

// in order to call action (in onClick for example):
fetcher.submit({ 
    data: {  /* type safe - only `SomeDataShapeActionOne` is allowed here */ },
    paramsToReplace: { slug: 'some-slug' } // type safe, you must provide `slug` param
  }
)

// if you want to call action 'action-two' you need another fetcher:

//  const fetcher = useSubmitFetcher({
//      path: '/some/:slug',
//      action: 'action-two'
//})

// usage is the same as above but type of `fetcher.data` is `ActionTwoReturnType | undefined` and etc.

It is easier for loaders...

const fetcher = useLoader('/some/:slug')

fetcher.data // type safe -> return type of /some/:slug loader | undefined

fetcher.load({
    paramsToReplace: { slug: 'some-slug' } // type safe, you must provide `slug` param
  }
)

I know that it can't be easily generalized for the whole react router project (other APIs and all supported use cases), but for me, it is quite a powerful custom fetchers API that I use a lot and this is really good fit for project i am currently working on.

Just decided to share with you for may be inspiration.

This custom fetchers API is used a lot in the Evidently OSS project.

Real code examples:

1. update dataset metadata:
   • fetcher
   • route actions
2. Load data points for dashboard panel
   • fetcher
   • route loader

Feel free to clone the repo and check it live - it is a fully working project with 100% type safety with no framework mode/codegen types - just vanilla ts types infered from source code (with a bit of limits but still pretty powerful). I created custom wrapper around react router for this before you released full type safety

You can check the whole project here https://github.com/evidentlyai/evidently/tree/79c758ff60c8d01ba5f39d34c76b7b8d654a295e/ui/service