{"id":8384,"date":"2026-01-28T09:26:35","date_gmt":"2026-01-28T14:26:35","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=8384"},"modified":"2026-01-28T09:26:36","modified_gmt":"2026-01-28T14:26:36","slug":"single-flight-mutations-in-tanstack-start-part-2","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/single-flight-mutations-in-tanstack-start-part-2\/","title":{"rendered":"Single Flight Mutations in TanStack Start: Part 2"},"content":{"rendered":"\n

In part 1<\/a>, we talked about how single flight mutations allow you to update data, and re-fetch all the relevant updated data for the UI, all in just one roundtrip across the network. <\/p>\n\n\n\n

We implemented a trivial solution for this, which is to say that we threw caution (and coupling) to the wind and just re-fetched what we needed in the server function we had for updating data. This worked fine, but it was hardly scalable, or flexible.<\/p>\n\n\n

\n
\n

Article Series<\/h3>\n <\/header>\n
\n
    \n
  1. \n Single Flight Mutations in TanStack Start: Part 1<\/a>\n <\/li>\n
  2. \n Single Flight Mutations in TanStack Start: Part 2<\/a>\n <\/li>\n <\/ol>\n <\/div>\n<\/div>\n\n\n\n

    In this post, we’ll accomplish the same thing, but in a much more flexible way. We’ll define some refetching middleware that we can attach to any server function. The middleware will allow us to specify, via react-query keys, what data we want re-fetched, and it’ll handle everything from there.<\/p>\n\n\n\n

    We’ll start simple, and keep on adding features and flexibility. Things will get a bit complex by the end, but please don’t think you need to use everything we’ll talk about. In fact, for the vast majority of apps, single flight mutations probably won’t matter at all. And don’t be fooled: simply re-fetching some data in a server function might be good enough for a lot of smaller apps as well.<\/p>\n\n\n\n

    But in going through all of this we’ll get to see some really cool TanStack, and even TypeScript features. Even if you never use what we go over for single flight mutations, there’s a good chance this content will come in handy for something else.<\/p>\n\n\n\n

    Our First Middleware<\/h2>\n\n\n\n

    TanStack Query<\/a> (which we sometimes refer to as react-query, it’s package name) already has a wonderful system of hierarchical keys. Wouldn’t it be great if we could just have our middleware receive the query keys of what we want to refetch, and have it just… work? Have the middleware figure out how<\/em> to refetch does seem tricky, at first. Sure, our queries have all been simple calls (by design) to server functions. But we can’t pass a server function reference up to the server; functions are not serializable. How could they be? You can send strings and numbers (and booleans) across the wire, serialized as JSON, but sending a function (which can have state, close over context, etc) makes no sense.<\/p>\n\n\n\n

    Unless<\/em> they’re TanStack Start server functions, that is. <\/p>\n\n\n\n

    It turns out the incredible engineers behind this project customized their serialization engine to support server functions. That means you can send a server function to the server, from the client, and it will work fine. Under the covers, server functions have an internal ID. TanStack picks this up, sends the ID, and then de-serializes the ID on the other end.<\/p>\n\n\n\n

    To make this even easier, why don\u2019t we just attach the server function (and the argument it takes) right in to the query options we already have defined. Then our middleware can take the query keys we want re-fetched, look up the query from TanStack Query internals (which we’ll dive into) and just make everything work.<\/p>\n\n\n\n

    Let’s Get Started<\/h2>\n\n\n\n

    First we’ll import some goodies<\/p>\n\n\n

    import<\/span> { createMiddleware, getRouterInstance } from<\/span> \"@tanstack\/react-start\"<\/span>;\nimport<\/span> { QueryClient, QueryKey } from<\/span> \"@tanstack\/react-query\"<\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Next, let’s update our query options for our epics list query (the main list of epics).<\/p>\n\n\n
    export<\/span> const<\/span> epicsQueryOptions = (page<\/span>: number<\/span><\/span>) =><\/span> {\n  return<\/span> queryOptions({\n    queryKey: [\"epics\"<\/span>, \"list\"<\/span>, page],\n    queryFn: async<\/span> () => {\n      const<\/span> result = await<\/span> getEpicsList({ data: page });\n      return<\/span> result;\n    },\n    staleTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    gcTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    meta: {\n      __revalidate: {\n        serverFn: getEpicsList,\n        arg: page,\n      },\n    },\n  });\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Note the new meta<\/code> section. This allows us to add any random metadata that we want to our query. Here we send over a reference to the getEpicsList<\/code> server function, and the arg it takes. If this duplication makes you uneasy, stay tuned. We’ll also update the summary query (for the counts) the same way, though that’s not shown here.<\/p>\n\n\n\n
    Let’s build this middleware piece by piece.<\/p>\n\n\n
    \/\/ the server function and args are all `any`, for now, <\/span>\n\/\/ to keep things simple we'll see how to type them in a bit<\/span>\ntype<\/span> RevalidationPayload = {\n  refetch: {\n    key: QueryKey;\n    fn: any<\/span>;\n    arg: any<\/span>;\n  }[];\n};\n\ntype<\/span> RefetchMiddlewareConfig = {\n  refetch: QueryKey[];\n};\n\nexport<\/span> const<\/span> refetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .inputValidator((config<\/span>?: RefetchMiddlewareConfig<\/span><\/span>) =><\/span> config)\n  .client(async<\/span> ({ next, data }) => {\n    const<\/span> { refetch = [] } = data ?? {};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We define an input to the middleware. This input will automatically get merged<\/em> with whatever input is defined on any server function this middleware winds up attached to.<\/p>\n\n\n\n
    We define our input as optional (config?<\/code>) since it’s entirely possible we might want to sometimes call our server function and simply not refetch anything.<\/p>\n\n\n\n
    Now we start our client callback, which runs directly in our browser. We’ll first grab the array of query keys we want refetched.<\/p>\n\n\n
    const<\/span> { refetch = [] } = data ?? {};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Then we’ll get our queryClient<\/code> and the cache attached to it, and define the payload we’ll send to the server callback of our middleware, which will do the actual refetching.<\/p>\n\n\n\n
    const<\/span> router = await<\/span> getRouterInstance();\nconst<\/span> queryClient: QueryClient = router.options.context.queryClient;\nconst<\/span> cache = queryClient.getQueryCache();\n\nconst<\/span> revalidate: RevalidationPayload = {\n  refetch: [],\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Our queryClient<\/code> is already attached to the main TanStack router context, so we can get the router, and just grab it.<\/p>\n\n\n\n
    Remember before when we added that __revalidate<\/code> payload to our query options, with the server function, and arg? Let’s look in our query cache for each key, and retrieve the query options for them.<\/p>\n\n\n
    refetch.forEach((key<\/span>: QueryKey<\/span><\/span>) =><\/span> {\n  const<\/span> entry = cache.find({ queryKey: key, exact: true<\/span> });\n  if<\/span> (!entry) return<\/span>;\n\n  const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\n  if<\/span> (revalidatePayload) {\n    revalidate.refetch.push({\n      key,\n      fn: revalidatePayload.serverFn,\n      arg: revalidatePayload.arg,\n    });\n  }\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The check if (!entry) return;<\/code> protects us from refetches being requested for queries that don’t exist in cache\u2014ie, if they’ve never been fetched in the UI. If that happens, just skip to the next one. We have no way to refetch it if we don’t have the serverFn<\/code>.<\/p>\n\n\n\n
    You could expand the input to this middleware and send up a different payload of query keys, along with the actual refetching payload (including server function and arg) for queries you absolutely want run, even if they haven’t yet been requested. Perhaps you’re planning on redirecting after the mutation, and you want that new page’s data prefetched. We won’t implement that here, but it’s just a variation on this same theme. These pieces are all very composable, so build whatever you happen to need!<\/p>\n\n\n\n
    This code then grabs the meta object, and puts the properties onto the payload we’ll send to the server.<\/p>\n\n\n
    const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\nif<\/span> (revalidatePayload) {\n  revalidate.refetch.push({\n    key,\n    fn: revalidatePayload.serverFn,\n    arg: revalidatePayload.arg,\n  });\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Try not to let the various any<\/code> types bother you; I’m omitting some type definitions that would have been straightforward to define, in order to help prevent this long post from getting even longer.<\/p>\n\n\n\n
    Calling next<\/code> triggers the actual invocation of the server function (and any other middleware in the chain). The sendContext<\/code> arg allows us to send data from<\/em> the client, up to<\/em> the server. The server is allowed to call next<\/code> with a sendContext<\/code> payload that sends data back to the client.<\/p>\n\n\n
    const<\/span> result = await<\/span> next({\n  sendContext: {\n    revalidate,\n  },\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The result<\/code> payload is what comes back from the server function invocation. The context object on it will have a payloads array, returned from the .server<\/code> callback just below, with entries containing a key (the query key), and result (the actual data). We’ll loop it, and update the query data accordingly.<\/p>\n\n\n\n
    We’ll fix the TS error covered up with \/\/ @ts-expect-error<\/code> momentarily.<\/p>\n\n\n
    \/\/ @ts-expect-error<\/span>\nfor<\/span> (const<\/span> entry of result.context?.payloads ?? []) {\n  queryClient.setQueryData(entry.key, entry.result);\n}\n\nreturn<\/span> result;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The Server Callback<\/h2>\n\n\n\n
    The server callback looks like this, in its entirety.<\/p>\n\n\n
    .server(async<\/span> ({ next, context }) => {\n  const<\/span> result = await<\/span> next({\n    sendContext: {\n      payloads: [] as<\/span> any<\/span>[]\n    }\n  });\n\n  const<\/span> allPayloads = context.revalidate.refetch.map(refetchPayload<\/span> =><\/span> {\n    return<\/span> {\n      key: refetchPayload.key,\n      result: refetchPayload.fn({ data: refetchPayload.arg })\n    };\n  });\n\n  for<\/span> (const<\/span> refetchPayload of allPayloads) {\n    result.sendContext.payloads.push({\n      key: refetchPayload.key,\n      result: await<\/span> refetchPayload.result\n    });\n  }\n\n  return<\/span> result;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We immediately call next()<\/code>, which runs the actual server function this middleware is attached to. We pass a payloads<\/code> array in sendContext<\/code>. This governs what gets sent back<\/em> to the client callback (that’s how .client<\/code> got the payloads array we just saw it looping through).<\/p>\n\n\n\n
    Then we run through the revalidate payloads sent up from the client. The client sent them via sendContext<\/code>, and we read them from the context object (send<\/em> context, get it?). We then call all the server functions, and add to that payloads array.<\/p>\n\n\n\n
    Here’s the entire middleware:<\/p>\n\n\n
    export<\/span> const<\/span> refetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .inputValidator((config<\/span>?: RefetchMiddlewareConfig<\/span><\/span>) =><\/span> config)\n  .client(async<\/span> ({ next, data }) => {\n    const<\/span> { refetch = [] } = data ?? {};\n\n    const<\/span> router = await<\/span> getRouterInstance();\n    const<\/span> queryClient: QueryClient = router.options.context.queryClient;\n    const<\/span> cache = queryClient.getQueryCache();\n\n    const<\/span> revalidate: RevalidationPayload = {\n      refetch: [],\n    };\n\n    refetch.forEach((key<\/span>: QueryKey<\/span><\/span>) =><\/span> {\n      const<\/span> entry = cache.find({ queryKey: key, exact: true<\/span> });\n      if<\/span> (!entry) return<\/span>;\n\n      const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\n      if<\/span> (revalidatePayload) {\n        revalidate.refetch.push({\n          key,\n          fn: revalidatePayload.serverFn,\n          arg: revalidatePayload.arg,\n        });\n      }\n    });\n\n    const<\/span> result = await<\/span> next({\n      sendContext: {\n        revalidate,\n      },\n    });\n\n    \/\/ @ts-expect-error<\/span>\n    for<\/span> (const<\/span> entry of result.context?.payloads ?? []) {\n      queryClient.setQueryData(entry.key, entry.result);\n    }\n\n    return<\/span> result;\n  })\n  .server(async<\/span> ({ next, context }) => {\n    const<\/span> result = await<\/span> next({\n      sendContext: {\n        payloads: [] as<\/span> any<\/span>[],\n      },\n    });\n\n    const<\/span> allPayloads = context.revalidate.refetch.map(refetchPayload<\/span> =><\/span> {\n      return<\/span> {\n        key: refetchPayload.key,\n        result: refetchPayload.fn({ data: refetchPayload.arg }),\n      };\n    });\n\n    for<\/span> (const<\/span> refetchPayload of allPayloads) {\n      result.sendContext.payloads.push({\n        key: refetchPayload.key,\n        result: await<\/span> refetchPayload.result,\n      });\n    }\n\n    return<\/span> result;\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Fixing the TypeScript Error<\/h2>\n\n\n\n
    Why is this line invalid?<\/p>\n\n\n
    \/\/ @ts-expect-error<\/span>\nfor<\/span> (const<\/span> entry of result.context?.payloads ?? []) {<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    This line runs in the .client<\/code> callback, after<\/em> we call next()<\/code>. Essentially, we’re trying to read properties sent back to the client, from the server (via the sendContext<\/code> payload). This runs, and works properly. But why don’t the types line up?<\/p>\n\n\n\n
    I covered this in my Middleware post linked above, but our server callback can see what gets sent to it from the client, but the reverse is not true. This knowledge just inherently does not go in both directions; the type inference cannot run backwards.<\/p>\n\n\n\n
    The solution is simple: just break the middleware into two pieces, and make one of them a middleware dependency on the other.<\/p>\n\n\n
    const<\/span> prelimRefetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .inputValidator((config<\/span>?: RefetchMiddlewareConfig<\/span><\/span>) =><\/span> config)\n  .client(async<\/span> ({ next, data }) => {\n    const<\/span> { refetch = [] } = data ?? {};\n\n    const<\/span> router = await<\/span> getRouterInstance();\n    const<\/span> queryClient: QueryClient = router.options.context.queryClient;\n\n    \/\/ same<\/span>\n    \/\/ as<\/span>\n    \/\/ before<\/span>\n\n    return<\/span> await<\/span> next({\n      sendContext: {\n        revalidate,\n      },\n    });\n\n    \/\/ those last few lines are removed<\/span>\n  })\n  .server(async<\/span> ({ next, context }) => {\n    const<\/span> result = await<\/span> next({\n      sendContext: {\n        payloads: [] as<\/span> any<\/span>[],\n      },\n    });\n\n    \/\/ exactly the same as before<\/span>\n\n    return<\/span> result;\n  });\n\nexport<\/span> const<\/span> refetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .middleware([prelimRefetchMiddleware]) \/\/ <-------- connect them!<\/span>\n  .client(async<\/span> ({ next }) => {\n    const<\/span> result = await<\/span> next();\n\n    const<\/span> router = await<\/span> getRouterInstance();\n    const<\/span> queryClient: QueryClient = router.options.context.queryClient;\n\n    \/\/ and here's those last few lines we removed from above<\/span>\n    for<\/span> (const<\/span> entry of result.context?.payloads ?? []) {\n      queryClient.setQueryData(entry.key, entry.result);\n    }\n\n    return<\/span> result;\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    It’s the same as before, except everything in the .client<\/code> callback after<\/em> the call to next()<\/code> is now in its own middleware. The rest is in a different middleware, which is an input to this one. Now when we call next<\/code> in refetchMiddleware<\/code>, TypeScript is able to see the data that’s been sent down from the server, since that was done in prelimRefetchMiddleware<\/code>, which is an input<\/em> to this middleware, which allows TypeScript to fully see the flow of types.<\/p>\n\n\n\n
    Wiring it Up<\/h2>\n\n\n\n
    Now we can take our server function for updating an epic, remove the refecthes, and add our refetch middleware.<\/p>\n\n\n
    export<\/span> const<\/span> updateEpic = createServerFn({ method: \"POST\"<\/span> })\n  .middleware([refetchMiddleware])\n  .inputValidator((obj<\/span>: { id<\/span>: number<\/span>; name<\/span>: string<\/span> }<\/span>) =><\/span> obj)\n  .handler(async<\/span> ({ data }) => {\n    await<\/span> new<\/span> Promise<\/span>(resolve<\/span> =><\/span> setTimeout(resolve, 1000<\/span> * Math<\/span>.random()));\n    await<\/span> db.update(epicsTable).set({ name: data.name }).where(eq(epicsTable.id, data.id));\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We set it up to call from our React component with the useServerFn<\/code> hook, which handles things like errors and redirects automatically.<\/p>\n\n\n
    const<\/span> runSave = useServerFn(updateEpic);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Remember when I said that inputs to middleware are automatically merged with inputs to the underlying server function? We can see that first hand when we call the server function.<\/p>\n\n\n\n
    \"A
    (unknown[]<\/code> is the correct type for react-query query keys)<\/figcaption><\/figure>\n\n\n\n
    Now we can call it, and specify the queries we want refetched.<\/p>\n\n\n
    await<\/span> runSave({\n  data: {\n    id: epic.id,\n    name: newValue,\n    refetch: [\n      [\"epics\"<\/span>, \"list\"<\/span>, 1<\/span>],\n      [\"epics\"<\/span>, \"list\"<\/span>, \"summary\"<\/span>],\n    ],\n  },\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    When we run it, it works. Both the list of epics, and also the summary list correctly update with our changes, without<\/em> any new requests in the network tab. When testing single flight mutations, we’re not really looking for something<\/em> to indicate that it worked, but rather a lack of<\/em> new network requests, for updated data.<\/p>\n\n\n\n
    Improving Things<\/h2>\n\n\n\n
    Query keys are hierarchical in react-query. You might already be familiar with this. Normally, when updating data, it would be common to do something like:<\/p>\n\n\n
    queryClient.invalidateQueries({ queryKey: [\"epics\"<\/span>, \"list\"<\/span>] });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Which refetches any<\/em> queries whose key starts with<\/em> [\"epics\", \"list\"]<\/code>. Can we do something similar in our middleware? Like, just pass in that key prefix, and have it find, and refetch whatever’s there?<\/p>\n\n\n\n
    Let’s do it!<\/p>\n\n\n\n
    Getting the matching keys will be slightly<\/em> more complicated. Each key we pass up will potentially be a key prefix, matching multiple entries, so we\u2019ll use flatMap<\/code> to find all matches, with the nifty cache.findAll<\/code> method.<\/p>\n\n\n
    const<\/span> allQueriesFound = refetch.flatMap(\n  k<\/span> =><\/span> cache.findAll({ queryKey: k, exact: false<\/span> })\n);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Now we loop them, and do the same thing as before.<\/p>\n\n\n
    const<\/span> allQueriesFound = refetch.flatMap(\n  k<\/span> =><\/span> cache.findAll({ queryKey: k, exact: false<\/span> })\n);\n\nallQueriesFound.forEach(entry<\/span> =><\/span> {\n  const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\n  if<\/span> (revalidatePayload) {\n    revalidate.refetch.push({\n      key: entry.queryKey,\n      fn: revalidatePayload.serverFn,\n      arg: revalidatePayload.arg,\n    });\n  }\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    This works!<\/p>\n\n\n\n
    Going Deeper<\/h2>\n\n\n\n
    Our solution still isn’t ideal. What if we page around in our epics page (up to page 2, up to page 3, then back down). Our solution will find page 1, and our summary query, but also pages 2 and 3, since they’re now in cache. But pages 2 and 3 aren’t really active, and we shouldn’t refetch them, since they’re not even being displayed.<\/p>\n\n\n\n
    Let’s change our code to only refetch active queries. Detecting whether a query entry is actually active is as simple as adding the type<\/code> argument to findAll<\/code>.<\/p>\n\n\n
    cache.findAll({ queryKey: key, exact: false<\/span>, type<\/span>: \"active\"<\/span> });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Our code now looks like this:<\/p>\n\n\n
    const<\/span> allQueriesFound = refetch.flatMap(key<\/span> =><\/span> cache.findAll({ queryKey: key, exact: false<\/span>, type<\/span>: \"active\"<\/span> }));\n\nallQueriesFound.forEach(entry<\/span> =><\/span> {\n  const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\n  if<\/span> (revalidatePayload) {\n    revalidate.refetch.push({\n      key: entry.queryKey,\n      fn: revalidatePayload.serverFn,\n      arg: revalidatePayload.arg,\n    });\n  }\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Even Deeper<\/h2>\n\n\n\n
    This works. But when you think about it, those other, inactive queries should probably be invalidated. We don’t want to waste resources refetching them immediately, since they’re not being used; but if the user were to browse back to those pages, we probably want the data refetched. Tanstack Query makes that easy, via the invalidateQueries<\/code> method.<\/p>\n\n\n\n
    We’ll add this to the client callback of the middleware we feed into.<\/p>\n\n\n
    data?.refetch.forEach(key<\/span> =><\/span> {\n  queryClient.invalidateQueries({ queryKey: key, exact: false<\/span>, type<\/span>: \"inactive\"<\/span>, refetchType: \"none\"<\/span> });\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Loop the query keys we passed in, and invalidate any of the inactive queries (the active ones have already been refetched), but without refetching them.<\/p>\n\n\n\n
    Here’s our entire, updated middleware.<\/p>\n\n\n
    const<\/span> prelimRefetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .inputValidator((config<\/span>?: RefetchMiddlewareConfig<\/span><\/span>) =><\/span> config)\n  .client(async<\/span> ({ next, data }) => {\n    const<\/span> { refetch = [] } = data ?? {};\n\n    const<\/span> router = await<\/span> getRouterInstance();\n    const<\/span> queryClient: QueryClient = router.options.context.queryClient;\n    const<\/span> cache = queryClient.getQueryCache();\n\n    const<\/span> revalidate: RevalidationPayload = {\n      refetch: [],\n    };\n\n    const<\/span> allQueriesFound = refetch.flatMap(key<\/span> =><\/span> cache.findAll({ queryKey: key, exact: false<\/span>, type<\/span>: \"active\"<\/span> }));\n\n    allQueriesFound.forEach(entry<\/span> =><\/span> {\n      const<\/span> revalidatePayload: any<\/span> = entry?.meta?.__revalidate ?? null<\/span>;\n\n      if<\/span> (revalidatePayload) {\n        revalidate.refetch.push({\n          key: entry.queryKey,\n          fn: revalidatePayload.serverFn,\n          arg: revalidatePayload.arg,\n        });\n      }\n    });\n\n    return<\/span> await<\/span> next({\n      sendContext: {\n        revalidate,\n      },\n    });\n  })\n  .server(async<\/span> ({ next, context }) => {\n    const<\/span> result = await<\/span> next({\n      sendContext: {\n        payloads: [] as<\/span> any<\/span>[],\n      },\n    });\n\n    const<\/span> allPayloads = context.revalidate.refetch.map(refetchPayload<\/span> =><\/span> {\n      return<\/span> {\n        key: refetchPayload.key,\n        result: refetchPayload.fn({ data: refetchPayload.arg }),\n      };\n    });\n\n    for<\/span> (const<\/span> refetchPayload of allPayloads) {\n      result.sendContext.payloads.push({\n        key: refetchPayload.key,\n        result: await<\/span> refetchPayload.result,\n      });\n    }\n\n    return<\/span> result;\n  });\n\nexport<\/span> const<\/span> refetchMiddleware = createMiddleware({ type<\/span>: \"function\"<\/span> })\n  .middleware([prelimRefetchMiddleware])\n  .client(async<\/span> ({ data, next }) => {\n    const<\/span> result = await<\/span> next();\n\n    const<\/span> router = await<\/span> getRouterInstance();\n    const<\/span> queryClient: QueryClient = router.options.context.queryClient;\n\n    for<\/span> (const<\/span> entry of result.context?.payloads ?? []) {\n      queryClient.setQueryData(entry.key, entry.result, { updatedAt: Date<\/span>.now() });\n    }\n\n    data?.refetch.forEach(key<\/span> =><\/span> {\n      queryClient.invalidateQueries({ queryKey: key, exact: false<\/span>, type<\/span>: \"inactive\"<\/span>, refetchType: \"none\"<\/span> });\n    });\n\n    return<\/span> result;\n  });<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We tell TanStack Query to invalidate (but not refetch) any inactive queries matching our key.<\/p>\n\n\n\n
    This works perfectly. If we browse up to pages 2 and 3, and then back to page 1, then edit a todo, we do in fact see our list, and summary list update. If we then page back to page 2, and 3, we’ll see network requests fire to get fresh data.<\/p>\n\n\n\n
    Icing on the Cake<\/h2>\n\n\n\n
    Remember when we added the server function, and the arg it takes to our query options?<\/p>\n\n\n
    export<\/span> const<\/span> epicsQueryOptions = (page<\/span>: number<\/span><\/span>) =><\/span> {\n  return<\/span> queryOptions({\n    queryKey: [\"epics\"<\/span>, \"list\"<\/span>, page],\n    queryFn: async<\/span> () => {\n      const<\/span> result = await<\/span> getEpicsList({ data: page });\n      return<\/span> result;\n    },\n    staleTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    gcTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    meta: {\n      __revalidate: {\n        serverFn: getEpicsList,\n        arg: page,\n      },\n    },\n  });\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    I briefly noted that it was a bit gross to duplicate the server function, and arg in both our meta<\/code> object, and our queryFn<\/code>. Let’s fix this.<\/p>\n\n\n\n
    Let’s start with the simplest possible helper to remove this duplication, and as before, iterate on it.<\/p>\n\n\n
    export<\/span> function<\/span> refetchedQueryOptions<\/span>(queryKey: QueryKey, serverFn: any<\/span>, arg?: any<\/span><\/span>) <\/span>{\n  const<\/span> queryKeyToUse = [...queryKey];\n  if<\/span> (arg != null<\/span>) {\n    queryKeyToUse.push(arg);\n  }\n  return<\/span> queryOptions({\n    queryKey: queryKeyToUse,\n    queryFn: async<\/span> () => {\n      return<\/span> serverFn({ data: arg });\n    },\n    meta: {\n      __revalidate: {\n        serverFn,\n        arg,\n      },\n    },\n  });\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    It’s just a simple helper that takes in your query key, server function and arg, and returns back some of our query options: our queryKey<\/code> (to which we add whatever argument we need for the server function), the queryFn<\/code> which calls the server function, and our meta object.<\/p>\n\n\n\n
    Our epics list query now looks like this:<\/p>\n\n\n
    export<\/span> const<\/span> epicsQueryOptions = (page<\/span>: number<\/span><\/span>) =><\/span> {\n  return<\/span> queryOptions({\n    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>], getEpicsList, page),\n    staleTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    gcTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n  });\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    This works, but it’s not great. We have any<\/code> types everywhere, which means the argument we pass to our server function is never type checked. Even worse, the return value of our queryFn<\/code> is not type checked, which means our queries (like this very epics list query) now return any<\/code>.<\/p>\n\n\n\n
    Let’s add some typings. Server functions are just functions. They take a single object argument, and if the server function has defined an input, then that argument will have a data property for that argument. That’s a lot of words to say what we already know. When we call a server function, we pass our argument like this<\/p>\n\n\n
    const<\/span> result = await<\/span> runSaveSimple({\n  data: {\n    id: epic.id,\n    name: newValue,\n  },\n});<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    How’s this for a second draft?<\/p>\n\n\n
    export<\/span> function<\/span> refetchedQueryOptions<\/span><T<\/span> extends<\/span> (arg: { data: any<\/span> }<\/span>) => Promise<\/span><any<\/span>>>(\n  queryKey: QueryKey,\n  serverFn: T,\n  arg: Parameters<T>[0][\"data\"],\n<\/span>) <\/span>{\n  const<\/span> queryKeyToUse = [...queryKey];\n  if<\/span> (arg != null<\/span>) {\n    queryKeyToUse.push(arg);\n  }\n  return<\/span> queryOptions({\n    queryKey: queryKeyToUse,\n    queryFn: async<\/span> (): Promise<\/span><Awaited<ReturnType<T>>> => {\n      return<\/span> serverFn({ data: arg });\n    },\n    meta: {\n      __revalidate: {\n        serverFn,\n        arg,\n      },\n    },\n  });\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    We’ve constrained our server function to an async function which takes a data<\/code> prop on its object arg, and we’ve used that to statically type the argument. This is good, but we get an error when we use this on server functions which have no arguments.<\/p>\n\n\n
    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>, \"summary\"<\/span>], getEpicsSummary)\n\/\/ Expected 3 arguments, but got 2.<\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Adding an undefined<\/code> does fix this, and everything works.<\/p>\n\n\n
    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>, \"summary\"<\/span>], getEpicsSummary, undefined<\/span>),<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    If you’re normal, you’re probably happy with that. And you should be. But if you’re weird like me, you might wonder if you can’t make it perfect. Ideally it would be cool if we could pass a statically typed argument when using a server function that takes an input, and when using a server function with no input, pass nothing.<\/p>\n\n\n\n
    TypeScript has a feature exactly for this: overloaded functions<\/strong>.<\/p>\n\n\n\n
    This post is already far too long, so I’ll post the code, and leave deciphering it as an exercise for the reader (and likely a future blog post).<\/p>\n\n\n
    import<\/span> { QueryKey, queryOptions } from<\/span> \"@tanstack\/react-query\"<\/span>;\n\ntype<\/span> AnyAsyncFn = (...args<\/span>: any<\/span>[]<\/span>) =><\/span> Promise<\/span><any<\/span>>;\n\ntype<\/span> ServerFnArgs<TFn extends<\/span> AnyAsyncFn> = Parameters<TFn>[0<\/span>] extends<\/span> infer TRootArgs\n  ? TRootArgs extends<\/span> { data: infer TResult }\n    ? TResult\n    : undefined<\/span>\n  : never;\n\ntype<\/span> ServerFnHasArgs<TFn extends<\/span> AnyAsyncFn> = ServerFnArgs<TFn> extends<\/span> infer U ? (U extends<\/span> undefined<\/span> ? false<\/span> : true<\/span>) : false<\/span>;\n\ntype<\/span> ServerFnWithArgs<TFn extends<\/span> AnyAsyncFn> = ServerFnHasArgs<TFn> extends<\/span> true<\/span> ? TFn : never;\ntype<\/span> ServerFnWithoutArgs<TFn extends<\/span> AnyAsyncFn> = ServerFnHasArgs<TFn> extends<\/span> false<\/span> ? TFn : never;\n\ntype<\/span> RefetchQueryOptions<T> = {\n  queryKey: QueryKey;\n  queryFn?: (_: any<\/span><\/span>) =><\/span> Promise<\/span><T>;\n  meta?: any<\/span>;\n};\n\ntype<\/span> ValidateServerFunction<Provided, Expected> = Provided extends<\/span> Expected ? Provided : \"This server function requires an argument!\"<\/span>;\n\nexport<\/span> function<\/span> refetchedQueryOptions<\/span><TFn<\/span> extends<\/span> AnyAsyncFn<\/span>>(\n  queryKey: QueryKey,\n  serverFn: ServerFnWithArgs<TFn>,\n  arg: Parameters<TFn>[0][\"data\"],\n<\/span>): RefetchQueryOptions<\/span><Awaited<\/span><ReturnType<\/span><TFn<\/span>>>><\/span>;\nexport<\/span> function<\/span> refetchedQueryOptions<\/span><TFn<\/span> extends<\/span> AnyAsyncFn<\/span>>(\n  queryKey: QueryKey,\n  serverFn: ValidateServerFunction<TFn, ServerFnWithoutArgs<TFn>>,\n<\/span>): RefetchQueryOptions<\/span><Awaited<\/span><ReturnType<\/span><TFn<\/span>>>><\/span>;\nexport<\/span> function<\/span> refetchedQueryOptions<\/span><TFn<\/span> extends<\/span> AnyAsyncFn<\/span>>(\n  queryKey: QueryKey,\n  serverFn: ServerFnWithoutArgs<TFn> | ServerFnWithArgs<TFn>,\n  arg?: Parameters<TFn>[0][\"data\"],\n<\/span>): RefetchQueryOptions<\/span><Awaited<\/span><ReturnType<\/span><TFn<\/span>>>> <\/span>{\n  const<\/span> queryKeyToUse = [...queryKey];\n  if<\/span> (arg != null<\/span>) {\n    queryKeyToUse.push(arg);\n  }\n  return<\/span> queryOptions({\n    queryKey: queryKeyToUse,\n    queryFn: async<\/span> () => {\n      return<\/span> serverFn({ data: arg });\n    },\n    meta: {\n      __revalidate: {\n        serverFn,\n        arg,\n      },\n    },\n  });\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    With this in place we can now call it with server functions that take an argument.<\/p>\n\n\n
    export<\/span> const<\/span> epicsQueryOptions = (page<\/span>: number<\/span><\/span>) =><\/span> {\n  return<\/span> queryOptions({\n    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>], getEpicsList, page),\n    staleTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n    gcTime: 1000<\/span> * 60<\/span> * 5<\/span>,\n  });\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The parameter is now checked. It errors with the wrong type.<\/p>\n\n\n
    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>], getEpicsList, \"\"<\/span>)\n\/\/ Argument of type 'string' is not assignable to parameter of type 'number'.<\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    It errors if you pass no argument as well.<\/p>\n\n\n
    ...refetchedQueryOptions([\"epics\"<\/span>, \"list\"<\/span>], getEpicsList)\n\/\/ Argument of type 'RequiredFetcher<undefined, (page: number) => number, Promise<{ id: number; name: string; }[]>>' is not assignable to parameter of type '\"This server function requires an argument!\"'.<\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    That last error isn’t the clearest, but if you read to the end you get a pretty solid hint as to what’s wrong, thanks to this dandy little helper.<\/p>\n\n\n
    type<\/span> ValidateServerFunction<Provided, Expected> = Provided extends<\/span> Expected ? Provided : \"This server function requires an argument!\"<\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
    And it works with a server function that takes no arguments. Again, a full explanation of this TypeScript will have to wait for a future post.<\/p>\n\n\n\n
    Concluding Thoughts<\/h2>\n\n\n\n
    Single flight mutations are a great tool for speeding up updates within your web app, particularly when it’s a performance boost to avoid follow-up network requests for data after an initial mutation. Hopefully this post has shown you the tools needed to put it all together.<\/p>\n\n\n
    \n  
    \n    
    Article Series<\/h3>\n  <\/header>\n  
    \n            
      \n                      
    1. \n              Single Flight Mutations in TanStack Start: Part 1<\/a>\n            <\/li>\n                      
    2. \n              Single Flight Mutations in TanStack Start: Part 2<\/a>\n            <\/li>\n                  <\/ol>\n        <\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
      This post introduces a middleware approach that allows efficient data refetching. The middleware enables the attachment of query keys and server functions, enhancing scalability and flexibility.<\/p>\n","protected":false},"author":21,"featured_media":8372,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1],"tags":[174,3,240,184],"class_list":["post-8384","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-data","tag-javascript","tag-tanstack","tag-typescript"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/frontendmasters.com\/blog\/wp-content\/uploads\/2026\/01\/tanstack-round-trip.jpg?fit=2000%2C1200&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8384","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/comments?post=8384"}],"version-history":[{"count":13,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8384\/revisions"}],"predecessor-version":[{"id":8417,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8384\/revisions\/8417"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media\/8372"}],"wp:attachment":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media?parent=8384"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/categories?post=8384"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/tags?post=8384"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
    If you’ve never touched TanStack’s middleware before and are feeling overwhelmed, my middleware post<\/a> might be a good introduction.<\/p>\n\n\n