Ambients Declaration

TypeScript offers a method to securely and effortlessly utilize established JavaScript libraries such as jQuery, AngularJS, Node.js, and others. Ambient declarations enable the safe usage of these widely used JavaScript libraries.

Ambient declarations inform the TypeScript compiler regarding the actual source code (such as variables and functions) located in different files. When our TypeScript code requires utilizing a third-party library created in standard JavaScript, such as jQuery, AngularJS, or Node.js, we can create ambient declarations. These declarations outline the types that would exist and are intended to be expressed in TypeScript.

Ambients Declarations

Ambient declaration files must be saved using the extension (.d.ts). Each top-level definition in a file with the .d.ts extension should be preceded by the declare keyword. This indicates to the developer that TypeScript will not produce any output code. The developer must verify that the declared entity will be present during runtime.

Ambient declarations inform the compiler that the corresponding source code is located in a different location. If these source codes are not present during runtime and an attempt is made to utilize them, it will result in a failure without any prior notification.

Ambient declaration files resemble documentation files. Should the source undergo modifications, the documentation must also be revised accordingly. Failure to update the ambient declaration file will result in compilation errors.

Test.d.ts

The aforementioned file cannot be transcompiled into JavaScript. However, we can utilize this file for type safety and IntelliSense functionality.

The ambient variables and methods can be defined utilizing the declare keyword. The structure for the ambient declaration is illustrated below.

Syntax

declare module module_name{
}

Syntax to access ambient files

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

Example

The concept of ambient declaration can be illustrated through the following example. In this instance, we are utilizing a third-party JavaScript library with the code provided below.

Addition.js

var TestSum;  
(function (TestSum) {  
   var Calc = (function () { 
      function Calc() { 
      } 
      Calc.prototype.doSum = function (a, b) {
         return a + b;
      }
   })
})

The JS file presented above requires a conversion to TypeScript, but time constraints limit our ability to rewrite the entire library. However, to utilize the doSum function with type safety, we can achieve this through an ambient declaration. Let's proceed to create an ambient declaration file.

CalcSum.d.ts

declare module TestSum { 
   export class Calc { 
      doSum(a:number, b:number) : number; 
   }
}

Next, integrate the ambient declaration file (CalcSum.d.ts) into our TypeScript document.

Main.ts

/// <reference path = "CalcSum.d.ts" /> 
var obj = new TestSum.Calc(); 
console.log("Sum: " +obj.doSum(15,25));

Compile and run the Main.ts file using the command provided in the console.

$ tsc main.ts
$ node Main.js

We will get the following output.

Sum: 40