Module signatures, also known as interfaces, are an explicit place to put type annotations. But they actually serve several purposes:
- Export a module's public API
- Document the types of a module's public API
- Provide a place to put module documentation
- Hide non-public elements of a module
- Hide implementation details of types
Keeping in mind the points mentioned earlier, when would you not want to use a signature for your module? It's not set in stone, but my rule of thumb is to not use a signature when my API is experimental and still evolving (in semantic versioning terms, less than version 1.0.0.), or when the module is purely an application module and is not meant to be published as a library for others to consume (although the line between these is somewhat grainy).
Signatures come in two forms–interface files and syntactic signatures...