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:

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

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

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

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

// @ts-expect-error because when the cb is provided, void is returned so you can't use ".then"!
asyncAdd(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:

type asyncAddCb = (result: number) => void
// define all valid function signatures
function asyncAdd(a: number, b: number): Promise<number>
function asyncAdd(a: number, b: number, cb: asyncAddCb): void

// define the actual implementation
// notice cb is optional
// also notice that the return type is inferred, but it could be specified as `void | Promise<number>`
function asyncAdd(a: number, b: number, cb?: asyncAddCb) {
	const result = a + b
	if (cb) return cb(result)
	else return Promise.resolve(result)
}

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:

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

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

export const apple = 'apple'
export const orange = 'orange'
export 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:

import codegen from 'codegen.macro'

// using as a tagged template literal:
codegen`
  module.exports = "const tag = 'this is an example'"
`

// using as a function
codegen(`
  module.exports = "const fn = 'this is another example'"
`)

// codegen-ing an external module (and pass an argument):
const jpgs = codegen.require('./get-files-list', '**/*.jpg')

const ui = <Codegen>{`module.exports = require('./some-jsx-code')`}</Codegen>

Then that could compile to something like this:

// using as a tagged template literal:
const tag = 'this is an example'

// using as a function
const fn = 'this is another example'

// codegen-ing an external module (and pass an argument):
const jpgs = ['kody.jpg', 'olivia.jpg', 'marty.jpg']

const 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.

import { createMacro } from 'babel-plugin-macros'
import type { MacroHandler } from 'babel-plugin-macros'

const codegenMacro: MacroHandler = function codegenMacro(/* some args */) {
	// the implementation here is irrelevant
}

// use the `createMacro` utility to turn the codegenMacro into a babel macro
const 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:

// This handles the tagged template literal API:
declare function codegen(
	literals: TemplateStringsArray,
	...interpolations: Array<unknown>
): any

// this handles the function call API:
declare function codegen(code: string): any

// this handles the `codegen.require` API:
declare namespace codegen {
	function require(modulePath: string, ...args: Array<unknown>): any
}

// Unfortunately I couldn't figure out how to add TS support for the JSX form
// Something about the overload not being supported because codegen can't be all the things or whatever
// 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:

export 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!