@yume-chan/koshare-router-client NPM

Koshare Router Client

license npm type definitions npm bundle size

A Koshare Router client implementation for browsers and Node.js

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();
})();