TypeScript provides the way to safely and easily use existing JavaScript libraries like jQuery, AngularJS, Node.js, etc. The Ambient declarations allow us to use existing popular JavaScript libraries safely.
Ambient declarations tell the TypeScript compiler about the actual source code (like variable/functions) existing elsewhere. If our TypeScript code needs to use a third-party library that was written in plain JavaScript libraries like jQuery/AngularJS/Node.js, we can always write ambient declarations. The ambient declaration describes the types that would have been there and will be written in TypeScript.
Ambient declarations files need to save with the extension (d.ts). A file with extension .d.ts must have the declare keyword prefixed to each root level definition. It makes clear to the author that there will be no code emitted by TypeScript. The author needs to ensure that the declared item will exist at runtime.
Ambient declarations tell the compiler about the actual source code exist elsewhere. If these source codes do not exist at runtime and we try to use them, then it will break without warning.
Ambient declarations files are like docs file. If the source changes, the docs need to be kept updated also. If the ambient declaration file is not updated, it returns compilation errors.
Test.d.ts
We cannot trans-compiled the above file into JavaScript. We can use the above file for type-safety and IntelliSense.
We can declare the ambient variables and methods by using the declare keyword. The syntax for the ambient declaration is like below.
declare module module_name{
}Syntax to access ambient files
///
Example
We can understand the ambient declaration with the following example. Here, we are using a third-party JavaScript library with the below code.
Addition.js
var TestSum;
(function (TestSum) {
var Calc = (function () {
function Calc() {
}
Calc.prototype.doSum = function (a, b) {
return a + b;
}
})
})Above is a JS file and we have not much time to re-write this library to TypeScript. But still, if we need to use the doSum() function with type safety, then we can do this by using ambient declaration. Let us create an ambient declaration file.
CalcSum.d.ts
declare module TestSum {
export class Calc {
doSum(a:number, b:number) : number;
}
}Now, include this ambient declaration file (CalcSum.d.ts) into our TypeScript file.
Main.ts
///var obj = new TestSum.Calc(); console.log("Sum: " +obj.doSum(15,25));
Compile and executed the Main.ts file by using the following command on the console.
$ tsc main.ts $ node Main.js
We will get the following output.
