electron-ebt v1.1.0
electron-ebt
A module that provides interaction between two IPC clients (ipcMain, browserContents, or ipcRendering) with the ability to confirm sending a message or prevent sending. Facilitates communication between windows.
install
npm i --save electron-ebt
usage
initialization
const EBT = require('electron-ebt')
initializing process/window (main/renderer process):
// main process
const { BrowserWindow, ipcMain } = require('electron')
// renderer process
const { remote: { BrowserWindow, ipcMain } } = require('electron')
const EBT = require('electron-ebt')
const win = new BrowserWindow(...)
const ebt = new EBT()
ebt.initialize({
name: 'test_win',
sender: win.webContents,
listener: ipcMain // default value for main process
}, params /* Object, optional */)
target window (renderer process):
const { ipcRenderer } = require('electron')
const EBT = require('electron-ebt')
const ebt = new EBT()
ebt.initialize({
name: 'test_win',
sender: ipcRenderer, // default value for renderer process
listener: ipcRenderer // default value for renderer process
}, params /* Object, optional */)
for target window, it is not necessary to specify a
sender
andlistener
.
Alternative initialization:
ebt.initialize('test_win')
init data (first argument):
name | type | desription | default |
---|---|---|---|
name | String | It is with this name that all messages will be sent. | null |
sender | Object | The send method of this object will be used to send messages. | ipcRenderer for renderer process. null fo main process |
listener | Object | Receiving messages will be through this object | ipcRenderer for renderer process. ipcMain for renderer process |
Params:
name | type | desription | default |
---|---|---|---|
confirmTimeout | Number | Waiting for a response if failure is not a Promise. At the expiration of the specified time, an exception will be thrown | 2000 |
waitConfirmTimeout | Number | Waiting for a response if failure is a Promise. At the expiration of the specified time, an exception will be thrown. | 30000 |
Reset handlers:
ebt.reinitialize()
sending message
method EBT.prototype.send returns Promise
The first argument will go everywhere callbacks object events.
The class of the event object can be obtained:
const { EBTEvent } = require('electron-ebt')
sending:
try {
const res = await ebt.send('test' /*event name*/, {} /*data*/)
console.log(res) // answer
} catch(e) {
console.error(e) // answer error
}
prevent sending a message
Before sending a message, an event with prefix
pre:
will be triggered.ebt.on('pre:test', event => { console.log(event.initiator) // true console.log(event.defaultPrevented) // false if (event.data.a === 1) event.preventDefault() console.log(event.defaultPrevented) // true })
try { await ebt.send('test', { a: 1 }) } catch(error) { console.log(error) // Error: Event test has been prevented console.log(error.prevented) // true }
### Message processing upon receipt:
Upon receipt of the message, it is possible to return the result along with confirmation
***target:***
```js
ebt.on('test', (event, data) => {
// event.data === data
console.log(data) // { a: 1 }
event.setResult({ b: 2 })
})
sender
const res = await ebt.send('test', { a: 1 })
console.log(res) // { b: 2 }
EBTEvent()
All handlers receive the first argument an instance of this object.
methods and properties
name | type | desription | params | returns |
---|---|---|---|---|
data | Object | The data transmitted by the sender | {} | |
initiator | Boolean | Returns a true if the message is initiated (send method is called) by the current object | false | |
defaultPrevented | Boolean | Whether method preventDefault was previously called or not | false | |
isPromise | Function | Do I have to wait for completion of the promises before getting the result | false | |
isError | Function | Has an Error object been added | false | |
getResult | Function | Result Already Installed | Object | |
setResult | Function | Setting result | Object | |
getPromises | Function | Returns a Promise that will end when the previously installed Promises are completed. | Promise |
EBTEvent.prototype.getResult()
{
result: {},
error: null, // or Error('')
prevented // === event.defaultPrevented
}
EBTEvent.prototype.setResult()
Takes one argument that can match the types:
Object, Error, Promise, Function
Object: Each established result supplements that which has been established earlier.
// TARGET
ebt.on('test', event => event.setResult({ a: 1 }))
ebt.on('test', event => event.setResult({ b: 2 }))
/*...*/
// SENDER
console.log(await ebt.send('test')) // { a: 1, b: 2 }
Error: The error is set once. After installing the error, only promise can be transmitted. Object and Error are no longer accepted.
// TARGET
ebt.on('test', event => event.setResult(new Error('test event error №1')))
ebt.on('test', event => event.setResult({ a: 1 }))
ebt.on('test', event => event.setResult(new Error('test event error №2')))
/*...*/
// SENDER
try {
await ebt.send('test')
} catch(error) {
console.error(error) // Error: test event error №1
}
Promise: Target will wait for all promises to be completed before sending confirmation.
// TARGET
ebt.on('test', event => event.setResult(new Promise(resolve => {
setTimeout(resolve, 1500)
})))
/*...*/
// SENDER
console.time('t')
await ebt.send('test')
console.timeEnd('t') // ~1500ms
Setting the result is possible both by returning the data and by calling event.setResult()
// TARGET
ebt.on('test', event => event.setResult(new Promise(resolve => {
resolve({ a: 1 })
})))
ebt.on('test', event => event.setResult(new Promise(resolve => {
event.setResult({ b: 2 })
resolve()
})))
/*...*/
// SENDER
console.log(await ebt.send('test')) // { a: 1, b: 2 }
// TARGET
ebt.on('test', event => event.setResult(new Promise((resolve, reject) => {
reject(new Error('test error'))
})))
/*...*/
// SENDER
try {
await ebt.send('test')
} catch(error) {
console.error(error) // Error: test error
}
// TARGET
ebt.on('test', event => event.setResult(new Promise(resolve => {
event.setResult(new Error('test error'))
resolve()
})))
/*...*/
// SENDER
try {
await ebt.send('test')
} catch(error) {
console.error(error) // Error: test error
}
If the wait exceeds the one set in params.waitConfirmTimeout during initialization, sending the message will fail.
// TARGET
ebt.on('test', event => event.setResult(new Promise(resolve => {
setTimeout(resolve, 40000)
})))
/*...*/
// SENDER
ebt.initialize({/*...*/}, {
waitConfirmTimeout: 30000
})
try {
await ebt.send('test')
} catch(error) {
console.error(error) // Error: Callback time expired [test] [30000ms]
}
Function: The result of the event will get the result of the function.
// set result
ebt.on('test', event => event.setResult(() => {
return { a: 1 }
}))
// set error
ebt.on('test', event => event.setResult(() => {
return new Error('test error')
}))
ebt.on('test', event => event.setResult(() => {
throw new Error('test error')
}))
// set promise
ebt.on('test', event => event.setResult(() => {
return new Promise(/* ... */)
}))
ebt.on('test', event => event.setResult( async () => {
await sleep(1000)
}))