1 | # dts-bundle
|
2 |
|
3 | [![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)
|
4 |
|
5 | > Export TypeScript .d.ts files as an external module definition
|
6 |
|
7 | This module is a naïve string-based approach at generating bundles from the .d.ts declaration files generated by a TypeScript compiler.
|
8 |
|
9 | 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`).
|
10 |
|
11 | :warning: Experimental; use with care.
|
12 |
|
13 | This module was born out of necessity and frustration. It is a little hacky but at least it seems to work..
|
14 |
|
15 | - Original code was extracted from an ad-hoc Grunt-task so for now it is fully synchronous with no error feedback.
|
16 | - It works by line-by-line string operations so please [report](https://github.com/grunt-ts/dts-bundle/issues) any edge-cases.
|
17 |
|
18 |
|
19 | ## Usage
|
20 |
|
21 | 1) Get it from npm:
|
22 |
|
23 | ````
|
24 | npm install dts-bundle
|
25 | ````
|
26 |
|
27 | 2) Compile your modules with the TypeScript compiler of your choice with the `--declaration` and `--outDir` flags (and probably `--module commonjs` too).
|
28 |
|
29 | Something like:
|
30 |
|
31 | ````shell
|
32 | tsc src/index.ts --declaration --module commonjs --target es5 --outDir build
|
33 | ````
|
34 |
|
35 | 3) Run `dts-bundle` (you can run it from cli, see "Command line" section.
|
36 |
|
37 | Let's assume the project is called `cool-project` and the main module is `build/index.js` with a `build/index.d.ts`:
|
38 |
|
39 | ````js
|
40 | var dts = require('dts-bundle');
|
41 |
|
42 | dts.bundle({
|
43 | name: 'cool-project',
|
44 | main: 'build/index.d.ts'
|
45 | });
|
46 | ````
|
47 |
|
48 | 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.
|
49 |
|
50 | **Optional:**
|
51 |
|
52 | 4) Bonus points if you link the generated definition in your package.json's (or bower.json) `typescript` element:
|
53 |
|
54 | ````json
|
55 | {
|
56 | "name": "cool-project",
|
57 | "version": "0.1.3",
|
58 |
|
59 | "typescript": {
|
60 | "definition": "build/cool-project.d.ts"
|
61 | }
|
62 | }
|
63 | ````
|
64 |
|
65 | 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.
|
66 |
|
67 |
|
68 | ### Wrappers
|
69 |
|
70 | 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).
|
71 |
|
72 |
|
73 | ## Options
|
74 |
|
75 | Example of all options:
|
76 |
|
77 | ````js
|
78 | var opts = {
|
79 |
|
80 | // Required
|
81 |
|
82 | // name of module likein package.json
|
83 | // - used to declare module & import/require
|
84 | name: 'cool-project',
|
85 | // path to entry-point (generated .d.ts file for main module)
|
86 | // if you want to load all .d.ts files from a path recursively you can use "path/project/**/*.d.ts"
|
87 | // ^ *** Experimental, TEST NEEDED, see "All .d.ts files" section
|
88 | // - either relative or absolute
|
89 | main: 'build/index.d.ts',
|
90 |
|
91 | // Optional
|
92 |
|
93 | // base directory to be used for discovering type declarations (i.e. from this project itself)
|
94 | // - default: dirname of main
|
95 | baseDir: 'build',
|
96 | // path of output file. Is relative from baseDir but you can use absolute paths.
|
97 | // if starts with "~/" then is relative to current path. See https://github.com/TypeStrong/dts-bundle/issues/26
|
98 | // ^ *** Experimental, TEST NEEDED
|
99 | // - default: "<baseDir>/<name>.d.ts"
|
100 | out: 'dist/cool-project.d.ts',
|
101 | // include typings outside of the 'baseDir' (i.e. like node.d.ts)
|
102 | // - default: false
|
103 | externals: false,
|
104 | // reference external modules as <reference path="..." /> tags *** Experimental, TEST NEEDED
|
105 | // - default: false
|
106 | referenceExternals: false,
|
107 | // filter to exclude typings, either a RegExp or a callback. match path relative to opts.baseDir
|
108 | // - RegExp: a match excludes the file
|
109 | // - function: (file:String, external:Boolean) return true to exclude, false to allow
|
110 | // - always use forward-slashes (even on Windows)
|
111 | // - default: *pass*
|
112 | exclude: /^defs\/$/,
|
113 | // delete all source typings (i.e. "<baseDir>/**/*.d.ts")
|
114 | // - default: false
|
115 | removeSource: false,
|
116 | // newline to use in output file
|
117 | newline: os.EOL,
|
118 | // indentation to use in output file
|
119 | // - default 4 spaces
|
120 | indent: ' ',
|
121 | // prefix for rewriting module names
|
122 | // - default ''
|
123 | prefix: '__',
|
124 | // separator for rewriting module 'path' names
|
125 | // - default: forward slash (like sub-modules)
|
126 | separator: '/',
|
127 | // enable verbose mode, prints detailed info about all references and includes/excludes
|
128 | // - default: false
|
129 | verbose: false,
|
130 | // emit although included files not found. See "Files not found" section.
|
131 | // *** Experimental, TEST NEEDED
|
132 | // - default: false
|
133 | emitOnIncludedFileNotFound: false,
|
134 | // emit although no included files not found. See "Files not found" section.
|
135 | // *** Experimental, TEST NEEDED
|
136 | // - default: false
|
137 | emitOnNoIncludedFileNotFound: false,
|
138 | // output d.ts as designed for module folder. (no declare modules)
|
139 | outputAsModuleFolder: false,
|
140 | // path to file that contains the header
|
141 | // // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header
|
142 | // - default: null
|
143 | headerPath: "path/to/header/file",
|
144 | // text of the the header
|
145 | // doesn't work with headerPath
|
146 | // // insert a header in output file. i.e.: http://definitelytyped.org/guides/contributing.html#header
|
147 | // - default: ''
|
148 | headerTex: ""
|
149 | };
|
150 |
|
151 | // require module
|
152 | var dts = require('dts-bundle');
|
153 |
|
154 | // run it
|
155 | dts.bundle(opts);
|
156 | ````
|
157 |
|
158 | ### All `.d.ts` files
|
159 |
|
160 | Experimental - Test needed - https://github.com/TypeStrong/dts-bundle/issues/29
|
161 |
|
162 | You can bundle the definitions from for all files contained on a directory, and children directories.
|
163 | If you set `main` parameter to some path ended with `**/*.d.ts` then `dts-bundle` load all .d.ts files and generate a bundle.
|
164 | Internally `dts-bundle` builds a temporally file with export of the rest of the files. You can see it on verbose mode: i.e:
|
165 |
|
166 | ```` typescript
|
167 | // ## temporally main file ##
|
168 | export * from './Core/Bootstrap';
|
169 | export * from './Core/ChangeDetection';
|
170 | export * from './Core/ControllerDecorator';
|
171 | export * from './Core/LifeCycle\LifeCycleHooks';
|
172 | export * from './Decorators/Component';
|
173 | export * from './Decorators/Input';
|
174 | export * from './Decorators/Output';
|
175 | export * from './Directives/ngPropertyBinding';
|
176 | export * from './Events/EventEmitter';
|
177 | export * from './Expressions/ExpressionParser';
|
178 | export * from './Expressions/Ng1Lexer\Lexer';
|
179 | export * from './Ng2Emulation';
|
180 | export * from './Templates/HtmlParser\Parser';
|
181 | export * from './Templates/HtmlParser\ParserRule';
|
182 | export * from './Templates/HtmlParser\Rules\EventBindingRule';
|
183 | export * from './Templates/HtmlParser\Rules\TwoWayBindingRule';
|
184 | export * from './Utils/AngularHelpers';
|
185 | ````
|
186 |
|
187 | Then `dts-bundle` processes this file. When finish the temporally file is deleted.
|
188 |
|
189 | ### Module folders
|
190 | NPM introduced support for in-package typings,
|
191 | it is done by adding typings key into package.json file, which should refer to the
|
192 | typings file.
|
193 | when this is the case, the d.ts file is threated as module folder, and declare module
|
194 | is not allowed.
|
195 |
|
196 | * `outputAsModuleFolder`. When using this option output d.ts will be compatible with module folder. which means, no declare module are used,
|
197 | and all internal references are removed as they are merged into the output d.ts.
|
198 |
|
199 | ### Files not found.
|
200 |
|
201 | Experimental - Test needed -
|
202 |
|
203 | `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,
|
204 | 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
|
205 | 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
|
206 | the bundle then you have two options to control these cases:
|
207 |
|
208 | * `emitOnIncludedFileNotFound`. When there are files not found and these file should be included in the bundle,
|
209 | `dts-bundle` writes the output file if `emitOnIncludedFileNotFound` is true. This allow you to have external file
|
210 | definitions that you will load by other way in your final project.
|
211 | * `emitOnNoIncludedFileNotFound`. When there are files not found and these file shouldn't be included in the bundle,
|
212 | `dts-bundle` writes the output file if `emitOnNoIncludedFileNotFound` is true. This allow you don't to include external
|
213 | typings in your temporally output compile path.
|
214 |
|
215 | ## Return value
|
216 |
|
217 | Experimental - Test needed -
|
218 |
|
219 | `bundle` function return an object that implement this interface:
|
220 |
|
221 | ```` typescript
|
222 | export interface BundleResult {
|
223 | // a map with parse result per each process module.
|
224 | fileMap: { [moduleName: string]: Result; };
|
225 | // list of files not found that should be included in the bundle.
|
226 | includeFilesNotFound: string[];
|
227 | // list of files not found that shouldn`t be no included in the bundle.
|
228 | noIncludeFilesNotFound: string[];
|
229 | // true if dts-bunlde wrote the result, false otherwise.
|
230 | emitted?: boolean;
|
231 | // original options passed to the function.
|
232 | options: Options;
|
233 | }
|
234 | ````
|
235 |
|
236 | You can use the return value to determine if continue your gulp or grunt task or stop and emit an error.
|
237 |
|
238 | # Command line
|
239 |
|
240 | 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).
|
241 | You have to install it using -g:
|
242 |
|
243 | ````
|
244 | npm install dts-bundle -g
|
245 | ````
|
246 |
|
247 | You can use the following options:
|
248 |
|
249 | ````
|
250 | Usage: dts-bundle [options]
|
251 |
|
252 | Options:
|
253 |
|
254 | -h, --help output usage information
|
255 | -V, --version output the version number
|
256 | --configJson <value> path to json config file. Load it first and override options with additional parameters
|
257 | --name <value> name of module likein package.json *required
|
258 | --main <value> path to entry-point (see documentation) *required
|
259 | --baseDir [value] base directory to be used for discovering type declarations
|
260 | --out [value] path of output file. Is relative from baseDir but you can use absolute paths.
|
261 | --externals include typings outside of the "baseDir" (i.e. like node.d.ts)
|
262 | --referenceExternals reference external modules as <reference path="..." /> tags
|
263 | --removeSource delete all source typings (i.e. "<baseDir>/**/*.d.ts")
|
264 | --newline [style] newline style to use in output file => unix|windows|currentOsDefault
|
265 | --prefix [value] prefix for rewriting module names
|
266 | --verbose enable verbose mode, prints detailed info about all references and includes/excludes
|
267 | --emitOnIncludedFileNotFound emit although included files not found. See readme "Files not found" section.
|
268 | --emitOnNoIncludedFileNotFound emit although no included files not found. See readme "Files not found" section.
|
269 | --outputAsModuleFolder output as module folder format (no declare module) . See readme "Module folders" section.
|
270 | --headerPath [value] path to file that contains the header
|
271 | --headerText [value] text of the header. Doesn't work with headerPath.
|
272 | ````
|
273 |
|
274 | For example:
|
275 | ````
|
276 | dts-bundle --name cool-project --main build/output/index.d.ts
|
277 | ````
|
278 | You can load config from a json file:
|
279 | ```` json
|
280 | // dts-bundle.json file
|
281 | {
|
282 | "name": "cool-project",
|
283 | "main": "tmp/out/index.d.ts"
|
284 | }
|
285 | ````
|
286 | Run this way:
|
287 | ````
|
288 | dts-bundle --configJson dts-bundle.json
|
289 | ````
|
290 | And can override properties:
|
291 | ````
|
292 | dts-bundle --configJson dts-bundle.json --name coolest
|
293 | ````
|
294 | Emitting `tmp/out/cooles.d.ts`.
|
295 |
|
296 |
|
297 | ## Todo
|
298 |
|
299 | - add feature to create a DefinitelyTyped header (using `definition-header` package)
|
300 | - add feature to auto-update package.json/bower.json with the definition link
|
301 | - find time to implement a parser based solution
|
302 | - run IO asyncronous
|
303 |
|
304 |
|
305 | # History
|
306 |
|
307 | * 0.4.x Several features.
|
308 | * CLI command
|
309 | * Support not found file (`emitOnIncludedFileNotFound` and `emitOnNoIncludedFileNotFound`)
|
310 | * Output relative to current path using "~/"
|
311 | * referenceExternals option
|
312 | * All files feature using `**/*.d.ts` on `main` option
|
313 | * Return a object with the result
|
314 | * Add Header using `headerPath`
|
315 | * 0.3.x - Support es6 module syntax & rewrite by TypeScript
|
316 | * 0.2.x - Fixed bugs & added many options (thanks @poelstra)
|
317 | * 0.1.x - First release
|
318 |
|
319 | ## Key People
|
320 |
|
321 | * [Javier Ros (tolemaC)](http://github.com/tolemac) : current lead
|
322 | * [Bart van der Schoor](https://github.com/Bartvds) : original creator
|
323 |
|
324 | ## Contributions
|
325 |
|
326 | They are very welcome. Beware this module is a quick hack-job so good luck!
|
327 |
|
328 | * Martin Poelstra (@poelstra): Exclude 'external' typings, optional debug output, improved configurability.
|
329 |
|
330 | ## License
|
331 |
|
332 | Licensed under the MIT license.
|
333 |
|
\ | No newline at end of file |