.d.ts simple example

A .d.ts file, short for Declaration File, is used in TypeScript to describe the shape of JavaScript code. These files provide TypeScript with type information about libraries and modules written in plain JavaScript. They help TypeScript understand the types and structures of objects, functions, and variables defined in JavaScript code, enabling better static type checking and editor support.

Example of a .d.ts File

Let's create a simple example to demonstrate how a .d.ts file works:

Step 1: Create a JavaScript Module

First, create a JavaScript module that we want to provide type definitions for. Let's call this module mathFunctions.js:

// mathFunctions.js

/**
 * Adds two numbers.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
  return a + b;
}

/**
 * Subtracts two numbers.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @returns {number} The difference of a and b.
 */
function subtract(a, b) {
  return a - b;
}

// Exporting the functions
module.exports = {
  add,
  subtract
};

Step 2: Create a .d.ts Declaration File

Next, create a .d.ts file named mathFunctions.d.ts. This file will contain TypeScript type declarations for the functions defined in mathFunctions.js:

// mathFunctions.d.ts

/**
 * Adds two numbers.
 * @param a The first number.
 * @param b The second number.
 * @returns The sum of a and b.
 */
export function add(a: number, b: number): number;

/**
 * Subtracts two numbers.
 * @param a The first number.
 * @param b The second number.
 * @returns The difference of a and b.
 */
export function subtract(a: number, b: number): number;

Step 3: Using the Module with TypeScript

Now, you can use the mathFunctions module in a TypeScript file (app.ts), importing the functions and benefiting from TypeScript's type checking:

// app.ts

import { add, subtract } from './mathFunctions';

let result1 = add(10, 5);       // result1 is inferred as number
let result2 = subtract(10, 5);  // result2 is inferred as number

console.log(result1); // Output: 15
console.log(result2); // Output: 5

// TypeScript will provide IntelliSense and type checking for these functions
let invalidResult = add('a', 'b'); // Error: Argument of type '"a"' is not assignable to parameter of type 'number'.

Explanation

• JavaScript Module (mathFunctions.js): This file defines two functions, add and subtract, and exports them using module.exports.

• TypeScript Declaration File (mathFunctions.d.ts): This file provides type annotations and documentation comments for the functions defined in mathFunctions.js. It uses TypeScript syntax to declare the function signatures (add and subtract) along with their parameter types and return types.

• Usage in TypeScript (app.ts): In a TypeScript file, you can import functions from mathFunctions.js using standard ES6 import syntax. TypeScript leverages the type information from mathFunctions.d.ts to provide type checking, IntelliSense, and code navigation features. This helps catch type errors at compile-time and improves code robustness.