feat: add ipcRenderer.invoke() (#18449)

docs/api/ipc-main.md

@@ -88,7 +88,61 @@ Removes the specified `listener` from the listener array for the specified
 
 Removes listeners of the specified `channel`.
 
-## Event object
+### `ipcMain.handle(channel, listener)`
+
+* `channel` String
+* `listener` Function<Promise> | Function<any>
+  * `event` IpcMainInvokeEvent
+  * `...args` any[]
+
+Adds a handler for an `invoke`able IPC. This handler will be called whenever a
+renderer calls `ipcRenderer.invoke(channel, ...args)`.
+
+If `listener` returns a Promise, the eventual result of the promise will be
+returned as a reply to the remote caller. Otherwise, the return value of the
+listener will be used as the value of the reply.
+
+```js
+// Main process
+ipcMain.handle('my-invokable-ipc', async (event, ...args) => {
+  const result = await somePromise(...args)
+  return result
+})
+
+// Renderer process
+async () => {
+  const result = await ipcRenderer.invoke('my-invokable-ipc', arg1, arg2)
+  // ...
+}
+```
+
+The `event` that is passed as the first argument to the handler is the same as
+that passed to a regular event listener. It includes information about which
+WebContents is the source of the invoke request.
+
+### `ipcMain.handleOnce(channel, listener)`
+
+* `channel` String
+* `listener` Function<Promise> | Function<any>
+  * `event` IpcMainInvokeEvent
+  * `...args` any[]
+
+Handles a single `invoke`able IPC message, then removes the listener. See
+`ipcMain.handle(channel, listener)`.
+
+### `ipcMain.removeHandler(channel)`
+
+* `channel` String
+
+Removes any handler for `channel`, if present.
+
+## IpcMainEvent object
 
 The documentation for the `event` object passed to the `callback` can be found
 in the [`ipc-main-event`](structures/ipc-main-event.md) structure docs.
+
+## IpcMainInvokeEvent object
+
+The documentation for the `event` object passed to `handle` callbacks can be
+found in the [`ipc-main-invoke-event`](structures/ipc-main-invoke-event.md)
+structure docs.

docs/api/ipc-renderer.md

@@ -57,10 +57,39 @@ Removes all listeners, or those of the specified `channel`.
 * `...args` any[]
 
 Send a message to the main process asynchronously via `channel`, you can also
-send arbitrary arguments. Arguments will be serialized in JSON internally and
+send arbitrary arguments. Arguments will be serialized as JSON internally and
 hence no functions or prototype chain will be included.
 
-The main process handles it by listening for `channel` with [`ipcMain`](ipc-main.md) module.
+The main process handles it by listening for `channel` with the
+[`ipcMain`](ipc-main.md) module.
+
+### `ipcRenderer.invoke(channel[, arg1][, arg2][, ...])`
+
+* `channel` String
+* `...args` any[]
+
+Returns `Promise<any>` - Resolves with the response from the main process.
+
+Send a message to the main process asynchronously via `channel` and expect an
+asynchronous result. Arguments will be serialized as JSON internally and
+hence no functions or prototype chain will be included.
+
+The main process should listen for `channel` with
+[`ipcMain.handle()`](ipc-main.md#ipcmainhandlechannel-listener).
+
+For example:
+```javascript
+// Renderer process
+ipcRenderer.invoke('some-name', someArgument).then((result) => {
+  // ...
+})
+
+// Main process
+ipcMain.handle('some-name', async (event, someArgument) => {
+  const result = await doSomeWork(someArgument)
+  return result
+})
+```
 
 ### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
 

docs/api/structures/ipc-main-event.md

@@ -5,4 +5,3 @@
 * `sender` WebContents - Returns the `webContents` that sent the message
 * `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling.  You should use this method to "reply" to the sent message in order to guaruntee the reply will go to the correct process and frame.
   * `...args` any[]
-IpcRenderer

docs/api/structures/ipc-main-invoke-event.md

@@ -0,0 +1,4 @@
+# IpcMainInvokeEvent Object extends `Event`
+
+* `frameId` Integer - The ID of the renderer frame that sent this message
+* `sender` WebContents - Returns the `webContents` that sent the message