Functions and their signatures

A promise in two directions

Every function has a signature: the types of what it takes, and the type of what it returns. Writing it down is not ceremony — it is the two facts every caller depends on, said once, checked everywhere.

The parameters say what the function will accept. The return type says what the caller can count on. Between them, they turn "read the whole function to find out" into "read one line".

A signature does not promise that the function is correct, that it finishes, or that it does not throw. It promises the shape of the exchange: values of these types go in, a value of that type comes out. Everything else is the body’s business.

How the promise is checked

When you call add(2, 3), the checker takes the types of the arguments — number and number — and compares them, in order, with the parameter list. Then it gives the call expression the return type from the signature, without looking inside the body. That is the economy of a signature: callers are checked against one line, and the body can be rewritten freely as long as it still keeps the promise.

The body is checked in the other direction. Every return statement is compared with the declared return type, and a path that falls off the end of a function promising number is an error. That error points at the function, not at a call, because the body is the side that broke the promise.

The same function, promised out loud

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

function announce(message: string): void {
  console.log(message);
}

const double = (value: number): number => value * 2;

Nothing to return is worth saying too

void is the return type for a function that answers with nothing — it logs, it saves, it clears. Saying so is what stops the call site from using the result of a function that never had one.

A return type is also a check on you: a function that promises number cannot end with a bare return; on one path and return 5; on another. The compiler walks every path and holds you to the promise.

Optional and default values

A question mark marks a parameter the caller may skip: function greet(who?: string). Inside the function its type is string | undefined — the compiler insists you handle the missing case, which is exactly the bug the annotation just prevented.

A default value makes the same promise but always has something to give: function greet(who = "friend"). The parameter stays a string; the caller may still pass one.

A function type is a shape too

Functions can be passed around, so they need types as well. (n: number) => number describes a function that takes a number and returns one. The arrow is the type-level way of saying "a function from these arguments to this result".

That type is checked where the function is supplied. A callback with the wrong parameter type is refused at the line that passed it, which is the earliest place the mistake could possibly be seen.

What the caller sees

A signature is documentation the compiler enforces. Rename a parameter and no call site changes; change a type or add a required parameter and every caller that no longer fits is reported.

That is why the signature should be settled before the body. The signature is the decision; the body is one implementation of it, and the checker will tell you if the two disagree.

What goes wrong

The optional parameter is where most first errors appear. function greet(who?: string) gives who the type string | undefined, so who.toUpperCase() is refused with Object is possibly ’undefined’. That message is not an obstacle to work around; it is the missing branch made visible. The fix is an if (who) guard or a default value, and both are shorter than the bug report you would otherwise write.

The second error is arity: calling add(2) reports that two arguments were expected. TypeScript refuses both too few and too many arguments, because an argument the function ignores is usually a caller that meant something else. Keep the call and the signature in step, and let the error tell you which is wrong.

Try these next

• Write applyTwice that takes a number and a function, and call it with a doubling function.
• Add a default value to an optional parameter and compare the two versions at the call site.
• Give a function an explicit : void return type, then try to log its result and read the error.