Generate a single declaration file for external modules

[mhegazy]

If compiling external modules, with --declaration, each module gets its own declaration file. this is not useful for library authors, who probably want to hand off a single .d.ts file for all their modules. the only way to do this now, is to either hand edit the file, or use a tool to concatenate the output.

This becomes even more desirable with ES6 module export/import where a module can reexport exports of another module.

See discussion in #2516 (comment) for more details.

[mhegazy]

Also related to #17

[basarat]

Tagging @csnover because of https://github.com/SitePen/dts-generator

[NoelAbrahams]

I would like to have a generate-single-declaration-file option (without combining JavaScript output) for _internal modules_ as well. See #192.

[ToddThomson]

My experiences with Typescript 1.5 have been positive. The only thing that keeps giving me grief is the internal "module" ( which is only a namespace ). I really don't like fighting back and forth between internal and external/real/es6 modules and what I am allowed to do with both ( mostly the grief that comes from defining external module bundles ). I really only want to use the ES6 module syntax going forward.
I have no issues with 1 file = 1 es6 module and optimizing during a production build. However there are times that I want to bundle files/modules together at compilation time. Even if this just produced a named typescript definition file I would be happy.
I am wondering if you can leverage the tsconfig.json "project" file to provide "bundles". A bundle would look like:
"bundles": {
"bundle-name": [ "some/module", "another/module" ],
"another-bundle-name": [ "yet-another-module" ]
}
An appropriate arg could be used for command line builds.

@mhegazy I want to re-phrase your statement.
Every lib developer wants an auto-magic generation of declarations. Period.

If all code initially uses internal modules, then it does not matter if declarations are spread over several files. Files can be copy-pasted and used as is. I see no problem in this scenario.

But, if your lib uses external libraries, i.e. import/require, then manual labour is required, because developer needs

declare module "external-thingy" {
...
}

and this currently is not done automatically.
Manual process involves writing "internal module" declaration, which is "export = Foo" into external module declaration. We need are way to have simple (automatable) solution to declare above thing.
Again, number of files is not an issue!

If modules are all internal, then multiple files declaration can be concat-ed with gulp / grunt into single file without stepping on each other's toes. Such is simple nature of internal modules.

Say. There was a news that number of node (npm) modules is already comparable if not surpassing a number of maven (!) modules. Hooray! It is time to fix external modules' declarations!

[ToddThomson]

I've put together an npm module ( TsProject ) that uses the tsconfig.json file to define bundles. It generates a typescript source file based on the dependencies in a source file as specified by a bundle. The generated typescript source file is output along with the compiled javascript and definition file.

[poelstra]

I'm not too sure it's really "a single .d.ts file" that we'd need.

Having one .d.ts file per .emitted .js file is a very good fit for the CommonJS way of working.
Relevant advantages I see:

• possibility for having multiple versions of the same module
• only rewriting changed files, without having to rewrite the complete bundle

Note that with external modules, the name of an external module is typically not present in the file itself. It is determined by its filename. So, I'd vote for keeping the currently generated .d.ts files as-is, and not e.g. put 'declare module "my-module" {}' inside of them, not even in an 'overall bundle file'.

Tools like dts-bundle and dts-generator seem to prefer to write out one file, but I believe this is mainly because TypeScript doesn't allow specifying relative paths for the import()'s in .d.ts files.

I think that if TSC would allow those paths even in .d.ts files, dts-bundle or dts-generator would no longer be necessary.

Still, a solution needs to be found for any other 'really external' modules (i.e. different npm packages, not just different .ts files inside the package) that are referenced, as this would basically mean that the /// <reference ...> line of the package would need to be 'local' to that package's .d.ts file. Otherwise these really external modules will start conflicting with similar modules in other packages.

TSC disallows having an external module be declared multiple times, which you can only get to work if all references are pointing to the same definition file. So, let's not try to 'throw away' that information by bundling, but support the case of leaving the files where they are, and use the 'real' filesystem to resolve the references.

Note: my use-case is mainly 'plain' CommonJS, using TSC's --outDir option, and using browserify for the browser. I guess that the single-.d.ts-file case would be handy for TSC's --out option.

Use case against clobbering declarations into a single file.

Step one. I ship a node lib with one declarations file. Due to having declarations, users of the lib (developers!) now can see type info and comments, when these were properly transferred into declarations.
Step two. In Eclipse, for example, developer is pressing F3 to see what is used. IDE will show only respective definition.
Developer's intention, though, is to see a source (js) of a beast, which he is using. If declarations' folder structure maps that of module's code, then respective js can be easily found. Not so, when declarations are in a single file.

[basarat]

Worth sharing here : #2829 all it needs is the path to your package.json + tsconfig.json to generate and consume node packages. no additional configuration required.

[basarat]

@poelstra

my use-case is mainly 'plain' CommonJS, using TSC's --outDir option, and using browserify for the browser. I guess that the single-.d.ts-file case would be handy for TSC's --out option

Not true. Look at : https://github.com/TypeStrong/atom-typescript-examples/blob/master/node/lib/main.ts You can import any file you have exported despite using a single .d.ts definition file

Again the details of the proposal : #2829