README

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 and listener.

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:

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)
}))

Usage no npm install needed!