# bare-tcp

<mark style="{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }">
  stable
</mark>

[`bare-tcp`](https://github.com/holepunchto/bare-tcp) — Native TCP sockets for JavaScript. It is a native addon and requires Bare `>=1.16.0`.

Mirrors the Node.js [`net`](https://nodejs.org/api/net.html) module.

```sh
npm i bare-tcp
```

## Usage [#usage]

```js
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 [#api]

### TCPSocket [#tcpsocket]

#### `new TCPSocket(opts?: TCPSocketOptions)` [#new-tcpsocketopts-tcpsocketoptions]

Create a new TCP socket.

**Parameters**

| Parameter | Type                                    | Default | Description                                                                                   |
| --------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `opts?`   | [`TCPSocketOptions`](#tcpsocketoptions) | —       | Options; `readBufferSize` defaults to `65536`, and `allowHalfOpen` and `eagerOpen` to `true`. |

#### `TCPSocket.address(): TCPSocketAddress | null` [#tcpsocketaddress-tcpsocketaddress--null]

#### `connect` [#connect]

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

| Parameter    | Type                                                  | Default | Description                                                                                                                    |
| ------------ | ----------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `port`       | `number`                                              | —       | The port to connect to.                                                                                                        |
| `host?`      | `string`                                              | —       | The host to connect to; defaults to `'localhost'`.                                                                             |
| `opts?`      | [`TCPSocketConnectOptions`](#tcpsocketconnectoptions) | —       | Connection options; if `host` is a hostname it is resolved with `opts.lookup`, which defaults to `dns.lookup` from `bare-dns`. |
| `onconnect?` | `() => void`                                          | —       | Called when the connection is established.                                                                                     |

**Throws**

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

#### `connecting: boolean` [#connecting-boolean]

Whether the socket is currently connecting.

#### `keepAlive: boolean` [#keepalive-boolean]

#### `keepAliveInitialDelay: number` [#keepaliveinitialdelay-number]

#### `localAddress: string` [#localaddress-string]

The local IP address of the socket, if connected.

#### `localFamily: string` [#localfamily-string]

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

#### `localPort: number` [#localport-number]

The local port of the socket, if connected.

#### `noDelay: boolean` [#nodelay-boolean]

#### `open(fd: number, opts?: TCPSocketOpenOptions, onconnect?: () => void): this` [#openfd-number-opts-tcpsocketopenoptions-onconnect---void-this]

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

Overloads:

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

**Parameters**

| Parameter    | Type                                            | Default | Description                                                              |
| ------------ | ----------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `fd`         | `number`                                        | —       | The file descriptor of an existing TCP connection to open the socket on. |
| `opts?`      | [`TCPSocketOpenOptions`](#tcpsocketopenoptions) | —       | `fd` may be given here instead of as the first argument.                 |
| `onconnect?` | `() => void`                                    | —       | Called once when the socket emits `'connect'`.                           |

#### `pending: boolean` [#pending-boolean]

Whether the socket has not yet connected.

#### `readyState: 'open' | 'opening' | 'readOnly' | 'writeOnly' | 'closed'` [#readystate-open--opening--readonly--writeonly--closed]

The current state of the socket.

#### `TCPSocket.ref(): this` [#tcpsocketref-this]

Ref the socket, preventing the process from exiting.

#### `remoteAddress: string` [#remoteaddress-string]

The remote IP address of the socket, if connected.

#### `remoteFamily: string` [#remotefamily-string]

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

#### `remotePort: number` [#remoteport-number]

The remote port of the socket, if connected.

#### `setKeepAlive(enable?: boolean, delay?: number): this` [#setkeepaliveenable-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:

```ts
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` [#setnodelayenable-boolean-this]

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

**Parameters**

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

#### `setTimeout(ms: number, ontimeout?: () => void): this` [#settimeoutms-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**

| 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` [#timeout-number]

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

#### `TCPSocket.unref(): this` [#tcpsocketunref-this]

Unref the socket, allowing the process to exit.

### TCPServer [#tcpserver]

#### `new TCPServer(opts?: TCPServerOptions, onconnection?: (socket: TCPSocket) => void)` [#new-tcpserveropts-tcpserveroptions-onconnection-socket-tcpsocket--void]

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

Overloads:

```ts
new TCPServer(opts?: TCPServerOptions, onconnection?: (socket: TCPSocket) => void)
new TCPServer(onconnection: (socket: TCPSocket) => void)
```

**Parameters**

| Parameter       | Type                                    | Default | Description                                                                                                                                                            |
| --------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`TCPServerOptions`](#tcpserveroptions) | —       | Options applied to each incoming socket; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, and `keepAlive`, `noDelay`, and `pauseOnConnect` to `false`. |
| `onconnection?` | `(socket: TCPSocket) => void`           | —       | Called on each `'connection'` event.                                                                                                                                   |

#### `TCPServer.address(): TCPSocketAddress | null` [#tcpserveraddress-tcpsocketaddress--null]

**Returns** [`TCPSocketAddress`](#tcpsocketaddress) | `null` — The bound address as `{ address, family, port }`, or `null` if the server is not listening.

#### `close(onclose?: () => void): this` [#closeonclose---void-this]

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

**Parameters**

| Parameter  | Type         | Default | Description                                                                             |
| ---------- | ------------ | ------- | --------------------------------------------------------------------------------------- |
| `onclose?` | `() => void` | —       | Called once when the server emits `'close'`, after all existing connections have ended. |

#### `closing: boolean` [#closing-boolean]

Whether the server is closing.

#### `connections: Set<TCPSocket>` [#connections-settcpsocket]

A `Set` of active connections.

#### `listen` [#listen]

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

| Parameter      | Type                                                | Default | Description                                                                                                                                    |
| -------------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `port?`        | `number`                                            | —       | The port to listen on; if `0` (the default), an available port is assigned.                                                                    |
| `host?`        | `string`                                            | —       | The host to listen on; defaults to `'localhost'`.                                                                                              |
| `backlog?`     | `number`                                            | —       | The maximum length of the queue of pending connections (default `511`).                                                                        |
| `opts?`        | [`TCPServerListenOptions`](#tcpserverlistenoptions) | —       | Listen options; the positional arguments may be given here instead, and `lookup` (default `dns.lookup`) resolves `host` when it is a hostname. |
| `onlistening?` | `() => void`                                        | —       | Called once when the server emits `'listening'`.                                                                                               |

**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` [#listening-boolean]

Whether the server is listening.

#### `maxConnections: number` [#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` [#tcpserverref-this]

Ref the server, preventing the process from exiting.

#### `TCPServer.unref(): this` [#tcpserverunref-this]

Unref the server, allowing the process to exit.

### Functions [#functions]

#### `createConnection` [#createconnection]

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

| Parameter    | Type                                         | Default | Description                                                         |
| ------------ | -------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `port`       | `number`                                     | —       | The port to connect to.                                             |
| `host?`      | `string`                                     | —       | The host to connect to; defaults to `'localhost'`.                  |
| `opts?`      | `TCPSocketOptions & TCPSocketConnectOptions` | —       | Options passed to both the `TCPSocket` constructor and `connect()`. |
| `onconnect?` | `() => void`                                 | —       | Called when the connection is established.                          |

#### `createServer(opts?: TCPServerOptions, onconnection?: (socket: TCPSocket) => void): TCPServer` [#createserveropts-tcpserveroptions-onconnection-socket-tcpsocket--void-tcpserver]

Create a new TCP server. `server` extends \<[https://github.com/holepunchto/bare-events>](https://github.com/holepunchto/bare-events>).

Overloads:

```ts
createServer(opts?: TCPServerOptions, onconnection?: (socket: TCPSocket) => void): TCPServer
createServer(onconnection: (socket: TCPSocket) => void): TCPServer
```

**Parameters**

| Parameter       | Type                                    | Default | Description                                                                                                                                                            |
| --------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts?`         | [`TCPServerOptions`](#tcpserveroptions) | —       | Options applied to each incoming socket; `readBufferSize` defaults to `65536`, `allowHalfOpen` to `true`, and `keepAlive`, `noDelay`, and `pauseOnConnect` to `false`. |
| `onconnection?` | `(socket: TCPSocket) => void`           | —       | Called on each `'connection'` event.                                                                                                                                   |

#### `socketpair(): [first: number, second: number]` [#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` [#isiphost-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` [#isipv4host-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` [#isipv6host-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-and-variables]

#### `constants` [#constants]

```ts
constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    CLOSED: number
    UNREFED: number
  }
  address: {
    MAX_LENGTH: number
  }
}
```

Object containing internal state constants.

### Types [#types]

#### `IPFamily` [#ipfamily]

```ts
type IPFamily = 4 | 6
```

The IP address family: `4` for IPv4 or `6` for IPv6.

#### `TCPServerDropInfo` [#tcpserverdropinfo]

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

Details of a connection dropped because `maxConnections` was exceeded.

#### `TCPServerEvents` [#tcpserverevents]

```ts
interface TCPServerEvents {
  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`.

#### `TCPServerListenOptions` [#tcpserverlistenoptions]

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

Options for `listen()`.

#### `TCPServerOptions` [#tcpserveroptions]

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

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

#### `TCPSocketAddress` [#tcpsocketaddress]

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

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

#### `TCPSocketConnectOptions` [#tcpsocketconnectoptions]

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

Options for `connect()`.

#### `TCPSocketEvents` [#tcpsocketevents]

```ts
interface TCPSocketEvents {
  connect: []
  lookup: [err: Error | null, address: string | null, family: IPFamily | 0, host: string]
  timeout: []
  data: [data: unknown]
  end: []
  readable: []
  piping: [dest: Writable]
  close: []
  error: [err: Error]
  drain: []
  finish: []
  pipe: [src: Readable]
}
```

Events emitted by a `TCPSocket`.

#### `TCPSocketOpenOptions` [#tcpsocketopenoptions]

```ts
interface TCPSocketOpenOptions {
  fd?: number
  keepAlive?: boolean | number
  keepAliveInitialDelay?: number
  noDelay?: boolean
  timeout?: number
}
```

#### `TCPSocketOptions` [#tcpsocketoptions]

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

Options for a `TCPSocket`.

### Classes [#classes]

#### `TCPError` [#tcperror]

```ts
class TCPError {
  code: string
}
```

An error produced by `bare-tcp`; `code` identifies the failure.

## `bare-tcp/constants` [#bare-tcpconstants]

### Constants and variables [#constants-and-variables-1]

#### `constants.constants` [#constantsconstants]

```ts
constants: {
  state: {
    CONNECTING: number
    CONNECTED: number
    BINDING: number
    BOUND: number
    READING: number
    CLOSING: number
    CLOSED: number
    UNREFED: number
  }
  address: {
    MAX_LENGTH: number
  }
}
```

Object containing internal state constants.

## `bare-tcp/errors` [#bare-tcperrors]

### Classes [#classes-1]

#### `errors.TCPError` [#errorstcperror]

An error produced by `bare-tcp`; `code` identifies the failure.

## See also [#see-also]

* Builds on `bare-dns`, `bare-events`, and `bare-stream`.
* Sockets are [`bare-stream`](/bare/reference/bare/modules/bare-stream) duplex streams.
* [Bare modules](/bare/reference/bare/modules) — the full `bare-*` catalog.
* [Bare runtime API](/bare/reference/bare/runtime) — the runtime these modules extend.