{"id":8524,"date":"2026-02-13T12:00:13","date_gmt":"2026-02-13T17:00:13","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=8524"},"modified":"2026-02-13T12:01:11","modified_gmt":"2026-02-13T17:01:11","slug":"fun-with-typescript-generics","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/fun-with-typescript-generics\/","title":{"rendered":"Fun with TypeScript Generics"},"content":{"rendered":"\n

Generics are an incredibly powerful feature of TypeScript<\/a>. There’s endless content on TypeScript in general, and generics in particular. This post will differ a bit and cover things more deeply.<\/p>\n\n\n\n

This won’t be a generic introduction to generics (pun intended). Instead, we’ll implement a very, very niche use case, and in the process cover some advanced uses for generics, plus conditional types, and some other goodies.<\/p>\n\n\n\n

A Quick Refresher on Generics & Conditional Types<\/h2>\n\n\n\n

Let’s take a very, very fast introduction to the key concepts of this post. We’ll use extremely contrived examples to keep everything as brief as possible.<\/p>\n\n\n\n

If you’re already an expert, just scroll past. If you’re not sure, give it a read, and if what’s in this section isn’t old hat, you might want to read some refresher materials before tackling the rest of this post.<\/p>\n\n\n\n

Generics<\/h3>\n\n\n\n

Think of generics as function parameters that are types. What do I mean by that? Normally function parameters are values<\/em> (or references to a value, but we won’t bother with that).<\/p>\n\n\n

function<\/span> arrayLength<\/span>(arr: any<\/span>[]<\/span>) <\/span>{\n  return<\/span> arr.length;\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Here, arr<\/code> is an array. Right now, it’s an array of any<\/code>. If we wanted, we could type this array a bit more accurately by adding a generic argument.<\/p>\n\n\n
function<\/span> arrayLengthTyped<\/span><T<\/span>>(arr: T[]<\/span>) <\/span>{\n  return<\/span> arr.length;\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now, whenever we call this method and pass an array, the generic argument T<\/code> will infer to whatever the type of the array is. Make no mistake, even though T<\/code> makes this method definition more accurate, it’s completely pointless. The original method was perfectly fine. The value of arr<\/code> is an array of any<\/code>, but it doesn’t matter; no matter what the elements of the array are, the .length<\/code> property will always be there.<\/p>\n\n\n\n
Let\u2019s go from one pointless function to another. Let\u2019s implement our own filter.<\/p>\n\n\n
function<\/span> filterUntyped<\/span>(array: any<\/span>[], predicate: (item: any<\/span>) => boolean<\/span><\/span>): any<\/span>[] <\/span>{\n  return<\/span> array.filter(predicate);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This time we actually have a problem. There’s absolutely no checking done on the predicate function we pass in.<\/p>\n\n\n
type<\/span> User = {\n  name: string<\/span>;\n};\n\nconst<\/span> users: User[] = [];\n\nfilterUntyped(users, user<\/span> =><\/span> user.nameX === \"John\"<\/span>);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We\u2019re passing in a function that takes each member of the array, but we\u2019re clearly misusing it; there is no nameX property on each user. This is where generics shine.<\/p>\n\n\n
function<\/span> filterTyped<\/span><T<\/span>>(array: T[], predicate: (item: T) => boolean<\/span><\/span>): T<\/span>[] <\/span>{\n  return<\/span> array.filter(predicate);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now TypeScript will verify everything.<\/p>\n\n\n\n
filterTyped(users, user => user.nameX === \"John\");
\/\/ -----------------------------^^^^^<\/em>
\/\/ Property 'nameX' does not exist on type 'User'. Did you mean 'name'?<\/em><\/pre>\n\n\n\n
We can even limit generic arguments. What if we have a bunch of different user types?<\/p>\n\n\n
type<\/span> User = {\n  name: string<\/span>;\n};\n\ntype<\/span> AdminUser = User & {\n  role: string<\/span>;\n};\n\ntype<\/span> BannedUser = User & {\n  reason: string<\/span>;\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
For whatever strange reason, we wanted to take the filterTyped<\/code> function from before.<\/p>\n\n\n
function<\/span> filterTyped<\/span><T<\/span>>(array: T[], predicate: (item: T) => boolean<\/span><\/span>): T<\/span>[] <\/span>{\n  return<\/span> array.filter(predicate);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
But this time have it only works with any User<\/code> type.<\/p>\n\n\n\n
If you’re thinking just ditch the generics altogether and…<\/em><\/p>\n\n\n
function<\/span> filterUser<\/span>(array: User[], predicate: (item: User) => boolean<\/span><\/span>): User<\/span>[] <\/span>{\n  return<\/span> array.filter(predicate);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
…not so fast. This function, while appealing, winds up erasing our return type.<\/p>\n\n\n
const<\/span> adminUsers: AdminUser[] = [];\nconst<\/span> adminUsersNamedAdam = filterUser(adminUsers, user<\/span> =><\/span> user.name === \"Adam\"<\/span>);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The variable adminUsersNamedAdam<\/code> is typed as User[]<\/code>, and how could it not be? filterUser<\/code> is explicitly typed to return User[].<\/code><\/p>\n\n\n\n
The correct solution is to go back to the generic version, but restrict<\/em> the acceptable values for T.<\/p>\n\n\n
function<\/span> filterUserCorrect<\/span><T<\/span> extends<\/span> User<\/span>>(array: T[], predicate: (item: T) => boolean<\/span><\/span>): T<\/span>[] <\/span>{\n  return<\/span> array.filter(predicate);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now our return type is correctly inferred: it’s the exact same type that we pass in for the array. But we\u2019re only able to invoke it with a type that matches the User<\/code> type, which is to say, has a name<\/code> property that\u2019s a string.<\/p>\n\n\n\n
Conditional Types<\/h3>\n\n\n\n
Conditional types allow us to, essentially, ask questions<\/em> about types and form new types based on the answers.<\/p>\n\n\n
type<\/span> IsArray<T> = T extends<\/span> any<\/span>[] ? true<\/span> : false<\/span>;\n\ntype<\/span> YesIsArray = IsArray<number<\/span>[]>;\ntype<\/span> NoIsNotArray = IsArray<number<\/span>>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Here YesIsArray<\/code> is the literal type true<\/code> while NoIsNotArray<\/code> is the literal type false<\/code>. This is obviously pointless; the real value of conditional types usually comes with inferred types.<\/p>\n\n\n
type ArrayOf<T<\/span>><\/span> = T extends Array<infer<\/span> U<\/span>><\/span> ? U : never;\n\ntype NumberType = ArrayOf<number[]<\/span>><\/span>;\ntype NeverType = ArrayOf<number<\/span>><\/span>;<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
Here the Number<\/code> type is number<\/code> and the NeverType type is, predictably, never<\/code>. And yes, we can (and should) use generic constraints with these helper types<\/p>\n\n\n
type ArrayOf2<T extends Array<\/span><any>> = T extends Array<\/span><infer U> ? U : never;\n\ntype NumberType2 = ArrayOf2<number[]>;\ntype NeverType2 = ArrayOf2<number>;\n\/\/ ------------------------^^^^^^^<\/span>\n\/\/ Type 'number' does not satisfy the constraint 'any[]'<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now we’re forbidden from using ArrayOf2<\/code> with any type that’s not an array of something, so we’ll never have to worry about getting never<\/code> back.<\/p>\n\n\n\n
Let’s Get Started<\/h2>\n\n\n\n
I recently wrote a two-part post on single flight mutations<\/a> using TanStack Start<\/a>. In order to make that work, we very carefully put together react-query options. Our query functions (which do the actual data fetching) were purposefully designed to be a single call against a TanStack Server Function. Then that same query function, as well as the argument payload it takes, were placed on react-query’s meta<\/code> option.<\/p>\n\n\n\n
Then, in middleware on the server, we received query keys and looked up the server function and argument payload for a query so we could refetch its data.<\/p>\n\n\n\n
As part of those efforts, we built a simple helper to remove the duplication between the query function and the meta option.<\/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\u2019s a helper that takes in the query key, the server function, and argument payload, if any, and returns back some<\/em> of our query options. It does this so the query function, and meta option will always be in sync with whatever server function is fetching our data. Then we compose it 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 proof-of-concept version worked fine, but nothing was typed. Our server function and argument payload were both marked as any<\/code>, which didn\u2019t just fail to restrict invalid argument payloads, but also, disastrously, led all query hooks that used this to report the queried data as any<\/code>.<\/p>\n\n\n\n
This post will implement a fully typed version of our refetchedQueryOptions<\/code> function. It’s much harder than it might appear!<\/p>\n\n\n\n
Our Success Criteria<\/h2>\n\n\n\n
Here’s our complete test setup.<\/p>\n\n\n
import<\/span> { QueryKey, queryOptions } from<\/span> \"@tanstack\/react-query\"<\/span>;\nimport<\/span> { createServerFn } from<\/span> \"@tanstack\/react-start\"<\/span>;\n\n\/\/ ============================ Current Implementation ============================<\/span>\n\nexport<\/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}\n\n\/\/ ============== Server Functions for testing ==============<\/span>\n\nconst<\/span> serverFnWithArgs = createServerFn({ method: \"GET\"<\/span> })\n  .inputValidator((arg<\/span>: { value<\/span>: string<\/span> }<\/span>) =><\/span> arg)\n  .handler(async<\/span> () => {\n    return<\/span> { value: \"Hello World\"<\/span> };\n  });\n\nconst<\/span> serverFnWithoutArgs = createServerFn({ method: \"GET\"<\/span> }).handler(async<\/span> () => {\n  return<\/span> { value: \"Hello World\"<\/span> };\n});\n\n\/\/ ============================ Tests ============================<\/span>\n\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs, { value: \"\"<\/span> });\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithoutArgs);\n\n\/\/ wrong argument type<\/span>\n\/\/ FAILS - Unused '@ts-expect-error' directive.<\/span>\n\/\/ @ts-expect-error<\/span>\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs, 123<\/span>);\n\n\/\/ need an argument<\/span>\n\/\/ FAILS - Unused '@ts-expect-error' directive.<\/span>\n\/\/ @ts-expect-error<\/span>\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
At the top we have the current iteration of our refetchedQueryOptions<\/code> method. Beneath that, we have some server functions that will help us test this, one with an argument, the other without. And beneath that, we see four calls to refetchedQueryOptions<\/code> to validate that our type checking is working properly. The top two we expect to succeed, and the bottom two we expect to error, which we verify with the \/\/ @ts-expect-error<\/code> directive. This directive, well, expects<\/em> an error on the very next line. If there is an error on the very next line, all is well; if there is no error on the next line, the @ts-expect-error<\/code> directive will itself raise an error.<\/p>\n\n\n\n
Above, with our initial implementation, we see our expected errors fail to error out. This makes sense, since everything is typed as any<\/code>, and our arg<\/code> parameter is optional, so really anything goes.<\/p>\n\n\n\n
Even if you’re more than willing to live with imperfect typings, this current solution isn’t good for much. Since serverFn<\/code> is typed as any, our queryFn<\/code> will return any<\/code>. That means any application code that’s using useQuery<\/code> or useSuspenseQuery<\/code> will now spit out any<\/code> for your data.<\/p>\n\n\n\n
The rest of this post will get everything typed properly. We’ll have to do some unhinged things, so hopefully we’ll learn something new and maybe even have some fun.<\/p>\n\n\n\n
Iteration 1<\/h2>\n\n\n\n
How’s this for a minimal improvement? Right now, the lack of a return type for the server function is absolutely killing us. Any usage of this query data will give use any<\/code>. We really<\/em> want our data properly typed in application code.<\/p>\n\n\n\n
TanStack Server functions are just… functions<\/em>. They’re special in that you can call them from the client or the server, but at the end of the day, they’re functions. They always take in a single argument that has a data<\/code> property for the standard arguments your function has defined (it also allows you to pass things like headers, but we won’t worry about that, here).<\/p>\n\n\n\n
Couldn’t we add a generic to our function, representing the server function? Once we have a function, we can use TypeScript’s built-in Parameters<\/code> and ReturnType<\/code> helpers. Let’s see what that looks like.<\/p>\n\n\n
export<\/span> function<\/span> refetchedQueryOptions<\/span><T<\/span> extends<\/span> (arg: { data: any<\/span> }<\/span>) => Promise<\/span><any<\/span>>>(<\/span><\/span>\n<\/span><\/span>  queryKey: QueryKey,<\/span><\/span><\/span>\n<\/span><\/span>  serverFn: T,<\/span><\/span><\/span>\n<\/span><\/span>  arg: Parameters<T>[0][\"data\"],<\/span><\/span><\/span>\n<\/span><\/mark><\/span>) <\/span>{<\/span>\n<\/span><\/span>  const<\/span> queryKeyToUse = [...queryKey];<\/span><\/span>\n<\/span><\/span>  if<\/span> (arg != null<\/span>) {<\/span><\/span>\n<\/span><\/span>    queryKeyToUse.push(arg);<\/span><\/span>\n<\/span><\/span>  }<\/span><\/span>\n<\/span><\/span>  return<\/span> queryOptions({<\/span><\/span>\n<\/span><\/span>    queryKey: queryKeyToUse,<\/span><\/span>\n<\/span><\/span>    queryFn: async<\/span> (): Promise<\/span><Awaited<ReturnType<T>>> => {<\/span><\/span>\n<\/span><\/mark>      return<\/span> serverFn({ data: arg });<\/span><\/span>\n<\/span><\/span>    },<\/span><\/span>\n<\/span><\/span>    meta: {<\/span><\/span>\n<\/span><\/span>      __revalidate: {<\/span><\/span>\n<\/span><\/span>        serverFn,<\/span><\/span>\n<\/span><\/span>        arg,<\/span><\/span>\n<\/span><\/span>      },<\/span><\/span>\n<\/span><\/span>    },<\/span><\/span>\n<\/span><\/span>  });<\/span><\/span>\n<\/span><\/span>}<\/span><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We constrain our generic to be a function that takes in an arg<\/code> with a data<\/code> property. Moreover, we can now use<\/em> our T<\/code> generic in the parameter definition of arg<\/code>, here arg: Parameters<T>[0][\"data\"]<\/code>. Whatever our function is, we say that arg<\/code> is the same type as the data<\/code> property on the main argument that the function takes in.<\/p>\n\n\n\n
How does this look? Let’s check our tests<\/p>\n\n\n
refetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs, { value: \"\"<\/span> });\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithoutArgs);\n\/\/ Error: Expected 3 arguments, but got 2.<\/span>\n\n\/\/ wrong argument type<\/span>\n\/\/ @ts-expect-error<\/span>\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs, 123<\/span>);\n\n\/\/ need an argument<\/span>\n\/\/ @ts-expect-error<\/span>\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We have one problem. It seems we need to pass an argument for the query function which\u2026 doesn\u2019t take any parameters. It makes sense: refetchedQueryOptions<\/code> does indeed define an arg<\/code> parameter, which needs to be passed. I’ll be quick to note that simply passing undefined<\/code> for that arg works perfectly.<\/p>\n\n\n
refetchedQueryOptions([\"test\"<\/span>], serverFnWithoutArgs, undefined<\/span>);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This solves all our problems; our test code now has zero errors. For the vast, vast majority of apps, this will likely be fine. It’s entirely possible the work I’m about to show you to improve on this may not be worth the effort. But<\/em>, going through that effort will likely teach us some neat things about TypeScript, and if we’re a special kind of strange, may even be fun.<\/p>\n\n\n\n
False Prophets<\/h2>\n\n\n\n
You might think making arg optional would solve all our problems. Unfortunately, when we do that, arg<\/code> becomes optional everywhere<\/em>, including places we want to require it<\/p>\n\n\n
\/\/ need an argument<\/span>\n\/\/ FAILS - Unused '@ts-expect-error' directive.<\/span>\n\/\/ @ts-expect-error<\/span>\nrefetchedQueryOptions([\"test\"<\/span>], serverFnWithArgs);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
If you’re an advanced TypeScript user you might think a conditional type is what we need. Detect the inferred arg type (what’s in the data<\/code> arg), and if it’s not undefined, require it, but if it is<\/em> undefined, then don’t<\/em> require it. Unfortunately, there’s not really an easy way to represent “pass nothing” as the result of a conditional type. I’ve tried, and I was never able to get things fully working. I may have been missing something (feel free to drop a comment if you can figure it out), but even if there’s a trick to make it work, there’s a much more straightforward, idiomatic solution.<\/p>\n\n\n\n
We essentially want different function signatures in different circumstances: we want an arg when the server function we pass in takes an arg, and we want no arg when the server function we pass in takes no arg. Different function signatures is usually referred to as function overloading in computer science, and TypeScript supports this.<\/p>\n\n\n\n
Function Overloading in TypeScript<\/h3>\n\n\n\n
As the simplest possible example, imagine you wanted to write an add<\/code> function with two versions: one that takes in two numbers, and adds them; and one that takes in two strings, and concatenates them. Conceptually, we want this:<\/p>\n\n\n
function<\/span> add<\/span>(x: number<\/span>, y: number<\/span><\/span>): number<\/span> <\/span>{\n  return<\/span> x + y;\n}\n\nfunction<\/span> add<\/span>(x: string<\/span>, y: string<\/span><\/span>): string<\/span> <\/span>{\n  return<\/span> x + y;\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
But that’s not valid; since JavaScript is a dynamically typed language, you can’t have more than one function of the same name, in the same scope. TypeScript<\/em> does, however, allow us to overload functions, but the mechanics are a bit different.<\/span> Here’s how we do this:<\/p>\n\n\n
function<\/span> add<\/span>(x: number<\/span>, y: number<\/span><\/span>): number<\/span><\/span>;\nfunction<\/span> add<\/span>(x: string<\/span>, y: string<\/span><\/span>): string<\/span><\/span>;\nfunction<\/span> add<\/span>(x: string<\/span> | number<\/span>, y: string<\/span> | number<\/span><\/span>): string<\/span> | number<\/span> <\/span>{\n  if<\/span> (typeof<\/span> x === \"string\"<\/span> && typeof<\/span> y === \"string\"<\/span>) {\n    return<\/span> x + y;\n  }\n  if<\/span> (typeof<\/span> x === \"number\"<\/span> && typeof<\/span> y === \"number\"<\/span>) {\n    return<\/span> x + y;\n  }\n  throw<\/span> new<\/span> Error<\/span>(\"Invalid arguments\"<\/span>);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We start with the function definitions<\/em>. This one:<\/p>\n\n\n
function<\/span> add<\/span>(x: number<\/span>, y: number<\/span><\/span>): number<\/span><\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
And this one:<\/p>\n\n\n
function<\/span> add<\/span>(x: string<\/span>, y: string<\/span><\/span>): string<\/span><\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
These define the actual API of our function. We declare that this function can take in two numbers and return a number, or two strings and return a string.<\/p>\n\n\n\n
Then we have the actual implementation of the function.<\/p>\n\n\n
function<\/span> add<\/span>(x: string<\/span> | number<\/span>, y: string<\/span> | number<\/span><\/span>): string<\/span> | number<\/span> <\/span>{\n  if<\/span> (typeof<\/span> x === \"string\"<\/span> && typeof<\/span> y === \"string\"<\/span>) {\n    return<\/span> x + y;\n  }\n  if<\/span> (typeof<\/span> x === \"number\"<\/span> && typeof<\/span> y === \"number\"<\/span>) {\n    return<\/span> x + y;\n  }\n  throw<\/span> new<\/span> Error<\/span>(\"Invalid arguments\"<\/span>);\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The inputs and return types all have to be a union of every definition. In other words, the actual implementation has to accept any of the definitions.<\/p>\n\n\n\n
And now, when we try to call this function, we only see the definitions available to us.<\/p>\n\n\n
\n
\"Code<\/figure>\n<\/div>\n\n
\n
\"\"<\/figure>\n<\/div>\n\n\n
The implementation is a little weird. You might wonder why we need<\/p>\n\n\n
throw<\/span> new<\/span> Error<\/span>(\"Invalid arguments\"<\/span>);<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The only valid invocations for this function are two strings or two numbers; that’s all TypeScript will allow. So why does TypeScript require us to have that throw at the end? If both arguments are not strings, and neither argument is a number, the function will never be allowed. Unfortunately, TypeScript isn’t quite smart enough to understand that. The function implementation has x and y both as string | number<\/code> so as far as it’s concerned, x<\/code> could be a string and y<\/code> could be a number. Understanding that this combination is disallowed by the prior overload definitions isn’t currently within TypeScript’s capabilities.<\/p>\n\n\n\n
Building Our Solution<\/h2>\n\n\n\n
So we want to overload refetchedQueryOptions<\/code> twice: once for a server function that takes in an argument, and once for a server function that takes no arguments. How do we define either case? This is where things get fun.<\/p>\n\n\n\n
To start, let’s define a type representing any async function<\/p>\n\n\n
type<\/span> AnyAsyncFn = (...args<\/span>: any<\/span>[]<\/span>) =><\/span> Promise<\/span><any<\/span>>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This seems like a waste of time, but it’ll save us some typing and add a lot of clarity soon.<\/p>\n\n\n\n
Let\u2019s define a type that takes in an async function and just strips out the argument type. A conditional type is perfect for this. We saw something similar before with a conditional type that strips out the type of an array’s elements.<\/p>\n\n\n
type<\/span> ArrayOf<T extends<\/span> Array<\/span><any<\/span>>> = T extends<\/span> Array<\/span><infer U> ? U : never;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We check that T extends an array, and then we plopped infer U<\/code> right into the generic slot the Array type already has. Let’s do something similar to get the parameter type of an async function.<\/p>\n\n\n
type<\/span> ServerFnArgs<TFn extends<\/span> AnyAsyncFn> = Parameters<TFn>[0<\/span>] extends<\/span> { data: infer TResult } ? TResult : undefined<\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
There’s a Parameters<T><\/code> type that can pluck parameters out of a function type. We grab the zero’th parameter (functions can have multiple parameters, but server functions only have one). On that single, 0th parameter, look for a data<\/code> property, and if present, infer that. Otherwise return undefined.<\/p>\n\n\n\n
From there we can start to ask questions about our types.<\/p>\n\n\n
type<\/span> ServerFnHasArgs<TFn extends<\/span> AnyAsyncFn> = ServerFnArgs<TFn> extends<\/span> undefined<\/span> ? false<\/span> : true<\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
And we can then make other type helpers.<\/p>\n\n\n
type<\/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;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
We’ve built some helper types that take a function type in, and tests whether that function has, or does not have server function arguments.<\/p>\n\n\n\n
One major bummer of TypeScript overloading is that we can’t rely on inferred return types, so we’ll have to define our return type manually.<\/p>\n\n\n
type<\/span> RefetchQueryOptions<T> = {\n  queryKey: QueryKey;\n  queryFn: (_?: any<\/span><\/span>) =><\/span> Promise<\/span><T>;\n  meta: any<\/span>;\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
And with that, we should be ready to define our overload signatures.<\/p>\n\n\n
export<\/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: ServerFnWithoutArgs<TFn>,\n<\/span>): RefetchQueryOptions<\/span><Awaited<\/span><ReturnType<\/span><TFn<\/span>>>><\/span>;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
One version for a Server Function that takes an argument, as well as the argument, and a version for a Server Function that takes no argument, with no such argument passed.<\/p>\n\n\n\n
The full implementation:<\/p>\n\n\n
export<\/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> {\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
And that’s that.<\/p>\n\n\n\n
Generics, combined with conditional types, can make for an incredibly powerful combination. When you look at things the right way, you can ask very useful questions about your types that allow you to build the precise API you want.<\/p>\n\n\n\n
Concluding Thoughts<\/h2>\n\n\n\n
I hope this deep dive into a niche use case has taught you at least something useful about TypeScript. Even if you never need to solve this particular problem \u2014 and let’s face it, you probably won’t \u2014 these tools and skills are widely applicable.<\/p>\n","protected":false},"excerpt":{"rendered":"
Generics, combined with conditional types can make for an incredibly powerful combination. When you look at things the right way, you can ask very useful questions about your types that allow you to build the precise API you want.<\/p>\n","protected":false},"author":21,"featured_media":8569,"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":[450,184],"class_list":["post-8524","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-generics","tag-typescript"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/frontendmasters.com\/blog\/wp-content\/uploads\/2026\/02\/type.jpg?fit=2000%2C1200&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8524","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=8524"}],"version-history":[{"count":17,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8524\/revisions"}],"predecessor-version":[{"id":8603,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/8524\/revisions\/8603"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media\/8569"}],"wp:attachment":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media?parent=8524"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/categories?post=8524"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/tags?post=8524"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}