typings/typings

*DEPRECATED* The TypeScript Definition Manager

The TypeScript Definition Manager.

Deprecation Notice: Regarding [email protected]

For users doing typings install dt~<package> --global and receiving errors.

Starting from TypeScript 2.0, users can install typings using npm install @types/<package>. These typings are coming from DefinitelyTyped. In the future, we hope redirects will be enabled to support existing maintainers to contribute effectively to NPM's @types as they did to typings/registry.

Typings on DefinitelyTyped have also moved to the external module format supported by TypeScript. This finally solved the real problem that Typings was trying to solve! It also means it will cause errors such as:

> typings install dt~angular --global 

typings ERR! message Attempted to compile "angular" as a global module,
but it looks like an external module. You'll need to remove the global option to continue.

To resolve this, we recommend moving to TypeScript 2.0's official aquisition method (npm install @types/angular). You can also drop the --global flag from typings, though some definitions on DefinitelyTyped may not work with the Typings approach because of new TypeScript features (namely UMD namespaces).

This project will remain operational for the foreseeable future, but is effectively deprecated. New projects should use @types from NPM.

Quick Start

# Install Typings CLI utility.
npm install typings --global

# Search for definitions.
typings search tape

# Find a definition by name.
typings search --name react

# If you use the package as a module:
# Install non-global typings (defaults to "npm" source, configurable through `defaultSource` in `.typingsrc`).
typings install debug --save

# If you use the package through `<script>`, it is part of the environment, or
# the module typings are not yet available, try searching and installing with `--global`:
typings install dt~mocha --global --save

# If you need a specific commit from github.
typings install d3=github:DefinitelyTyped/DefinitelyTyped/d3/d3.d.ts#1c05872e7811235f43780b8b596bfd26fe8e7760 --global --save

# Search and install by version.
typings info env~node --versions
typings install [email protected] --global --save

# Install typings from a particular source (use `<source>~<name>` or `--source <source>`).
typings install env~atom --global --save
typings install bluebird --source npm --save

# Use `typings/index.d.ts` (in `tsconfig.json` or as a `///` reference).
cat typings/index.d.ts

Usage

Typings is the simple way to manage and install TypeScript definitions. It uses typings.json, which can resolve to the Typings Registry, GitHub, NPM, Bower, HTTP and local files. Packages can use type definitions from various sources and different versions, knowing they will never conflict for users.

typings install debug --save

The public registry is maintained by the community, and is used to resolve official type definitions for JavaScript packages.

Read More

• Commands
• Coming from TSD?
• Example typings
• Why external modules?
• About the registry
• FAQ
• Known Issues

Sources

• npm - dependencies from NPM
• github - dependencies directly from GitHub (E.g. Duo, JSPM)
• bitbucket - dependencies directly from Bitbucket
• jspm: - dependencies from installed JSPM packages with typings distributed. Requires [email protected]+.
• bower - dependencies from Bower
• common - "standard" libraries without a known "source"
• shared - shared library functionality
• lib - shared environment functionality (mirror of shared) (--global)
• env - environments (E.g. atom, electron) (--global)
• global - global (window.<var>) libraries (--global)
• dt - typings from DefinitelyTyped (usually --global)

Contributing

# Installation
# Fork this repo (https://github.com/typings/typings)
# Clone the fork (E.g. `https://github.com/<your_username>/typings.git`)
cd typings

# Install modules
npm install

# Build
npm run build

# Test
npm run test

Change Log

License

MIT

typings's Issues

Warning when dependencies are listed but not installed

Maybe with a "pre-boot" step for any command, we can do a "check setup" where we verify all the correct typings are installed.

Print "uninstalled", "missing", "extraneous" in `typings ls`

Would be nice to see what is and isn't installed. Need to differentiate better between missing and uninstalled though.

Edit: Also, outdated.

Collect missing modules and print a warning after installation

It would be cool to collect all the missing modules names, and locations they are being included from, and print them at the end. For example, when installing blue-tape it has a dependency on tape which has an ambient dependency on node where it uses stream. The warning there could be something like:

Unresolved dependencies (most likely provided by ambient typings):
- stream (from "blue-tape~tape")

How to handle references?

The references lines are likely incorrect, especially after we rewrite them. The first approach I was going to take is inlining the references into the type definitions. However, I found that when writing an "external module definition" the module imports could not be resolved unless I used references. Is there a case where applications are being composed of references and what is the proper compiled type meant to look like?

Edit: Looks like it might was having a separate issue with the imports (hmm, atom-typescript). How do I still write these? Is inlining them as "ambient" the best approach?

Typings installation should not resolve ambient dependencies

Currently ambient dependencies are resolved on child dependencies, but not used. They should be kept for reference in client messaging, but definitely not used to resolve on.

Fix `typings install <npm_package> -S` writing path to `package.json`

We don't resolve from there correctly. We should also fix resolving from here anyway, since it might be useful for linked/internal modules.

Integrate with the registry

Commands that should work out of the box:

• tdw install [name] (if there's multiple sources, prompt)
• tdw install [name] --source [npm | ambient | bower | common]
• tdw install --implicit (scour package.json and bower.json and auto-install everything with versions)

Improve installation error messaging

For example, here's NPM (note the CLI version, error code, etc):

npm ERR! publish Failed PUT 403
npm ERR! Darwin 15.0.0
npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "publish"
npm ERR! node v5.0.0
npm ERR! npm  v3.3.6
npm ERR! code E403

npm ERR! "You cannot publish over the previously published version 0.1.5." : typings
npm ERR! 
npm ERR! If you need help, you may report this error at:
npm ERR!     <https://github.com/npm/npm/issues>

npm ERR! Please include the following file with any support request:
npm ERR!     /Users/blakeembrey/Projects/typings/cli/npm-debug.log

Edit: Also https://github.com/DefinitelyTyped/tsd/blob/15753b12dd36ad1f349da6cc19e7b9bf68af312e/src/tsd/util/error-handler.ts

Create a `prune` command

Remove extraneous dependencies, just like NPM.

Update `typings.json` to support version numbers

This is required for keeping dependencies in sync. It'll break the nice decentralisation that occurs right now, but if typings.json could specify 1.2.0 (for example), we can validate that against both the registry versions and the package.json version to keep typings in sync.

Edit: Can't just be numbers. We have multiple sources and the name can be different to the installed typing. E.g. registry:npm/[email protected].

Linked: #24

Edit 2: The registry can be an array of sources - does this mean it'll only ever be one source now? If it's multiple, we could reuse the version field in typings.json to handle this.

Edit 3: If we use the version field in typings.json, we might need to support a "for" field that tells us which registry this is typed for.

Print references after installation

Since references are not used or followed, but deleted, we should print warnings when they are removed, where they have been removed from and where they originally linked to (the shorthand) so people can install them manually if they need to.

Warn when installing from `master` using GitHub/Bitbucket

It's a bad practice to install code that can mutate. We should alert people as much as possible.

typings search <query> [--source <source>]

Relies on #29 to be implemented.

typings sync [ npm | bower ]

Automatically find all NPM, Bower, etc. dependencies listed and install them to typings.

Question: What does the save flag look like? Do we do dependencies separate from devDependencies? Does --save save all dependencies and devDependencies to the respective fields in typings.json - regardless of flag? That one seems the most reasonable.

Compiled file formatting

Format the compiled code consistently, spaces, etc. and then use correct indentation. Then wrapping the code can be cleaner.

Reference: https://github.com/Microsoft/TypeScript/blob/master/lib/typescript.d.ts#L1819

Add `--source dt` to install from DefinitelyTyped

It's still a huge collection of TypeScript definitions, even though they are all ambient and won't work 100% correctly we should be able to install from there automatically.

Search all registry sources on installation without a `--source`

E.g. Prompt for whichever source is found.

Found multiple sources:
- npm
- bower
- ambient

Add version CLI argument

I should be able to check the module version using --version or -v.

Improve error messaging

The current error messaging is quite obscure. Instead, it should probably be using a custom error subclass and we can add a code and data properties to be able to compose longer message descriptions and titles.

Edit: Ideas:

• Error message i18n
• Error codes
• Multiple message strings (error message, possible solution, etc.)

Add insights to CLI

https://www.npmjs.com/package/insight

Create a guide on manually converting definitions to typings

It should be pretty simple. 99% of the time it's just moving the stuff inside declare module "x" to the outside, then adding typings.json with the name (this is even optional really) and submitting it to the registry.

Reference: TypeStrong/ts-node#43 (comment)

Ambient dependency installation

Ambient dependencies should have the ability to import from modules, but the TypeScript compiler disallows this behaviour inside a single typing. Instead, all dependencies should be compiled and output separately and the main ambient module should use references to import from them. This would avoid the global namespace hacks that currently exist in DefinitelyTyped.

Create CLI help arguments

Kind of essential. When the command is wrong or when the user uses --help, print the help dialog.

Warn when deleting a dependency that is not installed

For example, we probably just made a typo.

Approach for jquery and jquery-plugin type definitions

With reference to the jquery type definition and the type definition of the jqueryui jquery plugin (https://jqueryui.com/)

The current pattern for jquery plugins (as I understand it) is:

• jquery type definition defines:
  • ambient JQueryStatic interface
  • ambient var's $ and jQuery, both of type JQueryStatic
• jquery plugins also define an ambient JQueryStatic (e.g. for jqueryui)
• Declaration merging ensures the two (or more) ambient JQueryStatic definitions are merged

What is the planned approach with typings?

I note that ambient modules are also open-ended (para 4), but I suspect we don't want to use this for one major reason: we want the developer to have to reference import $ from "jqueryui" (or similar) in order that the underlying module dependencies get loaded in the right order.

Recommend that you don't use `typings` field in `package.json`, and `typings.json` together

Using the typings field tells TypeScript it'll work as an external module, but if there's a typings.json that won't work with the TypeScript node resolution. These resolutions can't be used together, so if your package requires a typings.json file you shouldn't also provide a typings field in package.json to confuse the compiler and consumers.

Use typings for typings

This'll make it easier to maintain the typings in the repo, and also allow people to use typings programmatically without having to manually add all the dependencies (you know, the whole reason typings exists already). However, it's going to be an interesting hack which may have side effects (hopefully just good ones!).

Warn when installing a typing that already has a TypeScript compatible "typings" field

TypeScript and resolve using "node-style" resolution. We should warn the user when purposefully installing that typing.

Writing dependency to file should use shorthand

E.g. Rewrite https://raw.githubusercontent.com/... to the github:... syntax.

Should generate all files for a dependency, including unreferenced

For example, xtend (typings here: https://github.com/typings/typed-xtend) includes to main files but only one is referenced. The generated typings need to include both. The solution is (probably) to have a files field in typings.json, as otherwise those files can not be discovered magically unless the entire way resolving changes (but then we'll start hitting rate limiting using the GitHub API).

Edit: This is only relevant for direct dependencies. Sub-dependencies should follow the paths.

TypeScript version

If this is covered elsewhere, please accept my apologies and point me in the right direction.

How do you envisage the user's version of TypeScript will fit into the picture?

For example, the ImmutableJS type definition can (and most likely will) be enhanced in a number of places with the introduction of tuple types and polymorphic this (to give just two examples). But these changes to the type definition would not be backwards compatible because the language features themselves are breaking changes. Hence multiple versions of the type definition will need to be maintained (something that could benefit from code generation, but I suspect that is beyond the scope of this project)

Which means a type definition is, in reality, a function of:

• package version
• TypeScript version

Thoughts on how best to deal with this situation?

When deleting `declare` keyword, keep trivia

I forgot to add this back. Kind of important for keeping the comments and newlines in tact.

Edit: Note that I should delete the trailing trivia (E.g. declare const should delete the space between declare and const, not the prefixed spaces).

`typings publish [location] --source npm --name <pkg> --version <semver>`

Infer location where possible when in a git repository. If the location can not be inferred, prompt. All other options can be prompted for when not provided or valid.

Cross tracked from typings/registry#2

Print the installed dependency tree on resolve

Once you install a dependency, it should print that dependency tree in the CLI to render "successful".

The same thing should happen after typings install to show what actually got installed. That will basically be typings ls output.

Create a `bundle` command

It's pretty much how install already happens, but should bundle the current file and output to a specific destination. Example:

typings bundle -o main.d.ts
typings bundle --browser --out browser.d.ts

Support configuration through package.json

It would be nice to support configuring typings through package.json, for example like babel does it (choice between package.json or a .babelrc file).

Solve "globals" installation (vs using a module system)

How do modules declare themselves as global and what parts they expose globally? Maybe we should add a "globals" field for typings.json that says what is declared and where it comes from. It would then install as usual, but the final step would be to declare the globals. A "hack/feature" that would work is to write a separate ambient bundle with the "external module" typings as a dependency - then just re-export parts. That hack depends on #1 being solved.

Edit: For anyone landing on this, for now, it's easily solved by installing as an "ambient dependency" that re-exports a normal dependency. This can and will be automated in the future, likely with a map of some kind in typings.json.

Implement registry API endpoint

Required for searching.

Optimize dependency resolution

If the user is using typings.json, traverse the typings tree. Otherwise, traverse the tree as a dependency. This will save a few filesystem reads and traversals by detecting which resolution is used (native or typings).

Expose a way to clear cache and document it

Something like rm -rf $(typings cache --print) or typings clear-cache for worst case corruption situations (shouldn't ever happen, but just in case).

Change `typings/` structure

Currently I have to ignore folders twice when using ignore instead of files in tsconfig.json (that's the whole reason for the current structure. This is the proposed change:

typings/definitions/browser -> typings/browser/definitions
typings/definitions/main -> typings/main/definitions
typings/ambient/browser -> typings/browser/ambient
typings/ambient/main -> typings/main/ambient

On top of this, I'll likely move the .d.ts files into folders with the module names to allow expansion in the future. It's likely I'll need a manifest file to support ls without doing HTTP calls, for example.

It's just switching the definition type with the dependency type.

Enable `ambientDevDependencies`

From TypeStrong/ts-node#43 (comment). This are development dependencies that are ambient. It's purely for semantic separation, but should be useful for the UX when we log than ambient dependencies of a module for users.

Prompt for a name on installation (when missing)

typings install github:... should prompt for the name of the repo, with the default being a sanitized repo name (replaced ^typed- and -typings$ in the repo name when no path).

Add instructions on using as part of the build process

You need to use it with the "postinstall" step if you use "prepublish" to build a TypeScript library since install runs the pre-publish script (npm/npm#3059). This is an issue when you reference NPM typings, as they won't be installed yet. However, if they aren't installed the "prepublish" will fail since the typings are missing. Kind of a catch 22, the only solution is postinstall - thankfully it works as expected.

Implement lockfile for modifying `typings.json` concurrently (any file modifications really)

https://www.npmjs.com/package/lockfile

Print an "installed by" blurb at the top of installed definition files

Maybe with a list of the resolved/used dependency tree? This way, when people are reading the compiled type definition they aren't confused by where it all come from.

Add update notifier to CLI

https://github.com/yeoman/update-notifier

Create a `validate` command

There should be a built-in validation command that will ensure the typings are accessible to the greatest number of consumers. For example:

typings validate
# Checks the typings field is set in `package.json`/`bower.json`
# Checks all dependencies are defined in `typings.json`
# Checks installation compiles properly with all types available

Edit: It should also be able to run the compiled types against a test suite, for usage in type definition repos, as one example.

Critical race condition on installation

I believe it's caused by serviejs/popsicle-cache#3, sometimes installation will break down with a syntax error because an extra } exists in the tmpdir cache. The current fix is to rm -rf $(node -p "require('path').join(require('os').tmpdir(), 'popsicle-cache')").

Create a `convert` command

It should be able to point to an ambient module, like in DefinitelyTyped, and pull it into an external module definition. Or specify as ambient output and pull into modules.

typings convert tape.d.ts --name tape
typings convert node.d.ts --ambient