JavaScript program always contains specific libraries to solve the problem without copy-paste a problem solution between the projects. A lot of libraries exist in NPM Registry. And to make program type safe we need to have some mechanism which will provide ability to annotate with types code which developer can't change. In order to handle this, Hegel supports the concept of a “library definition”.
We decided not to create our own "library definition" language, because we could face next problem: creating of "library definitions" from scratch for all popular libraries. So, we decided to use popular "library definition" format - TypeScript.
More information about TypeScript library definition you can find at Definition Files. There is only problems with: enums, modules, conditional types, because Hegel doesn't provide any additional and non-type safe concepts for type annotations.
Currently we are working for function type overloading which will help to make more warm relationships with "d.ts" files.
Definition Directories
As was mentioned in Configuration "typings" section you may configure path for typings and can have multiple directories for typings. We decided that the best practice will be to "store" your third-party typings inside "node_modules/@types" directory and local typings inside "@types" directory (this behaviour is by default).
Definition search strategy
Hegel will try to find type definition for specific library by the next algorythm:
- Search inside defined "typings" configuration section paths by the order they are defined inside the section.
- Search for typing path which are defined inside "types" section of specific package
package.jsonfile. - Search for path of specific package with "d.ts" extension instead ".js"
- Try to inference types of specific package.
Lets explore it by example:
import * as smthg from "awesome-library";
First step is atempt to find "awesome-library" types definition inside defined paths from "typings" configuration section (by default "@types" and "node_modules/@types") If "awesome-library.d.ts" file exist inside "@types" or "node_modules/@types" directories algorythm will be stoped and return found definition.
Otherwise, Hegel will try to resolve definition which can be defined in "types" section of "node_modules/awesome-library/package.json" file.
If it doesn't exist, Hegel will try to find file by resolved "awesome-library" path. Lets imagine that this path is "node_modules/awesome-library/index.js". So, Hegel will try to read "node_modules/awesome-library.d.ts" file and will return the typings if the file exists.
Otherwise, Hegel will try to inference types of the module by himself without any type definitions. Note, if Hegel inferences a module and this module contains type errors, Hegel will notify you about module problems and you need to define the typings manualy inside local "@types" directory.