1 | # electron-promise-ipc
|
2 |
|
3 | [![Build Status](https://travis-ci.org/sibnerian/electron-promise-ipc.svg?branch=master)](https://travis-ci.org/sibnerian/electron-promise-ipc) [![Coverage Status](https://coveralls.io/repos/github/sibnerian/electron-promise-ipc/badge.svg?branch=master)](https://coveralls.io/github/sibnerian/electron-promise-ipc?branch=master) [![npm version](https://badge.fury.io/js/electron-promise-ipc.svg)](https://badge.fury.io/js/electron-promise-ipc)
|
4 |
|
5 | #### Promise-y IPC calls in Electron.
|
6 |
|
7 | ## Installation
|
8 |
|
9 | ```sh
|
10 | npm install --save electron-promise-ipc
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | The most common use case: from the renderer, get data from the main process as a promise.
|
16 |
|
17 | ```js
|
18 | // in main process
|
19 | import promiseIpc from 'electron-promise-ipc';
|
20 | import fsp from 'fs-promise';
|
21 |
|
22 | promiseIpc.on('writeSettingsFile', (newSettings, event) => {
|
23 | return fsp.writeFile('~/.settings', newSettings);
|
24 | });
|
25 |
|
26 | // in renderer
|
27 | import promiseIpc from 'electron-promise-ipc';
|
28 |
|
29 | promiseIpc
|
30 | .send('writeSettingsFile', '{ "name": "Jeff" }')
|
31 | .then(() => console.log('You wrote the settings!'))
|
32 | .catch((e) => console.error(e));
|
33 | ```
|
34 |
|
35 | You can also send data from the main process to a renderer, if you pass in its [WebContents](http://electron.atom.io/docs/api/web-contents) object.
|
36 |
|
37 | ```js
|
38 | // in main process
|
39 | import promiseIpc from 'electron-promise-ipc';
|
40 |
|
41 | promiseIpc
|
42 | .send('getRendererData', webContentsForRenderer)
|
43 | .then((rendererData) => console.log(rendererData))
|
44 | .catch((e) => console.error(e));
|
45 |
|
46 | // in renderer
|
47 | import promiseIpc from 'electron-promise-ipc';
|
48 |
|
49 | promiseIpc.on('getRendererData', (event) => {
|
50 | return getSomeSuperAwesomeRendererData();
|
51 | });
|
52 | ```
|
53 |
|
54 | Any arguments to `send()` will be passed directly to the event listener from `on()`, followed by the IPC [event](https://electronjs.org/docs/api/ipc-main#event-object) object. If there is an error thrown in the main process's listener, or if the listener returns a rejected promise (e.g., lack of permissions for a file read), then the `send()` promise is rejected with the same error.
|
55 |
|
56 | Note that because this is IPC, only JSON-serializable values can be passed as arguments or data. Classes and functions will generally not survive a round of serialization/deserialization.
|
57 |
|
58 | ## Preload
|
59 |
|
60 | As of Electron 5.0, `nodeIntegration` is _disabled by default._ This means that you cannot import `promiseIpc` directly. Instead, you will need to use a [preload](https://www.electronjs.org/docs/api/browser-window) script when opening a `BrowserWindow`. Preload scripts can access builtins such as `require` even if `nodeIntegration` is disabled.
|
61 |
|
62 | For convenience, this library provides a preload script which you can require that sets `window.promiseIpc`.
|
63 |
|
64 | ```js
|
65 | // preload.js
|
66 | require('electron-promise-ipc/preload');
|
67 | ```
|
68 |
|
69 | ## Advanced usage
|
70 |
|
71 | #### Timeouts
|
72 |
|
73 | By default, the promise will wait forever for the other process to return it some data. If you want to set a timeout (after which the promise will be rejected automatically), you can create another instance of `PromiseIpc` like so:
|
74 |
|
75 | ```js
|
76 | // main process code remains the same
|
77 | import promiseIpc from 'electron-promise-ipc';
|
78 |
|
79 | promiseIpc.on('someRoute', () => {
|
80 | return someOperationThatNeverCompletesUhOh();
|
81 | });
|
82 |
|
83 | // in renderer - timeout is specified on the side that requests the data
|
84 | import { PromiseIpc } from 'electron-promise-ipc';
|
85 |
|
86 | const promiseIpc = new PromiseIpc({ maxTimeoutMs: 2000 });
|
87 |
|
88 | promiseIpc
|
89 | .send('someRoute', '{ "name": "Jeff" }')
|
90 | .then(() => console.log('You wrote the settings!'))
|
91 | .catch((e) => console.error(e)); // will error out after 2 seconds
|
92 | ```
|
93 |
|
94 | #### Removing Listeners
|
95 |
|
96 | You can remove a listener with the `off()` method. It's aliased to `removeListener()` as well.
|
97 |
|
98 | ```js
|
99 | import promiseIpc from 'electron-promise-ipc';
|
100 |
|
101 | promiseIpc.on('someRoute', () => {
|
102 | return something();
|
103 | });
|
104 |
|
105 | promiseIpc.off('someRoute'); // never mind
|
106 | ```
|
107 |
|
108 | ## License
|
109 |
|
110 | MIT
|