Primitive Types

From a .NET perspective, JavaScript primitive types are slightly limited. The String and Boolean types are as you would expect, and the Number type is the equivalent of System.Double; there is no integer type in TypeScript or JavaScript.

var heroName : string = "Bilbo Baggins";
var orcsNeedAShower : bool = true;

The null and undefined types, however, are often a source of confusion. In a nutshell, undefined is equivalent to a variable having no value or object assigned to it, while null means an object has been assigned to the variable but that object is null (a la C#). So undefined is a value, while null is an object. To add a little more confusion, variables cannot be typed as Undefined or Null, but they can be given the values undefined and null explicitly (or by not setting a variable’s value when declaring it, in undefined’s case).

var numberOfGoblins : number;
// Same as var numberOfGoblins : number = undefined;

var ageOfGandalf = undefined;
// Same as var ageOfGandalf : any = undefined;
 
var ageOfSaruman : number = null;
// Primitives can be given the null value (confusingly)
 
var ageOfRadagast = null;
// Same as var ageOfRadagast : any = null;
 
var error1 : Null; // Throws an error
var error2 : Undefined; // Throws an error

The Any Type

I’ve mentioned it in passing so far, but there’s one more variable type to cover in detail. If you do not assign a variable a type, the TLS assigns it the Any type. If you do this, or set it explicitly, it will be allowed to act as any standard, dynamically typed JavaScript variable that can be set any value, from complex objects to a simple number.

var changeling;      // assigned type Any implicitly
var morph : any;     // assigned type Any explicitly

When a variable is given the Any type, the TLS will try to infer the type of the variable you are using in order to make sure you’re not doing anything potentially incorrect with it. However, if you do want to use it as a dumping ground for random values, that’s entirely up to you. JavaScript allows this, and TypeScript does too.

Of course, as TypeScript actually gives you a strongly typed diving board over the shark-infested waters of dynamic JavaScript variables, you should always prefer to assign a specific type to a variable rather than the Any type. You’ll get no IntelliSense help or red squigglies to help you deal with Any type variables correctly. Future iterations of the TypeScript compiler will also verify that there are no spurious variables of type Any in your program.

Arrays

If you’re a C# developer, arrays use the same syntax and literals as you’re already used to. An array type is defined by using the name of the type in the array followed by a pair of square brackets. For example:

var emptyArray: any[] = new Array();

Array literals are written as comma-separated lists surrounded by a pair of square brackets:

var actors: string[] =  ["Martin Freeman", "Ian Holm", "Elijah Wood"];

You can assign only one type to all the elements in an array. You can’t state a set of allowed types. You can, however, declare the array to be of type any[], in which case the array can hold any value of any type—numbers, objects, functions, other arrays, and so forth.

Arrays are of variable length, and not fixed length as in C#. You can retrieve the number of items in the array by using its length property and add or remove items with its push or  pop functions as you would in .NET.

You can iterate through the items in an array by using either for or for..in loops as demonstrated here:

// standard for loop
for (var i = 0; i < actors.length; i++)
{
    console.log(actors[i]);
}

// for..in loop
for (var actor in actors)
{
    console.log(actor);
}

Note that you can reference an item in an array by using both a number and a string. However, using a string indexer returns a value of type any rather than one of type string. For example:

var asExpected = actors[0];        // returns string "Martin Freeman"
var gotcha = actors["Ian Holm"];   //  returns value of type any

The same is true of all arrays of type T[]. Using a numerical index returns a value of type T. Using a string index returns a value of type Any.

var trilogies: string[][] = [
    ["An Unexpected Journey", "The Desolation of Smaug", "There and Back Again"],
    ["The Fellowship Of the Ring", "The Two Towers", "The Return Of The King"]
];

var trilogies: string[][] = new Array();
trilogies.push(["An Unexpected Journey", "The Desolation of Smaug", "There and Back Again"]);
trilogies.push(["The Fellowship Of the Ring", "The Two Towers", "The Return Of The King"]);

Casts

One of the more common issues of working with strongly typed variables is the need to cast between types from time to time. Naturally, it’s preferable to use a method such as ToString or ParseInt to do the conversion for you, but there are occasions in both .NET and TypeScript programming when an explicit cast (boxing) is required. In the TypeScript specification (section 4.13), it’s referred to as type assertion, but it’s still casting. The syntax is to put the target type between < and > symbols and then place it in front of the variable or expression that returns a value. For example:

var a : int = <int>SomeNumberAsAString;

Those familiar with client-side web programming using JavaScript and the Document Object Model (DOM) may occasionally come across issues as a result of the strongly typed nature of TypeScript that would not arise in plain JavaScript. For example, in the Stack Overflow post- http://stackoverflow.com/questions/12686927/typescript-casting-htmlelement, a user copied some working DOM-manipulation code straight from JavaScript into TypeScript and was told a method he was calling on an HTML element did not exist. It transpired that JavaScript was transparently converting the element his code selected (an HTMLElement) into a different type that did define the method (an HTMLScriptElement), but as TypeScript would not do that without an explicit cast, an error occurred. However, we can cast the type of the returned object to an HTMLScriptElement.

var script = <HTMLScriptElement>document.....

Don’t forget that type assertions are only a design-time feature of TypeScript designed to make sure that you can indeed cast from one type to another and that what you call on the newly cast object is possible. TypeScript uses structural (duck) typing, so if a Duck object has the same methods and properties as a Pig object—Oink(), Snort(), and so forth—apart from it being a very strange duck, it can be cast into a Pig object.

Section 4.13 of the TypeScript specification

In TypeScript, then, you won’t be able to cast an integer to an HTMLScriptElement, for instance, but you would in JavaScript, and you would find out something was wrong only at runtime.

Ambient Declarations

As you saw in Chapter 1, you can use ambient declarations to create a placeholder variable to represent an object or other variable not declared in full in your current TypeScript file. For example, you might want to use a third-party JavaScript library that does not have its own declaration file. You can use an ambient declaration to introduce an object created in that library into your script without having the compiler throw an error because it does not know what the variable is referring to. For example, if you wanted to add a reference to the global jQuery object $ without adding a reference to the jQuery declaration file, you would write this:

declare var $;

The key is to prefix the variable declaration with the declare keyword, as you saw in the example at the end of Chapter 1.

Variations on a Signature

TypeScript functions may take three types of parameters when defined:

• Positional parameters
• Optional parameters
• Rest parameter

function CelsiusToFahrenheit(celsius: number): number {
    return (celsius * (9 / 5) + 32);
}

var kelvin: number;
function CelsiusConverter (celsius: number,
    calculateKelvinToo?: bool = false): number {
    if ( calculateKelvinToo) { kelvin = celsius −273.1;  }
    return (celsius * (9 / 5) +32);
}

function CelsiusConverter (celsius: number,
    calculateKelvinToo?: bool = false ): number {
   ...
}

var kelvin: number;
function CelsiusConverter (celsius: number,
    calculateKelvinToo?: bool): number {
    if ( calculateKelvinToo !== null && calculateKelvinToo !== undefined ) {
       if ( calculateKelvinToo) { kelvin = celsius −273.1;  }
    }
    return (celsius * (9 / 5) +32);
}

function CountDwarvesTallerThan(minHeight: number, ...dwarves: Dwarf[]) : number {
    var count: number = 0;
    for (var i = 0; i < dwarves.length; i++) {
        if (dwarves[i].height > minHeight) {
            count++;
        }
    }
    return count;
}

Function Overloads

TypeScript also supports the overloading of functions, albeit without quite the same efficacy as .NET. JavaScript has no concept of method overloading itself, so while the TLS enforces strong typing against the various overloads at design time, you still have to write a generalized form of the function that will work in “raw” JavaScript that discerns which one of the overloads you’re using and operates accordingly.

All of this explanation really requires an example to clarify the picture.

In .NET, a method can be overloaded by creating multiple functions with the same name, but each working with different parameter types. For example, in C# I might overload a function called CalculateArea like so:

public double CalculateArea(Square shape)
{
   return shape.x * shape.y;
}
 
public double CalculateArea(Ellipse shape)
{
   return shape.r1 * shape.r2 * Math.PI;
}
 
public double CalculateArea(Triangle shape)
{
   return 0.5 * shape.x * shape.y;
}

The function name is the same, but the signature of each overload (that is, their name and parameters but, crucially, not the return type) is different.

In TypeScript, a method is overloaded by stacking each signature variant of the function on top of a single implementation of the function. For example:

function CalculateArea(shape : Square) : number;
function CalculateArea(shape : Ellipse) : number;
function CalculateArea(shape : Triangle): number;
function CalculateArea(shape : Shape) : number {     //  <−− The crucial line!!
   if (shape instanceof Square) {
     return (<Square>shape).x * (<Square>shape).y;
   }
   if (shape instanceof Ellipse) {
     return (<Ellipse>shape).r1 * (<Ellipse>shape).r2 * Math.PI;
   }
   if (shape instanceof Triangle) {
     return 0.5 * (<Triangle>shape).x * (<Triangle>shape).y;
   }
   throw new TypeError("Unsupported type!");
}

The key differences here are as follows:

• You must explicitly type your functions—parameters and return types—if you want to overload them.
• There is an additional generalized function signature at the bottom of the stack.

• You need to generalize all parameters and the return type. Use optional parameters if the number of parameters varies plus default parameter values as appropriate.
• You need to generalize the return type as well: it is key.
• The signature of the implementation has to be compatible with all of the overloads.

• You must type-check the parameters within the function body. Again, the final JavaScript method is not type safe, so TypeScript forces you to write overloaded functions in this way. Use typeof to test for primitive types and instanceof for everything else.

Basically, you are creating just one function and giving it a number of signatures so that TypeScript doesn’t give compile errors when you pass it differently typed parameters. This means that while you’re still writing the code, the TLS will strongly type the function calls correctly, but when compiled to JavaScript, the concrete function alone will be visible. For example, the overloaded CalculateArea function in the preceding code compiles down into the following JavaScript:

function CalculateArea(shape) {
    if(shape instanceof Square) {
        return (shape).x * (shape).y;
    }
    if(shape instanceof Ellipse) {
        return (shape).r1 * (shape).r2 * Math.PI;
    }
    if(shape instanceof Triangle) {
        return 0.5 * (shape).x * (shape).y;
    }
    throw new TypeError("Unsupported type!");
}

And, unless you call CalculateArea from outside your TypeScript, you know that all the calls to this concrete function will work with the objects sent to them because all calls have been vetted by the TLS. (They may throw a TypeError, but that still counts as working in this case.)

Class Members

TypeScript classes provide for the same three types of class members you would expect to find in .NET:

• Properties and fields to store data
• Methods to define behavior
• Events to provide interactions between different objects and classes

Let’s look at each of these in turn.

class SimpleWebSocket {
    serviceUrl: string;
}

class SimpleWebSocket {
    private serviceUrl: string;
    get ServiceUrl(): string {
        // Fields and Properties are always referred to in class prefixed with 'this.'
        return this.serviceUrl;
    }

    set ServiceUrl(value: string) {
        this.serviceUrl = value;
    }
}

class SimpleWebSocket {
    Close(code: number, reason: string): void {
        console.log(code + " : " + reason);
        this.state = this.SocketState.CLOSED;
    }
}

class SimpleWebSocket {
    Close(code: string): void;
    Close(code: string, reason: string): void;
    Close(code: number): void;
    Close(code: number, reason: string): void;
    Close(code: any, reason?: string): void {
        var logEntry: string = code.toString();
        if (reason) { logEntry += (" : " + reason); }
        console.log(logEntry);
        this.state = this.SocketState.CLOSED;
    }
}

class SimpleWebSocket {
    state : number;
 
    Close(code: number, reason: string): void {
        console.log(code + " : " + reason);
        this.state = this.SocketState.CLOSED;
    }
}

class UITester {
    menuTouches : number;
    sidebarTouches : number;
 
    beginMenuTest(): void {
        this.menuTouches = 0;   // Right!!
        menu.onmouseenter = function (e) {
            this.menuTouches++;  // Wrong!!
        }
}

    beginSidebarTest() : void {
        this.sidebarTouches = 0;  // Right!!
        sidebar.onmousemove = e => {
            this.sidebarTouches++;  // Still right!!
        }
    }
}

class SimpleWebSocket {
    constructor (url: string) {
        this.serviceUrl = url;
        this.state = this.SocketState.OPEN;
        this.messagesSent = 0;
    }
}

class SimpleWebSocket {
    constructor ();
    constructor (url: string);
    constructor (url?: string) {
        if (url !== null && url !== undefined) {
            this.ServiceUrl = url;
        }
        else {
            this.ServiceUrl = " http://localhost:80 ";
        }
        this.state = this.SocketState.OPEN;
        this.messagesSent = 0;
    }
}

// Using the DOM
document.getElementById("btnGo").addEventListener("click", displayDate);
 
// Using jQuery
$("#btnGo").click(displayDateJQ);

// Declare the delegate (if using non-generic pattern).
public delegate void SampleEventHandler(object sender, SampleEventArgs e);
 
// Declare the event.
public event SampleEventHandler SampleEvent;

class SimpleWebSocket {
    onOpen?: (ev: Event) => any;
}

Access Modifiers

You can add public and private accessors to the fields, properties, and methods inside a class:

• public (the default) indicates that the class member is available to all code in another module after it has been exported.
• private indicates that the class member is available only to other code in the same assembly.

For instance:

class SimpleWebSocket {
    private serviceUrl : string;
}

Note, however, that, as discussed earlier, the class member will not actually be accessible only to the class when compiled as JavaScript. It is only at design time that the TLS enforces the concept of private members.

Instantiating Classes

To create an object, you can instantiate a class by using the new keyword, exactly as you would in C#:

var TestSocket : SimpleWebSocket = new ←    SimpleWebSocket(" http://testthis.com");

After you’ve created the object, you can assign and retrieve that instance’s properties and invoke its methods:

console.log("Opened a connection to " + TestSocket.ServiceUrl);
TestSocket.Send("Test the socket");
TestSocket.Close(200, "OK");
console.log(TestSocket.state.toString());

Check whether you can create an instance of a class by using an object literal.

Static Classes and Members

You can use the static keyword to indicate that a class property, field, or function is shared by all instances of a class, as you would in C# or by using the shared keyword in Visual Basic. To access the static member, use the name of the class without instantiating it:

class SimpleWebSocket {
    static origin: string;
 
    static ThrowError(code: number) {
        this.Close(code);   // NB. You can call non-static methods from a static method.
    }
}
 
SimpleWebSocket.origin = "Program Name";
SimpleWebSocket.ThrowError(404);

Note that if you are referencing the static member from within a class function, you do not need to prefix it with this:

class SimpleWebSocket {
    constructor (url: string) {
        this.ServiceUrl = url;                      // non-static members. 'this' required
        this.state = this.SocketState.OPEN;
        this.messagesSent = 0;
        SimpleWebSocket.origin = "This Program";    // static member. No 'this' required.
    }
 
    static origin: string;
}

Unlike .NET, static methods do not have to call only static methods or reference only static fields and properties. Also, while there is no explicit way to label a class as static, it is perfectly correct to label every member of a class as static, which amounts to the same thing. There is just no way to have the TLS check that all members of a class are static. You have to do it yourself.

Object Literals vs. Anonymous Types

In .NET, anonymous types allow you to create objects without a class definition. The compiler then generates a class for you that has no name and only the properties you specify when creating the object. For instance:

var simpleAnonymousObject = new { This = 123, That = "A string" };

In TypeScript, a similar system occurs through the use of JSON-formatted object literals. A variable can be assigned an object literal—the new keyword is not required in TypeScript—and the TLS then infers the type of that variable.

var anon = { This : 123, That : "A String" };

Hover your cursor over the anon variable name and you’ll see the inferred type, which in this case is

{
   This: number;
   That: string;
}

Inheritance

JavaScript mirrors the concept of class inheritance through the creation of a prototype chain on your objects. While TypeScript compiles the relationship between classes and base classes into similar code, the actual syntax to indicate that relationship in TypeScript is more akin to that of .NET, using the extends keyword to indicate an inheritance relationship.

class ComplexWebSocket extends SimpleWebSocket {
}

If you need to reference the base class from within the derived one—for example, to access the base class’s (constructor) function, use the super keyword:

class ComplexWebSocket extends SimpleWebSocket {
    constructor (url: string, protocol: string) {
        super(url);            // calls the base class constructor function
        this.protocol = protocol;
    }
 
    protocol: string;
 
    ThrowError(code: number) {
        // some code
        super.Close(code);     // calls Close on the base class.
    }
}

In the case of instantiating an object of the derived type, the base class’s constructor function will be called automatically if it isn’t done so explicitly (as shown in the preceding code) within its own constructor.

/// <reference path="SimpleWebSocket.ts"/>
class ComplexWebSocket extends SimpleWebSocket {
   ...
}

Send(data: string): void {
    console.log(data);
    this.messagesSent++;
}

Send(data: string): void {     //  <−− matches signature in base class
    // new code
}
 
Send(data: any): void {        //  <−− is a generalized form of the function
    // new code
}

var cws = new ComplexWebSocket("someUrl", "http");
 
//  Calls Send defined in ComplexWebSocket or base class version
//  if not defined in ComplexWebSocket
cws.Send("a message");
 
// Throws an error.
cws.super.Send("another msg");

Close(code: string): void;
Close(code: string, reason: string): void;
Close(code: number): void;
Close(code: number, reason: string): void;
Close(code: any, reason?: string): void {
    var logEntry: string = code.toString();
    if (reason) { logEntry += (" : " + reason); }
    console.log(logEntry);
    this.state = this.SocketState.CLOSED;
}

Close(code: string): void;
Close(code: string, reason: string): void;
Close(code: number): void;
Close(code: number, reason: string): void;
Close(code: any, reason?: string): void {
   // ^^ or a further generalized form ^^ of the function signature
   // new code
}  

Using Interfaces as Function Types

If one of the goals of TypeScript is to make JavaScript more maintainable, then using interfaces to represent function types will definitely help. It can certainly make things more legible, and the clearer code is, the easier it is to maintain. Consider the following code:

var sayHello: (input: string) : string = function (s: string) {
    return "Hello " + s;
}
var stringUtils: { (input: string): string; }[];
stringUtils.push(sayHello);

Even though sayHello is just a function that takes a string and returns one, and stringUtils is an array of such functions, it’s not difficult to see how such types can quickly become difficult to write and interpret with more parameters, perhaps some of those being functions and arrays of functions everywhere. A parenthetical crisis!

Fortunately, we can refactor the function signature into an interface, and things become instantly more legible. And bracket free.

interface IFnStringManipulator {
    (input: string) : string;
}
 
var sayHello: IFnStringManipulator = function (s: string) {
    return "Hello " + s;
}
var stringUtils: IFnStringMaipulator[];
stringUtils.push(sayHello);

At this point, we should note that the tooling to go with this useful refactoring is a bit lacking at the moment. There’s currently no support in Visual Studio for the Extract Interface refactoring available with .NET languages. (See the discussion at http://typescript.codeplex.com/discussions/400724.) Also, IntelliSense tells you that sayHello is of type IFnStringManipulator rather than presenting the actual function signature. Of course, you can right-click IFnStringManipulator and choose Go To Definition (F12) to see what it is, but the to-and-fro between files is a pain.

Using Interfaces as Object Types

As .NET developers, it’s easy to understand why defining interfaces as behavioral sets of functions is a good idea. It’s quite easy to translate those concepts into TypeScript. For instance:

interface IComparable {
    CompareTo(obj: any): number;
}
 
interface IEnumerable {
    [index: number]: any;
}
 
interface ICloneable {
    Clone(): any;
}

And it’s not too difficult to check whether an object implements an interface either. You need to check that all the elements in the interface exist on the object.

function ImplementsICloneable (obj : any) :bool {
    return (obj && obj.Clone);
}

However, why define interfaces that represent whole classes? Why not just write classes? Well, the TLS understands and uses both classes and interfaces to provide IntelliSense and other type-related services, but there are (currently) very few third-party JavaScript libraries out there that also come in TypeScript, let alone in classes, for the TLS to consume and help us code more accurately. Hence declaration files exist, making full use of interfaces and ambient variable declarations to represent complete classes in these libraries where TypeScript classes are not available.

Rambling aside, interfaces representing object types can contain placeholders for the following:

• Constructors
• Fields
• Optional fields
• Methods
• Overloaded methods
• Indexers

As in .NET, you cannot add static members to interfaces, and currently you cannot specify that a field should be private and accessed through getter and setter methods. To demonstrate, here’s the nearest interface equivalent for the SimpleWebSocket class we’ve used in this chapter.

// Entire Class Interface
interface IWebSocket {
    // use 'new' to indicate constructor
    new (url: string) : SimpleWebSocket;
 
    // fields
    state: number;
    messagesSent: number;
 
    // optional fields
    protocols?: string;
 
    // properties can be added
    // but getters and setters cannot be enforced
    ServiceUrl: string;
 
    // methods
    Send(data: string): void;
    onError(errorCode: number, message: string): void;
 
    // 'overloaded' method
    Close(code: string): void;
    Close(code: string, reason: string): void;
    Close(code: number): void;
    Close(code: number, reason: string): void;
 
    // indexer - socket[12] returns message #12 perhaps
    [index: number] : string;
}

Note how we use the new keyword to indicate a constructor function in the interface rather than constructor. Also the entry for the overloaded Close method does not include the generalized function signature we actually need to use to implement it.

Combining Interfaces

In .NET, a class can inherit more than one interface. In TypeScript, an interface represents an object type. Variables and parameters can’t have more than one object type, so how can we create a variable based on IEnumerable and ICloneable, for instance? The answer is to create another interface that does inherit from both IEnumerable and ICloneable:

interface IEnumerableClone extends IEnumerable, ICloneable {
    // any overrides or additional items
}

Now you can set an object to be of the new derived type:

var BobaFett : IEnumerableClone;

An interface can inherit from zero or more base interfaces. Inheritance is expressed using the extends keyword followed by a comma-separated list of the base interfaces. As with classes, you can choose to use the base interface members in the new child interface or to hide them using new declarations. The TypeScript specification (section 7.1) lays out the rules for hiding base interface members:

• A base interface property is hidden by a property declaration with the same name.
• A base interface call signature is hidden by a call signature declaration with the same number of parameters and identical parameter types in the respective positions.
• A base interface construct signature is hidden by a construct signature declaration with the same number of parameters and identical parameter types in the respective positions.
• A base interface index signature is hidden by an index signature declaration with the same parameter type.

The following constraints must be satisfied by an interface declaration, or otherwise a compile-time error occurs:

• An interface cannot, directly or indirectly, be a base interface of itself.
• Inherited properties with the same name must have identical types.
• The declared interface must be a subtype of each of its base interfaces.

The net result is that if you’re inheriting from two or more base interfaces that define items of the same name but different types, your child interface needs to redefine that item by using a more generalized form, much the same as you need to do when overloading a method.