Koshare Router Client

A Koshare Router client implementation for browsers and Node.js

• What's Koshare Router
• Protocol Specification
• Install
  • Node.js
• API
  • prefix
• Usage
• Development
  • Install dependencies
  • Testing
  • Coverage
• License

What's Koshare Router

Koshare Router is a simple publish/subscribe protocol running on WebSocket, originally designed by @gladkikhartem.

Protocol Specification

Read here.

Install

npm i @yume-chan/koshare-router-client

Node.js

ws is a peer dependency, so you need to install it manually for Node.js.

npm install ws

API

type ForwardPacketHandler<T> = (packet: ForwardPacket<T>) => void;

export default class KoshareClient {
    static connect(endpoint: string, prefix?: string): Promise<KoshareClient>;

    subscribe<T extends object>(topic: string, handler: ForwardPacketHandler<T>): Promise<void>;

    unsubscribe(topic: string): Promise<void>;
    unsubscribe<T extends object>(topic: string, handler: ForwardPacketHandler<T>): Promise<void>;

    broadcast<T extends object>(topic: string, body?: T): Promise<void>;
    message<T extends object>(topic: string, destination: number, body?: T): Promise<void>;

    close(): void;
}

export class KoshareReconnectClient extends KoshareClient {
    static connect(endpoint: string, prefix?: string): Promise<KoshareReconnectClient>;
}

The KoshareReconnectClient will try to reconnect automatically when connection is lost.

prefix

Call connect() with prefix will append prefix to all topics automatically, helping avoid collsions with other users.

Usage

import KoshareClient from '@yume-chan/koshare-router-client';

(async () => {
    const echo = await KoshareClient.connect('wss://chensi.moe/koshare');
    await echo.subscribe('echo', async (packet) => {
        await echo.message('echo', packet.src, { ...packet, type: undefined, topic: undefined, src: undefined, dst: undefined });
    });

    const client = await KoshareClient.connect('wss://chensi.moe/koshare');
    await client.subscribe('echo', (packet) => {
        console.log(packet);
    });
    await client.broadcast('echo', { content: 'test' });

    echo.close();
    client.close();
})();

Development

This project uses pnpm (GitHub) to manage dependency packages.

Install dependencies

pnpm i

You may also use npm, but the lockfile may become out of sync.

Testing

npm test

Coverage

npm run coverage

License

MIT