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.