Creating TypeScript type declaration file for an existing jQuery plugin

Microsoft recently announced a scripting language that compiles into JavaScript. It is known as TypeScript.
TypeScript is super set of JavaScript. Using TypeScript, one can write type safe client side script. If you are not familiar with TypeScript yet, you may checkout the following resources:

• IntroducingTypeScript by Anders Hejlsberg
• HelloTypeScript – Getting Started by Sumit Maitra

Any existing JavaScript library can be used with TypeScript if a type declaration file is created for the library. A type declaration file provides a TypeScript interface to interact with the library. TypeScript team has created the declaration files for jQuery and Node.js libraries.

In this post, we will create a TypeScript declaration file for jQuery-idle Timeout plugin. It is a small plugin which signs off the user if the user didn’t interact with the page for some time. Using this plugin is very easy. Following is an example of the usage:

$(document).idleTimeout({
    inactivity: 5000,
    noconfirm: 1000,
    sessionAlive: 1000,
    redirect_url: 'TimedOut.html',
    click_reset: true,
    alive_url: 'default.htm',
    showDialog: false
});

The above script sets redirects user to the page TimedOut.html if the user didn’t interact with the page for 5 seconds or more.
From the usage of the plugin, it is clearly visible that,

• The function idleTimeout is invoked using jQuery object
• The function idleTimeout accepts a set of options

In the source of jQuery-idleTimeout plugin, we see the following assignment statement in the beginning:

var defaults = {
            inactivity: 1200000, //20 Minutes
            noconfirm: 10000, //10 Seconds
            sessionAlive: 30000, //10 Minutes
            redirect_url: '/js_sandbox/',
            click_reset: true,
            alive_url: '/js_sandbox/',
            logout_url: '/js_sandbox/',
            showDialog: true
        }

From here, we get to know the list of configurable options. As TypeScript is strongly typed, we need to define an interface to hold the above properties. One important thing to remember here is that, the fields should be made nullable in the interface.  

The interface can be as follows:

interface JQIdleTimeoutSettings {
    inactivity?: number;
    noconfirm?: number;
    sessionAlive?: number;
    redirect_url?: string;
    click_reset?: bool;
    alive_url?: string;
    logout_url?: string;
    showDialog?: bool;
    }

The function idleTimeout is invoked using a jQuery object. In the declaration file of jQuery, an interface is defined to hold all functions which have to be invoked using jQuery objects. Name of the interface is JQuery.

We shouldn’t modify the source of jQuery’s declaration file to add the idleTimeout function. Instead, we have to define an interface extending JQuery as follows:

interface JQueryTimeout extends JQuery {
    idleTimeout(settings: JQIdleTimeoutSettings): JQueryTimeout;
}

I made the declaration file open on GitHub. You can find it here.

Using the declaration file:
To use the declaration file in a TypeScript file, a reference of the declaration file should be added. Calling the idleTimeout function in TypeScript is quite similar to that of in JavaScript code. Only difference being, we need to type cast the jQuery object to type of JQueryTimeout.

/// <reference path="jQueryIdleTimeout.d.ts" />

(<JQueryTimeout>$(document)).idleTimeout({
                inactivity: 5000,
                noconfirm: 1000,
                sessionAlive: 1000,
                redirect_url: 'TimedOut.html',
                click_reset: true,
                alive_url: 'default.htm',
                showDialog: false
});

This is because, in TypeScript, $(document) returns an object of type JQuery. The function idleTimeout is declared in the interface JQueryTimeout, which is extended from the interface JQuery.

Happy coding!