What are the ".d.ts" files?

Question

Studying Typescript I noticed that there are files .d.ts and that it is possible to declare the guys there, but:

• What is the actual usefulness of files .d.ts?
• If I already declare the guys in the file .ts, I must still have a .d.ts correspondent?
• When does it make sense for them to be generated automatically? - There is the configuration declaration in the tsconfig.json for this, but I did not understand when it makes sense to use it.

Answer 1

The main point of creating Typescript is to give more robustness to complex systems. Javascript was created thinking for use in scripts very simple to automate some action on a page, not to make real software.

Although Typescript has script in the name it is not for that. The main point that differentiates a language from script for a language capable of handling more complex code bases is dynamic typing.

Typescript uses static typing in its code. So there are more rigid contracts, which is what gives robustness.

But TS was created to be compatible with JS, and in fact TS compiles to a JS target code (so in the execution the typing happens to be dynamic, but after compiled the robustness has already been guaranteed, only the performance will be dynamic language, which is worse, but it may not be so much because there are already some guarantees that Jitter can benefit in some points). You can mix TS and JS code, then TS was born very strong.

But JS codes don’t have manifest types so they don’t have these contracts. While it’s local, it doesn’t change anything for Typescript, but when it lacks typing in public Apis (parameters and return of methods for example) the TS compiler is rendered and can’t give the guarantees that it can normally give. Everything works, but it doesn’t get possible errors there, and tools may not help as much.

What then to do to put guys in something that didn’t have guys?

Well, in C/C++ these contracts have always been in separate files (in general the .h of header). You first created them for all applications to use them because and only what the compiler needed to secure the contracts and then created the real codes that met those contracts.

In TS they did the opposite, they started creating these files after JS code already existed. Some people went to the main existing libraries for TS to see what the contracts were, as far as I could see (some libraries are very bad and the contract left very open, there is not much to do but to say explicitly that it is open even, just not to give error for nothing), and there they put in these files .d the types of data that would be used in the existing Apis. So the TS compiler can use them to give the necessary guarantees. The .ts final is to indicate clearly that this is from the TS, although it is related to a JS code, for the JS does not need this.

Any serious public library created today to web front which is not written in TS (and many more are), and which were then written in JS (comes out a new one per second, you know this :P :D) if it is serious the person already creates those files with the contracts to run well together with TS.

If you are making the code in TS even then these files are not necessary, at least if you are typing everything right as TS says. If you’re not typing then your code is half JS yet, there you need it, but it doesn’t make sense when you use TS.

Answer 2

The archives *.d.ts are called declaration files. The d in the name comes from declaration.

The main utility is to declare types for applications or libraries originally made in Javascript. Thus, whoever uses, in Typescript, the API (encoded in Javascript) will have access to the types, even if they have not been directly defined in the implementation.

It is very useful for libraries to support typescript users without the need to rewrite all the source code in another language.

If I already declare the guys in the file .ts, I must still have a .d.ts correspondent?

Most of the time, no. If you are writing your code in Typescript, static type definitions will already be "included" in it, next to the implementation. There are more complex cases where separation can be useful.

When it makes sense to automatically generate them?

The option --declaration should be used if you want to generate the declaration files. It is especially useful if you want to create a library that already "comes" with type definition. Since when compiled, Typescript source code "loses" static types, declaration files are the only way to keep this information after compilation.

There is the property types (or typings) of package.json. You can use it to "publish" a standard type definition file in your package.

To documentation covers some other use cases and information.

Answer 3

It serves to provide type information in API written in Javascript. For example, using a Jquery in its code, Voce uses this type of file for this, instead of rewriting the entire Jquery into TS, you can just declare the types in that file .d.ts.

To map, as far as I remember, Voce must create a file d.ts of the same file name .js. Example:

React code with TS:

import * as myMod from 'my-module';

 // ...

Code in index.js:

module.exports = function(qualquer) {

 // ....

 return qualquer
}

Add types by creating one index.d.ts

declare module 'my-module' {
 export default function qualquer(arg1: string, arg2: string): QualquerCoisa;
}

interface QualquerCoisa {
 idade: number;
 altura: number;
}

Summing up, d.ts is a Typescript declaration file for a Javascript file. *Remembering that who will be imported will be the index.d.ts because it will be an interface between your JS code and the TS.