Have ideas to improve npm?Join in the discussion! »

    soxx

    2.0.3 • Public • Published

    soxx

    ⚡️ The missing microlib for websocket communication in the modern web browser. 🍰

    Provides connecting, disconnecting, writing, retrying and listening. Not much else.

    Scope

    In the interest of size and speed, the scope of this library extends to modern browsers only. Compatibility with older browsers that do not support websockets is not the aim or goal of this lib.

    Installation

    To install Soxx, you first need to get the lib either from the releases page or via NPM:

    npm install soxx

    Then, you can either include dist/soxx.js file in your html file as such:

    <script src='path/to/soxx.js'></script>

    or you can include it via broswerify:

    var Soxx = require('soxx')

    API

    Create

    To start a connection, you need to instatiate the lib:

    var opts = {
      url:'ws://sockb.in/'
    }
    var websocket = new Soxx(opts)

    Once instantiated, you can connect, assign listeners, and fire events back to the server.

    Connect

    var opts = {
      url:'ws://sockb.in/',
      onOpen: function(event){
        // do something here
      }
    }
    var websocket = new Soxx(opts)
    websocket.connect()

    Once the lib establishes a connection with the websocket server, it will fire onOpen as specified.

    Disconnect

    var opts = {
      url:'ws://sockb.in/',
      onClose: function(event){
        // do something here
      }
    }
    var websocket = new Soxx(opts)
    websocket.connect()
    websocket.disconnect()

    Once when you fire disconnect, it will fire onClose as specified.

    Write

    var opts = {
      url:'ws://sockb.in/'
    }
    var websocket = new Soxx(opts)
    websocket.connect()
    var message = 'Hello World!'
    websocket.write(message)

    Note: message should only be a string.

    Listen

    var opts = {
      url:'ws://sockb.in/',
      onMessage: function(message){
        // do something with the message
      }
    }
    var websocket = new Soxx(opts)
    websocket.connect()

    The message will come in as a raw string, you'll need to do parsing on it as you prefer.

    Error Handling & Retry

    var opts = {
      url:'ws://sockb.in/',
      retry: {
        count: 5, // number of times to retry as a whole since instantiation
        delay: 1000 // time to wait before retrying connection
      },
      onRetry: function(){
        // do something (this is inline, don't do async here)
      },
      onError: function(eventt){
        // handle error the way you like
      }
    }
    var websocket = new Soxx(opts)
    websocket.connect()
    

    If the connection is dropped or if an error is sent, it will attempt to retry if there is a retry sub-object present.

    Changelog

    All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning and Keep A Changelog.

    v2.0.0 | 2016-04-29

    branch: release/v2.0.0

    REWRITE

    This version bump is a complete rewrite. New API, new internals, new everything. Because YOLO.

    v1.1.0 | 2015-07-21

    branch: release/v1.1.0

    Type Link Description
    Added #4 Added off() functionality

    v1.0.0 | 2015-07-21

    branch: release/v1.0.0

    Type Link Description
    Added ba18c0c Added initial files

    License

    ISC

    Install

    npm i soxx

    DownloadsWeekly Downloads

    1

    Version

    2.0.3

    License

    ISC

    Last publish

    Collaborators

    • avatar