What are Ambients in TypeScript ?

Typescript provides a way for using third-party libraries like Node.js, jQuery, AngularJS, etc. in an easier and safer manner. These are done with the help of Ambient declarations.

Ambient Declarations are a method which informs the TypeScript compiler that the real source code (like functions or variables) exists in another place. If we attempt to utilize these source codes when they do not exist at runtime, then without giving hint it will break. We have to always write ambient declarations if our TypeScript code needs to use third-party JavaScript libraries such as jQuery, AngularJS, Node.js, etc. 

When using these JavaScript libraries such as  jQuery, AngularJS, Node.js, etc, then validating code completion and typesafety becomes difficult for a TypeScript programmer. So, Ambient declarations assist to directly integrate other JavaScript libraries into TypeScript.

Defining Ambients Declarations: Ambient Declarations files has to be saved with the extension d.ts. There must have the declare keyword prefixed to each root level definition in Ambient declarations files with extension d.ts. The author will be cleared by this that there will not be any code released by TypeScript. The author requires to confirm that at runtime the declared item will exist.

Ambient declarations files are similar to doc files (The doc file needs to be kept updated if the source changes). So, If the ambient declaration files are not updated then they will return compilation errors. By convention Ambient declarations files are kept in a type declaration file having extension d.ts. As given below :

Trial.d.ts

The above file cannot be trans-compiled into JavaScript file. It can be used for code completion and type-safety.

Now to declare the ambient methods and variables, we have to use the declare keyword. The syntax for declaring ambient variables or ambient declarations are as given below:

Syntax:

declare module module_name {
}

Syntax to mention the ambient files in the client TypeScript file is given below :

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

Features: Following are the features of ambient in TypeScript:

• Ambient declarations permits to safely use existing well-liked JavaScript libraries.
• Ambient declarations assist to directly integrate other JavaScript libraries into TypeScript..
• Ambient declarations is a way to tell the compiler about existing variable/functions/etc.
• There is a declare keyword in ambient declaration, which means that we declare the typing of a variable without their implementation, and TypeScript will just suppose that we will somehow comprise that implementation (through adding a script tag or whatever custom compiler we have).

Applications: Ambients in TypeScript are used to describe the shape of libraries that are not written in TypeScript, to do so we have to declare the API which the library reveals. It is because hardly any top-level objects are revealed by JavaScript libraries, one better way to represent them is namespaces.

We call a declare keyword in the ambient declaration, which means that we declare the typing of a variable without their implementation, and TypeScript will just suppose that we will somehow comprise that implementation (through adding a script tag or whatever custom compiler we have). Generally, they are described in .d.ts files. So, we have to write an ambient module to write type declarations for code that is already written in JavaScript. As declared above that that these are defined in a file that ends with .d.ts file extension.

So fundamentally ambient declarations are an assurance that is made with the compiler. If third-party libraries do not exist at runtime and if we try to use them then things will break without warning. 

Example 1: To understand the ambient declaration look at the example which is given below. Here the third-party JavaScript library is used with the code given below:

Javascript

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

Being a JS file we have no time to re-write this library given into typescript.  But however, you do require to add the doAdd() function with type safety, then by using ambient declaration we can do this. So, now we will create an ambient declaration file.

Javascript

declare module TestAdd{
   export class Calc {
      doAdd(x:number, z:number) : number;
   }
}

Now, we will include this ambient declaration file (CalAdd.d.ts) in the typescript file. It is given below –

Main.ts

var obj = new TestAdd.Calc();
console.log("Add: " +obj.doAdd(60, 15));

Now, by using the following command on the console, compile and execute the Main.ts file:

$ tsc main.ts
$ node Main.js

Output: We will get the following output:

75

Example 2: To understand the ambient declaration look at the example which is given below. Here the third-party JavaScript library is used with the code given below :

Javascript

var TestDif;
(function (TestDif) {
   var Calc = (function () {
      function Calc() {
      }
      Calc.prototype.doDif = function (x, z) {
         return x - z;
      }
   })
})

Being a JS file we have no time to re-write this library given into typescript.  But however, you do require to add the doSubtract() function with type safety, then by using ambient declaration we can do this. So, now we will create an ambient declaration file.

Javascript

declare module TestDif{
   export class Calc {
      doSubtract(x:number, z:number) : number;
   }
}

Now, we will include this ambient declaration file in the typescript file. It is given below :

Main.ts

var obj = new TestDif.Calc();
console.log("Subtract: " + obj.doSubtract(50, 10));

Now, by using the following command on the console, compile and execute the Main.ts file :

$ tsc main.ts 
$ node Main.js

Output: We will get the following output:

40