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`.

`_destroy(err: Error | null, cb: StreamCallback): void`

Parameters

Parameter	Type	Default	Description
`err`	`Error` \| `null`	—	—
`cb`	`StreamCallback`	—	—

`_final(cb: StreamCallback): void`

Parameters

Parameter	Type	Default	Description
`cb`	`StreamCallback`	—	—

`_open(cb: StreamCallback): void`

Parameters

Parameter	Type	Default	Description
`cb`	`StreamCallback`	—	—

`_predestroy(): void`

`_read(size: number): void`

Parameters

Parameter	Type	Default	Description
`size`	`number`	—	—

`_write(data: unknown, encoding: StreamEncoding, cb: StreamCallback): void`

Parameters

Parameter	Type	Default	Description
`data`	`unknown`	—	—
`encoding`	`StreamEncoding`	—	—
`cb`	`StreamCallback`	—	—

`_writev(batch: { chunk: unknown; encoding: StreamEncoding }[], cb: StreamCallback): void`

Parameters

Parameter	Type	Default	Description
`batch`	`{ chunk: unknown; encoding: StreamEncoding }[]`	—	—
`cb`	`StreamCallback`	—	—

`closed: boolean`

`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.

`cork(): void`

`destroy(err?: Error | null): void`

Parameters

Parameter	Type	Default	Description
`err?`	`Error` \| `null`	—	—

`destroyed: boolean`

`destroying: boolean`

`end(cb?: StreamCallback): this`

Overloads:

end(cb?: StreamCallback): this
end(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): this
end(data: unknown, cb?: StreamCallback): this

Parameters

Parameter	Type	Default	Description
`cb?`	`StreamCallback`	—	—

`errored: Error | null`

`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.

`pause(): this`

`pending: boolean`

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

`pipe<S extends Writable>(dest: S, cb?: StreamCallback): S`

Parameters

Parameter	Type	Default	Description
`dest`	`S`	—	—
`cb?`	`StreamCallback`	—	—

`push(data: unknown | null, encoding?: BufferEncoding): boolean`

Parameters

Parameter	Type	Default	Description
`data`	`unknown` \| `null`	—	—
`encoding?`	`BufferEncoding`	—	—

`read(): unknown | null`

`readable: boolean`

`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.

`resume(): this`

`setEncoding(encoding: BufferEncoding): void`

Parameters

Parameter	Type	Default	Description
`encoding`	`BufferEncoding`	—	—

`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.

`uncork(): void`

`NetSocket.unref(): this`

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

`unshift(data: unknown | null, encoding?: BufferEncoding): boolean`

Parameters

Parameter	Type	Default	Description
`data`	`unknown` \| `null`	—	—
`encoding?`	`BufferEncoding`	—	—

`writable: boolean`

`write(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): boolean`

Overloads:

write(data: unknown, encoding?: BufferEncoding, cb?: StreamCallback): boolean
write(data: unknown, cb?: StreamCallback): boolean

Parameters

Parameter	Type	Default	Description
`data`	`unknown`	—	—
`encoding?`	`BufferEncoding`	—	—
`cb?`	`StreamCallback`	—	—

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.

`addListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`addOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`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'`.

`emit<E extends keyof M>(name: E, ...args: M[E]): boolean`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`args`	`M[E]`	—	—

`eventNames(): (keyof M)[]`

`getMaxListeners(): number`

`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'`.

`listenerCount<E extends keyof M>(name: E): number`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—

`listeners<E extends keyof M>(name: E): EventHandler<M[E]>[]`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—

`listening: boolean`

true if the server is currently listening for connections.

`off<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`on<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`once<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`prependListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`prependOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`rawListeners<E extends keyof M>(name: E): EventHandler<M[E]>[]`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—

`NetServer.ref(): this`

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

`removeAllListeners<E extends keyof M>(name?: E): this`

Parameters

Parameter	Type	Default	Description
`name?`	`E`	—	—

`removeListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	—
`fn`	`EventHandler<M[E]>`	—	—

`setMaxListeners(n: number): this`

Parameters

Parameter	Type	Default	Description
`n`	`number`	—	—

`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`

Returns 4 if host is an IPv4 address, 6 if it is an IPv6 address, or 0 otherwise.

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	The string to check.

`isIPv4(host: string): boolean`

Returns true if host is an IPv4 address.

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	The string to check.

`isIPv6(host: string): boolean`

Returns true if host is an IPv6 address.

Parameters

Parameter	Type	Default	Description
`host`	`string`	—	The string to check.

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 | number
  keepAliveInitialDelay?: number
  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 {
  backlog?: number
  path?: string
  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: {
  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