❮ Ts Namespace Ts Number ❯

TypeScript Declaration Files

As a superset of JavaScript, TypeScript inevitably needs to reference other third-party JavaScript libraries during development. Although direct reference allows the use of the library's classes and methods, it prevents the use of TypeScript features such as type checking. To address this issue, the functions and methods in these libraries are stripped of their implementations, leaving only the exported type declarations, resulting in a declaration file that describes the JavaScript library and module information. By referencing this declaration file, TypeScript's various features can be leveraged to use the library files.

If we want to use a third-party library, such as jQuery, we typically retrieve an element with the id 'foo' like this:

$('#foo');
// or
jQuery('#foo');

However, in TypeScript, we don't know what $ or jQuery is:

jQuery('#foo');

// index.ts(1,1): error TS2304: Cannot find name 'jQuery'.

At this point, we need to use the declare keyword to define its type, helping TypeScript to check if the types of the parameters we pass are correct:

declare var jQuery: (selector: string) => any;

jQuery('#foo');

The types defined by declare are only used for compile-time checks and are removed in the compilation result.

The compilation result of the above example is:

jQuery('#foo');

Declaration Files

Declaration files have the suffix .d.ts, for example:

tutorialpro.d.ts

The syntax format for declaring files or modules is as follows:

declare module Module_Name {
}

The syntax format for importing declaration files in TypeScript is:

/// &lt;reference path = "tutorialpro.d.ts" />

Of course, the declaration files for many popular third-party libraries, such as jQuery, do not need to be defined by us, as they have already been defined by others: jQuery in DefinitelyTyped.

Example

The following defines a third-party library to demonstrate:

CalcThirdPartyJsLib.js File Code:

var tutorialpro;  
(function(tutorialpro) {
    var Calc = (function () { 
        function Calc() { 
        } 
    })
    Calc.prototype.doSum = function (limit) {
        var sum = 0; 

        for (var i = 0; i <= limit; i++) { 
            sum = sum + i; 
        }
        return sum; 
    }
    tutorialpro.Calc = Calc; 
    return Calc; 
})(tutorialpro || (tutorialpro = {})); 
var test = new tutorialpro.Calc();

If we want to reference the above code in TypeScript, we need to set up a declaration file Calc.d.ts, with the following code:

Calc.d.ts File Code:

declare module tutorialpro { 
   export class Calc { 
      doSum(limit:number) : number; 
   }
}

The declaration file does not contain implementations; it only contains type declarations. To include the declaration file in TypeScript:

CalcTest.ts File Code:

/// &lt;reference path = "Calc.d.ts" /> 
var obj = new tutorialpro.Calc(); 
// obj.doSum("Hello"); // Compilation error
console.log(obj.doSum(10));

The following line causes a compilation error because we need to pass a numeric parameter:

obj.doSum("Hello");

Use the tsc command to compile the above code file:

tsc CalcTest.ts

The generated JavaScript code is as follows:

CalcTest.js File Code:

/// &lt;reference path = "Calc.d.ts" /> 
var obj = new tutorialpro.Calc();
//obj.doSum("Hello"); // Compilation error
console.log(obj.doSum(10));

Finally, we write a tutorialpro.html file to include the CalcTest.js file and the third-party library CalcThirdPartyJsLib.js:

Example

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>tutorialpro.org(tutorialpro.org)</title>
<script src = "CalcThirdPartyJsLib.js"></script> 
<script src = "CalcTest.js"></script> 
</head>
<body>
    <h1>Declaration File Test</h1>
    <p>Test it out</p>
</body>
</html>

❮ Ts Namespace Ts Number ❯