Wondering what’s next for npm?Check out our public roadmap! »

    json-rpc-dual-engine

    0.5.4 • Public • Published

    json-rpc-dual-engine

    GitHub Workflow Status (branch) NPM node-current npm GitHub last commit npm

    This is a zero-dependencies protocol agnostic implementation of the JSON-RPC-2.0 spec to allow remote function calls.

    This package includes a client and a server, but you can import either separately without increasing the size of your final build, if you don't need both.

    Install

    npm install json-rpc-dual-engine

    Usage

    Server

    Create the server and register the methods that can be called from the client:

    const JsonRpcServer = require('json-rpc-dual-engine/server');
    
    const server = JsonRpcServer();
    
    server.register('multiply', (a, b) => a * b);

    Use the accept method to deliver incoming remote method calls to the server. The server validates the json-rpc message call, calls the appropriate registered method, and generate the appropriate json-rpc response based on the return of the registered handler.

    Register a onresponse callback to receive the json-rpc responses generated by the server.

    server.onresponse = response => console.log(response);
    
    server.accept('{"jsonrpc":"2.0","method":"multiply","params":[7,11],"id":"1"}');
    
    // Output: '{"jsonrpc":"2.0","result":77,"id":"1"}'

    Client

    Create the client and setup the onrequest callack to send request made by the client to the server.

    const JsonRpcClient = require('json-rpc-dual-engine/client');
    
    const client = JsonRpcClient();
    
    client.onrequest = request => console.log(request);
    
    const resultPromise = client.request('multiply', [7, 11]);
    
    // Output: '{"jsonrpc":"2.0","method":"multiply","params":[7,11],"id":"1"}'

    Use the accept method to deliver incoming server responses to the client to resolve request promises.

    // Using setTimeout to simulate a future incoming message from the server
    setTimeout(100, () => client.accept('{"jsonrpc":"2.0","result":77,"id":"2"}'));
    
    const result = await client.request('multiply', [7, 11]);
    
    console.log(result); // Output: 77

    You can also use the remote sugar proxy object to make things simpler:

    const remote = client.remote;
    
    const result = await remote.multiply(7, 11);
    
    console.log(result); // Output: 77

    Server and Client

    Use JsonRpcDualEngine() to create a json-rpc engine that behaves as both client and server. The accept method of the dual engine can accept both rpc requests and responses, and it has both the onresponse and onrequest callbacks.

    const { JsonRpcDualEngine } = require('json-rpc-dual-engine');
    
    const engine1 = JsonRpcDualEngine();
    const engine2 = JsonRpcDualEngine();
    
    engine1.register('getId', () => '1');
    engine2.register('getId', () => '2');
    
    engine1.onrequest = request => engine2.accept(request);
    engine1.onresponse = response => engine2.accept(response);
    engine2.onrequest = request => engine1.accept(request);
    engine2.onresponse = response => engine1.accept(response);
    
    console.log(await engine1.remote.getId()); // Output: '2'
    console.log(await engine2.remote.getId()); // Output: '1'

    WebSocket Example

    On the server side:

    const JsonRpcServer = require('json-rpc-dual-engine/server');
    const WebSocket = require('ws');
    
    const engine = JsonRpcServer();
    const wss = new WebSocket.Server();
    const websocket = await new Promise(resolve => wss.on('connection', resolve));
    
    // Incoming messages from the websocket will be handled by the engine
    // Whenever the engine has a response to send, send it through the websocket
    websocket.onmessage = message => engine.accept(message.data);
    engine.onresponse = response => websocket.send(response);
    
    // Register a method to handle incoming json-rpc-2.0 requests from the client
    engine.register('multiply', (a, b) => a * b);

    On the client side:

    const JsonRpcClient = require('json-rpc-dual-engine/client');
    const WebSocket = require('ws');
    
    const engine = JsonRpcClient();
    const websocket = new WebSocket('ws://remote.example');
    
    await new Promise((resolve, reject) =>
    {
    	websocket.onopen = resolve;
    	websocket.onerror = reject;
    });
    
    // Incoming messages from the websocket will be handled by the engine
    // Whenever the engine has a request to send, send it through the websocket
    websocket.onmessage = message => engine.accept(message.data);
    engine.onrequest = request => websocket.send(request);
    
    // Sends a json-rpc-2.0 request through the webscoket to the remote server and waits for the response
    const result = await engine.remote.multiply(7, 11);
    
    console.log(result); // Output: 77

    Node Streams

    You can use the JsonRpcStream to work with Node.js streams. It creates a Duplex streams that sends incoming data to the engine and outputs messages (client requests or server responses) generated by engine. It works with both client and server engines.

    const { JsonRpcClient, JsonRpcServer } = require('json-rpc-dual-engine');
    const JsonRpcStream = require('json-rpc-dual-engine/stream');
    
    const server = JsonRpcStream(JsonRpcServer());
    const client = JsonRpcStream(JsonRpcClient());
    
    // Streams use the dual engine, which can act as both client and server
    server.engine.register('multiply', (a, b) => a * b);
    
    // Pipes requests from the client to the server, and responses from the server back to the client
    client.pipe(server).pipe(client);
    
    const result = await client.engine.request('multiply', [7, 11]);
    
    console.log(result); // Output: 77

    Contributing

    Install

    npm install
    

    Test

    npm test
    

    Coverage

    npm run coverage
    

    LICENSE

    MIT

    Install

    npm i json-rpc-dual-engine

    DownloadsWeekly Downloads

    15

    Version

    0.5.4

    License

    MIT

    Unpacked Size

    49.1 kB

    Total Files

    24

    Last publish

    Collaborators

    • avatar