A javascript client (node) for a Meteor backend.
2.x.x
is out, find out what changed in the CHANGELOG
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:
- hook any existing application to a real-time meteor API
- use any front-end framework you want with a Meteor backend
- develop browser extensions backed by Meteor
- use Meteor as a backend for a react-native app
- 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
npm install --save asteroid
import {createClass} from "asteroid";
const Asteroid = createClass();
// Connect to a Meteor backend
const asteroid = new Asteroid({
endpoint: "ws:https://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 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.
ddp
: establishes the ddp connectionmethods
: adds methods for invoking ddp remote methodssubscriptions
: adds methods for subscribing to ddp publicationslogin
: adds methods for logging inpassword-login
: adds methods for password logins / user creation
- asteroid-immutable-collections-mixin: stores collections published by the server into an immutable map
- asteroid-oauth-mixin: allows logging in via oauth
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.
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.
Create the Asteroid
class. Any passed-in mixins will be added to the default
mixins.
mixins
Array< object > optional: mixins you want to use
The Asteroid
class.
Creates a new Asteroid instance (which is also an EventEmitter
).
On instantiation:
- the
ddp
mixin will automatically connect to the Meteor backend - the
login
mixin will try to resume a previous session
options
object required:endpoint
string required: the DDP endpoint to connect to, e.g.ws:https://example.com/websocket
SocketConstructor
function optional [default:WebSocket
]: the class to be used to create the websocket connection to the server. In node, usefaye-websocket-node
'sClient
. In older browsers which do not supportWebSocket
, usesockjs-client
'sSockJS
autoConnect
boolean optional [default:true
]: whether to auto-connect to the server on instantiation. Otherwise theconnect
method can be used to establish the connectionautoReconnect
boolean optional [default:true
]: wheter to auto-reconnect when the connection drops for whatever reason. This option will be ignored - and the connection won't be re-established - if the connection is terminated by calling thedisconnect
methodreconnectInterval
number optional [default: 10000]: the interval in ms between reconnection attempts
An Asteroid instance.
Provided by the ddp
mixin.
Establishes a connection to the ddp server. No-op if a connection is already established.
None.
Nothing.
Provided by the ddp
mixin.
Terminates the connection to the ddp server. No-op if there's no active connection.
None.
Nothing.
Provided by the methods
mixin.
Calls a server-side method with the specified arguments.
method
string required: the name of the method to callparam1, param2, ...
...any optional: parameters passed to the server method
A promise to the method return value (the promise is rejected if the method throws).
Provided by the methods
mixin.
Same as call
, but using as array of parameters instead of a list.
method
string required: the name of the method to callparams
Array< any > optional: an array of parameters passed to the server method
Same as call
, see above.
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).
-
name
string required: the name of the publication -
param1, param2, ...
...any optional: a list of parameters that are passed to the publication function on the server
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:
ready
: emitted without parameters when the subscription is marked asready
by the servererror
: emitted with the error as first and only parameter when the server signals an error occurred on the subscription- TODO
stopped
: emitted when the subscription stops
Provided by the subscriptions
mixin.
Unsubscribes from a publication.
id
string required: theid
of the subscription
Nothing.
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.
options
object required:username
string optionalemail
string optionalpassword
string required
Note: you must specify either options.username
or options.email
.
A promise which resolves to the userId
of the created user when the creation
succeeds, or rejects when it fails.
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.
options
object required:username
string optionalemail
string optionalpassword
string required
Note: you must specify either options.username
or options.email
.
A promise which resolves to the userId
of the logged in user when the login
succeeds, or rejects when it fails.
Provided by the login
mixin.
Log in the user.
params
object required: params to pass for login with a custom provider
A promise which resolves to the userId
of the logged in user when the login
succeeds, or rejects when it fails.
Provided by the login
mixin.
Logs out the user.
None
A promise which resolves to null when the logout succeeds, or rejects when it fails.
connected
(emitted by theddp
mixin)disconnected
(emitted by theddp
mixin)loggedIn
(emitted by thelogin
mixin)loggedOut
(emitted by thelogin
mixin)