14.x Node.js contract

API reference

The event-driven Node.js surface stays small. Profile selection and parser construction happen before a client or server enters its message path.

Node.js-only JavaScript API.

The imports below load raw Node TCP, TLS, UDP, local-socket, filesystem, OS, process, and Buffer APIs. They do not run in web browsers, whether bundled or unbundled; no browser entry is published.

Imports and instances

import ipc, {IPCModule} from 'node-ipc';

// Shared singleton
ipc.config.id = 'primary';

// Independent configuration, clients, and server
const secondary = new IPCModule();
secondary.config.id = 'secondary';

Instance isolation

Each IPCModule owns its own config, of client store, and server reference.

Parser exports

import {
  RawParser,
  FastParser,
  GuardedParser,
  AssuredParser,
  IPCProtocolError
} from 'node-ipc';

import {createParser} from 'node-ipc/parsers';
import MessageParser from 'node-ipc/parsers/message';

Parser remains an alias of FastParser. MessageParser is an opt-in js-message compatibility parser, not a hardened decoder. See the parser contract.

Stores

Property	Value	Meaning
`ipc.config`	Defaults object	Configuration copied into new clients and servers.
`ipc.of`	Object	Connected or connecting clients keyed by service id.
`ipc.server`	Server or `false`	The server created by the latest `serve*` call.

Connect

`connectTo(id[, path][, callback])`

Creates a Unix-domain or Windows named-pipe client and stores it at ipc.of[id]. The default path is socketRoot + appspace + id.

ipc.connectTo('world', () => {
  ipc.of.world.on('connect', ready);
});

`connectToNet(id[, host][, port][, callback])`

Creates a TCP client, or a TLS client when ipc.config.tls is an options object. Host and port default to network configuration.

ipc.connectToNet('api', '127.0.0.1', 8000, () => {
  ipc.of.api.on('connect', ready);
});

Client operations

Member	Contract
`client.on(type, handler)`	Subscribes to lifecycle, error, data, or application events.
`client.once(type, handler)`	Runs one time, then removes the handler.
`client.off(type, handler)`	Removes a handler; `'*'` removes all in the selected scope.
`client.emit(type, data)`	Writes an application event, or a raw buffer when configured.

Serve

`serve([path][, callback])`

Creates a local socket server. Call ipc.server.start() after registering handlers.

ipc.serve(() => {
  ipc.server.on('request', handle);
});
ipc.server.start();

`serveNet([host][, port][, UDPType][, callback])`

Creates TCP or TLS by default. Pass 'udp4' or 'udp6' to create a datagram endpoint.

ipc.serveNet('127.0.0.1', 8000, ready);
ipc.server.start();

Server operations

Member	Contract
`server.start()`	Binds the configured socket and publishes `start`.
`server.stop()`	Closes the listening server.
`server.on(type, handler)`	Subscribes to lifecycle, error, data, or application events.
`server.emit(socket, type, data)`	Sends to one stream client or one UDP address/port.
`server.broadcast(type, data)`	Sends to every known socket.
`server.sockets`	Known sockets, including observed UDP peers.

Disconnect and log

`disconnect(id)`

Marks the client as explicitly disconnected, removes handlers, destroys the socket, and deletes ipc.of[id]. Missing ids are harmless.

`log(...values)`

Inspects objects and sends one joined string to the configured logger unless silent is true.

Lifecycle events

Scope	Event	Arguments
Client	`connect`	None
Client	`disconnect`	None; a retry may follow.
Client	`destroy`	None; no retry remains.
Client / server	`error`	Error object.
Raw client / server	`data`	Buffer; server also receives socket.
Server	`start`	Bound socket information.
Server	`connect`	Connected socket.
Server	`socket.disconnected`	Socket and destroyed socket id.
Both	Application event	Decoded data; server also receives socket.

Guarded and Assured reject lifecycle and Object.prototype names received on the wire. Fast does not perform that name check.

← Parser contract Examples →