Jack Franklin
314b8c8aea
If we have a helper method that returns data, TS will moan about there not actually being a return in the function body. Adding code that throws an error fixes this and is safe as this bridge code is never executed, it exists to satisfy our compilers. Change-Id: Iff34733adac4267ff04aff1ba0bb58a38c71dd6b Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2366794 Commit-Queue: Jack Franklin <jacktfranklin@chromium.org> Commit-Queue: Alex Rudenko <alexrudenko@chromium.org> Auto-Submit: Jack Franklin <jacktfranklin@chromium.org> Reviewed-by: Alex Rudenko <alexrudenko@chromium.org>
Component bridges generation
We're building our web components in TypeScript but have to ensure that our legacy Closure code is happy and type-checks. See Building bridges to a TypeScript world for more details.
If you'd like to generate a bridge for a given component, run:
npm run generate-bridge-file ./front_end/path/to/component.ts
This will generate ./front_end/path/to/component_bridge.js.
Do not modify this by hand!.
If you change any types in component.ts, you should rerun this command (this will soon be enforced in a PRESUBMIT check).
## Details on the bridge
The bridges contain:
- Any interfaces that are needed in Closure code. These are taken from the TypeScript source and converted as a
@typedefthat Closure can understand. - A class definition for the custom element in the form of
class X extends HTMLElement. We use this class definition as a type in Closure land. - Any public methods defined in the component complete with JSDoc comments. Note that the function body is left empty.
- A function named
createX, whereXis the name of the component, that callsdocument.createElement('...').
## Debugging the bridges generation
The bridges code parses the component file to a TypeScript AST and walks through it looking for the particular parts of the code that are required.
The walking is done in walk_tree.ts which generates a state object which gets passed into generate_closure.ts which spits out JavaScript with JSDocs.
value_for_type_node.ts is able to take a single TypeScript node and convert it to the equivalent in Closure and this is used when generating interface definitions and JSDoc parameter comments.
You'll also find a suite of tests for this code in test/unittests/scripts/component_bridges.
These are not run on CQ but please use them locally when making a change to the generation. You can run them with:
npm run generate-bridges-test
It's important to note that the bridge generation code is not exhaustive; there are various TypeScript types that it does not yet support or understand. Rather than implement support for every node we're incrementally adding support as we need it. You should get a loud error message explaining that you're using an unsupported type. Feel free to make a CL to add support and if you'd like help reach out to one of the OWNERS.