Functions

The TypeScript type system pays a lot of love to functions, after all they are the core building block of a composable system.

Parameter annotations

Of course you can annotate function parameters just like you can annotate other variables:

  1. // variable annotation
  2. var sampleVariable: { bar: number }
  4. // function parameter annotation
  5. function foo(sampleParameter: { bar: number }) { }

Here I used inline type annotations. Of course you can use interfaces etc.

Return type annotation

You can annotate the return type after the function parameter list with the same style as you use for a variable, e.g. : Foo in the below example:

  1. interface Foo {
  2.     foo: string;
  3. }
  5. // Return type annotated as `: Foo`
  6. function foo(sample: Foo): Foo {
  7.     return sample;
  8. }

Of course I used an interface here, but you are free to use other annotations e.g. inline annotations.

Quite commonly you don’t need to annotate the return type of a function as it can generally be inferred by the compiler.

  1. interface Foo {
  2.     foo: string;
  3. }
  5. function foo(sample: Foo) {
  6.     return sample; // inferred return type 'Foo'
  7. }

However it is generally a good idea to add these annotation to help with errors e.g.:

  1. function foo() {
  2.     return { fou: 'John Doe' }; // You might not find this misspelling `foo` till it's too late
  3. }
  5. sendAsJSON(foo());

If you don’t plan to return anything from a function to you can annotate it as :void. You can generally drop :void and leave it to the inference engine though.

Optional Parameters

You can mark a parameter as optional:

  1. function foo(bar: number, bas?: string): void {
  2.     // ..
  3. }
  5. foo(123);
  6. foo(123, 'hello');

Alternatively you can even provide a default value (using = someValue after the parameter declaration) which will get injected for you if the caller doesn’t provide that argument:

  1. function foo(bar: number, bas: string = 'hello') {
  2.     console.log(bar, bas);
  3. }
  5. foo(123);           // 123, hello
  6. foo(123, 'world');  // 123, world

Overloading

TypeScript allows you to declare function overloads. This is useful for documentation + type safety purpose. Consider the following code:

  1. function padding(a: number, b?: number, c?: number, d?: any) {
  2.     if (b === undefined && c === undefined && d === undefined) {
  3.         b = c = d = a;
  4.     }
  5.     else if (c === undefined && d === undefined) {
  6.         c = a;
  7.         d = b;
  8.     }
  9.     return {
  10.         top: a,
  11.         right: b,
  12.         bottom: c,
  13.         left: d
  14.     };
  15. }

If you look at the code carefully you realize the meaning of a,b,c,d change based on how many arguments are passed in. Also the function only expects 1, 2 or 4 arguments. These constraints can be enforced and documented using function overloading. You just:

  • declare the function header multiple times,
  • the last function header is the one that is actually active within the function body but is not available to the outside world.

This is shown below:

  1. // Overloads
  2. function padding(all: number);
  3. function padding(topAndBottom: number, leftAndRight: number);
  4. function padding(top: number, right: number, bottom: number, left: number);
  5. // Actual implementation that is a true representation of all the cases the function body needs to handle
  6. function padding(a: number, b?: number, c?: number, d?: number) {
  7.     if (b === undefined && c === undefined && d === undefined) {
  8.         b = c = d = a;
  9.     }
  10.     else if (c === undefined && d === undefined) {
  11.         c = a;
  12.         d = b;
  13.     }
  14.     return {
  15.         top: a,
  16.         right: b,
  17.         bottom: c,
  18.         left: d
  19.     };
  20. }

Here the first three function signatures are what is available as valid calls to padding:

  1. padding(1); // Okay: all
  2. padding(1,1); // Okay: topAndBottom, leftAndRight
  3. padding(1,1,1,1); // Okay: top, right, bottom, left
  5. padding(1,1,1); // Error: Not a part of the available overloads

Of course it’s important for the final declaration (the true declaration as seen from inside the function) to be compatible with all the overloads. This is because that is the true nature of the function calls that the function body needs to account for.

Function overloading in TypeScript doesn’t come with any runtime overhead. It just allows you to document the manner you expect the function to be called in and the compiler holds the rest of your code in check.