npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

capacitor-tcp-socket

v8.0.0

Published

A TCP Socket Plugin for capacitor

Readme

capacitor-tcp-socket

Native TCP byte-stream clients and servers for Capacitor on iOS and Android. Thanks to @ottimis.

Installation

npm install capacitor-tcp-socket@^8
npx cap sync

Supports Capacitor 7 and 8, CocoaPods and Swift Package Manager. The example uses Capacitor 8 (Node 22+, JDK 21, Android SDK 36, Xcode 26+). SPM requires iOS 15+. Host applications must also meet their Capacitor version's platform requirements. For a new SPM app: npx cap add ios --packagemanager SPM, then npx cap sync ios. The Swift package product is CapacitorTcpSocket. The iOS implementation uses Apple Network.framework.

Socket behavior

| Operation or condition | Behavior | | --- | --- | | Read/accept/connect timeout | Rejects with TIMEOUT; default 10 whole seconds | | Timeout zero | Waits indefinitely; negative/fractional/nonfinite values are invalid | | Peer finishes sending | Read rejects EOF; sending can continue if the peer still receives | | Local disconnect | Pending I/O and later send/read reject CLOSED | | Empty send | Successful no-op on an open client | | Hex | Complete bytes only; whitespace and one leading 0x prefix are accepted | | Base64 | Canonical standard padded Base64; malformed data is rejected | | Invalid UTF-8 on read | Base64 result with encoding: 'base64' | | Concurrent operations | FIFO reads and FIFO writes per client; the two directions progress independently | | Closing issued handles | disconnect/closeServer are idempotent; unknown handles reject INVALID_ARGUMENT | | Browser | All TCP methods reject UNIMPLEMENTED; payloads are not logged by the plugin |

read returns up to expectLen bytes (default 1024, at most 64 KiB per result), not a complete application message. Call it repeatedly and assemble your protocol's frames. A successful read contains data; EOF and timeout are errors, never empty success results. Queued read timeouts start when that read begins. Use a positive timeout for periodic waiting; use disconnect to cancel an indefinite read.

Network routes, DNS, OS diagnostics, local-network permissions and background execution depend on the operating system. TCP packet boundaries and scheduling may vary between devices. For arbitrary binary data, use Hex or Base64. Even valid UTF-8 text may be split inside a multibyte character by TCP; assemble bytes and use a streaming decoder if your protocol requires streaming text.

Client usage

import { TcpSocket, DataEncoding } from 'capacitor-tcp-socket';

const { client } = await TcpSocket.connect({
  ipAddress: '192.168.1.100', port: 9100, timeout: 10,
});
try {
  await TcpSocket.send({ client, data: 'Hello', encoding: DataEncoding.UTF8 });
  // One chunk, not necessarily a whole response. Frame/assemble as required.
  const chunk = await TcpSocket.read({ client, expectLen: 4096, timeout: 10,
    encoding: DataEncoding.BASE64 });
  const bytes = Uint8Array.from(atob(chunk.result), c => c.charCodeAt(0));
  // Process bytes according to the application's protocol.
} finally {
  await TcpSocket.disconnect({ client });
}

Server usage

import { TcpSocket } from 'capacitor-tcp-socket';

const { server, port } = await TcpSocket.listen({ ipAddress: '127.0.0.1', port: 0 });
try {
  const { client } = await TcpSocket.accept({ server, timeout: 10 });
  try {
    await TcpSocket.send({ client, data: 'hello from server' });
  } finally {
    await TcpSocket.disconnect({ client });
  }
} finally {
  await TcpSocket.closeServer({ server });
}

Listening defaults to loopback and an OS-assigned port. Use 0.0.0.0 explicitly for LAN clients. Only one accept may be pending per server (BUSY otherwise). Closing a listener rejects pending accepts with CLOSED and preserves accepted clients. Pending unaccepted connections are bounded by listener backlog; excess connections may be refused by the OS. Plugin destruction closes owned sockets.

For iOS LAN access, add NSLocalNetworkUsageDescription to the host Info.plist and grant local-network access. Bonjour declarations are only needed for actual Bonjour browsing/advertising. A phone's localhost is not the development Mac. Android's INTERNET permission is included by manifest merging.

Errors

Use error.code, not OS-dependent message text:

| Code | Meaning | | --- | --- | | INVALID_ARGUMENT | Invalid options, encoding, data representation or unknown handle | | TIMEOUT | Connect, read or accept deadline elapsed | | EOF | Peer ended its sending direction | | CLOSED | Client/listener/plugin was closed locally | | BUSY | An accept is already pending on this listener | | CONNECT_FAILED | Connection establishment failed | | LISTEN_FAILED | Binding/listening failed | | IO_ERROR | Other established-connection or accept failure | | UNIMPLEMENTED | Raw TCP is unavailable in browsers |

Example and verification

See example/README.md for real device/simulator TCP tests. npm test checks the shared runtime input contract; npm run build builds the package and API docs. Native tests exercise real sockets, concurrency, cancellation, encoding, lifecycle cleanup and half-close behavior. Browser tests verify the unsupported boundary; they are not substitutes for native tests.

API

Native TCP byte-stream client and server APIs. Unsupported in browsers.

listen(...)

listen(options?: ListenOptions | undefined) => Promise<ListenResult>

Bind a local listener. Defaults to loopback and an OS-assigned port.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | ListenOptions |

Returns: Promise<ListenResult>


accept(...)

accept(options: AcceptOptions) => Promise<ConnectResult>

Accept one connection. Only one accept may be pending per listener.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | AcceptOptions |

Returns: Promise<ConnectResult>


closeServer(...)

closeServer(options: CloseServerOptions) => Promise<CloseServerOptions>

Close a listener; accepted clients remain open. Idempotent for issued IDs.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | CloseServerOptions |

Returns: Promise<CloseServerOptions>


connect(...)

connect(options: ConnectOptions) => Promise<ConnectResult>

Connect without blocking other plugin operations.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | ConnectOptions |

Returns: Promise<ConnectResult>


send(...)

send(options: SendOptions) => Promise<void>

Send all bytes, in invocation order. Empty data is a successful no-op.

| Param | Type | | ------------- | --------------------------------------------------- | | options | SendOptions |


read(...)

read(options: ReadOptions) => Promise<ReadResult>

Read up to expectLen bytes. Reads queue per client; EOF and timeout reject.

| Param | Type | | ------------- | --------------------------------------------------- | | options | ReadOptions |

Returns: Promise<ReadResult>


disconnect(...)

disconnect(options: DisconnectOptions) => Promise<DisconnectResult>

Close the client and interrupt pending I/O. Idempotent for issued IDs.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | DisconnectOptions |

Returns: Promise<DisconnectResult>


Interfaces

ListenResult

| Prop | Type | | ------------ | ------------------- | | server | number | | port | number |

ListenOptions

| Prop | Type | Description | | --------------- | ------------------- | -------------------------------------------------------------------------------- | | ipAddress | string | Local bind address; use 0.0.0.0 explicitly for LAN clients. @default "127.0.0.1" | | port | number | Local port; zero asks the OS to assign one. @default 0 |

ConnectResult

| Prop | Type | | ------------ | ------------------- | | client | number |

AcceptOptions

| Prop | Type | Description | | ------------- | ------------------- | --------------------------------------------------- | | server | number | | | timeout | number | Whole seconds; zero waits indefinitely. @default 10 |

CloseServerOptions

| Prop | Type | | ------------ | ------------------- | | server | number |

ConnectOptions

| Prop | Type | Description | | --------------- | ------------------- | --------------------------------------------------------------------------------------- | | ipAddress | string | Server IP address or hostname. | | port | number | Server port. @default 9100 | | timeout | number | Whole seconds, including connection establishment; zero waits indefinitely. @default 10 |

SendOptions

| Prop | Type | Description | Default | | -------------- | ----------------------------------------------------- | ------------------------------------------------------------- | ------------------------------ | | client | number | | | | data | string | UTF-8 text, canonical standard Base64, or complete Hex bytes. | | | encoding | DataEncoding | | DataEncoding.UTF8 |

ReadResult

| Prop | Type | | -------------- | ----------------------------------------------------- | | result | string | | encoding | DataEncoding |

ReadOptions

| Prop | Type | Description | | --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | client | number | | | expectLen | number | Maximum bytes to return, not a message size or minimum. @default 1024 | | timeout | number | Whole seconds from the start of this queued read; zero waits indefinitely. @default 10 | | encoding | DataEncoding | Invalid UTF-8 is returned as Base64 with encoding set accordingly. @default DataEncoding.UTF8 |

DisconnectResult

| Prop | Type | | ------------ | ------------------- | | client | number |

DisconnectOptions

| Prop | Type | | ------------ | ------------------- | | client | number |

Enums

DataEncoding

| Members | Value | | ------------ | --------------------- | | UTF8 | 'utf8' | | BASE64 | 'base64' | | HEX | 'hex' |