simpleddp-core

A javascript isomorphic/universal ddp client (successor of ddp.js).

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

To install ddp.js using npm:

npm install ddp.js

or using yarn:

yarn add ddp.js

Example usage

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

ddp.on("connected", () => {
console.log("Connected");
});

const subId = ddp.sub("mySubscription");
ddp.on("ready", message => {
if (message.subs.includes(subId)) {
console.log("mySubscription ready");
}
});
ddp.on("added", message => {
console.log(message.collection);
});

const myLoginParams = {
user: {
email: "user@example.com"
},
password: "hunter2"
};
const methodId = ddp.method("login", [myLoginParams]);
ddp.on("result", message => {
if (message.id === methodId && !message.error) {
console.log("Logged in!");
}
});
`

Developing

After cloning the repository, install npm dependencies with npm install.
Run npm test to run unit tests, or npm run dev to have mocha re-run your
tests when source or test files change.

To run e2e tests, first install meteor. Then,
start the meteor server with npm run start-meteor. Finally, run
npm run e2e-test to run the e2e test suite, or npm run e2e-dev to have
mocha re-run the suite when source or test files change.

Public API

$3

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:

- cleanQueue boolean optional [default: false]: whether to clean ddp message
queue on disconnect or not.

- 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).

- autoConnect boolean optional [default: true]: whether to establish
the connection to the server upon instantiation. When false, one can
manually establish the connection with the connect method.

- autoReconnect boolean optional [default: true]: whether to try to
reconnect to the server when the socket connection closes, unless the closing
was initiated by a call to the disconnect method.

- reconnectInterval number optional [default: 10000]: the interval in ms
between reconnection attempts.

#### Returns

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

---

$3

Calls a remote method.

#### Arguments

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

- params array required: array of 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.

#### Example usage

Server code:
`js
Meteor.methods({
myMethod (param_0, param_1, param_2) {
/ ... /
}
});
`
Client code:
`js
const methodCallId = ddp.method("myMethod", [param_0, param_1, param_2]);
`

---

$3

Subscribes to a server publication.

#### Arguments

- name string required: name of the server publication.

- params array required: array of 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.

#### Example usage

Server code:
`js
Meteor.publish("myPublication", (param_0, param_1, param_2) {
/ ... /
});
`
Client code:
`js
const subscriptionId = ddp.sub("myPublication", [param_0, param_1, param_2]);
`

---

$3

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).

---

$3

Connects to the ddp server. The method is called automatically by the class
constructor if the autoConnect option is set to true (default behaviour).
So there generally should be no need for the developer to call the method
themselves.

#### Arguments

None

#### Returns

None

---

$3

Disconnects from the ddp server by closing the WebSocket connection. You can
listen on the disconnected event to be notified of the disconnection.

#### Arguments

None

#### Returns

None

Public events

$3

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

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

$3

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

$3

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`