zhengbli / tsjs-lib-generator

Tool for generating dom related TypeScript and JavaScript library files

TypeScript and JavaScript lib generator

AppVeyor Status: Travis CI Status:

This tool is used to generate dom.generated.d.ts and webworker.generated.d.ts for TypeScript, and domWeb.js and domWindows.js for Visual Studio JavaScript language service. The input file is the XML spec file generated by the Microsoft Edge browser.

Build Instructions

To build the tool, simply clone this repo, and run build.cmd (Windows) or build.sh (OS X/Unix) on the command line. If it runs successfully, the output files will be generated under the generated folder.

Note: for OS X and Unix users, Mono 4.2 or higher is required.

Contribution Guidelines

The dom.generated.d.ts and webworker.generated.d.ts files in the TypeScript repo are used as baselines. For each pull request, we will run the script and compare the generated files with the baseline files. In order to make the tests pass, please update the baseline as well in any pull requests.

For common changes, it is sufficient to change the json files. There are three json files that are used to alter the file generation: addedTypes.json, overridingTypes.json, and removedTypes.json. The format of each file can be inferred from their existing content.

The common steps to send a pull request are:

0. Open or refer to an issue in the TypeScript repo.
1. Add missing elements to inputfiles/addedTypes.json, overriding elements to inputfiles/overridingTypes.json, or elements to remove to inputfiles/removedTypes.json.
2. Run the script locally to obtain new dom.generated.d.ts and webworker.generated.d.ts.
3. Update the files in the baselines folder using the newly generated files.

When should a DOM API be included here?

If a DOM API is still a draft, it belongs on DefinitelyTyped. When it graduates past draft stage, it can be added here and removed from DefinitelyTyped. A feature is considered a draft if:

W3C

A Working Draft should go on DefinitelyTyped. A feature that is a Candidate Recommendation (or has passed that stage) should be added here.

WhatWG

A "Working Draft" (example) should go on DefinitelyTyped. A "Living Standard" (example) should be added here.

Code Structure

• Shared.fs: handles the parsing from XML spec file, and stores the common data structures for later use.
• TS.fs: handles the emitting of the lib.d.ts file.
• JS.fs: handles the emitting of the domWeb.js and domWindows.js.

Input Files

• browser.webidl.xml: an XML spec file generated by Microsoft Edge. Do not edit this file.
  • Due to the different update schedules between Edge and TypeScript, this may not be the most up-to-date version of the spec.
• webworker.webidl.xml: an XML spec file generated by Microsoft Edge that contains types for Web Workers. Do not edit this file.
• addedTypes.json: types that should exist in either browser or webworker but are missing from the Edge spec. The type can be property, method, interface, constructor, or indexer.
• overridingTypes.json: types that are defined in the spec file but has a better or more up-to-date definitions in the json files.
• removedTypes.json: types that are defined in the spec file but should be removed.
• comments.json: comment strings to be embedded in the generated .js files.
• jsTemplate.js: the initial templates for domWeb.js and domWindows.js, which contains the necessary helper functions.
• sample.json: sample json file used to tell F# json type provider that structure of the json files. The content of it is not used anywhere.