axaptional
electron-ipc
An easy-to-use symmetric wrapper around Electron's IPC API
Note: This package is still a work in progress and should not be used in any projects yet, let alone any production environments.
Features
This package allows you to use a normalized, symmetric API for IPC. This means that both the client and server APIs can be used as if they were exactly the same.
The following means of asynchronous communication are currently supported:
- listeners / callbacks
- native Promises (ES2015+)
- custom Promises (like
bluebird)
Installation
Use npm to install @axaptional/electron-ipc:
$ npm install @axaptional/electron-ipcExtensions
Cancelable Promises
If you want to use cancelable Promises, install a Promise library like
bluebird supporting this feature,
then register your Promise constructor with
any-promise like this:
require('any-promise/register/bluebird');
// or
import 'any-promise/register/bluebird';You will need to register your custom Promise constructor in both the main and
the renderer process in order to use canceling in both.
any-promise is automatically installed since it is a dependency of this
package.
Observables
The extension package for Observable support is not available yet.
If you want to use Observables, install
@axaptional/electron-ipc-rx.
This package will add $-postfix counterparts to most methods,
e.g. post$(...).
Keep in mind that you will need to adjust your imports when switching from
electron-ipc.
Usage
Post messages and receive responses
Probably one of the most prominent use cases is that you want to initiate a main process function from the renderer process and do something with the result of that function in the renderer process.
Renderer Process
import { Client } from '@axaptional/electron-ipc';
const client = new Client();
client.post('message', 'this').then(response => {
console.log(response); // Prints "And here is the reply to this"
});Main Process
import { BrowserWindow } from 'electron';
import { Server } from '@axaptional/electron-ipc';
const myWindow = new BrowserWindow();
// ...
const server = new Server(myWindow.webContents);
server.on('message', message => {
return `And here is the reply to ${message}`;
});Posting from main and responding from renderer
If you want to use IPC in the other direction, you can:
The APIs for Client and Server are exactly the same.
For example, you can also post a message from the main process to the
renderer process, then use on/once to respond back.
In the above code, you could just swap all lines after the
Client and Server initializations to do just that.
Serialization
Since Promises can only resolve to one value and to keep consistency, only single-object messages can be posted and received.
However, you may wrap your data in an array or object literal to post multiple values, then use parameter destructuring on the receiving end, like so:
client.post('message', ['one', 'two']).then(({ success, text }) => {
if (success) {
console.log(text);
}
});Keep in mind that any data passed will automatically be serialized to JSON by Electron. This means that values such as functions and classes cannot be passed.
Also be aware that objects received by responses via post or through channels
via on or once will have all class prototype information stripped.
Methods
For short explanations on available methods, see Methods.
For the code documentation, see Documentation.
License
This package is available under the MIT license.