lithium

A data centric WebSocket library for both Node.js and the Browser.

npm install lithium
7 downloads in the last week
15 downloads in the last month

Lithium

Lithium is a data centric WebSocket library for both Node.js and the Browser.

Installation

Client

<script type="text/javascript" src="lithium.client.js"></script>

Server

npm install lithium

Usage

Below is an example of a simple, JSON based echo server.

Client

var client = new lithium.Client(function(client) {

    client.on('message', function(msg) {
        ...
    });

    client.send({
        msg: 'Hello World'
    });

}, JSON.stringify, JSON.parse);

Server

var lithium = require('lithium');

var server = new lithium.Server(function(remote) {

    remote.accept();
    remote.on('message', function(msg) {
        remote.send(msg);
    });

}, JSON.stringify, JSON.parse);

server.listen(8000);

Features

  • WebSocket Protocols (v75, v76, hixie and hyby)
  • Binary Message Support
  • Consistent API on both Server and Client
  • No dependencies

API

Server

A http.Server-like interface for managing web socket connections.

Methods

  • Constructor - lithium.Server([Function:callback] [, Function:encoder, Function:decoder] [, Number:maxFrameSize] [, Number:delay])

    Creates a new server instance.

    The optional callback argument is shortcut for the connection event.

    If both the encoder and decoder arguments are present, messages will be passed to these functions when being send / received.

    The maxFrameSize parameter will kill any connections that send a frame with more than 32768 bytes by default.

    delay introduces an optional read and write delay for all connections. Its specified in milliseconds, 250ms will result in a total roundtrip of 500ms.

    For example, in order to process and treat all messages as JSON objects pass

  • listen(Number:port [, String:hostname])

    Makes the server listen for incoming web socket requests on port and - optionally - hostname.

  • listen(http(s).Server)

    Makes the server listen for incoming web socket request on an existing instance of http.Server or https.Server.

  • Boolean - isRunning()

    Returns whether the server is running (listening for new connections).

  • Array[Remote] - remotes([Function:filter])

    Returns a array with all remotes that are currently connected to the server (meaning that only accepted remotes will be contained in the array).

    Filter is an optional function behaving much like Array.filter in that it filters the remotes before returning them.

  • Integer - send(Any:message [, Function:filter])

    Sends a message to all accepted remotes on the server.

    Filter is an optional function behaving much like Array.filter in that it filters the remotes before messaging them.

    Returns the number of remotes the message was sent to.

  • Boolean - close([string:reason])

    Closes the server by preventing any furhter connections to be made and invokes the close method of all the server's remotes.

    The optional reason is only supported in newer versions of the WebSocket protocol and will be available as the reason property on the WebSocket's close event.

    Returns false in case the server is already closed.

Events

  • connection(Remote:remote)

    Emitted when a remote connects to the server.

  • accepted(Remote:remote)

    Emitted when the server accepts a remote.

  • rejected(Remote:remote)

    Emitted when the server rejects a remote.

  • closed(Remote:remote, Boolean:closedByRemote)

    Emitted when a remote disconnects from the server.

    closedByRemote will be true in the case that the disconnect was initiated by the remote.

  • close()

    Emitted when the server stops listening for new connections.

Remotes

Each remote encapsulate a single web socket connection to a client.

A remote is only recognized as being connected after it was accepted.

Properties

  • String - id
  • String - address

    Address of the underlying socket connection.

  • Intege - port

    Port of the underlying socket connection.

  • Integer - bytesSend

    Number of raw bytes (including protocol overhead) send over the socket.

  • Integer - bytesReceived

    Number of raw bytes (including protocol overhead) send over the socket.

  • Integer - version

    The version of the underlying WebSocket protocol for this remote.

Methods

  • Boolean - accept()

    Accepts a pending remote connection, which adds it to the list of connected remotes on the server.

    Once a remote is accepted messages can be send to it.

    Returns true in case the remote was accepted or false in case it could not be accepted.

  • Boolean - reject([String:reason])

    Rejects a pending remote and sends an optional reason as a message before closing the connection.

    Returns true in case the remote was rejected or false in case it could not be rejected.

  • Boolean - isPending()

    Returns whether or not the connection is pending.

    Pending means that the connection is yet to be either accepted or rejected.

  • Boolean - send(any:message)

    Sends a message to the remote.

    Returns true in case the message was send or false in case it could not be send.

  • Boolean - close([Any:reason])

    Closes the connection to the remote.

    The optional reason is only supported in newer versions of the WebSocket protocol and will be available as the reason property on the WebSocket's close event.

    Returns true in case the connection was closed or false in case it was not.

Events

  • message(Any:message)

    Emitted when a message is received from a remote.

  • close(Boolean:closedByRemote)

    Emitted when the remote is disconnected from the server.

    closedByRemote will be true in the case that the disconnect was initiated by the remote.

Client

A thin wrapper around the browser side WebSocket object, providing a interface that is consistent with the lithium server.

Methods

  • Constructor - lithium.Client([Function:callback] [, Function:encoder, Function:decoder]) (Constructor)

    The optional callback argument is shortcut for the connection event.

    If both the encoder and decoder arguments are present, messages will be passed to these functions when being send / received.

    For example, in order to process and treat all messages as JSON objects pass

  • Boolean - connect(Integer:port [, String:hostname])

    Connects to the server at port and - optionally - hostname.

  • Boolean - isConnected()

    Returns true in case the client is currently connected to the server.

  • Boolean - wasConnected()

    Returns true in case the client was connected to the server before it closed.

  • Boolean - send(any:message)

    Sends a message to the remote.

    Returns true in case the message was send or false in case it could not be send.

  • Boolean - close()

    Closes the connection to the server.

    Returns false in case the connection is already closed.

Events

  • connection()

    Emitted once the connection to the server is established.

  • message(Any:message)

    Emitted when a message is received from the server.

  • close(Boolean:closedByServer, String:reason, Integer:code)

    Emitted when the client is disconnected from the server.

    In the case that the server has initiated the close of the connection, the value of closedByServer will be true.

License

Lithium is licensed under MIT.

npm loves you