Call Signatures and Function Objects

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Call signature

A member of an object type, (x: number): string, that says the value can be called.

Construct signature

A member written new (x: number): Thing, that says the value can be called with new to build something.

Function object

A function seen as an object that may have properties attached.

Expando property

A property you add to a function after declaring it, like slugify.calls = 0. TypeScript tracks it.

Constructor

The special function of a class that creates an instance when called with new.

Instance

An object created from a class with new.

Function (type)

A built-in type meaning "any callable". It turns off argument and result checking.

Intersection type

A type written A & B that has everything from both.

1. 1

   Add a second call signature

   In the first example add (start: number): number; to Counter. Predict whether tsc complains about makeCounter. It does not: as Counter told TypeScript to trust you, so the second signature is promised but never built. Call next(10) and notice it is accepted while the real function ignores the 10. A cast can't check a promise.

2. 2

   Write it as a function type

   Try replacing type Counter by type Counter = () => number. Predict which lines turn red. The members reset and count no longer exist on the type.

3. 3

   Call a wrong shape

   In the last example, change Function to (...args: number[]) => unknown and re-run. The call that passes (a: string) => ... is now rejected, and the result of fn(1, 2, 3) is unknown instead of any. Compare with the version using Function.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: Functions in JavaScript can carry properties, and can be called with new to build objects. A plain function type can't describe either, so those uses go unchecked. In JavaScript a function is an object with a special ability: it can be called (typeof reports "function", but it is still an object). Because it is an object, you can hang properties on it (slugify.calls = 0), and libraries do this all the time (axios is a function and also has axios.get; jQuery is a function and has $.ajax). To describe a value like that you need a type that says both "callable" and "has these properties".

2. 2

   A call signature inside an object type does that. It looks like a method without a name: type Counter = { (): number; reset(): void; count: number }. The (): number part says "you can call it with no arguments and get a number"; the rest are ordinary members. Parameters go inside the parentheses as usual, and a type can have several call signatures (an overloaded function, Topic 2.5).

3. 3

   Two spellings describe the same function type: the short function type expression (n: number) => string (Topic 2.1) and the call signature { (n: number): string }. Notice the arrow => in one and the colon : in the other. Use the short form when it is only a function. Use the call signature form when you need properties or several signatures in the same type.

4. 4

   TypeScript can also work out the properties you add to a function. If you declare function slugify(...) or const f = () => ... and then assign slugify.calls = 0 in the same scope, TypeScript treats it as a declared property (an expando property). For more control, Object.assign(fn, { label: "inc" }) returns the intersection ((n: number) => number) & { label: string } (Topic 3.3), which you can name with a type.

5. 5

   A construct signature describes something you can call with new: new (x: number, y: number) => Point. It looks like a call signature with new in front. A class constructor has this type. If you want a parameter that accepts "a class that builds a Point" (a factory, dependency injection, a registry of classes), type it like Maker: new (x: number, y: number) => { x: number; y: number }. Passing the class Point is accepted if its constructor and instances fit. Calling a new-only value without new is TS2348: Value of type 'PointMaker' is not callable. Did you mean to include 'new'?.

6. 6

   What about the built-in type **Function**? It means "anything callable" and nothing more. A value typed Function can be called with any arguments and returns any, so every check is off: fn(1, 2, 3) is accepted even if the real function wants a string. It is almost never what you want, and linters ban it. Prefer a specific function type such as (n: number) => number, or (...args: never[]) => unknown if you truly need "any function".

7. 7

   Rule of thumb: describe a plain callback with a function type expression. Add a call signature only when the value is callable and has members, or has several signatures. Add a construct signature when something must be created with new. And reach for Function or any for functions never: they remove exactly the checks you came here for.

• ↔

  Attaching properties to functions is compact (one export that is both callable and a namespace), but it hides state in a global-ish object and is harder to type and to tree-shake. Often a plain object with methods, or a class, is clearer.

• ↔

  Construct signatures make factories flexible, but classes with different constructors rarely fit one shape. Keep the signature small, or accept a factory function (() => T) instead of a class.

• I can write an object type with a call signature and members.

• I can say when to use a function type expression and when a call signature.

• I can write a construct signature and explain TS2348.

• I can explain why Function is unsafe and what to use instead.

• I can describe how properties on functions are typed.