Support user-defined type guard functions

[RyanCavanaugh]

We currently only support some baked-in forms of type checking for type guards -- typeof and instanceof. In many cases, users will have their own functions that can provide run-time type information.

Proposal: a new syntax, valid only in return type annotations, of the form x is T where x is a declared parameter in the signature, or this, and T is any type. This type is actually considered as boolean, but "lights up" type guards. Examples:

function isCat(a: Animal): a is Cat {
 return a.name === 'kitty';
}

var x: Animal;
if(isCat(x)) {
 x.meow(); // OK, x is Cat in this block
}

class Node {
 isLeafNode(): this is LeafNode { throw new Error('abstract'); }
}
class ParentNode extends Node {
 isLeafNode(): this is LeafNode { return false; }
}
class LeafNode extends Node {
 isLeafNode(): this is LeafNode { return true; }
}
var someNode: LeafNode|ParentNode;
if(someNode.isLeafNode()) {
 // someNode: LeafNode in this block
}

The forms if(userCheck([other args,] expr [, other args])) { and if(expr.userCheck([any args])) would apply the type guard to expr the same way that expr instanceof t and typeof expr === 'literal' do today.

[Nevor]

The second example does not seem to scale very well :

class Node {
 isLeafNode(): this is LeafNode { throw new Error('abstract'); }
 isOtherNode(): this is OtherNode { throw new Error('abstract'); }
}
class ParentNode extends Node {
 isLeafNode(): this is LeafNode { return false; } 
 isOtherNode(): this is OtherNode { return false; } 
}
class OtherNode extends Node {
 isLeafNode(): this is LeafNode { return false; }
 isOtherNode(): this is OtherNode { return true; } 
}
class LeafNode extends Node {
 isLeafNode(): this is LeafNode { return true; }
 isOtherNode(): this is OtherNode { return false; } 
}
var someNode: LeafNode|ParentNode|OtherNode;
if(someNode.isLeafNode()) {
 // someNode: LeafNode in this block
}

Furthermore, we are back with typing that is dependent on class construction while one would expect this to work with interface only for items as simple as these.

Finally, given that we are stuck with classes, we can currently encode this idiom more lightly with instanceof :

class SuperNode { }

class ParentNode extends SuperNode { 
 private constrain; // using dummy private to disjoint classes
}
class OtherNode extends SuperNode { 
 private constrain; 
}
class LeafNode extends SuperNode { 
 private constrain; 
 leafNode : string;
}


var someNode : ParentNode | OtherNode | LeafNode;

if(someNode instanceof LeafNode) {
 someNode.leafNode;
}

The first example seems to be an excellent case for #1003

[RyanCavanaugh]

Perhaps the second example was not clear in its intent. Consider something like this, where instanceof would not work:

interface Sortable {
 sort(): void;
}

class BaseCollection {
 isSortable(): this is Sortable { return false; }
}

class List extends BaseCollection implements Sortable {
 isSortable(): this is Sortable { return true; }
 sort() { ... }
}

class HashSet extends BaseCollection {
 isSortable(): this is Sortable { return false; }
}

class LinkedList extends BaseCollection implements Sortable {
 isSortable(): this is Sortable { return true; }
 sort() { ... }
}

[Nevor]

Indeed its intent is indeed clearer. So I have two comments :

1. With the current compiler, we can leverage that everything is either "undefined" or something to create an optional conversion :

interface Sortable {
 sort(): void;
}

class BaseCollection {
 asSortable() : Sortable { return undefined }
}

class List extends BaseCollection implements Sortable {
 asSortable() { return this }
 sort(){}
}

class HashSet extends BaseCollection {
}

class LinkedList extends BaseCollection implements Sortable {
 asSortable() { return this; }
 sort() { }
}

function someFun(collection : BaseCollection) {
 var asSortable = collection.asSortable();
 if(asSortable) {
 asSortable.sort();
 }
}

But I agree that it would be strange to do something through asSortable and then come back on collection to call other methods.

2. I assume that the compiler verifies that the result of "this is Sortable" is in accordance with what the class actually implements (the verification might be done structurally). In that case, what about generating the "return true" ?

class List extends BaseCollection implements Sortable {
 isSortable() : this is Sortable; // would return true
 sort() { ... }
}

class OtherList extends BaseCollection {
 isSortable() : this is Sortable; // would return true
 sort() { ... }
}

class OtherList2 extends BaseCollection {
 isSortable() : this is Sortable; // would return false
}

class OtherList3 {
 isSortable() : this is Sortable; // would return true
 sort() { ... }
}

class OtherList4 {
 isSortable() : this is Sortable; // would return false
}

[bgever]

This is a cool idea. Have you considered combining it with generics? Then you could do something like this for array checks:

function isNumber(nbr): nbr is number {
 return typeof nbr === 'number';
}

function isString(str): str is string {
 return typeof str === 'string';
}

function isArrayOf<T>(of: (item) => item is T, a: any[]): a is T[] {
 // Ensure that there's at least one item of T in the array, and all others are of T too.
}

function isArrayOrEmptyOf<T>(of: (item) => item is T, a: any[]): a is T[] {
 // Accepts an empty array, or where all items are of T.
}

function(input: string|string[]|number[]) {
 if (isString(input)) {
 // It's a string.
 }
 else if (isArrayOrEmptyOf(isString, input)) {
 // It's an array of string, or
 // an empty array (could be either of string or number!)
 }
 else if (isArrayOf(isNumber, input)) {
 // It's an array of number.
 }
}

[ahejlsberg]

Bart Verkoeijen (@bgever) We did indeed consider that. It breaks down to (a) allowing x is T where T is a type parameter, and (b) extending type inference such that a type argument can be inferred from the target type of a user defined type guard function. All up I think this could be really useful.

[Arnavion]

One example usage for the standard library - Array.isArray can be changed to:

interface ArrayConstructor {
 isArray<T>(arg: any): arg is T[];
}