kcpjs

| English | 简体中文 |

A pure JavaScript implementation of KCP (KCP Protocol) with FEC (Forward Error Correction) and encryption support.

---

Features

• Pure JavaScript Implementation: No native dependencies
• FEC Support: Reed-Solomon error correction
• Encryption Support: AES-GCM encryption
• TypeScript Support: Full type definitions
• High Performance: Optimized for real-time communication

Compared to node-kcp-x, this implementation adds two key features:

1. FEC (Forward Error Correction): Improves reliability over unreliable networks
2. Encryption: Secure data transmission

---

Installation

npm install kcpjs

---

Quick Start

Example 1: Echo Server

ts-node examples/echo.ts

Example 2: Client-Server Communication

# Terminal 1
ts-node examples/server.ts

# Terminal 2
ts-node examples/client.ts

---

API Reference

Server

ListenWithOptions(options)

Creates a KCP server listener

Parameters:

Parameter	Type	Description
port	number	Server port
block	CryptBlock | undefined	Encryption module
dataShards	number	FEC data shards
parityShards	number	FEC parity shards
callback	(session: Session) => void	Client connection callback

Client

DialWithOptions(options)

Creates a KCP client connection

Parameters:

Parameter	Type	Description
host	string	Server address
port	number	Server port
conv	number	Session ID
block	CryptBlock | undefined	Encryption module
dataShards	number	FEC data shards
parityShards	number	FEC parity shards

---

Usage Examples

Basic Server

import { ListenWithOptions } from 'kcpjs';

const server = ListenWithOptions({
    port: 22333,
    callback: (session) => {
        console.log('New client connected');

        session.on('recv', (data: Buffer) => {
            // Echo back received data
            session.write(data);
        });
    },
});

Basic Client

import { DialWithOptions } from 'kcpjs';

const session = DialWithOptions({
    host: '127.0.0.1',
    port: 22333,
    conv: 255,
});

session.on('recv', (data: Buffer) => {
    console.log('Received:', data.toString());
});

// Send data
setInterval(() => {
    const message = Buffer.from('Hello from client');
    session.write(message);
}, 1000);

---

Configuration

FEC (Forward Error Correction)

FEC helps recover lost packets without retransmission

• FEC is disabled by default
• dataShards: Number of data shards
• parityShards: Number of parity shards
• Set either to 0 to disable FEC

Window Limits

session.setWindowSize(sndwnd, rcvwnd) controls the KCP send and receive windows. Values above IKCP_WND_SND_MAX or IKCP_WND_RCV_MAX are clamped to the exported hard limits to keep per-session memory bounded.

Encryption

Supports AES-GCM encryption

• Encryption is disabled by default
• algorithm: Cipher algorithm (e.g., 'aes-128-gcm')
• key: Encryption key
• Each encrypted packet carries a unique authenticated nonce generated by AesBlock
• The former constructor iv argument is accepted for source compatibility but is no longer used
• Omit block to disable encryption

The per-packet nonce format is not wire-compatible with releases that reused the constructor IV.

---

Development

Build

yarn build

Format

yarn format

Lint

yarn lint

---

License

MIT License

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Related Projects

• kcp-go - Original KCP implementation in Go
• node-kcp-x - Basic Node.js KCP implementation