Math Magic with TypeScript Types

Published February 12, 2025 : updated February 19, 2025

For me, one of the killer features that makes TypeScript alluring is its structural type system. Other languages like Java, Flutter, and Go opt for a nominal type system which brings about its many benefits, but there some things that are simply impossible in other languages whose names do not begin with ‘Type’ and end with ‘Script’. I’ll show you how you can perform arithmetic with types in the most literal of senses. This will be an exciting read!

Basic arithmetic

So obviously, TypeScript has an arithmetic system:

const add = (a: number, b: number) {
    return a + b;
}

add(1, 2) // 3

Duh, this isn’t exciting at all. Luckily, we’re not interested in how to add 1 + 2. Let’s peel back more layers.

Numerical types

Can you guess the types of these variables? Hover over each definition to reveal their answers:

let 
let num1: number
num1 = 10;

const 
const num2: 3
num2 = 3;

const 
const num3: number
num3 = 1 + 2;

If you got all three correct, you already have a head-start in this topic! If you didn’t, don’t worry - we’ll go over why these answers are the way they are.

First example

In the first variable, we write let num1 = 10. This declares a variable with the value of 10. Pretty straightforward. The part that isn’t, however, comes in the form of its implicit type. TypeScript’s strongest aspect, arguably, is its ability to decide whether to infer types strictly or create a looser definition.

When we declare let, we aren’t certain that this value stays the same, so TypeScript knows that it is possible to mutate it in the future. To be safe, TypeScript assigns an implicit number type to the variable.

This means that num1 can be re-assigned any number, as long as its type is number. No random strings or arrays allowed!

let 
let num: number
num = 10;

num = "hello world";Error ts(2322)  ― Type 'string' is not assignable to type 'number'.

let num: number
num = 20;

Second example

For the second example, we have a constant, num2, with a value of 3. But this time, its type isn’t number - it’s 3?! Why is this the case?

This is again another demonstration of TypeScript’s type inference, but this time, built on JavaScript principles. TypeScript is is a superset of JavaScript, which means that hard rules in JS are still applicable here.

In this case, a const is immutable, thus TypeScript can narrowly infer its type as 3.

Now hold on, why is 3 even a type in the first place? Isn’t it a value? This is indeed true, except that TypeScript is also allows certain literal values to act as types. This is a unique and fascinating ability the language possesses, and is one that can be utilised in many cases.

For example, I could restrict a function argument to allow only certain numbers:

type 
type MusicControls = {
    setVolume: (volume: 0 | 25 | 50 | 100) => void;
}
MusicControls = {
  
setVolume: (volume: 0 | 25 | 50 | 100) => void
setVolume: (
volume: 0 | 25 | 50 | 100
volume: 0 | 25 | 50 | 100) => void;
};

const player: MusicControls
player.
setVolume: (volume: 0 | 25 | 50 | 100) => void
setVolume(10);Error ts(2345)  ― Argument of type '10' is not assignable to parameter of type '0 | 25 | 50 | 100'.
const player: MusicControls
player.
setVolume: (volume: 0 | 25 | 50 | 100) => void
setVolume(50);
const player: MusicControls
player.
setVolume: (volume: 0 | 25 | 50 | 100) => void
setVolume(100);

Pretty inflexible music player, but it shows that numbers are indeed valid types!

Third example

So in the third example, we end up with the number type. But we just learnt that const definitions should return their literal value as a type, so isn’t it intuitive for TypeScript to also assign 3 as the type? On paper, it does match the aforementioned criteria…

At first glance, the difference here isn’t easily noticeable. But there’s something about TypeScript’s compiler to take note of: types are only evaluated at compile-time. An arithmetic operation (in this case, addition) is a runtime operation.

What this means is that TypeScript actually has no idea what 1 + 2 resolves to at compile time! Therefore, it just infers that the type is of number.

Applying set theory

Now that you have a little background about implicit type specificity, let’s do a little exercise. Why does TypeScript complain about this?

const num: 1 = 10;Error ts(2322)  ― Type '10' is not assignable to type '1'.

The answer lies within set theory, regarding unions. In fact, the previous examples all had to do with set theory!

In TypeScript, number is known as the set that contains any number, e.g. 1; 20; 1,245; 429,582,157,197.

Think of it this way. 10 is assignable to the number set, because number contains all possible numbers. But can we instead assign number to 10?

Short answer is - nope. In this case, 1 is just a set that can only contain one value - 1. In the example, we try to assert 10 as 1, and it fails because of this reason.

Tuples

Now that we’ve gotten the basics out of the way, an essential factor of type manipulation is tuples. Tuples are arrays with fixed lengths and determined values, and these guys are extremely powerful in constructing complex types.

Here are the ways to create a tuple, and a definition of an array:

const tuple1 = [1, 2, 3] as 
type const = readonly [1, 2, 3]
const;
const tuple1: readonly [1, 2, 3]

const tuple2: [1, 2, 3] = [1, 2, 3];
const tuple2: [1, 2, 3]

const array: number[] = [1, 2, 3];
const array: number[]

We either use as const or assert the value as [1, 2, 3] to really convince TypeScript that what we declared is in fact a tuple. This means that its type and value are now the same: [1, 2, 3].

Without it, TypeScript will loosely infer number[], like on the last line.

We also can’t modify tuples in any form, and some methods are even omitted by TypeScript:

const 
const tuple: readonly [1, 2, 3]
tuple = [1, 2, 3] as 
type const = readonly [1, 2, 3]
const;

// can't reassign length
const tuple: readonly [1, 2, 3]
tuple.length = 0;Error ts(2540)  ― Cannot assign to 'length' because it is a read-only property.

const tuple: readonly [1, 2, 3]
tuple.push(10);Error ts(2339)  ― Property 'push' does not exist on type 'readonly [1, 2, 3]'.

The ‘length’ property

Okay, so tuples seem pretty rigid. Why are they useful anyway?

Their magic comes from the length property. It is readonly, so it has a special feature:

const 
const tuple: readonly [1, 2, 3]
tuple = [1, 2, 3] as 
type const = readonly [1, 2, 3]
const;

const tuple: readonly [1, 2, 3]
tuple.length;
length: 3

Remember the const examples from earlier? Just like in const definitions, the values in tuples are determinate, so TypeScript can safely assume the length of the tuple - which in this case is typed as 3. Compare that to a regular array, where we get number instead!

How cool is that?? This opens up a whole new world of possibilities in the type world.

With that, we can get started on implementing addition.

Creating the <Add> type

Our end type should produce a result like this.

type Three = Add<1, 2>;
//   ^ 3

Type recursion

Majority of what we’re about to do involves recursion. So let’s tackle that first.

In programming languages, recursion is a common way to get a function to execute itself repeatedly until a condition is met. It’s useful for things with arbitrary depth like returning a folder’s children, and each child’s children as well.

All recursive functions consist of 3 components:

The base case is a condition that terminates recursion to prevent infinite re-execution.
Recursion case(s) is/are where the function calls itself with modified arguments.
All recursive functions’ outputs should eventually fulfill the base case.

For instance, to find the factorial of a number, we can use this function:

function 
function factorial(n: number): number
factorial(
n: number
n: number): number {
  // base case
  if (
n: number
n === 1 || 
n: number
n === 0) return 
n: 1 | 0
n;

  // recursion case
  return 
n: number
n * 
function factorial(n: number): number
factorial(
n: number
n - 1);
  // eventually reaches 1, which fulfills the base case
}

const 
const result: number
result = 
function factorial(n: number): number
factorial(4); // 24

In TypeScript, we can use recursion on the type layer as well! Though it does work a little differently in terms of syntax.

Let’s zoom in on TypeScript’s bundled utility type, Awaited. It allows us to extract the type of a Promise’s resolved value recursively. Hover over its type definition!

type Unwrapped = 
type Awaited<T> = T extends null | undefined ? T : T extends object & {
    then(onfulfilled: infer F, ...args: infer _): any;
} ? F extends (value: infer V, ...args: infer _) => any ? Awaited<...> : never : T
Recursively unwraps the "awaited type" of a type. Non-promise "thenables" should resolve to never. This emulates the behavior of await.
Awaited<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<number>>>>>>;
type Unwrapped = number

We can also make our own crude implementation:

type 
type MyAwaited<T> = T extends PromiseLike<infer A> ? A extends PromiseLike<any> ? MyAwaited<A> : A : never
MyAwaited<
function (type parameter) T in type MyAwaited<T>
T> = 
function (type parameter) T in type MyAwaited<T>
T extends 
interface PromiseLike<T>
PromiseLike<infer 
function (type parameter) A
A>
  ? (
function (type parameter) A
A extends 
interface PromiseLike<T>
PromiseLike<any>
    ? 
type MyAwaited<T> = T extends PromiseLike<infer A> ? A extends PromiseLike<any> ? MyAwaited<A> : A : never
MyAwaited<
function (type parameter) A
A>
    : 
function (type parameter) A
A)
  : never;

type Unwrapped = 
type MyAwaited<T> = T extends PromiseLike<infer A> ? A extends PromiseLike<any> ? MyAwaited<A> : A : never
MyAwaited<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<number>>>>>>;
type Unwrapped = number

Let’s dissect our MyAwaited type:

Try to infer the type of A if T is a Promise.
If it is, check if A is also a Promise. This is our recursion case.
If it is, re-use the type, with A as the type argument.
If A does not extend Promise, we return A, as our final unwrapped type. This is our base case, and also our result.

Now that we’ve got out of the way, we can move on to the first real step.

Mapping numbers to tuples

Obviously, we can’t just do something like the following to achieve addition. TypeScript will not recogise this as valid code:

type 
type Three = 1
Three = 1 + 2;Error ts(1005)  ― ';' expected.

Things like mathematical operators do not work on the type layer. We need to think outside of the box. As we learnt, tuples contain a length property with a fixed number type. How can we utilise it?

We can use recursion to ‘modify’ a tuple. Let’s see this in action.

First, let’s define a helper type for getting a tuple’s length, for ease of use:

type 
type Length<T extends any[]> = T["length"]
Length<
function (type parameter) T in type Length<T extends any[]>
T extends any[]> = 
function (type parameter) T in type Length<T extends any[]>
T["length"];

Next, let’s make a way to convert numbers to tuples. Here’s the concept:

We want to define a recursive type
An internal counter should increment and be returned when we reach the desired number
We need to have a base case to stop recursion

With these points in mind, we’ll create a type that does this, step-by-step:

Let’s create a type called MapToTuple, which takes in a number:

type 
type MapToTuple<T extends number> = any
MapToTuple<
function (type parameter) T in type MapToTuple<T extends number>
T extends number> = ...

It’s going to be a recursive function, so want to create our base case and our accumulator - we’ll store that as ‘state’ via default generic values:

// 0 is an arbitrary value
type 
type MapToTuple<T extends number, Acc extends 0[] = []> = any
MapToTuple<
function (type parameter) T in type MapToTuple<T extends number, Acc extends 0[] = []>
T extends number, 
function (type parameter) Acc in type MapToTuple<T extends number, Acc extends 0[] = []>
Acc extends 0[] = []> = ...

The idea is to increase Acc, until its length matches T.

Next, create the recursion logic:

type 
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<
function (type parameter) T in type MapToTuple<T extends number, Acc extends 0[] = []>
T extends number, 
function (type parameter) Acc in type MapToTuple<T extends number, Acc extends 0[] = []>
Acc extends 0[] = []> = 
type Length<T extends any[]> = T["length"]
Length<
function (type parameter) Acc in type MapToTuple<T extends number, Acc extends 0[] = []>
Acc> extends 
function (type parameter) T in type MapToTuple<T extends number, Acc extends 0[] = []>
T
  ? 
function (type parameter) Acc in type MapToTuple<T extends number, Acc extends 0[] = []>
Acc
  : 
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<
function (type parameter) T in type MapToTuple<T extends number, Acc extends 0[] = []>
T, [...
function (type parameter) Acc in type MapToTuple<T extends number, Acc extends 0[] = []>
Acc, 0]>;

Okay. Let’s pause here. What exactly are we doing with extends?

Every time we compile the type, we check if the length of Acc is the same as T. If it is, we return Acc, our tuple type. If it’s not, we return MapToTuple again, but we do 2 things:

Pass T as the same argument. This shouldn’t change as it’s our desired number.
We use the spread operator ... on Acc to get its items, then append an extra value. This new value goes into the Acc slot.

The spread operator

The spread ... operator can be used on the type layer too. This gives us the value of a tuple.

  type 
type Arr1 = [1, 2, 3]
Arr1 = [1, 2, 3];
  type 
type Arr2 = [4, 5, 6]
Arr2 = [4, 5, 6];

  type Arr3 = [...
type Arr1 = [1, 2, 3]
Arr1, ...
type Arr2 = [4, 5, 6]
Arr2];
type Arr3 = [1, 2, 3, 4, 5, 6]

If we input a number into MapToTuple, this is what we get:

type Hello = 
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<4>;
type Hello = [0, 0, 0, 0]

type World = 
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<8>;
type World = [0, 0, 0, 0, 0, 0, 0, 0]

Summing it all together

We’re almost done! Let’s collect all of this into one convenient type - Add. The final step is to map each of the 2 numbers we want to add into a tuple, then concatenate them to get the total length:

type 
type Add<A extends number, B extends number> = [...MapToTuple<A, []>, ...MapToTuple<B, []>]["length"]
Add<
function (type parameter) A in type Add<A extends number, B extends number>
A extends number, 
function (type parameter) B in type Add<A extends number, B extends number>
B extends number> = 
type Length<T extends any[]> = T["length"]
Length<[...
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<
function (type parameter) A in type Add<A extends number, B extends number>
A>, ...
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T ? Acc : MapToTuple<T, [...Acc, 0]>
MapToTuple<
function (type parameter) B in type Add<A extends number, B extends number>
B>]>;

type Three = 
type Add<A extends number, B extends number> = [...MapToTuple<A, []>, ...MapToTuple<B, []>]["length"]
Add<1, 2>;
type Three = 3

type Ten = 
type Add<A extends number, B extends number> = [...MapToTuple<A, []>, ...MapToTuple<B, []>]["length"]
Add<4, 6>;
type Ten = 10

And we’ve done it! We’ve successfully implemented addition in TypeScript using only types! If this is still confusing to you, here’s a summary of everything we’ve done so far:

Step

0123456789

type Length<T extends any[]> = T["length"];
// 1: define the `Length` type, which takes any array `T`

We can take it a bit further. Here’s a bonus challenge.

Replicating the Fibonacci sequence

The Fibonacci sequence is a very famous pattern of numbers, denoted by Fn = F(n - 1) + F(n - 2), where n > 1. It’s a very common algorithm example on platforms like LeetCode, where programmers are often challenged to implement it with various languages. With TypeScript types however, it’s a different story!

I encourage you to attempt it yourself. We will re-use our created Add component here.

If you’re done, let’s start off with the type itself:

type 
type Fibonacci<N extends number, Sum extends number = 1, Prev extends number = 0, Counter extends number = 1> = any
Fibonacci<
  
function (type parameter) N in type Fibonacci<N extends number, Sum extends number = 1, Prev extends number = 0, Counter extends number = 1>
N extends number,
  
function (type parameter) Sum in type Fibonacci<N extends number, Sum extends number = 1, Prev extends number = 0, Counter extends number = 1>
Sum extends number = 1,
  
function (type parameter) Prev in type Fibonacci<N extends number, Sum extends number = 1, Prev extends number = 0, Counter extends number = 1>
Prev extends number = 0,
  
function (type parameter) Counter in type Fibonacci<N extends number, Sum extends number = 1, Prev extends number = 0, Counter extends number = 1>
Counter extends number = 1
> = ...;

N is the number we’re inputting. So if we input 4, we expect to get 3. With 8, we expect 21, etc.
Sum is similar to Acc in our Add type. Set initial value to 1, as the first term in the sequence is 1.
Prev is the value of previous Sum. At n = 1, Prev should be 0.
Counter is just how many times we have to iterate. Once we reach N, we stop executing (base case).

The implementation is something like this:

Step

0123456789

type Length<T extends any[]> = T["length"];
type MapToTuple<T extends number, Acc extends 0[] = []> = Length<Acc> extends T
	? Acc
	: MapToTuple<T, [...Acc, 0]>;
type Add<A extends number, B extends number> = 
	Length<[...MapToTuple<A>, ...MapToTuple<B>]>;
// ---cut---
type Fibonacci<
	N extends number,
	Sum extends number = 1,
	Prev extends number = 0,
	Counter extends number = 1
> = ...

Same concept, more complex implementation!

Limits

If you tinkered around with the code, you might’ve realised that this implementation of addition is actually quite limited. For example, let’s add 1000 to 1000:

type 
type Result = number
Result = 
type Add<A extends number, B extends number> = [...MapToTuple<A, []>, ...MapToTuple<B, []>]["length"]
Add<1000, 1000>;Error ts(2589)  ― Type instantiation is excessively deep and possibly infinite.

The code errors out and we get this message! What does it mean exactly?

Even though TypeScript allows recursive types, there is a hard recursion limit of 999 to help prevent programs from stalling. The only way to get around this is to use a very very complex workaround involving a genius level of string manipulation that my pea-brain cannot comprehend, so this limit is here to stay for the time being!

End

I hope you’ve enjoyed learning about the countless fascinating things about TypeScript’s type system. If you would like to see more challenges like these, check out the type-challenges repo.