Home

Awesome

npm version Build Status Coverage Status Dependency Status devDependency Status

asteroid

A javascript client (node) for a Meteor backend.

2.x.x is out, find out what changed in the CHANGELOG

Why

Meteor is an awesome framework for building real-time APIs. Its canonical front-end framework however is not very flexible. Adopting other front-ends comes with the cost of having to work around the limitations of meteor's build tool, which makes it very difficult, for instance, to use other tools like webpack, or to manage dependencies via npm.

Asteroid is an isomorphic/universal javascript library which allows to connect to a Meteor backend from almost any JS environment.

With Asteroid you can:

Advantages over the canonical Meteor front-end

Install

npm install --save asteroid

Usage

import {createClass} from "asteroid";

const Asteroid = createClass();
// Connect to a Meteor backend
const asteroid = new Asteroid({
    endpoint: "ws://localhost:3000/websocket"
});

// Use real-time collections
asteroid.subscribe("tasksPublication");

asteroid.ddp.on("added", ({collection, id, fields}) => {
    console.log(`Element added to collection ${collection}`);
    console.log(id);
    console.log(fields);
});

// Login
asteroid.loginWithPassword({username, email, password});

// Call method and use promises
asteroid.call("newUser")
    .then(result => {
        console.log("Success");
        console.log(result);
    })
    .catch(error => {
        console.log("Error");
        console.error(error);
    });

Mixins

Mixins are used to extend Asteroid's functionalities. You add mixins by passing them to the createClass function.

A mixin is an object with a set of enumerable function properties. Those functions will all be mixed into Asteroid.prototype. The special function init won't end up the in prototype. Instead it will be called on instantiation with the arguments passed to the constructor.

Included mixins

Third-party mixins

Development environment setup

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.

Contribute

Contributions are as always very welcome. If you have written a mixin for asteroid, feel free to make a PR to add it to this README.

API

module.createClass([mixins])

Create the Asteroid class. Any passed-in mixins will be added to the default mixins.

Arguments
Returns

The Asteroid class.


new Asteroid(options)

Creates a new Asteroid instance (which is also an EventEmitter).

On instantiation:

Arguments
Returns

An Asteroid instance.


connect()

Provided by the ddp mixin.

Establishes a connection to the ddp server. No-op if a connection is already established.

Arguments

None.

Returns

Nothing.


disconnect()

Provided by the ddp mixin.

Terminates the connection to the ddp server. No-op if there's no active connection.

Arguments

None.

Returns

Nothing.


call(method, [param1, param2, ...])

Provided by the methods mixin.

Calls a server-side method with the specified arguments.

Arguments
Returns

A promise to the method return value (the promise is rejected if the method throws).


apply(method, params)

Provided by the methods mixin.

Same as call, but using as array of parameters instead of a list.

Arguments
Returns

Same as call, see above.


subscribe(name, [param1, param2, ...])

Provided by the subscriptions mixin.

Subscribes to the specified publication. If an identical subscription (name and parameters) has already been made, Asteroid will not re-subscribe and return that subscription instead (subscriptions are idempotent, so it does not make sense to re-subscribe).

Arguments
Returns

A subscription object. Subscription objects have an id, which you can later use to unsubscribe, and are EventEmitter-s. You can listen for the following events:


unsubscribe(id)

Provided by the subscriptions mixin.

Unsubscribes from a publication.

Arguments
Returns

Nothing.


createUser(options)

Provided by the password-login mixin.

Creates a user and logs him in. Does not hash the password before sending it to the server. This should not be a problem, since you'll probably be using SSL anyway.

Arguments

Note: you must specify either options.username or options.email.

Returns

A promise which resolves to the userId of the created user when the creation succeeds, or rejects when it fails.


loginWithPassword(options)

Provided by the password-login mixin.

Logs the user in using username/email and password. Does not hash the password before sending it to the server. This should not be a problem, since you'll probably be using SSL anyway.

Arguments

Note: you must specify either options.username or options.email.

Returns

A promise which resolves to the userId of the logged in user when the login succeeds, or rejects when it fails.


login(params)

Provided by the login mixin.

Log in the user.

Arguments
Returns

A promise which resolves to the userId of the logged in user when the login succeeds, or rejects when it fails.


logout()

Provided by the login mixin.

Logs out the user.

Arguments

None

Returns

A promise which resolves to null when the logout succeeds, or rejects when it fails.


Public Asteroid events