Inference, and When to Annotate

1
2
3
4
5
6
7
8
9
10
11
12
13const title = 'Persuasion';
const year = 1817;
const finished = true;
const chapters = [1, 2, 3];
const author = { name: 'Austen', initials: 'JA' };

// Hover any of these in your editor and you will see a precise type.
// The compiler read the initialiser and drew the obvious conclusion.
console.log(title.toUpperCase());
console.log(year.toFixed(0));
console.log(finished === true);
console.log(chapters.map((n) => n * 2));
console.log(author.name.length);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17// `const` can never be reassigned, so the compiler records the exact value.
// The type of `direction` is not string — it is the literal type 'north'.
const direction = 'north';

// `let` can be reassigned, so the compiler widens to the general type.
// The type of `heading` is string.
let heading = 'north';
heading = 'south';

console.log(direction, heading);

// Same for numbers: `size` is the literal 10, `count` is number.
const size = 10;
let count = 10;
count = 11;

console.log(size, count);

1
2
3
4
5
6
7
8
9
10
11
12
13// `const` can never be reassigned, so the compiler records the exact value.
// The type of `direction` is not string — it is the literal type 'north'.
const direction = 'north';
// `let` can be reassigned, so the compiler widens to the general type.
// The type of `heading` is string.
let heading = 'north';
heading = 'south';
console.log(direction, heading);
// Same for numbers: `size` is the literal 10, `count` is number.
const size = 10;
let count = 10;
count = 11;
console.log(size, count);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16function turn(to: 'north' | 'south'): string {
  return `turning ${to}`;
}

// 1. const keeps the literal type.
const a = 'north';
console.log(turn(a));

// 2. Annotate the variable, so widening has a boundary to stop at.
let b: 'north' | 'south' = 'north';
b = 'south';
console.log(turn(b));

// 3. as const, when the value is inside something bigger.
const config = { heading: 'north' } as const;
console.log(turn(config.heading));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// No return annotation, and the compiler knows this returns a number.
function area(width: number, height: number) {
  return width * height;
}

// It follows branches, and unions the results. This returns string | number.
function format(value: number, asText: boolean) {
  if (asText) return value.toFixed(2);
  return value;
}

console.log(area(3, 4));
console.log(format(3.14159, true));
console.log(format(3.14159, false));

// It handles async: this is Promise<string>, inferred.
async function fetchName() {
  return 'Ada';
}

fetchName().then((name) => console.log('resolved to', name));

1
2
3
4
5
6
7
8
9
10
11
12// Annotated: if the body stops returning a number, the error appears HERE,
// on this function, which is where the mistake was made.
export function totalAnnotated(prices: number[]): number {
  return prices.reduce((sum, p) => sum + p, 0);
}

// Unannotated: the return type silently becomes whatever the body produces.
// Change the body and nothing complains here — the errors appear at every
// call site instead, which is further from the cause.
export function totalInferred(prices: number[]) {
  return prices.reduce((sum, p) => sum + p, 0);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const words = ['delta', 'alpha', 'charlie'];

// `w` is known to be string, because map on a string[] says so.
// Annotating it here would be noise.
console.log(words.map((w) => w.toUpperCase()));

// Same for sort, filter, reduce, forEach and every callback you are handed.
console.log([...words].sort((x, y) => x.localeCompare(y)));
console.log(words.filter((w) => w.startsWith('a')));

// It flows through your own functions too, as long as the parameter is typed.
function each(items: number[], visit: (item: number, index: number) => void) {
  items.forEach(visit);
}

each([10, 20], (item, index) => console.log(index, item));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17// Without the annotation this would be any[], and every later mistake with it
// would go unnoticed.
const seen: string[] = [];
seen.push('alpha');
seen.push('beta');
console.log(seen.join(', '));

// Same for Map and Set, which are extremely common in the algorithms course.
const counts = new Map<string, number>();
counts.set('a', 1);
counts.set('b', 2);
console.log([...counts.entries()]);

const unique = new Set<number>();
unique.add(1);
unique.add(1);
console.log('size:', unique.size);

1
2
3
4
5
6
7
8
9
10
11
12type Status = 'draft' | 'published' | 'archived';

// Inferred as the literal 'draft', which cannot then be reassigned to
// anything else. Annotating widens it to exactly what you want.
let state: Status = 'draft';
state = 'published';
console.log(state);

// Same idea for arrays that will hold more than they start with.
const mixed: (string | number)[] = [1, 2];
mixed.push('three');
console.log(mixed);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Over-annotated: every one of these is redundant.
const nameA: string = 'Ada';
const yearA: number = 1815;
const tagsA: string[] = ['maths', 'engines'];
const pairA: { x: number; y: number } = { x: 1, y: 2 };

// Exactly equivalent, and this is what you should write.
const nameB = 'Ada';
const yearB = 1815;
const tagsB = ['maths', 'engines'];
const pairB = { x: 1, y: 2 };

console.log(nameA === nameB, yearA === yearB);
console.log(tagsA.length === tagsB.length);
console.log(pairA.x === pairB.x);

// Worse than redundant: this annotation is strictly WORSE than inference,
// because it throws away the literal types the object would have had.
const looseA: { heading: string } = { heading: 'north' };
const tightB = { heading: 'north' };
console.log(looseA.heading, tightB.heading);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16type Palette = Record<string, string>;

// Annotated: checked, but every key is now just string, so the compiler
// has forgotten which keys exist.
const annotated: Palette = { primary: '#3055d8', danger: '#b4232a' };

// satisfies: checked against Palette, and the exact keys are remembered.
const checked = { primary: '#3055d8', danger: '#b4232a' } satisfies Palette;

console.log(annotated.primary);
console.log(checked.primary);

// The difference shows up in what the compiler will let you ask for.
// checked.primary is known to exist; on `annotated` any string key is allowed,
// including ones that are not there.
console.log(Object.keys(checked));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15interface Point {
  x: number;
  y: number;
}

function distance(a: Point, b: Point): number {
  const dx: number = a.x - b.x;
  const dy: number = a.y - b.y;
  return Math.sqrt(dx * dx + dy * dy);
}

const origin: Point = { x: 0, y: 0 };
const target: Point = { x: 3, y: 4 };

console.log('distance:', distance(origin, target));

1
2
3
4
5
6
7
8function distance(a, b) {
    const dx = a.x - b.x;
    const dy = a.y - b.y;
    return Math.sqrt(dx * dx + dy * dy);
}
const origin = { x: 0, y: 0 };
const target = { x: 3, y: 4 };
console.log('distance:', distance(origin, target));