dts-bundle/README.md

# dts-bundle

[![Build Status](https://travis-ci.org/TypeStrong/dts-bundle.svg)](https://travis-ci.org/TypeStrong/dts-bundle) [![NPM version](https://badge.fury.io/js/dts-bundle.svg)](http://badge.fury.io/js/dts-bundle) [![Dependency Status](https://david-dm.org/TypeStrong/dts-bundle.svg)](https://david-dm.org/TypeStrong/dts-bundle) [![devDependency Status](https://david-dm.org/TypeStrong/dts-bundle/dev-status.svg)](https://david-dm.org/TypeStrong/dts-bundle#info=devDependencies)

> 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](https://github.com/grunt-ts/dts-bundle/issues) any edge-cases.


## Usage

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](https://github.com/DefinitelyTyped/tsd) (from v0.6.x) can auto-link these into `tsd.d.ts` bundle file.


### Wrappers

There is also a Grunt plugin [grunt-dts-bundle](https://www.github.com/grunt-ts/grunt-dts-bundle) that goes well with Grunt based compilers, like [grunt-ts](https://www.github.com/grunt-ts/grunt-ts) or [grunt-typescript](https://github.com/k-maru/grunt-typescript).


## Options

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: "<baseDir>/<name>.d.ts"
	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 <reference path="..." /> tags *** Experimental, TEST NEEDED
	// - 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. "<baseDir>/**/*.d.ts")
	// - 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);
````

### All `.d.ts` files

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.
Internally `dts-bundle` 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.

### Module folders
NPM introduced support for in-package typings,
it is done by adding typings key into package.json file, which should refer to the
typings file.
when this is the case, the d.ts file is threated as module folder, and declare module
is not allowed.

* `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.

### Files not found.

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, 
when he loads all files `dts-bundle` 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 
definitions that you will load by other way in your final project.
* `emitOnNoIncludedFileNotFound`. 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.

## Return value

Experimental - Test needed -

`bundle` function return an object that implement this interface:

```` typescript
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`t be no included in the bundle.
    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.

# Command line

You can use `dts-bundle` from command line, its allow you use it from npm scripts [ see #13 ](https://github.com/TypeStrong/dts-bundle/issues/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 <value>            path to json config file. Load it first and override options with additional parameters
  --name <value>                  name of module likein package.json *required
  --main <value>                  path to entry-point (see documentation) *required
  --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 <reference path="..." /> tags
  --removeSource                  delete all source typings (i.e. "<baseDir>/**/*.d.ts")
  --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 `tmp/out/cooles.d.ts`.


## Todo

- 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


# History

* 0.4.x Several features.
  * CLI command
  * Support not found file (`emitOnIncludedFileNotFound` and `emitOnNoIncludedFileNotFound`)
  * Output relative to current path using "~/"
  * referenceExternals option
  * All files feature using `**/*.d.ts` on `main` option
  * Return a object with the result
  * Add Header using `headerPath` 
* 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

## Key People

* [Javier Ros (tolemaC)](http://github.com/tolemac) : current lead
* [Bart van der Schoor](https://github.com/Bartvds) : original creator

## Contributions

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.

## License

Licensed under the MIT license.