Example todo app using AngularJS. Same app using Meteor's front-end.
#asteroid
A javascript client (browser and node) for a Meteor backend.
##Table of contents
Advantages over the canonical Meteor front-end
##Why
Meteor is an awesome platform, but its canonical front-end is not very flexible. Asteroid gives the possibility to connect to a Meteor backend with any JS app.
Some of the things Asteroid allows you to do are:
-
make any existing application reactive
-
use any front-end framework you want with Meteor
-
develop browser extensions backed by Meteor
##Install
###In the browser
First, dowload the library:
bower install asteroid
Then, add the necessary libraries to your index.html
:
<script src="bower_components/ddp.js/src/ddp.js"></script>
<script src="bower_components/q/q.js"></script>
<script src="bower_components/asteroid/dist/asteroid.browser.js"></script>
If you want to login via oauth providers (facebook, google etc), also include the appropriate plugin:
<script src="bower_components/asteroid/dist/plugins/facebook-login.js"></script>
For facebook connect support in cordova via the facebook connect plugin, see https://github.com/keyvanfatehi/asteroid-facebook-connect
###In a chrome extension or in cordova
Just replace asteroid.browser.js
with asteroid.chrome.js
or asteroid.cordova.js
.
If using from within a chrome extension make sure to request for the tabs
and storage
permissions in your extensions manifest file.
###In node
Download the package:
npm install asteroid
Require it in your project:
var Asteroid = require("asteroid");
##Example usage
// Connect to a Meteor backend
var ceres = new Asteroid("localhost:3000");
// Use real-time collections
ceres.subscribe("tasksPublication");
var tasks = ceres.getCollection("tasks");
tasks.insert({
description: "Do the laundry"
});
// Get the task
var laundryTaskRQ = tasks.reactiveQuery({description: "Do the laundry"});
// Log the array of results
console.log(laundryTaskRQ.result);
// Listen for changes
laundryTaskRQ.on("change", function () {
console.log(laundryTaskRQ.result);
});
// Login your user
ceres.loginWithTwitter();
// Call method and use promises via the Q library
var ret = ceres.call('newUser');
ret.result
.then(function (result) {
console.log('Success:', result);
}).catch(function (error) {
console.error('Error:', error);
});
Please refer to the Q documentation for more information about handling promises.
##Advantages over the canonical Meteor front-end
-
Small footprint.
-
Framework agnostic. Use the tools you already know and love to build your app.
-
Allows to use Meteor as a full-blown backend or just as a real-time platform pluggable into any existing project.
-
Easily connect to multiple Meteor servers at the same time, perfect for building admin interfaces.
##Build asteroid locally
Clone the repository (or your fork) on your computer.
git clone https://github.com/mondora/asteroid
Enter the project's directory and install the required dependencies:
cd asteroid/
npm install
Start the development environment (requires gulp
installed globally):
gulp
Visit localhost:8080/browser.html
and localhost:8080/node.html
for unit tests result.
##Contribute
Contributions are as always very very welcome. If you want to help but don't know how to get started, feel free to schedule a pair programming session with me!
##API
##Asteroid methods
###new Asteroid(host, ssl, interceptor)
Creates a new Asteroid instance, that is, a connection to a Meteor server (via DDP).
After being constructed, the instance will connect itself to
the Meteor backend. It will also try, upon connection, to
resume a previous login session (with a token saved in
localstorage). The Asteroid.resumeLoginPromise
property
stores a promise which will be resolved if the resume was
successful, rejected otherwise.
If SockJS
is defined, it will be used as the socket
transport. Otherwise WebSocket
will be used. Note that
SockJS
is required for IE9 support.
#####Arguments
-
host
string required: the address of the Meteor server, e.g.example.meteor.com
-
ssl
boolean optional: whether to use SSL. Defaults tofalse
. -
interceptor
function optional: a function which will intercept any socket event. It will be called with an event object containing the name of the event, the timestamp of the event, and details about the event (for instance, in case of a "socket_message_received" event, it'll contain the payload of the message).
#####Returns
An Asteroid instance.
###Asteroid.on(event, handler)
Registers an event handler for the specified event.
#####Arguments
-
event
string required: the name of the event. -
handler
function required: the handler.
An Asteroid instance emits the following events:
-
connected
: emitted when the DDP connection is established. No arguments are passed to the handler. -
login
: emitted when the user logs in. The id of the logged in user will be passed as argument to the handler. -
logout
: emitted when the user logs out. No arguments are passed to the handler.
#####Returns
Nothing
###Asteroid.loginWith ... ()
Logs the user in via the specified third party (oauth) service.
#####Available services
-
facebook:
loginWithFacebook
-
google:
loginWithGoogle
-
twitter:
loginWithTwitter
-
github:
loginWithGithub
#####Returns
A promise which will be resolved with the logged user id if the login is successful. Otherwise it'll be rejected with the error.
###Asteroid.createUser(usernameOrEmail, password, profile)
Creates a user and logs him in. Does not hash the password before sending it to the server. This is not a problem, since you'll probably be using SSL anyway.
#####Arguments
-
usernameOrEmail
string required: the username or email. -
password
string required: the password. -
profile
object optional: a blackbox, you can throw anything in here and it'll end up intouser.profile
.
#####Returns
A promise which will be resolved with the logged user id if the creation and login are successful. Otherwise it'll be rejected with an error.
###Asteroid.loginWithPassword(usernameOrEmail, password)
Logs the user in username/email and password. Does not hash the password before sending it to the server. This is not a problem, since you'll probably be using SSL anyway.
#####Arguments
-
usernameOrEmail
string required: the username or email. -
password
string required: the password.
#####Returns
A promise which will be resolved with the logged user id if the login is successful. Otherwise it'll be rejected with an error.
###Asteroid.logout()
Logs out the user.
#####Arguments
None
#####Returns
A promise which will be resolved with if the logout is successful. Otherwise it'll be rejected with the error.
###Asteroid.subscribe(name, [param1, param2, ...])
Subscribes to the specified subscription. If an identical subscription (same name and parameters) has already been made, Asteroid will return that subscription.
#####Arguments
-
name
string required: the name of the subscription. -
param1, param2, ...
optional: a list of parameters that will be passed to the publish function on the server.
#####Returns
A subscription instance.
###Asteroid.Subscription
Subscription instances have the following properties:
-
id
string: theid
of the subscription, as returned by theddp.sub
method -
ready
promise: a promise which will be resolved with theid
of the subscription if the subscription succeeds (we receive the ddpready
message), or will be rejected if it fails (we receive, upon subscribing, thenosub
message).
And the following method:
stop
: it takes no argument, sends the ddpunsub
message and deletes the subscription so it can be garbage collected.
###Asteroid.call(method, [param1, param2, ...])
Calls a server-side method with the specified arguments.
#####Arguments
-
method
string required: the name of the method to call. -
param1, param2, ...
optional: a list of parameters that will be passed to the method on the server.
#####Returns
An object with two properties: result
and updated
. Both
properties are promises.
If the method is successful, the result
promise will be
resolved with the return value passed by the server. The
updated
promise will be resolved with nothing once the
server emits the updated
message, that tells the client
that any side-effect that the method execution caused on the
database has been reflected on the client (for example, if
the method caused the insertion of an item into a
collection, the client has been notified of said insertion).
If the method fails, the result
promise will be rejected
with the error returned by the server. The updated
promise will be rejected as well (with nothing).
###Asteroid.apply(method, params)
Same as Asteroid.call, but using as array of parameters instead of a list.
#####Arguments
-
method
string required: the name of the method to call. -
params
array optional: an array of parameters that will be passed to the method on the server.
#####Returns
Same as Asteroid.call, see above.
###Asteroid.getCollection(name)
Creates and returns a collection. If the collection already exists, nothing changes and the existing one is returned.
#####Arguments
name
string required: the name of the collection to create.
#####Returns
A reference to the collection.
#####Note
Asteroid auto-creates collections for you. For example, if
you subscribe to an hypothetical posts
subscription, the
server will start sending the client added
messages that
refer to items of the posts
collection. With Meteor's
front-end we would normally need to define the
posts
collection before we can access it.
With Asteroid, when the first added
message is received,
if the posts
collection doesn't exist yet, it will get
automatically created. We can then get a reference to
that collection by calling createCollection
(or by
accessing the semi-private Asteroid.collections
dictionary).
##Asteroid.Collection methods
All the following methods use latency compensation.
###Collection.insert(item)
Inserts an item into a collection. If the item does not
have an _id
property, one will be automatically generated
for it.
#####Arguments
item
object required: the object to insert. Must be JSON serializable. Optional support for EJSON is planned.
#####Returns
An object with two properties: local
and remote
. Both
properties are promises.
The local promise is immediately resolved with the _id
of
the inserted item. That is, unless an error occurred. In
that case, an exception will be raised. (TODO: this is a bit
of an API inconsistency which maybe should be fixed).
The remote promise is resolved with the _id
of the
inserted item if the remote insert is successful. Otherwise
it's rejected with the reason of the failure.
###Collection.update(id, item)
Updates the specified item.
#####Arguments
-
id
string required: the id of the item to update. -
item
object required: the object that will replace the old one.
#####Returns
An object with two properties: local
and remote
. Both
properties are promises.
The local promise is immediately resolved with the _id
of
the updated item. That is, unless an error occurred. In
that case, an exception will be raised. (TODO: this is a bit
of an API inconsistency which should be fixed).
The remote promise is resolved with the _id
of the updated
item if the remote update is successful. Otherwise it's
rejected with the reason of the failure.
#####Note
The API greatly differs from Meteor's API. Aligning the two is on the TODO list.
###Collection.remove(id)
Removes the specified item.
#####Arguments
id
string required: the id of the item to remove.
#####Returns
An object with two properties: local
and remote
. Both
properties are promises.
The local promise is immediately resolved with the _id
of
the removed item. That is, unless an error occurred. In
that case, an exception will be raised. (TODO: this is a bit
of an API inconsistency which should be fixed).
The remote promise is resolved with the _id
of the removed
item if the remote remove is successful. Otherwise it's
rejected with the reason of the failure.
###Collection.reactiveQuery(selector)
Gets a "reactive" subset of the collection.
#####Arguments
selector
object or function required: a MongoDB-style selector. Actually for now only a simple selector is supported (example{key1: val1, key2.subkey1: val2}
). To compensate for this, you can also pass in a filter function which will be invoked on each item of the collection. If the function returns a truthy value, the item will be included, otherwise it will be left out. Help on adding support for more complex selectors is appreciated.
#####Returns
A ReactiveQuery instance.
##ReactiveQuery methods and properties
###ReactiveQuery.result
The array of items in the collection that matched the query.
###ReactiveQuery.on(event, handler)
Registers a handler for an event.
#####Arguments
-
event
string required: the name of the event. -
handler
function required: the handler for the event.
Possible events are:
change
: emitted whenever the result of the query changes. The id of the item that changed is passed to the handler.