What is this TypeScript pattern with interface and declare var?

Issue

Looking at this as an example:

interface DOMPoint extends DOMPointReadOnly {
    w: number;
    x: number;
    y: number;
    z: number;
}

declare var DOMPoint: {
    prototype: DOMPoint;
    new(x?: number, y?: number, z?: number, w?: number): DOMPoint;
    fromPoint(other?: DOMPointInit): DOMPoint;
};

interface DOMPointReadOnly {
    readonly w: number;
    readonly x: number;
    readonly y: number;
    readonly z: number;
    matrixTransform(matrix?: DOMMatrixInit): DOMPoint;
    toJSON(): any;
}

declare var DOMPointReadOnly: {
    prototype: DOMPointReadOnly;
    new(x?: number, y?: number, z?: number, w?: number): DOMPointReadOnly;
    fromPoint(other?: DOMPointInit): DOMPointReadOnly;
};

interface DOMQuad {
    readonly p1: DOMPoint;
    readonly p2: DOMPoint;
    readonly p3: DOMPoint;
    readonly p4: DOMPoint;
    getBounds(): DOMRect;
    toJSON(): any;
}

Why are they declaring an uppercase variable the same name as the interface, with a different structure? What does it mean? And in the DOMQuad when they reference DOMPoint, are they referencing the var or the interface? What is the purpose of the var?

Solution

It's providing type information for the built-in DOMPoint class provided by the browser.

Why are they declaring an uppercase variable the same name as the interface, with a different structure?

The interface defines what instances of DOMPoint look like. The declare global var DOMPoint tells TypeScript that a global exists (provided by the browser) that is a function that creates DOMPoint instances (new) and a fromPoint static method.

This mimics what TypeScript does with class X { }, where it both creates a type (X) for what instances of X will look like, and a constructor function (X) which is a runtime value (not just a type).

And in the DOMQuad when they reference DOMPoint, are they referencing the var or the interface?

The interface.

What is the purpose of the var?

Purely to tell TypeScript it exists. It doesn't create it (the browser does), it's just so TypeScript knows that using DOMPoint is valid, it's a global that exists with the given signature.

Answered By - T.J. Crowder