API

Table of Contents

module vibe

`module vibe`

A vibe client module acting as a factory to create and manage socket. Every time the module is loaded through either Node's require, AMD's require or script tag, it's newly created. But you don't need to be aware of that.

This page already loaded the module. Open a console and type vibe.

Loading module.

Script tag

<script src="/vibe/vibe.min.js"></script>
<script>vibe;</script>

AMD loader

require(["vibe"], function(vibe) {});

Node.js

var vibe = require("vibe-client");

`export function open(uri: string, options?: SocketOptions): Socket`

Opens a socket and returns it. uri can be relative in browser.

Hello world.

vibe.open(uri);

`interface SocketOptions`

An interface of properties to get/set socket options. None of properties are required so it can be an empty object.

All possible options along with their default values.

Browser

vibe.open(uri, {
    reconnect: function(lastDelay) {
        return 2 * lastDelay || 500;
    },
    sharing: false,
    timeout: false,
    transports: null,
    xdrURL: null
});

Node.js

vibe.open(uri, {
    reconnect: function(lastDelay) {
        return 2 * lastDelay || 500;
    },
    timeout: false,
    transports: null
});

My configuration for testing.

vibe.open(uri, {reconnect: false, timeout: 3000, xdrURL: function(url) {return url;}});

`reconnect? (lastDelay: number, attempts: number): any`

Default: Generates a geometric series with initial delay 500 and ratio 2

`reconnect? (lastDelay: number, attempts: number): number`

A function to be used to schedule reconnection. The function is called every time after the close event and should return a delay in milliseconds. The function receives two arguments: The last delay in milliseconds used or null at first and the total number of reconnection attempts.

`reconnect? (lastDelay: number, attempts: number): boolean`

A function can return false to stop further reconnection.

`reconnect?: boolean`

The value false indicates no reconnection. It is useful in testing.

A Fibonacci series with first delay 500 and second delay 1000.

vibe.open(uri, {
    reconnect: function(lastDelay) {
        var beforeLastDelay = this.beforeLastDelay || 0;
        lastDelay = lastDelay || 500;
        this.beforeLastDelay = lastDelay;
        return beforeLastDelay + lastDelay; // 500, 1000, 1500, 2500 ...
    }
});

`sharing?: boolean`

Default: false

A flag indicating that connection sharing across tabs and windows is enabled or not. If this is turned on, as long as the cookie is enabled, the socket will try to automatically share a real connection if there is no corresponding one, and find and use a shared connection if it exists within the cookie's scope.

Note that this option is only for browser and if the web page or computer becomes horribly busy, a newly created socket might establish a physical connection though it doesn't break anything. Also the connection sharing will be rewritten so I don't recommend to use it for now.

`timeout?: any`

Default: false

`timeout?: number`

A timeout value in milliseconds. The timeout timer starts at the time the connecting event is fired. If the timer expires before the connection is established, the close event is fired.

`timeout?: boolean`

The value false means no timeout.

`transports?: string[]`

Default: null

An array of the transport ids, in order of index. The default value, null, means following the server's configuration. Therefore, you don't need to set it but if you set it, it is prioritized over that of server.

ws, sse, streamxhr, streamxdr, streamiframe, longpollajax, longpollxdr and longpolljsonp are available including a special one, stream and longpoll. For example, ["ws", "stream", "longpoll"] means given runtime environment, try WebSocket, if not possible try HTTP Streaming, if not possible use HTTP Long polling. Transport availability is calculated by feature detection in runtime environment and doesn't guarantee that selected transport will work with the given network and server.

`xdrURL? (uri: string): string`

Default: null

A function used to modify a url to add session information to enable streamxdr and longpollxdr transports. For security reasons, the XDomainRequest excludes cookie when sending a request, so the session cannot be tracked by cookie. That's why streamxdr and longpollxdr are disabled by default. However, if the server supports session tracking by url, it is possible to track session by setting xdrURL.

Session tracking by modifying url

Java Servlet

vibe.open(uri, {
    // input: url?k=v
    // output: url;jsessionid=${cookie.JSESSIONID}?k=v
    xdrURL: function(uri) {
        var sid = /(?:^|; )JSESSIONID=([^;]*)/.exec(document.cookie)[1];
        return url.replace(/;jsessionid=[^\?]*|(\?)|$/, 
            ";jsessionid=" + sid + "$1");
    }
});

PHP

vibe.open(uri, {
    // input: url?k=v
    // output: url?PHPSESSID=${cookie.PHPSESSID}&k=v
    xdrURL: function(uri) {
        var sid = /(?:^|; )PHPSESSID=([^;]*)/.exec(document.cookie)[1];
        return url.replace(/\?PHPSESSID=[^&]*&?|\?|$/, 
            "?PHPSESSID=" + sid + "&").replace(/&$/, "");
    }
});

`interface Socket`

An interface representing a socket created by calling vibe.open.

Echo

vibe.open(uri).on("open", function() {
    this.send("echo", "Hello World");
})
.on("echo", function(data) {
    console.log("echoed back", data);
});

`close(): Socket`

Closes the socket.

`off(event: string, handler: Function): Socket`

Removes a given event handler for a given event.

`on(event: string, handler: Function): Socket`

Adds a given event handler for a given event. If a handler is set, it will be reset upon reconnection so don't call on in dispatching event including open. Generally, added handler is called every time server sends the corresponding event, but if a given event is reserved, a given event handler behave differently like the following.

`connecting (): void`

A pseudo event which is fired only once in life cycle when a connection is tried.

Notifying a user of connection

// If this socket is in connecting, it will be executed immediately.
// If this socket is in opened, closed or waiting, it will be ignored.
vibe.open(uri).on("connecting", function() {
    console.log("Trying connection");
});

`open (): void`

A network event which is fired only once in life cycle when a connection is established and communication is possible.

Providing the application with an event channel with the server.

// If this socket is in opened, it will be executed immediately.
// If this socket is in connecting, closed or waiting, it will be ignored.
vibe.open(uri).on("open", function() {
    app.bridge(this);
});

`error (error: Error): void`

A message event which is fired every time an error has occurred. The error's message property can be one of the following values:

handshake: handshaking fails.
notransport: there is no available transport.
heartbeat: heartbeat fails.
notopened: socket is not opened.
timeout: it's timed out.
Otherwise, transport fails to establish a connection or a connection is closed due to some error. But if transport is sse, because it can't handle error, error event won't be fired although there was an error actually.

Logging given error.

// If this socket is in connecting and opened, it will be executed every time an error has occurred.
// If this socket is in closed or waiting, it will be ignored.
vibe.open(uri).on("error", function(error) {
    console.error(error);
});

`close (reason: string): void`

A network event which is fired once in life cycle when a connection has been closed for any reason or couldn't be establiahsed.

Releasing resources that it has been holding.

// If this socket is in connecting and opened, it will be executed on close event.
// If this socket is in closed or waiting, it will be executed immediately.
vibe.open(uri).on("close", function() {
    writer.close();
});

`waiting (delay: number, attempts: number): void`

A pseudo event which is fired only once in life cycle when a reconnection has scheduled. delay is the reconnection delay in milliseconds and attempts is the total number of reconnection attempts.

Notifiying a user of delay, the time have to wait for

// If this socket is in connecting and opened, it will be executed on waiting event.
// If this socket is in closed or waiting, it will be executed immediately.
vibe.open(uri).on("waiting", function(delay, attempts) {
    console.log("This is", attempts, (["st", "nd", "rd"][attempts - 1] || "th"), "attempt. It will connect in", (delay / 1000), "sec");
});

`[event: string]: (data?: any, reply?: {resolve: (data?: any) => void; reject: (data?: any) => void}) => void`

All the other event are message event and fired every time the server sends an event. data is data of the server sent event and reply is a controller to reply the server and not null only if server attaches resolved or rejected callback. Because this type of event will be used heavily, to manage such many events systematically, using some format like URI to event naming is helpful.

Receiving data

// If this socket is in connecting and opened, it will be executed every time an event has been received.
// If this socket is in closed or waiting, it will be ignored.
vibe.open(uri).on("/chat/message", function(message) {
    console.dir(message);
});

Replying to event

vibe.open(uri).on("/talk/request", function(account, reply) {
    $.templates("#template").link("#dialog section", account);
    $("#dialog").show().one("close", function() {
        if (this.returnValue) {
            reply.resolve();
        } else {
            reply.reject();
        }
    });
});

`once(event: string, handler: Function): Socket`

Adds a given one time event handler for a given event. A handler shares the same signatures with on. It can be removed by off and called only once in the life cycle or never.

Sending an event defensively.

// If this socket is in connecting, it will be executed on open event and removed.
// If this socket is in opened, it will be executed and removed immediately.
// If this socket is in closed or waiting, it will be ignored.
// Whether or not it is called, it will never called in further life cycle. 
socket.once("open", function() {
    this.send("event", "data");
});

`send(event: string, data?: any, resolved?: (data?: any) => void, rejected?: (data?: any) => void): Socket`

Sends the event with data attaching resolved and rejected callbacks. If a socket is not opened, it will fire an error event. If you have enabled connection sharing, don't attach resolved and rejected callbacks. In current implementation, it's not recommended.

Sending simple event.

vibe.open(uri).on("open", function() {
    this.send("/start");
});

Getting data from the server.

vibe.open(uri).on("open", function() {
    this.send("/account/find", "flowersinthesand", function(account) {
        console.dir(account);
    }, function(reason) {
        console.log("Got an error", reason);
    });
});

Sending events in order.

vibe.open(uri).on("open", function() {
    this.send("event", 1, function() {
        this.send("event", 2, function() {
            this.send("event", 3, function() {
                this.send("event", 4);
            });
        });
    });
});

`state(): string`

Determines the current state of the socket. Possible state values are connecting, opened, closed and waiting.

Tracking socket state

function logState() {
    console.log(this.state(), arguments);
}

vibe.open(uri).on("connecting", logState).on("open", logState).on("close", logState).on("waiting", logState);