Les unions de types en TypeScript

Beaucoup de bibliothèques JavaScript acceptent des valeurs de plus d'un seul type. Par exemple, la propriété AJAX jsonp avec jQuery peut être soit false (i.e. de type boolean) ou une chaîne de caractères (type string). Les fichiers de définition TypeScript (.d.ts) doivent représenter cette propriété avec le type any, perdant ainsi la sécurité du typage.

De même, la configuration du service HTTP d'AngularJS (https://docs.angularjs.org/api/ng/service/$http#usage) possède des propriétés de type boolean, Cache, number ou encore Promise.

Cette lacune peut souvent être contournée avec des surcharges de fonction, mais il n'y a pas d'équivalent pour les propriétés des objets, les contraintes sur les types, ou d'autres rôles concernant les types.

Le nouvel opérateur |, lorsqu'il est utilisé pour séparer deux types, produit une union de types représentant une valeur qui est de l'un des types en entrée.

Exemple :

interface Settings {
    foo: number|string;
}
function setSetting(s: Settings) { /* ... */ }
setSettings({ foo: 42 }); // OK
setSettings({ foo: '100' }); // OK
setSettings({ foo: false }); // Error, false is not assignable to number|string

Plusieurs types peuvent être combinés de cette façon :

function process(n: string|HTMLElement|JQuery) { /* ... */ }
process('foo'); // OK
process($('div')); // OK
process(42); // Error

N'importe quel type est un opérande valide pour l'opérateur |. Voici quelques exemples et comment ils seraient analysés :

var x: number|string[]; // x is a number or a string[]
var y: number[]|string[]; // y is a number[] or a string[]
var z: Array<number|string>; // z is an array of number|string
var t: F|typeof G|H; // t is an F, typeof G, or H
var u: () => string|number; // u is a function that returns a string|number
var v: { (): string; }|number; // v is a function that returns a string, or a number

Notez que les parenthèses n'étant pas nécessaires pour lever l'ambiguïté, elles ne sont pas acceptées.

La signification de A|B est un type qui est soit un A, soit un B. En particulier, c'est différent d'un type qui combinerait tous les membres de A et de B. Nous examinerons cela dans des exemples plus loin.

Quelques règles simples :

• identité : A|A est équivalent à A ;
• commutativité : A|B est équivalent à B|A ;
• associativité : (A|B)|C est équivalent à A|(B|C);
• effacement du sous-type : A|B est équivalent à A si B est un sous-type de A.

Le type A|B possède une propriété P de type X|Y si A possède une propriété P de type X et B possède une propriété P de type Y. Ces propriétés doivent soit être à la fois publiques, soit provenir du même site de déclaration (tel que spécifié dans les règles pour private/protected). Si l'une des propriétés est facultative, la propriété qui en résulte est également facultative.

Exemple :

interface Car {
    weight: number;
    gears: number;
    type: string;
}
interface Bicycle {
    weight: number;
    gears: boolean;
    size: string;
}
var transport: Car|Bicycle = /* ... */;
var w: number = transport.weight; // OK
var g = transport.gears; // OK, g is of type number|boolean
 
console.log(transport.type); // Error, transport does not have 'type' property
console.log((<Car>transport).type); // OK

Le type A|B a une signature d'indice [x: number]: T ou [x: string]: T si les deux A et B ont une signature d'indice de ce type.

D'autres scénarios nécessitent un type construit à partir de A et B ayant tous ses membres présents dans l'un ou l'autre des deux types, mais pas dans les deux. Au lieu d'ajouter une nouvelle syntaxe de type, nous pouvons représenter cela facilement en supprimant la restriction qui fait que les clauses extends peuvent ne pas référencer les paramètres de type de leur déclaration.

Exemple :

interface HasFoo<T> extends T {
    foo: string;
}
interface Point {
    x: number;
    y: number;
}
var p: HasFoo<Point> = /* ... */;
console.log(p.foo); // OK
console.log(p.x.toString(); // OK

Pour les unions de types où un opérande est une primitive, nous avons pu détecter certains schémas syntaxiques et ajuster le type d'un identifiant dans les blocs conditionnels.

Exemple :

var p: string|Point = /* ... */;
if(typeof p === 'string') {
    console.log(p); // OK, 'p' has type string in this block
} else {
    console.log(p.x.toString()); // OK, 'p' has type Point in this block
}

Cela pourrait également s'étendre à des vérifications d'appartenance :

interface Animal { run(); }
interface Dog extends Animal { woof(); }
interface Cat extends Animal { meow(); }
var x: Cat|Dog = /* ... */;
if(x.woof) {
   // x is 'Dog' here
}
if(typeof x.meow !== 'undefined') {
   // x is 'Cat' here
}