https://github.com/pmndrs/webidl-dts-gen
Converts Web IDL to Typescript (.d.ts)
https://github.com/pmndrs/webidl-dts-gen
Last synced: 5 months ago
JSON representation
Converts Web IDL to Typescript (.d.ts)
- Host: GitHub
- URL: https://github.com/pmndrs/webidl-dts-gen
- Owner: pmndrs
- Fork: true (giniedp/webidl2ts)
- Created: 2023-02-09T00:40:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-28T04:29:19.000Z (8 months ago)
- Last Synced: 2024-10-30T06:35:08.349Z (8 months ago)
- Language: TypeScript
- Size: 1.6 MB
- Stars: 10
- Watchers: 1
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# webidl-dts-gen
`webidl-dts-gen` is a Web IDL to d.ts converter
This tool generates a `.d.ts` file based on a WebIDL input file.
>**This is a fork of [webidl2ts](https://github.com/giniedp/webidl2ts). Thank you for your work giniedp!**
# Installation
```sh
npm install webidl-dts-gen
```
# Usage
```
Usage: webidl-dts-gen [options]
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
-i, --in Input file or url [required]
-o, --out Output file path [required]
-e, --emscripten Enable Emscripten mode [boolean] [default: false]
-n, --name Name of the module (emscripten mode) [default: "Module"]
-d, --default-export Write default export (emscripten mode) [boolean] [default: false]
```
## Definitions for browser libs
Generate type definitions from a local idl file:
```
webidl-dts-gen -i my.idl -o index.d.ts
```
Use remote IDL files:
```
webidl-dts-gen -i https://www.khronos.org/registry/webgl/specs/latest/2.0/webgl2.idl -o webgl.d.ts
```
Generate type definitions from online documentation:
```
webidl-dts-gen -i https://www.w3.org/TR/webxr/ -o webxr.d.ts
```
## Definitions for emscripten modules
Use the `-e` option to enable emscripten mode
```
webidl-dts-gen -e -i https://raw.githubusercontent.com/kripken/ammo.js/master/ammo.idl -o ammo.d.ts
```
# Usage in a project
This is an excerpt of a `package.json` with scripts to generate type definitions for the Ammojs project.
```json
{
"scripts": {
"generate": "yarn generate:module && yarn generate:ambient",
"generate:module": "webidl-dts-gen -i ./ammo.idl -n Ammo -ed -o ./builds/ammo.d.ts",
"generate:ambient": "webidl-dts-gen -i ./ammo.idl -n Ammo -e -o ./builds/ammo-ambient.d.ts"
}
}
```
And an excerpt of the project structure in this scenario would be
```
├── builds/ // build output folder
│ ├── ammo.d.ts // The generated d.ts file with a default export
│ ├── ammo-ambient.d.ts // The generated d.ts file with ambient declarations only
├── ammo.idl // The idl file
├── package.json // The package file
```
# Output and mode differences
Without the emscripten mode the provided IDL file must be a valid WebIDL 2 file. Otherwise it can not be parsed an an error is thrown. The generated `d.ts` output is roughly the same as with [TSJS-lib-generator](https://github.com/microsoft/TSJS-lib-generator).
Emscripten IDL files are not valid WebIDL 2 files. With emscripten mode enabled (`-e`) the IDL files are preprocessed so they can be parsed with the `webidl2` parser.
1. Inheritance statements are fixed:
```diff
-interface btVector4 {
+interface btVector4: btVector3 {
};
-btVector4 implements btVector3;
```
2. Array types (e.g. `float[]`) are converted to `FrozenArray` (e.g. `FrozenArray`)
Please file an issue if you need further adjustments
Some types are generated differently
| | `-e=true` | `-e=false` |
| ---------- | --------------------------------------- | ----------------------------------------- |
| interfaces | generated as classes | generated as interfaces and declared vars |
| attributes | generated with `get_` and `set_` prefix | generated as properties |
The generated d.ts output includes the following Module definition with `-e` enabled
```ts
declare function Module(target?: T): Promise
declare module Module {
function destroy(obj: any): void
function _malloc(size: number): number
function _free(ptr: number): void
function wrapPointer any>(ptr: number, Class: C): InstanceType
function getPointer(obj: unknown): number
function castObject any>(object: unknown, Class: C): InstanceType
function compare(object1: unknown, object2: unknown): boolean
const HEAP8: Int8Array
const HEAP16: Int16Array
const HEAP32: Int32Array
const HEAPU8: Uint8Array
const HEAPU16: Uint16Array
const HEAPU32: Uint32Array
const HEAPF32: Float32Array
const HEAPF32: Float64Array
// ... generated from IDL
}
```
The `-d` option adds a default export
```ts
export default Module
```
# References
- https://github.com/kripken/ammo.js/issues/233
- https://github.com/microsoft/TSJS-lib-generator
- https://github.com/osman-turan/ammo.js-typings
- https://ts-ast-viewer.com