Ambient Declarations in TypeScript

Assume you’re working on a TypeScript project and wish to use a JavaScript library or some non-TypeScript code. TypeScript does not grasp the structure of this external code by default since it lacks type information. This can be problematic because TypeScript is all about type safety and detecting problems before they occur. So, how do you get TypeScript to recognize and validate the types of this external code? This is where ambient declarations come into play.

Ambient declarations serve as a link between TypeScript and the outside world. They let you to tell TypeScript about the shape of this external code, allowing TypeScript to make intelligent suggestions, autocompletion, and, most crucially, catch type-related problems before you run your code.

This is how you do it:

You make a TypeScript file with the.d.ts extension. This file is only for type information and contains no actual code.

You use the declare keyword in this.d.ts file. This keyword informs TypeScript that you are discussing something in the real world. Declare can be used in front of variables, functions, classes, modules, or namespaces.

Within these declare declarations, you explain the structure of the external code. You’re just saying, “Hey TypeScript, here’s what this external thing looks like.”

Let’s look at a practical example:

Assuming you have the following JavaScript library code in a file named mathLibrary.js:

// mathLibrary.js
var mathLibrary = {
add: function (a, b) {
return a + b;
},
subtract: function (a, b) {
return a - b;
},
};

module.exports = mathLibrary;

Now, you want to use this JavaScript library in your TypeScript project with type checking and IntelliSense support. To achieve this, you can create an ambient declaration file named mathLibrary.d.ts:

// mathLibrary.d.ts
declare module 'mathLibrary' {
interface MathLibrary {
add(a: number, b: number): number;
subtract(a: number, b: number): number;
}

const mathLibrary: MathLibrary;

export = mathLibrary;
}

Here’s what’s happening in this TypeScript declaration file:

We define an ambient module called’mathLibrary’ using the declare module syntax. This module is equivalent to our external JavaScript library.

We define an interface named MathLibrary within the module to specify the form of our library’s API. It defines that the functions add and subtract take two integers as inputs and return a number.

We declare a MathLibrary constant of type MathLibrary. Our JavaScript library instance is represented by this constant.

We use export = mathLibrary; to indicate that we are exporting the mathLibrary object as this module’s default export.

With this ambient declaration file in place, you can use the JavaScript library mathLibrary in your TypeScript code as follows:

import mathLibrary = require('mathLibrary');

const result1 = mathLibrary.add(5, 3); // TypeScript checks the argument types
const result2 = mathLibrary.subtract(10, 2); // TypeScript checks the argument types

console.log(result1); // TypeScript knows this is a number
console.log(result2); // TypeScript knows this is a number