This site runs best with JavaScript enabled.

Define function overload types with TypeScript


Have your JS expressiveness and type it too.

Allow me to quickly answer to the "normal" use case of "How to define function overload types with TypeScript" with an example:

I want a function that accepts a callback or returns a promise if none is provided:

1const logResult = result => console.log(`result: ${result}`)
2asyncAdd(1, 2).then(logResult) // logs "result: 3"
3asyncAdd(3, 6, logResult) // logs "result: 9"

Here's how you'd implement this API using regular JavaScript:

1function asyncAdd(a, b, cb) {
2 const result = a + b
3 if (cb) return cb(result)
4 else return Promise.resolve(result)
5}

With this implementation, what we want is to have TypeScript catch this bad usage:

1// @ts-expect-error because when the cb is provided, void is returned so you can't use ".then"!
2asyncAdd(1, 2, logResult).then(logResult) // this would throw an error when trying to use ".then" (except we're using TypeScript so it won't even compile 😉)

So, here's how you'd type this kind of overloading:

1type asyncAddCb = (result: number) => void
2// define all valid function signatures
3function asyncAdd(a: number, b: number): Promise<number>
4function asyncAdd(a: number, b: number, cb: asyncAddCb): void
5
6// define the actual implementation
7// notice cb is optional
8// also notice that the return type is inferred, but it could be specified as `void | Promise<number>`
9function asyncAdd(a: number, b: number, cb?: asyncAddCb) {
10 const result = a + b
11 if (cb) return cb(result)
12 else return Promise.resolve(result)
13}

And then you're off to the races!

Dig deeper

The real inspiration for this blog post is a bit more complicated though and requires some background information:

I have a package called babel-plugin-codegen that allows you to generate code at compile time. For example, assume you have a file with the following code:

1// @codegen
2const fs = require('fs')
3const fruits = fs.readFileSync('./fruit.txt', 'utf8').toString().split('\n')
4module.exports = fruits
5 .map(fruit => `export const ${fruit} = '${fruit}';`)
6 .join('')

Assuming fruit.txt contains a list of fruits, this is what that'll compile to:

1export const apple = 'apple'
2export const orange = 'orange'
3export const pear = 'pear'

So, you generate a string of code, and codegen turns that to actual code that's fed into your output. This unlocks a lot of really cool things.

But the specifics of this babel plugin doesn't matter. What does matter is that you can also use this with babel-plugin-macros which is basically importable babel transforms. So instead of configuring babel-plugin-codegen, you can just configure babel-plugin-macros and then install codegen.macro and you can import and use it like so:

1import codegen from 'codegen.macro'
2
3// using as a tagged template literal:
4codegen`
5 module.exports = "const tag = 'this is an example'"
6`
7
8// using as a function
9codegen(`
10 module.exports = "const fn = 'this is another example'"
11`)
12
13// codegen-ing an external module (and pass an argument):
14const jpgs = codegen.require('./get-files-list', '**/*.jpg')
15
16const ui = <Codegen>{`module.exports = require('./some-jsx-code')`}</Codegen>

Then that could compile to something like this:

1// using as a tagged template literal:
2const tag = 'this is an example'
3
4// using as a function
5const fn = 'this is another example'
6
7// codegen-ing an external module (and pass an argument):
8const jpgs = ['kody.jpg', 'olivia.jpg', 'marty.jpg']
9
10const ui = <div>This is some example JSX code</div>

Anyway, codegen is pretty sweet. But you'll notice there's some hard-core overloading going here, so I thought I'd share how I typed this function overloading with TypeScript.

Function Overloading with TypeScript

Something really important to keep in mind is that the actual codegen function implementation is actually a babel macro, so it looks nothing like the way that these functions appear to work. It's called during the compilation process and the arguments it's called with is ASTs.

That said, at the end of the day, the consumer's experience is all that matters, so we need a version of the codegen function that works the way it's expected. So we'll define our types and then make sure that we cast the macro function like a regular function.

1import {createMacro} from 'babel-plugin-macros'
2import type {MacroHandler} from 'babel-plugin-macros'
3
4const codegenMacro: MacroHandler = function codegenMacro(/* some args */) {
5 // the implementation here is irrelevant
6}
7
8// use the `createMacro` utility to turn the codegenMacro into a babel macro
9const macro = createMacro(codegenMacro)

Ok, so keep in mind that the macro function is not actually ever called by user code. This function will be called by babel-plugin-macros, and it'll be called with the MacroHandler arguments. However, as far as TypeScript is concerned, the developer will be calling it, so we need to give it the right type definitions and everyone will be happy. So let's define those:

1// This handles the tagged template literal API:
2declare function codegen(
3 literals: TemplateStringsArray,
4 ...interpolations: Array<unknown>
5): any
6
7// this handles the function call API:
8declare function codegen(code: string): any
9
10// this handles the `codegen.require` API:
11declare namespace codegen {
12 function require(modulePath: string, ...args: Array<unknown>): any
13}
14
15// Unfortunately I couldn't figure out how to add TS support for the JSX form
16// Something about the overload not being supported because codegen can't be all the things or whatever
17// PRs welcome!

With those overloads defined, now we just need to force TypeScript to treat our macro file like the codegen function we've defined. We also need to make this the default export of our macro file, so we'll do all that at once:

1export default macro as typeof codegen

You can peruse it all together in babel-plugin-codegen src/macro.ts file.

I hope that's useful! Good luck to yah!

Discuss on TwitterEdit post on GitHub

Share article
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.

Join the Newsletter



Kent C. Dodds