Name: asteroid
Owner: Rocket.Chat
Description: An alternative client for a Meteor backend
Created: 2016-01-20 01:55:15.0
Updated: 2016-09-03 07:05:15.0
Pushed: 2016-08-31 10:40:28.0
Homepage: http://mondora.github.io/asteroid
Size: 639
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Example todo app using AngularJS. Same app using Meteor's front-end.
A javascript client (browser and node) for a Meteor backend.
Advantages over the canonical Meteor front-end
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
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
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.
Download the package:
npm install asteroid
Require it in your project:
var Asteroid = require("asteroid");
onnect to a Meteor backend
ceres = new Asteroid("localhost:3000");
se real-time collections
s.subscribe("tasksPublication");
tasks = ceres.getCollection("tasks");
s.insert({
scription: "Do the laundry"
et the task
laundryTaskRQ = tasks.reactiveQuery({description: "Do the laundry"});
og the array of results
ole.log(laundryTaskRQ.result);
isten for changes
dryTaskRQ.on("change", function () {
nsole.log(laundryTaskRQ.result);
ogin your user
s.loginWithTwitter();
all method and use promises via the Q library
ret = ceres.call('newUser');
result
hen(function (result) {
nsole.log('Success:', result);
atch(function (error) {
nsole.error('Error:', error);
Please refer to the Q documentation for more information about handling promises.
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.
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.
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!
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.
host string required: the address of the Meteor
server, e.g. example.meteor.com
ssl boolean optional: whether to use SSL. Defaults
to false.
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).
An Asteroid instance.
Registers an event handler for the specified event.
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.
Nothing
Logs the user in via the specified third party (oauth) service.
facebook: loginWithFacebook
google: loginWithGoogle
twitter: loginWithTwitter
github: loginWithGithub
A promise which will be resolved with the logged user id if the login is successful. Otherwise it'll be rejected with the error.
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.
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 into user.profile.
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.
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.
usernameOrEmail string required: the username or
email.
password string required: the password.
A promise which will be resolved with the logged user id if the login is successful. Otherwise it'll be rejected with an error.
Logs out the user.
None
A promise which will be resolved with if the logout is successful. Otherwise it'll be rejected with the error.
Subscribes to the specified subscription. If an identical subscription (same name and parameters) has already been made, Asteroid will return that subscription.
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.
A subscription instance.
Subscription instances have the following properties:
id string: the id of the subscription, as
returned by the ddp.sub method
ready promise: a promise which will be resolved with
the id of the subscription if the subscription succeeds
(we receive the ddp ready message), or will be rejected
if it fails (we receive, upon subscribing, the nosub
message).
And the following method:
stop: it takes no argument, sends the ddp unsub
message and deletes the subscription so it can be garbage
collected.Calls a server-side method with the specified 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.
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).
Same as Asteroid.call, but using as array of parameters instead of a list.
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.
Same as Asteroid.call, see above.
Creates and returns a collection. If the collection already exists, nothing changes and the existing one is returned.
name string required: the name of the collection to
create.A reference to the collection.
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
postscollection 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).
All the following methods use latency compensation.
Inserts an item into a collection. If the item does not
have an _id property, one will be automatically generated
for it.
item object required: the object to insert. Must
be JSON serializable. Optional support for EJSON is
planned.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.
Updates the specified item.
id string required: the id of the item to update.
item object required: the object that will
replace the old one.
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.
The API greatly differs from Meteor's API. Aligning the two is on the TODO list.
Removes the specified item.
id string required: the id of the item to remove.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.
Gets a “reactive” subset of the collection.
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.A ReactiveQuery instance.
The array of items in the collection that matched the query.
Registers a handler for an event.
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.