Export TypeScript .d.ts files as an external module definition
npm install dts-bundle   
> Export TypeScript .d.ts files as an external module definition
This module is a naïve string-based approach at generating bundles from the .d.ts declaration files generated by a TypeScript compiler.
The main use-case is generating definition for npm/bower modules written in TypeScript (commonjs/amd) so the TypeScript code should following the external-module pattern (using import/export's and --outDir).
:warning: Experimental; use with care.
This module was born out of necessity and frustration. It is a little hacky but at least it seems to work..
- Original code was extracted from an ad-hoc Grunt-task so for now it is fully synchronous with no error feedback.
- It works by line-by-line string operations so please report any edge-cases.
1) Get it from npm:
```
npm install dts-bundle
2) Compile your modules with the TypeScript compiler of your choice with the --declaration and --outDir flags (and probably --module commonjs too).
Something like:
``shell``
tsc src/index.ts --declaration --module commonjs --target es5 --outDir build
3) Run dts-bundle (you can run it from cli, see "Command line" section.
Let's assume the project is called cool-project and the main module is build/index.js with a build/index.d.ts:
``js
var dts = require('dts-bundle');
dts.bundle({
name: 'cool-project',
main: 'build/index.d.ts'
});
``
This will traverse all references and imports for the .d.ts files of your sub-modules and write build/cool-project.d.ts with the bundle of all 'local' imports.
Optional:
4) Bonus points if you link the generated definition in your package.json's (or bower.json) typescript element:
``json
{
"name": "cool-project",
"version": "0.1.3",
"typescript": {
"definition": "build/cool-project.d.ts"
}
}
``
Using this makes the definition findable for tooling, for example the TypeScript Definitions package manager (from v0.6.x) can auto-link these into tsd.d.ts bundle file.
There is also a Grunt plugin grunt-dts-bundle that goes well with Grunt based compilers, like grunt-ts or grunt-typescript.
Example of all options:
``js
var opts = {
// Required
// name of module likein package.json
// - used to declare module & import/require
name: 'cool-project',
// path to entry-point (generated .d.ts file for main module)
// if you want to load all .d.ts files from a path recursively you can use "path/project/*/.d.ts"
// ^ * Experimental, TEST NEEDED, see "All .d.ts files" section
// - either relative or absolute
main: 'build/index.d.ts',
// Optional
// base directory to be used for discovering type declarations (i.e. from this project itself)
// - default: dirname of main
baseDir: 'build',
// path of output file. Is relative from baseDir but you can use absolute paths.
// if starts with "~/" then is relative to current path. See https://github.com/TypeStrong/dts-bundle/issues/26
// ^ * Experimental, TEST NEEDED
// - default: "
out: 'dist/cool-project.d.ts',
// include typings outside of the 'baseDir' (i.e. like node.d.ts)
// - default: false
externals: false,
// reference external modules as
// - default: false
referenceExternals: false,
// filter to exclude typings, either a RegExp or a callback. match path relative to opts.baseDir
// - RegExp: a match excludes the file
// - function: (file:String, external:Boolean) return true to exclude, false to allow
// - always use forward-slashes (even on Windows)
// - default: pass
exclude: /^defs\/$/,
// delete all source typings (i.e. "
// - default: false
removeSource: false,
// newline to use in output file
newline: os.EOL,
// indentation to use in output file
// - default 4 spaces
indent: ' ',
// prefix for rewriting module names
// - default ''
prefix: '__',
// separator for rewriting module 'path' names
// - default: forward slash (like sub-modules)
separator: '/',
// enable verbose mode, prints detailed info about all references and includes/excludes
// - default: false
verbose: false,
// emit although included files not found. See "Files not found" section.
// * Experimental, TEST NEEDED
// - default: false
emitOnIncludedFileNotFound: false,
// emit although no included files not found. See "Files not found" section.
// * Experimental, TEST NEEDED
// - default: false
emitOnNoIncludedFileNotFound: false,
// output d.ts as designed for module folder. (no declare modules)
outputAsModuleFolder: false,
// path to file that contains the header
// // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header
// - default: null
headerPath: "path/to/header/file",
// text of the the header
// doesn't work with headerPath
// // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header
// - default: ''
headerTex: ""
};
// require module
var dts = require('dts-bundle');
// run it
dts.bundle(opts);
``
Experimental - Test needed - https://github.com/TypeStrong/dts-bundle/issues/29
You can bundle the definitions from for all files contained on a directory, and children directories.
If you set main parameter to some path ended with */.d.ts then dts-bundle load all .d.ts files and generate a bundle.dts-bundle
Internally builds a temporally file with export of the rest of the files. You can see it on verbose mode: i.e:
`` typescript``
// ## temporally main file ##
export * from './Core/Bootstrap';
export * from './Core/ChangeDetection';
export * from './Core/ControllerDecorator';
export * from './Core/LifeCycle\LifeCycleHooks';
export * from './Decorators/Component';
export * from './Decorators/Input';
export * from './Decorators/Output';
export * from './Directives/ngPropertyBinding';
export * from './Events/EventEmitter';
export * from './Expressions/ExpressionParser';
export * from './Expressions/Ng1Lexer\Lexer';
export * from './Ng2Emulation';
export * from './Templates/HtmlParser\Parser';
export * from './Templates/HtmlParser\ParserRule';
export * from './Templates/HtmlParser\Rules\EventBindingRule';
export * from './Templates/HtmlParser\Rules\TwoWayBindingRule';
export * from './Utils/AngularHelpers';
Then dts-bundle processes this file. When finish the temporally file is deleted.
* outputAsModuleFolder. When using this option output d.ts will be compatible with module folder. which means, no declare module are used,
and all internal references are removed as they are merged into the output d.ts.
Experimental - Test needed -
dts-bundle expects to find all references for all modules. Goes over all files referenced and tries to load each file to get the definitions, dts-bundle
when he loads all files determines if include each one in the final bundle. If some file is not found dts-bundle doesn't emit the
result file. You could want to emit the result file although some file are not found. The file not found can be an included or exclued file in
the bundle then you have two options to control these cases:
* emitOnIncludedFileNotFound. When there are files not found and these file should be included in the bundle, dts-bundle writes the output file if emitOnIncludedFileNotFound is true. This allow you to have external file emitOnNoIncludedFileNotFound
definitions that you will load by other way in your final project.
* . When there are files not found and these file shouldn't be included in the bundle, dts-bundle writes the output file if emitOnNoIncludedFileNotFound is true. This allow you don't to include external
typings in your temporally output compile path.
Experimental - Test needed -
bundle function return an object that implement this interface:
`` typescriptt be no included in the bundle.
export interface BundleResult {
// a map with parse result per each process module.
fileMap: { [moduleName: string]: Result; };
// list of files not found that should be included in the bundle.
includeFilesNotFound: string[];
// list of files not found that shouldn
noIncludeFilesNotFound: string[];
// true if dts-bunlde wrote the result, false otherwise.
emitted?: boolean;
// original options passed to the function.
options: Options;
}
```
You can use the return value to determine if continue your gulp or grunt task or stop and emit an error.
You can use dts-bundle from command line, its allow you use it from npm scripts see #13 .
You have to install it using -g:
``
npm install dts-bundle -g
You can use the following options:
``
Usage: dts-bundle [options]
Options:
-h, --help output usage information
-V, --version output the version number
--configJson
--name
--main
--baseDir [value] base directory to be used for discovering type declarations
--out [value] path of output file. Is relative from baseDir but you can use absolute paths.
--externals include typings outside of the "baseDir" (i.e. like node.d.ts)
--referenceExternals reference external modules as
--removeSource delete all source typings (i.e. "
--newline [style] newline style to use in output file => unix|windows|currentOsDefault
--prefix [value] prefix for rewriting module names
--verbose enable verbose mode, prints detailed info about all references and includes/excludes
--emitOnIncludedFileNotFound emit although included files not found. See readme "Files not found" section.
--emitOnNoIncludedFileNotFound emit although no included files not found. See readme "Files not found" section.
--outputAsModuleFolder output as module folder format (no declare module) . See readme "Module folders" section.
--headerPath [value] path to file that contains the header
--headerText [value] text of the header. Doesn't work with headerPath.
``
For example:
``
dts-bundle --name cool-project --main build/output/index.d.ts
You can load config from a json file: json``
// dts-bundle.json file
{
"name": "cool-project",
"main": "tmp/out/index.d.ts"
}
Run this way:
dts-bundle --configJson dts-bundle.json
And can override properties:
dts-bundle --configJson dts-bundle.json --name coolest
Emitting .
- add feature to create a DefinitelyTyped header (using definition-header package)
- add feature to auto-update package.json/bower.json with the definition link
- find time to implement a parser based solution
- run IO asyncronous
* 0.4.x Several features.
* CLI command
* Support not found file (emitOnIncludedFileNotFound and emitOnNoIncludedFileNotFound)/.d.ts
* Output relative to current path using "~/"
* referenceExternals option
All files feature using on main optionheaderPath`
* Return a object with the result
* Add Header using
* 0.3.x - Support es6 module syntax & rewrite by TypeScript
* 0.2.x - Fixed bugs & added many options (thanks @poelstra)
* 0.1.x - First release
* Javier Ros (tolemaC) : current lead
* Bart van der Schoor : original creator
They are very welcome. Beware this module is a quick hack-job so good luck!
* Martin Poelstra (@poelstra): Exclude 'external' typings, optional debug output, improved configurability.
Licensed under the MIT license.