Recommendation: Simplify NPM/Node code sharing

[basarat]

Proposal

Support typescript.definition in package.json of node packages as a part of module resolution.

Example

Consider this simple NPM package : https://www.npmjs.com/package/example-typescript-a (src: https://github.com/TypeStrong/atom-typescript-examples/tree/master/node/node_modules/example-typescript-a)

It is super simple to use from atom-typescript. Open any typescript file in atom-typescript, if you have done npm install example-typescript-a then you can just use it without any additional configuration: E.g.

import a = require('example-typescript-a');

var num = a.foo.a;
var str = a.foo.b;
console.log(num,str)

import bar = require("example-typescript-a/dist/bar");
console.log(bar.bar);

import bas = require("example-typescript-a/dist/bas");
console.log(bas.bas);

sample usage

How it works

This is because example-typescript-a specifies a location of a definition using typescript.definition :

{
    "name": "cool-module",
    "version": "1.2.3",
    "typescript": {
        "definition": "dist/cool-module.d.ts"
    }
}

And we look at node_modules up its directory and read package.json for typescript.definition, for each such module we implicitly include this definition file as a part of the current project.

Creating such a module

Creating such a module example-typescript-a is also super easy. All you need to do is a package.json like you would with any NPM package (we care about name, typescript.definition and optionally main) and tell us that you plan to use this package.json from tsconfig. Docs : https://github.com/TypeStrong/atom-typescript/blob/master/docs/tsconfig.md#package

Based on this we can create the correct typescript.definition file for you on build f6 :

• Sample package.json
• Sample tsconfig.json
• Sample .d.ts created

Future

If such a module depends on tsd definitions OR other projects that have their own typescript.definition we need a resolution algorithm for that something like take latest and ignore all others. Plan:

• we do some smart stuff in reading exported d.ts not giving TypeScript the external reference comments (e.g. node.d.ts here https://github.com/TypeStrong/atom-typescript-examples/blob/master/node/node_modules/example-typescript-b/definition/sample-b.d.ts) And instead pointing to our own .d.ts if we have it in our Typings.

/cc @csnover

[johnnyreilly]

👍

[poelstra]

I certainly like dts-generator, and having support for it in Atom Typescript is awesome. Thanks @csnover and @basarat 🌹

If you're not afraid to npm install -g tsd@next (i.e. v0.6), you can already use tsd link to achieve a similar effect: it uses typescript.definition in package.json.

I'm sure you know that already, but it may help others coming here.

However, I fear that going the dts-generator-road (i.e. the 'wrap modules in declare module "..." road') is not going to work for the more general case of having multiple modules and especially multiple versions of them.
See #2568 (comment) (rather lengthy, sorry...) for the reasoning.

[mhegazy]

The proposal we have is to use typings (or possibly types) see #2338. i know tsd is using typescript.defntions, now the question is, what is the advantages/disadvantageous of using the same name?

[mhegazy]

@basarat, this looks like it should be subsumed by #2338; do you agree?

[basarat]

Agreed 🌹

[mhegazy]

Thanks 🙇

[basarat]

now the question is, what is the advantages/disadvantageous of using the same name?

Use the new name. Its clear that its a different feature then and we can phase out what I did previously 👍