From 81795744cf82a57b129f8a1fe113a9b64f61ffb2 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Tue, 15 Jun 2021 13:50:31 -0700 Subject: [PATCH] fix: ensure the typescript definitions only export correct value types (#28712) * fix: ensure the typescript definitions only export correct value types In typescript there are two main types of "types" you can export, value types (class, const) and definition types (type, interface). The typescript compiler will let anything declared via const or class be used as a value. Unfortunately we were exporting a bunch of things (see the diff) as class/const when they weren't actually exported values. This lead to typescript being happy but the runtime throwing errors (not something we want). This change passes "exported-in" context through our docs, to the parser and then to the definitions generator to ensure we only mark things as exported in the ts defs that we actually export. Fixes #22167 * chore: update typescript-defs * chore: update typescript-defs * chore: fix bad typescript in IPC test * docs: test rendering of new syntax * chore: update per feedback, use same syntax but with 'this is not exportedd' line --- .markdownlint.json | 5 ++++- docs/api/browser-window-proxy.md | 3 ++- docs/api/client-request.md | 3 ++- docs/api/command-line.md | 3 ++- docs/api/cookies.md | 3 ++- docs/api/debugger.md | 3 ++- docs/api/dock.md | 3 ++- docs/api/download-item.md | 3 ++- docs/api/incoming-message.md | 3 ++- docs/api/message-port-main.md | 3 ++- docs/api/native-image.md | 3 ++- docs/api/service-workers.md | 3 ++- docs/api/session.md | 3 ++- docs/api/touch-bar-button.md | 3 ++- docs/api/touch-bar-color-picker.md | 3 ++- docs/api/touch-bar-group.md | 3 ++- docs/api/touch-bar-label.md | 3 ++- docs/api/touch-bar-other-items-proxy.md | 3 ++- docs/api/touch-bar-popover.md | 3 ++- docs/api/touch-bar-scrubber.md | 3 ++- docs/api/touch-bar-segmented-control.md | 3 ++- docs/api/touch-bar-slider.md | 3 ++- docs/api/touch-bar-spacer.md | 3 ++- docs/api/web-contents.md | 3 ++- docs/api/web-frame-main.md | 3 ++- docs/api/web-request.md | 3 ++- docs/api/webview-tag.md | 3 ++- package.json | 6 +++--- spec-main/api-ipc-spec.ts | 2 +- yarn.lock | 16 ++++++++-------- 30 files changed, 68 insertions(+), 39 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index 22b99e78ddb1..a1628ba622a3 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -22,5 +22,8 @@ "no-trailing-spaces": { "br_spaces": 0 }, - "single-h1": false + "single-h1": false, + "no-inline-html": { + "allowed_elements": ["br"] + } } diff --git a/docs/api/browser-window-proxy.md b/docs/api/browser-window-proxy.md index 33a1022317d9..4a025931dde5 100644 --- a/docs/api/browser-window-proxy.md +++ b/docs/api/browser-window-proxy.md @@ -2,7 +2,8 @@ > Manipulate the child browser window -Process: [Renderer](../glossary.md#renderer-process) +Process: [Renderer](../glossary.md#renderer-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ The `BrowserWindowProxy` object is returned from `window.open` and provides limited functionality with the child window. diff --git a/docs/api/client-request.md b/docs/api/client-request.md index d2c018b7e34c..e561498e67fd 100644 --- a/docs/api/client-request.md +++ b/docs/api/client-request.md @@ -2,7 +2,8 @@ > Make HTTP/HTTPS requests. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ `ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams) interface and is therefore an [EventEmitter][event-emitter]. diff --git a/docs/api/command-line.md b/docs/api/command-line.md index 8823dfbe0c4e..cae1d5bf9993 100644 --- a/docs/api/command-line.md +++ b/docs/api/command-line.md @@ -2,7 +2,8 @@ > Manipulate the command line arguments for your app that Chromium reads -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ The following example shows how to check if the `--disable-gpu` flag is set. diff --git a/docs/api/cookies.md b/docs/api/cookies.md index cd598bfeece8..5f876f971e49 100644 --- a/docs/api/cookies.md +++ b/docs/api/cookies.md @@ -2,7 +2,8 @@ > Query and modify a session's cookies. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ Instances of the `Cookies` class are accessed by using `cookies` property of a `Session`. diff --git a/docs/api/debugger.md b/docs/api/debugger.md index 1d9792193766..cfa2eb4a7fdb 100644 --- a/docs/api/debugger.md +++ b/docs/api/debugger.md @@ -2,7 +2,8 @@ > An alternate transport for Chrome's remote debugging protocol. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ Chrome Developer Tools has a [special binding][rdp] available at JavaScript runtime that allows interacting with pages and instrumenting them. diff --git a/docs/api/dock.md b/docs/api/dock.md index 2f1b12bff9d1..989940e7eb0d 100644 --- a/docs/api/dock.md +++ b/docs/api/dock.md @@ -2,7 +2,8 @@ > Control your app in the macOS dock -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ The following example shows how to bounce your icon on the dock. diff --git a/docs/api/download-item.md b/docs/api/download-item.md index d6cbeb6df364..6d4a0b3bec92 100644 --- a/docs/api/download-item.md +++ b/docs/api/download-item.md @@ -2,7 +2,8 @@ > Control file downloads from remote sources. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ `DownloadItem` is an [EventEmitter][event-emitter] that represents a download item in Electron. It is used in `will-download` event of `Session` class, and allows users to diff --git a/docs/api/incoming-message.md b/docs/api/incoming-message.md index 21dd938b32cc..8a9d1b027ad6 100644 --- a/docs/api/incoming-message.md +++ b/docs/api/incoming-message.md @@ -2,7 +2,8 @@ > Handle responses to HTTP/HTTPS requests. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ `IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) interface and is therefore an [EventEmitter][event-emitter]. diff --git a/docs/api/message-port-main.md b/docs/api/message-port-main.md index 6c84c28c49bb..530984391665 100644 --- a/docs/api/message-port-main.md +++ b/docs/api/message-port-main.md @@ -16,7 +16,8 @@ channel messaging. > Port interface for channel messaging in the main process. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### Instance Methods diff --git a/docs/api/native-image.md b/docs/api/native-image.md index 7856412aeae1..ad4cb2e1b10d 100644 --- a/docs/api/native-image.md +++ b/docs/api/native-image.md @@ -215,7 +215,8 @@ where `SYSTEM_IMAGE_NAME` should be replaced with any value from [this list](htt > Natively wrap images such as tray, dock, and application icons. -Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process) +Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### Instance Methods diff --git a/docs/api/service-workers.md b/docs/api/service-workers.md index a18133df192f..15bf1a13a20c 100644 --- a/docs/api/service-workers.md +++ b/docs/api/service-workers.md @@ -2,7 +2,8 @@ > Query and receive events from a sessions active service workers. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ Instances of the `ServiceWorkers` class are accessed by using `serviceWorkers` property of a `Session`. diff --git a/docs/api/session.md b/docs/api/session.md index 7e933743c9d9..25389f70b713 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -54,7 +54,8 @@ A `Session` object, the default session object of the app. > Get and set properties of a session. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ You can create a `Session` object in the `session` module: diff --git a/docs/api/touch-bar-button.md b/docs/api/touch-bar-button.md index 290e0d0a4078..01629ada3403 100644 --- a/docs/api/touch-bar-button.md +++ b/docs/api/touch-bar-button.md @@ -2,7 +2,8 @@ > Create a button in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarButton(options)` diff --git a/docs/api/touch-bar-color-picker.md b/docs/api/touch-bar-color-picker.md index 9a50a0d531fa..e549adf1ad93 100644 --- a/docs/api/touch-bar-color-picker.md +++ b/docs/api/touch-bar-color-picker.md @@ -2,7 +2,8 @@ > Create a color picker in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarColorPicker(options)` diff --git a/docs/api/touch-bar-group.md b/docs/api/touch-bar-group.md index 4c1f0866d283..a04b2279d0b5 100644 --- a/docs/api/touch-bar-group.md +++ b/docs/api/touch-bar-group.md @@ -2,7 +2,8 @@ > Create a group in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarGroup(options)` diff --git a/docs/api/touch-bar-label.md b/docs/api/touch-bar-label.md index 33fd244db490..8320aa0bc02c 100644 --- a/docs/api/touch-bar-label.md +++ b/docs/api/touch-bar-label.md @@ -2,7 +2,8 @@ > Create a label in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarLabel(options)` diff --git a/docs/api/touch-bar-other-items-proxy.md b/docs/api/touch-bar-other-items-proxy.md index a4e76def11ed..a00cd4b0b158 100644 --- a/docs/api/touch-bar-other-items-proxy.md +++ b/docs/api/touch-bar-other-items-proxy.md @@ -7,6 +7,7 @@ > > Note: Only one instance of this class can be added per TouchBar. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarOtherItemsProxy()` diff --git a/docs/api/touch-bar-popover.md b/docs/api/touch-bar-popover.md index 961f7072a4da..5d3b4ae8e667 100644 --- a/docs/api/touch-bar-popover.md +++ b/docs/api/touch-bar-popover.md @@ -2,7 +2,8 @@ > Create a popover in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarPopover(options)` diff --git a/docs/api/touch-bar-scrubber.md b/docs/api/touch-bar-scrubber.md index c21f6e1383fd..aa37c1e7aa98 100644 --- a/docs/api/touch-bar-scrubber.md +++ b/docs/api/touch-bar-scrubber.md @@ -2,7 +2,8 @@ > Create a scrubber (a scrollable selector) -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarScrubber(options)` diff --git a/docs/api/touch-bar-segmented-control.md b/docs/api/touch-bar-segmented-control.md index f25604592e17..1c0d411fd33e 100644 --- a/docs/api/touch-bar-segmented-control.md +++ b/docs/api/touch-bar-segmented-control.md @@ -2,7 +2,8 @@ > Create a segmented control (a button group) where one button has a selected state -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarSegmentedControl(options)` diff --git a/docs/api/touch-bar-slider.md b/docs/api/touch-bar-slider.md index 8bfdb5fc9643..bf9246c9079b 100644 --- a/docs/api/touch-bar-slider.md +++ b/docs/api/touch-bar-slider.md @@ -2,7 +2,8 @@ > Create a slider in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarSlider(options)` diff --git a/docs/api/touch-bar-spacer.md b/docs/api/touch-bar-spacer.md index de13c8d4e94b..8d160281f48d 100644 --- a/docs/api/touch-bar-spacer.md +++ b/docs/api/touch-bar-spacer.md @@ -2,7 +2,8 @@ > Create a spacer between two items in the touch bar for native macOS applications -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### `new TouchBarSpacer(options)` diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 12b0dd74608e..9e0e6e006694 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -49,7 +49,8 @@ Returns `WebContents` | undefined - A WebContents instance with the given ID, or > Render and control the contents of a BrowserWindow instance. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### Instance Events diff --git a/docs/api/web-frame-main.md b/docs/api/web-frame-main.md index b0460c1713b2..f4b974a649d3 100644 --- a/docs/api/web-frame-main.md +++ b/docs/api/web-frame-main.md @@ -68,7 +68,8 @@ or `undefined` if there is no WebFrameMain associated with the given IDs. ## Class: WebFrameMain -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ ### Instance Methods diff --git a/docs/api/web-request.md b/docs/api/web-request.md index 6ab12dad8287..cf25ff634b0f 100644 --- a/docs/api/web-request.md +++ b/docs/api/web-request.md @@ -2,7 +2,8 @@ > Intercept and modify the contents of a request at various stages of its lifetime. -Process: [Main](../glossary.md#main-process) +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ Instances of the `WebRequest` class are accessed by using the `webRequest` property of a `Session`. diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md index 478c854fc7a7..29753e4bcb7f 100644 --- a/docs/api/webview-tag.md +++ b/docs/api/webview-tag.md @@ -18,7 +18,8 @@ more information see the [BrowserWindow constructor docs](browser-window.md). > Display external web content in an isolated frame and process. -Process: [Renderer](../glossary.md#renderer-process) +Process: [Renderer](../glossary.md#renderer-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ Use the `webview` tag to embed 'guest' content (such as web pages) in your Electron app. The guest content is contained within the `webview` container. diff --git a/package.json b/package.json index a2b5fc7dc833..4629653601e9 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,8 @@ "repository": "https://github.com/electron/electron", "description": "Build cross platform desktop apps with JavaScript, HTML, and CSS", "devDependencies": { - "@electron/docs-parser": "^0.11.0", - "@electron/typescript-definitions": "^8.9.0", + "@electron/docs-parser": "^0.12.1", + "@electron/typescript-definitions": "^8.9.4", "@octokit/auth-app": "^2.10.0", "@octokit/rest": "^18.0.3", "@primer/octicons": "^10.0.0", @@ -143,4 +143,4 @@ "node script/gen-hunspell-filenames.js" ] } -} \ No newline at end of file +} diff --git a/spec-main/api-ipc-spec.ts b/spec-main/api-ipc-spec.ts index a67372bcd8d6..5b3963cc4a55 100644 --- a/spec-main/api-ipc-spec.ts +++ b/spec-main/api-ipc-spec.ts @@ -449,7 +449,7 @@ describe('ipc module', () => { }); }); - const generateTests = (title: string, postMessage: (contents: WebContents) => typeof WebContents.prototype.postMessage) => { + const generateTests = (title: string, postMessage: (contents: WebContents) => WebContents['postMessage']) => { describe(title, () => { it('sends a message', async () => { const w = new BrowserWindow({ show: false, webPreferences: { nodeIntegration: true, contextIsolation: false } }); diff --git a/yarn.lock b/yarn.lock index 0d5921d22df6..dc1e808340e0 100644 --- a/yarn.lock +++ b/yarn.lock @@ -18,10 +18,10 @@ esutils "^2.0.2" js-tokens "^4.0.0" -"@electron/docs-parser@^0.11.0": - version "0.11.0" - resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.11.0.tgz#182a9732d2fc7b40e3f506d3ab1a06270cdae6e4" - integrity sha512-i+OSWXXchoKVorR6cANqPKYJ1ccLAp+YCPTB+IJVWZ+Xtp6V2VXqLsjoy4mD32ss4CdX/6MLX62pb2sjGmmR6w== +"@electron/docs-parser@^0.12.1": + version "0.12.1" + resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.12.1.tgz#254c324b5953c67cdcce0a8902736778a1788742" + integrity sha512-E9/GjNVlFzBM2MNOoLjiKSE0xAMM3KsxvzMKmMeORY7aDbalObFm23XCh8DC8Jn/hfh6BzgVPF3OZO9hKvs5nw== dependencies: "@types/markdown-it" "^10.0.0" chai "^4.2.0" @@ -33,10 +33,10 @@ ora "^4.0.3" pretty-ms "^5.1.0" -"@electron/typescript-definitions@^8.9.0": - version "8.9.0" - resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.9.0.tgz#4a446ef875b55f6d3736df2a33bb19257b8146aa" - integrity sha512-26ze33/Ip2ivpCMHGRMLR+Dcm7DLNzPJL0iLJNonqPu2ikqnwJce1d2vkTDBBLzAiqUV3litVNTpnNS2Zg42MA== +"@electron/typescript-definitions@^8.9.4": + version "8.9.4" + resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.9.4.tgz#ec5c47aad3d45f2da2c40e22536720a9de64c2aa" + integrity sha512-KL3ohLe4D5lhJagBEj1Jpoh4BBiJMoCMlc6RSLPT+DaP0odgjEK+Ky6whRDW1cDDpgaSfMisdbN+CdOx3Y7JOg== dependencies: "@types/node" "^11.13.7" chalk "^2.4.2"