rockets-client
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    Rockets JS Client

    A small client for Rockets using JSON RPC as communication contract over a WebSocket.

    Travis CI Language grade: JavaScript

    Table of Contents

    Installation


    You can install this package from NPM:

    npm add rxjs rockets-client

    Or with Yarn:

    yarn add rxjs rockets-client

    CDN

    For CDN, you can use unpkg:

    https://unpkg.com/rockets-client/dist/bundles/rockets-client.umd.min.js

    The global namespace for rockets is rocketsClient:

    const {Client} = rocketsClient;
     
    const rockets = new Client({
        url: 'myhost'
    });

    Usage


    Connection

    Create a client and connect:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({
        url: 'myhost',
        onConnected() {
            console.info('I just connected');
        },
        onClosed(evt) {
            console.log(`Socket connection closed with code ${evt.code}`);
        }
    });

    Close the connection with the socket cleanly:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    rockets.subscribe({
        next(notification) {
            console.log(notification);
        },
        complete() {
            console.log('Socket connection closed');
        }
    });
     
    rockets.disconnect();

    Notifications

    Listen to server notifications:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    rockets.subscribe(notification => {
        console.log(notification);
    });

    Send notifications:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    rockets.notify('mymethod', {
        ping: true
    });

    Send a notification using the Notification object:

    import {Client, Notification} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const notification = new Notification('mymethod', {
        ping: true
    });
    rockets.notify(notification);

    Requests

    Make a request:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const response = await rockets.request('mymethod', {
        ping: true
    });
    console.log(response);

    NOTE: There is no need to wait for a connection to be established with the socket as requests will be buffered and sent once the connection is alive. In case of a socket error, the request promise will reject. The same is true for batch requests and notifications.

    Or make a request using the Request object:

    import {Client, Request} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const request = new Request('mymethod', {
        ping: true
    });
    const response = await rockets.request(request);
    console.log(response);

    Handle a request error:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    try {
        await rockets.request('mymethod');
    } catch (err) {
        console.log(err.code);
        console.log(err.message);
        console.log(err.data);
    }

    NOTE: Any error that may occur will be a JsonRpcError.

    Cancel a request:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const task = rockets.request('mymethod');
    task.cancel();

    Get progress updates for a request:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const task = rockets.request('mymethod');
    task.on('progress')
        .subscribe(progress => {
            console.log(progress);
        });

    Batching

    Make a batch request:

    import {Client, Notification, Request} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const request = new Request('mymethod');
    const notification = new Notification('mymethod');
    const [response] = await rockets.batch(...[
        request,
        notification
    ]);
     
    const result = await response.json();
    console.log(result);

    NOTE: Notifications will not return any responses and if no requests are sent, the batch request will resolve without any arguments.

    Handle a batch request error:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    try {
        const request = new Request('mymethod');
        await rockets.batch(request);
    } catch (err) {
        console.log(err.code);
        console.log(err.message);
        console.log(err.data);
    }

    NOTE: The batch promise will not reject for response errors, but you can catch the response error when using the response .json() method:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    try {
        const request = new Request('mymethod');
        const [response] = await rockets.batch(request);
        await response.json();
    } catch (err) {
        console.log(err.code);
        console.log(err.message);
        console.log(err.data);
    }

    Cancel a batch request:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const request = new Request('mymethod');
    const task = rockets.batch(request);
     
    task.cancel();

    NOTE: Notifications cannot be canceled.

    Get progress updates for a batch request:

    import {Client} from 'rockets-client';
     
    const rockets = new Client({url: 'myhost'});
     
    const request = new Request('mymethod');
    const task = rockets.batch(request);
     
    task.on('progress')
        .subscribe(progress => {
            console.log(progress);
        });

    Release


    If you're a contributor and wish to make a release of this package use:

    # Cut a minor release 
    # A release can be: patch, minor, major; 
    yarn release --release-as minor

    See release as a target type imperatively like npm-version for more release options.

    After the changes land in master, the new version will be automatically published by the CI.

    IMPORTANT: Follow the semver for versioning.

    Learning Material


    Install

    npm i rockets-client

    DownloadsWeekly Downloads

    14

    Version

    1.0.0

    License

    LGPL-3.0+

    Unpacked Size

    313 kB

    Total Files

    80

    Last publish

    Collaborators

    • rolandjitsu