bare-net

stable

bare-net — TCP and IPC servers and clients for JavaScript.

npm i bare-net

Usage

const net = require('bare-net')

const server = net.createServer()
server.on('connection', (socket) => socket.on('data', console.log))
server.listen(() => console.log('server is up'))

const { port } = server.address()
const socket = net.createConnection(port)
socket.write('hello world')

API

NetSocket

`new NetSocket(opts?: NetOptions)`

Create a NetSocket.

Parameters

Parameter	Type	Default	Description
`opts?`	`NetOptions`	—	Options; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `eagerOpen` to `false`.

`connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this`

Connect the socket to a path over IPC, or to a port/host over TCP.

Overloads:

connect(path: string, opts?: PipeConnectOptions, onconnect?: () => void): this
connect(path: string, onconnect: () => void): this
connect(port: number, host?: string, opts?: TCPSocketConnectOptions, onconnect?: () => void): this
connect(port: number, host: string, onconnect: () => void): this
connect(port: number, onconnect: () => void): this
connect(opts: NetSocketConnectOptions, onconnect?: () => void): this

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to connect to over IPC.
`opts?`	`PipeConnectOptions`	—	Connection options passed to the underlying socket; `path`, `port`, and `host` may be given here instead of as positional arguments.
`onconnect?`	`() => void`	—	Called once when the socket emits `'connect'`.

`connecting: boolean`

true while the underlying socket is in the process of connecting.

`localAddress: string`

Local IP address the socket is connected on, if connected over TCP.

`localFamily: string`

Local IP address family, if connected over TCP.

`localPort: number`

Local port the socket is connected on, if connected over TCP.

`pending: boolean`

true if the socket hasn't been assigned an underlying TCP or IPC socket yet.

`readyState: 'open' | 'readOnly' | 'writeOnly' | 'opening'`

Current connection state of the socket.

`NetSocket.ref(): this`

Reference the socket, keeping the event loop alive while it is open.

`remoteAddress: string`

Remote IP address the socket is connected to, if connected over TCP.

`remoteFamily: string`

Remote IP address family, if connected over TCP.

`remotePort: number`

Remote port the socket is connected to, if connected over TCP.

`setKeepAlive(enable?: boolean, delay?: number): this`

Enable or disable TCP keep-alive on the underlying socket.

Overloads:

setKeepAlive(enable?: boolean, delay?: number): this
setKeepAlive(delay: number): this

Parameters

Parameter	Type	Default	Description
`enable?`	`boolean`	—	Whether to enable keep-alive.
`delay?`	`number`	—	The initial delay in milliseconds before the first keep-alive probe is sent.

`setNoDelay(enable?: boolean): this`

Enable or disable Nagle's algorithm on the underlying socket.

Parameters

Parameter	Type	Default	Description
`enable?`	`boolean`	—	When `true` (the default), data is sent immediately without buffering.

`setTimeout(ms: number, ontimeout?: () => void): this`

Set the socket's inactivity timeout.

Parameters

Parameter	Type	Default	Description
`ms`	`number`	—	The inactivity timeout in milliseconds; pass `0` to disable the timeout.
`ontimeout?`	`() => void`	—	Called once when the socket emits `'timeout'`.

`timeout: number`

The socket's current inactivity timeout, in milliseconds.

`NetSocket.unref(): this`

Unreference the socket, allowing the event loop to exit while it is open.

NetServer

`new NetServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void)`

Create a NetServer, optionally registering a connection listener.

Overloads:

new NetServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void)
new NetServer(onconnection: (socket: NetSocket) => void)

Parameters

Parameter	Type	Default	Description
`opts?`	`NetOptions`	—	Options applied to each accepted socket; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `pauseOnConnect` to `false`.
`onconnection?`	`(socket: NetSocket) => void`	—	Called on each `'connection'` event.

`address(): string | TCPSocketAddress | null`

Returns the address the server is listening on, or null if it isn't listening.

`close(onclose: (err?: Error) => void): this`

Stop the server from accepting new connections.

Parameters

Parameter	Type	Default	Description
`onclose`	`(err?: Error) => void`	—	Called once when the server emits `'close'`.

`listen`

listen(path: string, backlog?: number, opts?: PipeServerListenOptions, onlistening?: () => void): this

Start the server listening on a path over IPC, or a port/host over TCP.

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to listen on over IPC.
`backlog?`	`number`	—	The maximum length of the queue of pending connections.
`opts?`	`PipeServerListenOptions`	—	—
`onlistening?`	`() => void`	—	Called once when the server emits `'listening'`.

`listening: boolean`

true if the server is currently listening for connections.

`NetServer.ref(): this`

Reference the server, keeping the event loop alive while it is listening.

`NetServer.unref(): this`

Unreference the server, allowing the event loop to exit while it is listening.

Functions

`createConnection`

createConnection(path: string, opts?: NetOptions & PipeConnectOptions, onconnect?: () => void): NetSocket

Create a NetSocket and connect it over IPC if a path is given, otherwise over TCP.

Parameters

Parameter	Type	Default	Description
`path`	`string`	—	The path to connect to over IPC.
`opts?`	`NetOptions & PipeConnectOptions`	—	Options for the socket and connection; if `path` is set the socket connects over IPC, otherwise over TCP.
`onconnect?`	`() => void`	—	Called when the connection is established.

`createServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void): NetServer`

Create a NetServer, optionally registering a connection listener.

Overloads:

createServer(opts?: NetOptions, onconnection?: (socket: NetSocket) => void): NetServer
createServer(onconnection: (socket: NetSocket) => void): NetServer

Parameters

Parameter	Type	Default	Description
`opts?`	`NetOptions`	—	Options applied to each accepted socket; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `pauseOnConnect` to `false`.
`onconnection?`	`(socket: NetSocket) => void`	—	Called on each `'connection'` event.

`isIP(host: string): IPFamily | 0`

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	—

`isIPv4(host: string): boolean`

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	—

`isIPv6(host: string): boolean`

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	—

Constants and variables

`constants`

constants: {
  type: { TCP: 1; IPC: 2 }
  state: { UNREFED: number; BINDING: number; BOUND: number }
}

Connection type and internal state flags used by sockets and servers.

Types

`NetOptions`

interface NetOptions {
  allowHalfOpen?: boolean
  eagerOpen?: boolean
  readBufferSize?: number
}

Options accepted when constructing a NetSocket or NetServer.

`NetSocketEvents`

interface NetSocketEvents {
  connect: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}

Events emitted by a NetSocket, extending the underlying duplex stream's events.

`NetSocketConnectOptions`

interface NetSocketConnectOptions {
  path?: string
  lookup?: DNSLookup
  host?: string
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}

`NetServerEvents`

interface NetServerEvents {
  close: []
  connection: [socket: NetSocket]
  error: [err: Error]
  listening: []
}

Events emitted by a NetServer.

`NetServerListenOptions`

interface NetServerListenOptions {
  path?: string
  backlog?: number
  lookup?: DNSLookup
  host?: string
  port?: number
  family?: `IPv${IPFamily}` | IPFamily | 0
  hints?: number
  all?: boolean
}

Classes

`errors`

class errors {
  code: string
}

`bare-net/constants`

Constants and variables

`constants.constants`

constants: {
  type: { TCP: 1; IPC: 2 }
  state: { UNREFED: number; BINDING: number; BOUND: number }
}

Connection type and internal state flags used by sockets and servers.

`bare-net/errors`

Classes

`NetError`

class NetError {
  code: string
}

bare-net

On this page