electron-promise-ipc

Run IPC calls with a promise API.

Usage no npm install needed!

<script type="module">
  import electronPromiseIpc from 'https://cdn.skypack.dev/electron-promise-ipc';
</script>

README

electron-promise-ipc

Build Status Coverage Status npm version

Promise-y IPC calls in Electron.

Installation

npm install --save electron-promise-ipc

Usage

The most common use case: from the renderer, get data from the main process as a promise.

// in main process
import promiseIpc from 'electron-promise-ipc';
import fsp from 'fs-promise';

promiseIpc.on('writeSettingsFile', (newSettings, event) => {
  return fsp.writeFile('~/.settings', newSettings);
});

// in renderer
import promiseIpc from 'electron-promise-ipc';

promiseIpc
  .send('writeSettingsFile', '{ "name": "Jeff" }')
  .then(() => console.log('You wrote the settings!'))
  .catch((e) => console.error(e));

You can also send data from the main process to a renderer, if you pass in its WebContents object.

// in main process
import promiseIpc from 'electron-promise-ipc';

promiseIpc
  .send('getRendererData', webContentsForRenderer)
  .then((rendererData) => console.log(rendererData))
  .catch((e) => console.error(e));

// in renderer
import promiseIpc from 'electron-promise-ipc';

promiseIpc.on('getRendererData', (event) => {
  return getSomeSuperAwesomeRendererData();
});

Any arguments to send() will be passed directly to the event listener from on(), followed by the IPC event 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.

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.

Preload

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 script when opening a BrowserWindow. Preload scripts can access builtins such as require even if nodeIntegration is disabled.

For convenience, this library provides a preload script which you can require that sets window.promiseIpc.

// preload.js
require('electron-promise-ipc/preload');

Advanced usage

Timeouts

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:

// main process code remains the same
import promiseIpc from 'electron-promise-ipc';

promiseIpc.on('someRoute', () => {
  return someOperationThatNeverCompletesUhOh();
});

// in renderer - timeout is specified on the side that requests the data
import { PromiseIpc } from 'electron-promise-ipc';

const promiseIpc = new PromiseIpc({ maxTimeoutMs: 2000 });

promiseIpc
  .send('someRoute', '{ "name": "Jeff" }')
  .then(() => console.log('You wrote the settings!'))
  .catch((e) => console.error(e)); // will error out after 2 seconds

Removing Listeners

You can remove a listener with the off() method. It's aliased to removeListener() as well.

import promiseIpc from 'electron-promise-ipc';

promiseIpc.on('someRoute', () => {
  return something();
});

promiseIpc.off('someRoute'); // never mind

License

MIT