Annotating Functions in Typescript

The most basic way of annotating a function in typescript is like this

function add(a: number, b: number): number{
 // logic
}

// or

const add = (a: number, b: number): number => {
    //logic
}

optional parameters are annotated with question marks param? like this

function optional(a: number, b?: number){
    console.log(a)
}

But what about callback functions, or functions where the type of the arguments and the return types are related (in that case, generic).

---

Function Values

Observe this JavaScript function

function multiplier(factor){
    return value => factor * value
}

so that we can use the function like this;

const n  = multiplier(6)
n(8) // 48

Function values are annotated in typescript like this

(param1: type, param2: type)=> type

// or

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

So to annotate the multiplier function, we have

function multiplier(factor: number): (value: number) => number{
    return value => factor * value
}

Your IDE (preferably) VSCode, will automatically infer the type of value (to be number) in the function logic

---

Generic functions

This function annotation is wrong

function pickFirst(array: Array<T>): T{
    return array[0]
}

Naturally this throws an error that
Cannot find name T

therefore, the format of annotating generic functions is

function fnName <T,U>(param: T): U{
    //logic
}

Observe where the generic names were declared. so, to correctly annotate the function above;

function pickFirst<T>(array: Array<T>): T{
    return array[0]
}

Now that works.

But what about Generic functions that have function parameters.

For instance, we want to annotate a custom map function named myMap which was written like this in Javascript

function myMap(arr, fn){
    rreturn arr.map(fn)
}

We can annotate it like this

function myMap<Input, Output>(arr: Input[], fn: (item: Input, index?: number) => Output): Output[]{
    return arr.map(fn)
}

What we should note in the snippet above is that the fn function takes an item of the same type of the Input array and returns an Output type.

What about the static Array.from() method?

function myFrom<Type>(iterable: Iterable<Type>): Array<Type>{
    // logic
}

or the array.filter() method?

function myFilter<Input>(arr: Input[], fn: (item: Input) => boolean): Input[]{
    return arr.filter(fn)
}

Generic constraints

You can also constrain generic variables to types that have a particular property. For instance,

function pickInnerFirst<T extends {length: number}>(array: Array<T>): T{
    return array[0][0]
}

This function picks the very first element in a 2 dimensional array

This ensures that it only works for arrays and strings (mostly) in such a way that

pickOne([12, 20, 30]) // wont work.

We can also use interfaces

interface Lengthly{
    length: number;
}

function pickInnerFirst<T extends Lengthly>(array: Array<T>): T{
    return array[0][0]
}

---

Function Interfaces

In case you don't know, Functions are objects and they have properties

const add = (a, b) => a + b

console.log(add.toString()) //(a, b) => a + b

// also
console.log(Object.getPrototypeOf(add) == Function.prototype) //true
console.log(Object.getPrototypeOf(Function.prototype) == Object.prototype) //true

The second example indicated that the add function is a child of Object.prototype (even though its not a direct child) and therefore is an object.

Funny enough, you can attach properties to a function in JavaScript

function shout(fn, value){
    fn(value)
    console.log(fn.description)
} 

function hey(value){
    console.log(value)
}

hey.description = `A function called ${hey.name}` // A

shout(hey, "Hola!!!")

This snippet will return

>> Hola!!!
>> A function called hey

Observe that at A we attached a property called description to the function which can only be possible with objects.

That is to conclude that;

Objects can be described with interfaces (normally). For functions, this is also possible. however, it is only something you should consider when you are adding special properties to your functions.

interface describableFunction{
    (value: string): void; //A
    description: string;
}

At comment A is where we describe the arguments and return types of the function.

So, to annotate the earlier code in typescript,

interface describableFunction{
    (value: string): void;
    description: string;
}

function shout(fn: describableFunction, value: string) { //A
    fn(value)
    console.log(fn.description)
}

function hey(value: string) {
    console.log(value)
}

hey.description = `A function called ${hey.name}`
shout(hey, "Hola!!!")

Observe the way we used the interface in the shout function at A.

---

Why should I understand how to annotate functions in Typescript?

Well, it helps in building a much smarter type system which in turn reduces your chances of bugs. If you are building a library or a framework, you might have to use some or most of the concepts mentioned here.
If you are just using libraries, these concepts are not really necessary, even though they can give you a much deeper understanding of the libraries you are working with.

If you have any questions or there are mistakes in this writing, feel free to share them in the comments below ⭐