Proposal of a convention about npm modules distribution.

[vilicvane]

There was an discussion about generating ambient declarations for external CommonJS modules: http://typescript.codeplex.com/workitem/2080

But even if typescript generates the definitions as we what we want, we'll still need to add references manually, which is not doing better job than JS libs with NuGet DefinitelyTyped packages.

I propose that when we publish a typescript package via npm, publish the .d.ts file(s) generated with the current style along with it.

So that we can manage to write a tool (or add a feature to something like WebEssentials) to watch related node_modules directory, resolve the definition references and create wrapped definition file(s) under scripts/typings folder.

Thoughts?

[RyanCavanaugh]

I'm not sure exactly what this means? Is this a proposal for community behavior, or a change in TypeScript?

[vilicvane]

@RyanCavanaugh this time it's for community behavior. (Or I need to post it elsewhere?)

[poelstra]

Note that the TypeScript Definition Manager (tsd) is also in the process of 'standardising' this, see https://github.com/DefinitelyTyped/tsd#link-to-package-manager-bundled-definitions

Ideally, TypeScript should produce external typings (when "-m commonjs" is supplied), but until then, one can use e.g. https://github.com/grunt-ts/dts-bundle as a (quick&dirty) tool to convert TypeScript's existing internal typings to external ones.

[vilicvane]

@poelstra thanks for your links, it's good to know there's already main stream tools working on this. :D

[xealot]

We have recently run into the situation where trying to use several Typescript projects that depend on one another can become quite a nightmare. This extends almost solely from the fact that when using external (real) modules the definition files are created per module and there isn't any clear way to concat them, compile them or otherwise export them for use in another project.

We will be investigating your links @poelstra, thank you.

I also wanted to ask if anything has changed regarding this particular situation.

[poelstra]

We started off trying to use the NPM-way of having many small modules, but this was too much hassle. We're still using CommonJS (solely), but are building almost everything as one big NPM module.

We've open-sourced one package for now (https://github.com/SpiritIT/timezonecomplete, shameless plug ;)), for which we also submitted typings to DefinitelyTyped, as the "tsd link" functionality didn't seem usable at the time. We're using dts-bundle for generating these typings, which tends to work great in practice.

So even in our main TypeScript project, we're effectively treating that package as any other 'plain' Javascript package, and 'manually' apply the DT typings. This is suboptimal, but it works.

I think the only strangeness we've had is that VS's IntelliSense occasionally forgets what members the enums in Timezonecomplete have, whereas the commandline compiler accepts the code just fine. Not sure why yet.

If you found a better workflow for using TypeScript modules, I'm very interested in hearing about it!

[xealot]

I want to mention that this most likely has a strong relationship to:
#17

[mhfrantz]

We're interested in a cleaner solution than ts-pkg-installer, which we wrote to address TypeScript modularity in the NPM/TSD ecosystem.

https://github.com/RedSeal-co/ts-pkg-installer

We also use dts-bundle, which complements ts-pkg-installer in that it generates a declaration file that can be installed with ts-pkg-installer.

[mhegazy]

@vladima has proposal in #2338 for managing typings as part of resolving node_modules. the idea is that the package.json would have a "types" as a property, and the typescript compiler will look up that file and use it if it exists. would that work?

[vilicvane]

@mhfrantz I am also designing a package manager for TypeScript. Hoping it could be compatible with NPM and other package managers like bower. And I would like it to support some simple pre-compile features for supporting libraries with or without module system. https://github.com/vilic/tying

[mhfrantz]

@mhegazy, having reference paths work with node_modules/package.json would be ideal. The most brittle part of the reference path feature is the necessity of specifying the exact location of files. Resolving reference paths within node_modules makes the most sense from the NodeJS standpoint.

It is important to incorporate DefinitelyTyped declarations as well, as all type information is not embedded within the NodeJS module itself.

It is also important to de-dupe the declarations.

[mhegazy]

Thanks @mhfrantz for the feedback, a few comments:

The most brittle part of the reference path feature is the necessity of specifying the exact location of files. Resolving reference paths within node_modules makes the most sense from the NodeJS standpoint.

The proposal in #2338 looks in node_modules and reads package.json

It is important to incorporate DefinitelyTyped declarations as well, as all type information is not embedded within the NodeJS module itself.

Any proposals on how to do that, and how would that be diffrent from something like what tsd is doing today.

It is also important to de-dupe the declarations.

What are the rules? any proposals on how this should be done?

[mhfrantz]

@mhegazy If you look at what ts-pkg-installer is trying to do, it builds a TSD config file so that if multiple modules depend on the same declaration, they will all resolve to the same file. This is awkward, since it involves building config files, and then running the TSD utility on the result.

If it were incorporated into TSC, then perhaps reference paths would contain simple names, like a module name. It could look in node_modules first, and then in typings.

For example, suppose you see this:

///<reference path="mocha"/>

This is a reference to the module "mocha", which (today) has no TypeScript declaration of its own. Thus, it would resolve to typings/mocha/mocha.d.ts.

[mhegazy]

so what is the proposal, add <root>/typings as an implicit include path? though I am not a fan of include paths in general.

[mhfrantz]

@mhegazy It is not as simple as adding <root>/typings as an include path, since the logic for determining the exact *.d.ts file name varies. Given a reference to "@scope/foo":

• If we find a module in node_modules called "@scope/foo", and its package.json contains a "types" section, then use that *.d.ts file.
• If we find a module in typings called "@scope/foo", then use foo.d.ts in that directory.

Thus the proposal is to support both NPM packages written in TypeScript with embedded type declarations as well as NPM packages whose type declarations come via TSD. This can be accomplished with a single, coherent reference path syntax that is agnostic of the distinction between these two cases.

[poelstra]

@mhfrantz Just re-read this thread, and noticed that I seem to have run into a similar issue as what you describe (de-dupeing declarations, and supporting TSD case).

I created #2839 with a proposal for a solution, would it fit to your use-case too?