rpc2-websocket-client

Fast JSON RPC 2.0 written in TypeScript.

TypeScript JSON RPC 2.0 WebSocket implementation with async-await Promises.

Description

I really lacked typescript support or type definitions of rpc-websockets. I kept everything as simple as possible for best performance and in principle stay close to the metal. Under the hood id-generation for requests is done using uuid/v1 to provide id uniqueness as an additional feature.

Installation

Using npm:

npm i rpc2-websocket-client

Using CDN （on browsers）

<script src="https://cdn.jsdelivr.net/npm/rpc2-websocket-client/dist/rpc-websocket-client.umd.full.js"></script>

Features

• TypeScript with documentation in comments.
• Unique RPC identifiers by uuid/v1.
• Lightweight. Allows you to call noRpc() method to prevent sending jsonrpc: '2.0' overhead from all messages if you'd like to ignore the JSON RPC 2.0 standard for better performance.
• Option to connect RpcWebSocketClient with already existing WebSocket with changeSocket() and listenMessages() methods. Useful if you use REST or GraphQL implementation from another library and want to handle JSON RPC 2.0 when communicating from server to client (that was my use case to develop this package).

Basic Usage

// vite 使用'rpc-websocket-client.umd.full'，解决require is not defined问题
// import {RpcWebSocketClient} from 'rpc2-websocket-client/dist/rpc-websocket-client.umd.full';
// vite.config.ts 增加以下配置
// export default {
//     optimizeDeps: {
//         include: ['rpc2-websocket-client/dist/rpc-websocket-client.umd.full']
//     }
// };
import { RpcWebSocketClient } from 'rpc2-websocket-client';

(async () => {

    const rpc = new RpcWebSocketClient();
    await rpc.connect(`ws://localhost:4000/`);
    // Connection is established now.

    // Let's hope there will be no error or it will be catched in some wrapper.
    await rpc.call(`auth.login`, [`rpcMaster`, `mySecretPassword`]);

    // Now lets be pesimistic.
    const res = await rpc.call(`auth.login`, [`rpcMaster`, `mySecretPassword`]).then(() => {
        // Woohoo, user logged!
    }).catch((err) => {

        // Err is typeof RpcError (code: number, message: string, data?: any).
        await rpc.call(`auth.signup`, {
            login: `rpcMaster`,
            password: `mySecretPassword`,
        });

        return false;
    });

    // If catch wrapper returned false, let's not continue.
    if (res === false) {
        return;
    }

    rpc.notify(`btw.iHateYou`, [`over and out`]);

    // Close the connection by using native ws.close().
    rpc.ws.close();

})();

Advanced Usage

import { RpcWebSocketClient } from 'rpc-websocket-client';

(async () => {
    // lets say you use WebSocket implementation for GraphQL Client -> Server communication
    // e.g. Apollo, and it's already connected
    // but you want to handle some of the Server -> Client communication with RPC

    const ws = (apollo as any).client.wsImpl;
    const rpc = new RpcWebSocketClient();

    rpc.onRequest.push((data) => {       // data is typeof RpcRequest
        // controller-like stuff
    });

    rpc.onNotification.push((data) => {  // data is typeof RpcNotification
        // notification handling
    });

    // here goes magic for listening to already-connected socket
    rpc.changeSocket(ws);
    rpc.listenMessages();
})();