This site runs best with JavaScript enabled.

TypeScript Function Syntaxes

Photo by hao wang


The syntax for various functions and function types in TypeScript with simple examples.

In JavaScript itself, there are lots of ways to write functions. Add TypeScript to the mix and all of a sudden it's a lot to think about. So with the help of some friends, I've put together this list of various function forms you'll typically need/run into with simple examples.

Keep in mind that there are TONS of combinations of different syntaxes. I only include those which are less obvious combinations or unique in some way.

First, the biggest confusion I always have with the syntax of things is where to put the return type. When do I use : and when do I use =>. Here are a few quick examples that might help speed you up if you're using this post as a quick reference:

1// Simple type for a function, use =>
2type FnType = (arg: ArgType) => ReturnType
3
4// Every other time, use :
5type FnAsObjType = {
6 (arg: ArgType): ReturnType
7}
8interface InterfaceWithFn {
9 fn(arg: ArgType): ReturnType
10}
11
12const fnImplementation = (arg: ArgType): ReturnType => {
13 /* implementation */
14}

I think that was the biggest source of confusion for me. Having written this, now I know that the only time I use => ReturnType is when I'm defining a function type as a type in itself. Any other time, use : ReturnType.

Continue reading for a bunch of examples of how this plays out in typical code examples.

Function declarations

1// inferred return type
2function sum(a: number, b: number) {
3 return a + b
4}
1// defined return type
2function sum(a: number, b: number): number {
3 return a + b
4}

In the examples below, we'll be using explicit return types, but you technically don't have to specify this.

Function Expression

1// named function expression
2const sum = function sum(a: number, b: number): number {
3 return a + b
4}
1// annonymous function expression
2const sum = function (a: number, b: number): number {
3 return a + b
4}
1// arrow function
2const sum = (a: number, b: number): number => {
3 return a + b
4}
1// implicit return
2const sum = (a: number, b: number): number => a + b
1// implicit return of an object requires parentheses to disambiguate the curly braces
2const sum = (a: number, b: number): {result: number} => ({result: a + b})

You can also add a type annotation next to the variable, and then the function itself will assume those types:

1const sum: (a: number, b: number) => number = (a, b) => a + b

And you can extract that type:

1type MathFn = (a: number, b: number) => number
2const sum: MathFn = (a, b) => a + b

Or you can use the object type syntax:

1type MathFn = {
2 (a: number, b: number): number
3}
4const sum: MathFn = (a, b) => a + b

Which can be useful if you want to add a typed property to the function:

1type MathFn = {
2 (a: number, b: number): number
3 operator: string
4}
5const sum: MathFn = (a, b) => a + b
6sum.operator = '+'

This can also be done with an interface:

1interface MathFn {
2 (a: number, b: number): number
3 operator: string
4}
5const sum: MathFn = (a, b) => a + b
6sum.operator = '+'

And then there's declare function and declare namespace which are intended to say: "Hey, there exist a variable with this name and type". We can use that to create the type and then use typeof to assign that type to our function. You'll often find declare used in .d.ts files to declare types for libraries.

1declare function MathFn(a: number, b: number): number
2declare namespace MathFn {
3 let operator: '+'
4}
5const sum: typeof MathFn = (a, b) => a + b
6sum.operator = '+'

Given the choice between type, interface, and declare function, I think I prefer type personally, unless I need the extensibility that interface offers. I'd only really use declare if I really did want to tell the compiler about something that it doesn't already know about (like a library).

Optional/Default params

Optional parameter:

1const sum = (a: number, b?: number): number => a + (b ?? 0)

Note that order matters here. If you make one parameter optional, all following parameters need to be optional as well. This is because it's possible to call sum(1) but not possible to call sum(, 2). However, it is possible to call sum(undefined, 2) and if that's what you want to enable, then you can do that too:

1const sum = (a: number | undefined, b: number): number => (a ?? 0) + b

Default params

When I was writing this, I thought it would be useless to use default params without making that param optional, but it turns out that when you have a default value, TypeScript treats it like an optional param. So this works:

1const sum = (a: number, b: number = 0): number => a + b
2sum(1) // results in 1
3sum(2, undefined) // results in 2

So that example is functionally equivalent to:

1const sum = (a: number, b: number | undefined = 0): number => a + b

TIL.

Interestingly, this also means that if you want the first argument to be optional but the second to be required, you can do that without using | undefined:

1const sum = (a: number = 0, b: number): number => a + b
2sum(undefined, 3) // results in 3

However, when you extract the type, you will need to add the | undefined manually, because = 0 is a JavaScript expression, not a type.

1type MathFn = (a: number | undefined, b: number) => number
2const sum: MathFn = (a = 0, b) => a + b

Rest params

Rest params is a JavaScript feature that allows you to collect the "rest" of the arguments of a function call into an array. You can use them at any parameter position (first, second, third, etc.). The only requirement is that it's the last parameter.

1const sum = (a: number = 0, ...rest: Array<number>): number => {
2 return rest.reduce((acc, n) => acc + n, a)
3}

And you can extract the type:

1type MathFn = (a?: number, ...rest: Array<number>) => number
2const sum: MathFn = (a = 0, ...rest) => rest.reduce((acc, n) => acc + n, a)

Object properties and Methods

Object method:

1const math = {
2 sum(a: number, b: number): number {
3 return a + b
4 },
5}

Property as function expression:

1const math = {
2 sum: function sum(a: number, b: number): number {
3 return a + b
4 },
5}

Property as arrow function expression (with implicit return):

1const math = {
2 sum: (a: number, b: number): number => a + b,
3}

Unfortunately, to extract the type you can't type the function itself, you have to type the enclosing object. You can't annotate the function with a type by itself when it's defined within the object literal:

1type MathFn = (a: number, b: number) => number
2
3const math: {sum: MathFn} = {
4 sum: (a, b) => a + b,
5}

Furthermore, if you want to add a property on it like some of the above examples, that is impossible to do within the object literal. You have to extract the function definition completely:

1type MathFn = {
2 (a: number, b: number): number
3 operator: string
4}
5const sum: MathFn = (a, b) => a + b
6sum.operator = '+'
7
8const math = {sum}

You may have noticed that this example is identical to an example above with only the addition of the const math = {sum}. So yeah, there's no way to do all this inline with the object declaration.

Classes

Classes themselves are functions, but they're special (have to be invoked with new), but this section will talk about how functions are defined within the class body.

Here's a regular method, the most common form of a function in a class body:

1class MathUtils {
2 sum(a: number, b: number): number {
3 return a + b
4 }
5}
6
7const math = new MathUtils()
8math.sum(1, 2)

You can also use a class field if you want the function to be bound to the specific instance of the class:

1class MathUtils {
2 sum = (a: number, b: number): number => {
3 return a + b
4 }
5}
6
7// doing things this way this allows you to do this:
8const math = new MathUtils()
9const sum = math.sum
10sum(1, 2)
11
12// but it also comes at a cost that offsets any perf gains you get
13// by going with a class over a regular object factor so...

And then, you can extract these types. Here's what it looks like for the method version in the first example:

1interface MathUtilsInterface {
2 sum(a: number, b: number): number
3}
4
5class MathUtils implements MathUtilsInterface {
6 sum(a: number, b: number): number {
7 return a + b
8 }
9}

Interestingly, it looks like you still have to define the types for the function, even though those are a part of the interface it's supposed to implement 🤔 🤷‍♂️

One final note. In TypeScript, you also get public, private, and protected. I personally don't use classes all that often and I don't like using those particular TypeScript features. JavaScript will soon get special syntax for private members which is neat (learn more).

Modules

Importing and exporting function definitions works the same way as it does with anything else. Where things get unique for TypeScript is if you want to write a .d.ts file with a module declaration. Let's take our sum function for example:

1const sum = (a: number, b: number): number => a + b
2sum.operator = '+'

Here's what we'd do assuming we export it as the default:

1declare const sum: {
2 (a: number, b: number): number
3 operator: string
4}
5export default sum

And if we want it to be a named export:

1declare const sum: {
2 (a: number, b: number): number
3 operator: string
4}
5export {sum}

Overloads

I've written about this especially and you can read that: Define function overload types with TypeScript. Here's the example from that post:

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

Basically what you do is define the function multiple times and only actually implement it the last time. It's important that the types for the implementation supports all the override types, which is why the cb is optional above`.

Generators

I've not once used a generator in production code... But when I played around with it a bit in the TypeScript playground there wasn't much to it for the simple case:

1function* generator(start: number) {
2 yield start + 1
3 yield start + 2
4}
5
6var iterator = generator(0)
7console.log(iterator.next()) // { value: 1, done: false }
8console.log(iterator.next()) // { value: 2, done: false }
9console.log(iterator.next()) // { value: undefined, done: true }

TypeScript correctly infers that iterator.next() returns an object with the following type:

1type IteratorNextType = {
2 value: number | void
3 done: boolean
4}

If you want type safety for the yield expression completion value, add a type annotation to the variable you assign it to:

1function* generator(start: number) {
2 const newStart: number = yield start + 1
3 yield newStart + 2
4}
5
6var iterator = generator(0)
7console.log(iterator.next()) // { value: 1, done: false }
8console.log(iterator.next(3)) // { value: 5, done: false }
9console.log(iterator.next()) // { value: undefined, done: true }

And now if you try to call iterator.next('3') instead of the iterator.next(3) you'll get a compilation error 🎉

Async

async/await functions in TypeScript work exactly the same as they do in JavaScript and the only difference in typing them is the return type will always be a Promise generic.

1const sum = async (a: number, b: number): Promise<number> => a + b
1async function sum(a: number, b: number): Promise<number> {
2 return a + b
3}

Generics

With a function declaration:

1function arrayify2<Type>(a: Type): Array<Type> {
2 return [a]
3}

Unfortunately, with an arrow function (when TypeScript is configured for JSX), the opening < of the function is ambiguous to the compiler. "Is that generic syntax? Or is that JSX?" So you have to add a little something to help it disambiguate it. I think the most straightforward thing to do is to have it extends unknown:

1const arrayify = <Type extends unknown>(a: Type): Array<Type> => [a]

Which conveniently shows us the syntax for extends in generics, so there you go.

Type Guards

A type guard is a mechanism for doing type narrowing. For example, it allows you to narrow something that is string | number down to either a string or a number. There are built-in mechanisms for this (like typeof x === 'string'), but you can make your own too. Here's one of my favorites (hat tip to my friend Peter who originally showed this to me):

You have an array with some falsy values and you want those gone:

1// Array<number | undefined>
2const arrayWithFalsyValues = [1, undefined, 0, 2]

In regular JavaScript you can do:

1// Array<number | undefined>
2const arrayWithoutFalsyValues = arrayWithFalsyValues.filter(Boolean)

Unfortunately, TypeScript doesn't consider this a type narrowing guard, so the type is still Array<number | undefined> (no narrowing applied).

So we can write our own function and tell the compiler that it returns true/false for whether the given argument is a specific type. For us, we'll say that our function returns true if the given argument's type is not included in one of the falsy value types.

1type FalsyType = false | null | undefined | '' | 0
2function typedBoolean<ValueType>(
3 value: ValueType,
4): value is Exclude<ValueType, FalsyType> {
5 return Boolean(value)
6}

And with that we can do this:

1// Array<number>
2const arrayWithoutFalsyValues = arrayWithFalsyValues.filter(typedBoolean)

Woo!

Assertion functions

You know how sometimes you do runtime checking to be extra-sure of something? Like, when an object can have a property with a value or null you want to check if it's null and maybe throw an error if it is null. Here's how you might do something like that:

1type User = {
2 name: string
3 displayName: string | null
4}
5
6function logUserDisplayNameUpper(user: User) {
7 if (!user.displayName) throw new Error('Oh no, user has no displayName')
8 console.log(user.displayName.toUpperCase())
9}

TypeScript is fine with user.displayName.toUpperCase() because the if statement is a type guard that it understands. Now, let's say you want to take that if check and put it in a function:

1type User = {
2 name: string
3 displayName: string | null
4}
5
6function assertDisplayName(user: User) {
7 if (!user.displayName) throw new Error('Oh no, user has no displayName')
8}
9
10function logUserDisplayName(user: User) {
11 assertDisplayName(user)
12 console.log(user.displayName.toUpperCase())
13}

Now, TypeScript is no longer happy because the call to assertDisplayName isn't a sufficient type guard. I'd argue this is a limitation on TypeScript's part. Hey, no tech is perfect. Anyway, we can help TypeScript out a bit by telling it that our function makes an assertion:

1type User = {
2 name: string
3 displayName: string | null
4}
5
6function assertDisplayName(
7 user: User,
8): asserts user is User & {displayName: string} {
9 if (!user.displayName) throw new Error('Oh no, user has no displayName')
10}
11
12function logUserDisplayName(user: User) {
13 assertDisplayName(user)
14 console.log(user.displayName.toUpperCase())
15}

And that's another way to turn our function into a type narrowing function!

Conclusion

That's definitely not everything, but that's a lot of the common syntax I find myself writing when dealing with functions in TypeScript. I hope it was helpful to you! Bookmark this and share it with your friends 😘

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