Docs: Function Parameter Bivariance

Official document about bivariance is too simple to understand for newbies.

enum EventType { Mouse, Keyboard }

interface Event { timestamp: number; }
interface MouseEvent extends Event { x: number; y: number }
interface KeyEvent extends Event { keyCode: number }

function listenEvent(eventType: EventType, handler: (n: Event) => void) {
    /* ... */
}

// Unsound, but useful and common
listenEvent(EventType.Mouse, (e: MouseEvent) => console.log(e.x + "," + e.y));

// Undesirable alternatives in presence of soundness
listenEvent(EventType.Mouse, (e: Event) => console.log((<MouseEvent>e).x + "," + (<MouseEvent>e).y));
listenEvent(EventType.Mouse, <(e: Event) => void>((e: MouseEvent) => console.log(e.x + "," + e.y)));

// Still disallowed (clear error). Type safety enforced for wholly incompatible types
listenEvent(EventType.Mouse, (e: number) => console.log(e));

And sample code is also confusing, painfully I have found these awesome examples:

// Contravariance
class Example {
    foo(maybe: number | undefined) { }
    str(str: string) { }
    compare(ex: Example) { }
}

class Override extends Example {
    foo(maybe: number) { } // Bad: should have error.
    str(str: 'override') { } // Bad: should have error.
    compare(ex: Override) { } // Bad: should have error.
}

and

// Bivariance
interface Comparer<T> {
    compare(a: T, b: T): number;
}

declare let animalComparer: Comparer<Animal>;
declare let dogComparer: Comparer<Dog>;

animalComparer = dogComparer;  // Ok because of bivariance
dogComparer = animalComparer;  // Ok

Related references:

• Strict function types
• Overridden method parameters are not checked for parameter contravariance

Above links are really helpful and clearly to illustrate bivariance.

Start with the linked TypeScript Handbook section on function parameter bivariance, then read the linked strict-function-types pull request and related issue. Clarify the explanation with examples like those in the report, and consider the work done when newcomers can understand why the assignments are accepted or rejected.