@arshaw/dts-bundle

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.

Usage

1. Get it from npm:

npm install dts-bundle

1. Compile your modules with the TypeScript compiler of your choice with the --declaration and --outDir flags (and probably --module commonjs too).

Something like:

tsc src/index.ts --declaration --module commonjs --target es5 --outDir build

1. 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:

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:

1. Bonus points if you link the generated definition in your package.json's (or bower.json) typescript element:

{
	"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.

Wrappers

There is also a Grunt plugin grunt-dts-bundle that goes well with Grunt based compilers, like grunt-ts or grunt-typescript.

Options

Example of all options:

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:

// ## 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:

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 . 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:

// 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) : current lead
• Bart van der Schoor : 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.