bare-tcp

bare-tcp — Native TCP sockets for JavaScript. It is a native addon and requires Bare >=1.16.0.

Mirrors the Node.js net module.

npm i bare-tcp

Usage

const tcp = require('bare-tcp')

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

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

API

TCPSocket

new TCPSocket(opts?: TCPSocketOptions)

Create a new TCP socket.

Parameters

connect

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

Connect the socket to port on host. If host is not provided, it defaults to 'localhost'. onconnect is called when the connection is established.

Parameters

Throws

• SOCKET_ALREADY_CONNECTED — the socket is already connecting or connected.
• INVALID_PORT — port is not an integer between 0 and 65535.

connecting: boolean

Whether the socket is currently connecting.

localAddress: string

The local IP address of the socket, if connected.

localFamily: string

The local IP family ('IPv4' or 'IPv6'), if connected.

localPort: number

The local port of the socket, if connected.

open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this

Open the socket on the file descriptor of an existing TCP connection, emitting 'connect' once open.

Overloads:

open(fd: number, opts?: { fd?: number }, onconnect?: () => void): this
open(fd: number, onconnect: () => void): this
open(opts: { fd: number }, onconnect?: () => void): this

Parameters

pending: boolean

Whether the socket has not yet connected.

readyState: 'open' | 'opening'

The current state of the socket. Either 'open' or 'opening'.

TCPSocket.ref(): this

Ref the socket, preventing the process from exiting.

remoteAddress: string

The remote IP address of the socket, if connected.

remoteFamily: string

The remote IP family ('IPv4' or 'IPv6'), if connected.

remotePort: number

The remote port of the socket, if connected.

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

Enable or disable keep-alive. delay is the initial delay in milliseconds before the first keep-alive probe is sent.

Overloads:

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

Parameters

setNoDelay(enable?: boolean): this

Enable or disable Nagle's algorithm. When enable is true (the default), data is sent immediately without buffering.

Parameters

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

Set a timeout in milliseconds. When the socket is idle for ms milliseconds, a timeout event is emitted. Pass 0 to disable the timeout.

Parameters

timeout: number

The timeout in milliseconds, or undefined if no timeout is set.

TCPSocket.unref(): this

Unref the socket, allowing the process to exit.

TCPServer

new TCPServer(opts?: TCPServerOptions, onconnection?: () => void)

Create a new TCP server. If onconnection is provided, it is added as a listener for the connection event.

Overloads:

new TCPServer(opts?: TCPServerOptions, onconnection?: () => void)
new TCPServer(onconnection: () => void)

Parameters

address(): TCPSocketAddress

Returns TCPSocketAddress — The bound address as { address, family, port }, or null if the server is not listening.

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

Close the server. No new connections will be accepted. The server emits close after all existing connections have ended.

Parameters

closing: boolean

Whether the server is closing.

connections: Set<TCPSocket>

A Set of active connections.

listen

listen(port?: number, host?: string, backlog?: number, opts?: TCPServerListenOptions, onlistening?: () => void): this

Start listening for connections on port and host. If port is 0, an available port is assigned. If host is not provided, it defaults to 'localhost'. backlog defaults to 511.

Parameters

Throws

• SERVER_ALREADY_LISTENING — the server is already listening.
• SERVER_IS_CLOSED — the server has been closed.
• INVALID_PORT — port is not an integer between 0 and 65535.

listening: boolean

Whether the server is listening.

maxConnections: number

The maximum number of concurrent connections; connections beyond it are destroyed and reported via the 'drop' event. Defaults to Infinity.

TCPServer.ref(): this

Ref the server, preventing the process from exiting.

TCPServer.unref(): this

Unref the server, allowing the process to exit.

Functions

createConnection

createConnection(port: number, host?: string, opts?: TCPSocketOptions & TCPSocketConnectOptions, onconnect?: () => void): TCPSocket

Create a new socket and connect it to port on host. Shorthand for new tcp.Socket(options).connect(port, host, options, onconnect).

Parameters

createServer(opts?: TCPServerOptions, onconnection?: () => void): TCPServer

Create a new TCP server. server extends <https://github.com/holepunchto/bare-events>.

Overloads:

createServer(opts?: TCPServerOptions, onconnection?: () => void): TCPServer
createServer(onconnection: () => void): TCPServer

Parameters

socketpair(): [first: number, second: number]

Create a pair of connected sockets, returning their file descriptors.

Returns [first: number, second: number] — The file descriptors of the two connected sockets.

isIP(host: string): IPFamily | 0

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

Parameters

isIPv4(host: string): boolean

Returns true if host is an IPv4 address.

Parameters

isIPv6(host: string): boolean

Returns true if host is an IPv6 address.

Parameters

Constants and variables

constants

constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    UNREFED: number
  }
}

Object containing internal state constants.

Types

TCPSocketAddress

interface TCPSocketAddress {
  address: string
  family: `IPv${IPFamily}`
  port: number
}

The address of a TCP socket, as { address, family, port }.

TCPSocketEvents

interface TCPSocketEvents extends DuplexEvents {
  connect: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
  timeout: [ms: number]
}

Events emitted by a TCPSocket.

TCPSocketOptions

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

Options for a TCPSocket.

TCPSocketConnectOptions

interface TCPSocketConnectOptions extends LookupOptions {
  lookup?: DNSLookup
  host?: string
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  noDelay?: boolean
  port?: number
  timeout?: number
}

Options for connect().

TCPServerDropInfo

interface TCPServerDropInfo {
  localAddress?: string
  localPort?: number
  localFamily?: string
  remoteAddress?: string
  remotePort?: number
  remoteFamily?: string
}

Details of a connection dropped because maxConnections was exceeded.

TCPServerEvents

interface TCPServerEvents extends EventMap {
  close: []
  connection: [socket: TCPSocket]
  drop: [info: TCPServerDropInfo]
  error: [err: Error]
  listening: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
}

Events emitted by a TCPServer.

TCPServerOptions

interface TCPServerOptions {
  allowHalfOpen?: number
  keepAlive?: boolean
  keepAliveInitialDelay?: boolean
  maxConnections?: number
  noDelay?: boolean
  pauseOnConnect?: boolean
  readBufferSize?: number
}

Options for a TCP server, applied to each incoming socket.

TCPServerListenOptions

interface TCPServerListenOptions extends LookupOptions {
  lookup?: DNSLookup
  backlog?: number
  host?: string
  port?: number
}

Options for listen().

Classes

TCPError

class TCPError {
  code: string
}

See also

• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.