Comparing JavaScript to an example DTS

This can be described by the following .d.ts:

ts
export function getArrayLength(arr: any[]): number;
export const maxInterval: 12;

The TypeScript playground can show you the .d.ts equivalent for JavaScript code. You can try it yourself here.

The .d.ts syntax intentionally looks like syntax. ES Modules was ratified by TC39 in 2019, while it has been available via transpilers for a long time, however if you have a JavaScript codebase using ES Modules:

js
export function getArrayLength(arr) {
  return arr.length;
}

This would have the following .d.ts equivalent:

In CommonJS you can export any value as the default export, for example here is a regular expression module:

js
module.exports = /hello( world)?/;

Which can be described by the following .d.ts:

ts
declare const helloWorld: RegExp;
export default helloWorld;

Or a number:

js
module.exports = 3.142;

One style of exporting in CommonJS is to export a function. Because a function is also an object, then extra fields can be added are included in the export.

js
function getArrayLength(arr) {
  return arr.slice;
}
getArrayLength.maxInterval = 12;
module.exports = getArrayLength;

Which can be described with:

ts
export default function getArrayLength(arr: any[]): number;
export const maxInterval: 12;

ts
declare function getArrayLength(arr: any[]): number;
declare namespace getArrayLength {
  declare const maxInterval: 12;
}
export = getArrayLength;

See Module: Functions for details of how that works, and the page.

Handling Many Consuming Import

There are many ways to import a module in modern consuming code:

ts
const fastify = require("fastify");
const { fastify } = require("fastify");
import fastify = require("fastify");
import * as Fastify from "fastify";
import { fastify, FastifyInstance } from "fastify";
import fastify from "fastify";
import fastify, { FastifyInstance } from "fastify";

Covering all of these cases requires the JavaScript code to actually support all of these patterns. To support many of these patterns, a CommonJS module would need to look something like:

js
class FastifyInstance {}
function fastify() {
  return new FastifyInstance();
}
fastify.FastifyInstance = FastifyInstance;
// Allows for { fastify }
fastify.fastify = fastify;
// Allows for strict ES Module support
fastify.default = fastify;
// Sets the default export
module.exports = fastify;

You may want to provide a type for JavaScript code which does not exist

js
function getArrayMetadata(arr) {
  return {
    length: getArrayLength(arr),
    firstObject: arr[0],
  };
}
module.exports = {
  getArrayMetadata,
};

This can be described with:

This example is a good case for to provide richer type information:

ts
export type ArrayMetadata<ArrType> = {
  length: number;
  firstObject: ArrType | undefined;
};
export function getArrayMetadata<ArrType>(
  arr: ArrType[]
): ArrayMetadata<ArrType>;

Now the type of the array propagates into the ArrayMetadata type.

The types which are exported can then be re-used by consumers of the modules using either import or import type in TypeScript code or JSDoc imports.

Trying to describe the runtime relationship of JavaScript code can be tricky. When the ES Module-like syntax doesn’t provide enough tools to describe the exports then you can use namespaces.

ts
// This represents the JavaScript class which would be available at runtime
export class API {
  constructor(baseURL: string);
  getInfo(opts: API.InfoRequest): API.InfoResponse;
}
// This namespace is merged with the API class and allows for consumers, and this file
// to have types which are nested away in their own sections.
declare namespace API {
  export interface InfoRequest {
    id: string;
  }
  export interface InfoResponse {
    width: number;
    height: number;
  }
}

To understand how namespaces work in .d.ts files read the .

You can use export as namespace to declare that your module will be available in the global scope in UMD contexts:

ts
export as namespace moduleName;

Reference Example

To give you an idea of how all these pieces can come together, here is a reference .d.ts to start with when making a new module

The layout of your declaration files should mirror the layout of the library.

A library can consist of multiple modules, such as

myLib
  +---- index.js
  +---- foo.js
  +---- bar
         +---- index.js
         +---- baz.js

These could be imported as

js
var a = require("myLib");
var b = require("myLib/foo");
var c = require("myLib/bar");
var d = require("myLib/bar/baz");

Your declaration files should thus be

If you are planning on submitting these changes to DefinitelyTyped for everyone to also use, then we recommend you:

Otherwise

1. Create a new file in the root of your source tree: [libname].d.ts
2. Add the template inside the braces of the declare module, and see where your usage breaks