Introduction

Child process message communication module. Provides the ability for child processes (created via child_process.fork) to send messages to the main process, serving as the core implementation of the framework's IPC communication mechanism on the child process side.

Child processes cannot directly access Electron's ipcRenderer/ipcMain, so they communicate with the main process via Node.js built-in process.send() method. The main process receives and dispatches these messages by listening to the child process's message event.

Message format follows the framework's unified IPC protocol:

{
  channel: string,       // Communication channel, e.g. 'ee#sendToMain'
  eventReceiver: string, // Receiver type, e.g. 'job' / 'task'
  event: string,         // Event name
  data: object           // Event data
}

The module exports both the ChildMessage class (for custom instantiation) and a childMessage singleton (for direct use in child process code).

Import

Both CJS and ESM:

// ESM
import { ChildMessage, childMessage } from 'ee-core/message';
// CJS
const { ChildMessage, childMessage } = require('ee-core/message');

From the main entry:

// ESM
import { ChildMessage, childMessage } from 'ee-core';
// CJS
const { ChildMessage, childMessage } = require('ee-core');

API

ChildMessage

Description: Child process message communication class. Encapsulates methods for child processes to send messages to the main process, distinguishing different receiver types (ChildJob vs ForkProcess). This class runs in the child process environment, relies on process.send() for communication, and returns false if the current process does not support process.send (non-forked process). Can be instantiated directly for custom scenarios, or use the pre-created childMessage singleton.
Parameters: None (class constructor has no parameters)
Returns: ChildMessage — New instance of the child message communication class
Example:

// Create a custom instance
const myMessenger = new ChildMessage();
myMessenger.sendToMain('customEvent', { data: 42 });

// Or use the singleton
childMessage.sendToMain('taskComplete', { result: 42 });

See also: childMessage singleton, Receiver constants

childMessage

Description: Pre-created singleton instance of ChildMessage. Ready for direct use in child process code without instantiation. All ChildMessage methods are available on this singleton.
Parameters: None (this is a pre-created singleton instance)
Returns: ChildMessage — Singleton child message instance
Example:

const { childMessage } = require('ee-core/message');

// Send to ChildJob handler in main process
childMessage.sendToMain('job-timer-progress', { jobId, number: 0 });

// Send to Fork process handler in main process
childMessage.send('dataReady', { items: [1, 2, 3] });

// Report an error
childMessage.sendErrorToTerminal(new Error('Task processing failed'));

// Exit the child process
childMessage.exit(0);

sendToMain(eventName, params)

Description: Send a message to the ChildJob instance in the main process. Uses Receiver.childJob ('job') as the receiver type. After the main process receives the message, it routes the event to the corresponding ChildJob handler (listened via myjob.on()).
Parameters: | Parameter | Type | Required | Description |
| eventName | string | Yes | Event name, the main process dispatches to the corresponding ChildJob handler based on this |
| params | Record<string, unknown> | No | Event parameters, defaults to {} |
Returns: boolean — Returns true if sent successfully, false if the current process does not support process.send (non-forked process)
Example:

// Listen in main process
myjob.on('job-timer-progress', (data) => {
  console.log('Progress:', data.number);
});

// Send in child process
const { childMessage } = require('ee-core/message');
childMessage.sendToMain('job-timer-progress', { jobId, number: 5 });

See also: Receiver.childJob, ChildJob

send(eventName, params, receiver)

Description: Send a message to the main process (generic method). Constructs a message object conforming to the framework's IPC protocol and sends it via process.send(). If no receiver is specified, defaults to Receiver.forkProcess ('task'), routing the message to the ForkProcess handler (listened via task.emitter.on()).
Parameters: | Parameter | Type | Required | Description |
| eventName | string | Yes | Event name |
| params | Record<string, unknown> | No | Event parameters, defaults to {} |
| receiver | string | No | Receiver type: 'job' for ChildJob-type child process, 'task' for Fork process (generic task). Defaults to 'task' |
Returns: boolean — Returns true if sent successfully, false if the current process does not support process.send
Example:

// Listen in main process (Fork task)
const timerTask = myJob.exec('./jobs/example/timer', { jobId });
timerTask.emitter.on('job-timer-progress', (data) => {
  console.log('Task progress:', data);
});

// Send in child process (default receiver: 'task')
childMessage.send('job-timer-progress', { jobId, number: 0, pid: 0 });

// Send to ChildJob handler explicitly
childMessage.send('customEvent', { result: 42 }, 'job');

See also: Receiver.forkProcess, Receiver.childJob, sendToMain

exit(code)

Description: Exit the current child process. Calls process.exit() with the specified code, terminating the child process immediately. This method never returns normally.
Parameters: | Parameter | Type | Required | Description |
| code | number | No | Exit code, defaults to 0 (normal exit) |
Returns: never — Never returns (process.exit terminates the process)
Example:

// Normal exit after task completion
childMessage.exit(0);

// Exit with error code
childMessage.exit(1);

sendErrorToTerminal(err)

Description: Send error information to the main process and display an exception dialog in the renderer process. Sends via the Processes.showException ('ee#showException') channel. After the main process receives it, it forwards to the renderer process via IPC, which displays a dialog with the error information. The error message includes a tip guiding the user to check the log file for details.
Parameters: | Parameter | Type | Required | Description |
| err | Error | Yes | Error object to be forwarded |
Returns: boolean — Returns true if sent successfully, false if the current process does not support process.send
Example:

try {
  // Some task processing that may fail
  processData();
} catch (err) {
  // Forward error to main process for display
  childMessage.sendErrorToTerminal(err);
  // Error message shown: "Error: processData failed Error !!! Please See file ee-core.log or ee-error-xxx.log for details !"
  childMessage.exit(1);
}

See also: Processes.showException