ddp.js

#WARNING Breaking changes from 0.6.x to 1.0.0, read the CHANGELOG for more info.

#ddp.js

A javascript isomorphic ddp client.

##What is it for?

The purpose of this library is:

• to set up and maintain a ddp connection with a ddp server, freeing the developer from having to do it on their own
• to give the developer a clear, consistent API to communicate with the ddp server

##Install

Via npm

npm install ddp.js

Or via bower

bower install ddp.js

##Example usage

var DDP = require("ddp.js");
var options = {
    endpoint: "http://localhost:3000/websocket",
    SocketConstructor: WebSocket
};
var ddp = new DDP(options);

ddp.on("connected", function () {
    console.log("Connected");

    var subId = ddp.sub("myCollection");
    ddp.on("ready", function (message) {
        if (message.id === subId) {
            console.log("Subscruption to myCollection ready");
        }
    });
    ddp.on("added", function (message) {
        console.log(message.collection);
    });

    var myLoginParams = {
        user: {
            email: "[e-mail]"
        },
        password: "hunter2"
    };
    var methodId = ddp.method("login", [myLoginParams]);
    ddp.on("result", function (message) {
        if (message.id === methodId && !message.error) {
            console.log("Logged in!");
        }
    });
});

##Tests

npm test to run tests, npm run coverage to generate the coverage report.

##Public API

###new DDP(options)

Creates a new DDP instance. After being constructed, the instance will establish a connection with the DDP server and will try to maintain it open.

####Arguments

• options object required

Available options are:

• endpoint string required: the location of the websocket server. Its format depends on the type of socket you are using.

• SocketConstructor function required: the constructor function that will be used to construct the socket. Meteor (currently the only DDP server available) supports websockets and SockJS sockets. So, practically speaking, this means that on the browser you can use either the browser's native WebSocket constructor or the SockJS constructor provided by the SockJS library. On the server you can use whichever library implements the websocket protocol (e.g. faye-websocket).

####Returns

A new DDP instance, which is also an EventEmitter instance.

---

###DDP.method(name, params)

Calls a remote method.

####Arguments

• name string required: name of the method to call.

• params array required: parameters to pass to the remote method. Pass an empty array if you do not wish to pass any parameters.

####Returns

The unique id (string) corresponding to the method call.

---

###DDP.sub(name, params)

Subscribes to a server publication.

####Arguments

• name string required: name of the server publication.

• params array required: parameters to pass to the server publish function. Pass an empty array if you do not wish to pass any parameters.

####Returns

The unique id (string) corresponding to the subscription call.

---

###DDP.unsub(id)

Unsubscribes to a previously-subscribed server publication.

####Arguments

• id string required: id of the subscription.

####Returns

The id corresponding to the subscription call (not of much use, but I return it for consistency).

##Public events

###Connection events

• connected: emitted with no arguments when the DDP connection is established.

• disconnected: emitted with no arguments when the DDP connection drops.

###Subscription events

All the following events are emitted with one argument, the parsed DDP message. Further details can be found on the DDP spec page.

• ready
• nosub
• added
• changed
• removed

###Method events

All the following events are emitted with one argument, the parsed DDP message. Further details can be found on the DDP spec page.

• result
• updated

Changelog

1.0.0 (January 11, 2015)

The library has been rewritten from scratch and its scope somewhat reduced. The purpose of the rewrite, other than simplification, was to implement better under-the-hood APIs to allow more flexibility.

The biggest change is that the library no longer handles method and subscription calls. I.e., it doesn't take anymore callbacks to the method and sub methods. Rather it returns the id of those calls, and lets the consumer handle the result, updated, ready, nosub events related to those calls. My plan is to bake this functionality directly into Asteroid, which sometimes need to have lower level access to those events.

Some options have been removed, namely do_not_autoconnect, do_not_autoreconnect and socket_intercept_function. The functionalities provided by the first two options can be recreated, but it requires meddling with the library internals (one has to re-define the _init method). I figured this wouldn't be a problem since I've never found a use case for them. The third functionality - i.e. intercepting the socket send method and doing something with the message that has been sent - is easily recreated by listening to the message:in, message:out private events of the _socket property of a DDP instance. Other private events are available on the property, making it easier to monitor and gather metrics about the WebSocket.