Service.js
Service.js is a library for managing abstractions over how your program interacts with the outside world.
A "service" is an interface to some global funcationality. Examples would be error reporting, data persistence, API abstraction, performance monitoring, audio playback abstraction, even DOM manipulation abstraction.
An "implementation" of a service is an object that implements the service's interface and registers itself with the services library. There may be multiple implementations of a service, the priority is determined by the order of registration.
An "instance" of a service is a particular implementation that's been
instantiated, intialized, and (usually) started. Instances are what the
application code actually uses and can be accessed by calling Services.ready.
An example should help clear this up.
Example Usage
In this example, we have two implementations of the "Socket" service, which the
pubsub service uses to actually accomplish sending and receiving messages.
The SocketService service uses websockets and registers itself first, thereby
having a higher priority. However, if the client doesn't have WebSockets, the
PollingService implementation of 'Socket' will be started instead.
// Web socket implmentation of 'Socket'
var WebSocketService = Object.create(Services.Service);
WebSocketService.isUsable = function() {
return 'WebSocket' in window;
};
Services.register('Socket', WebSocketService);
// Polling implementation of 'Socket'
var PollingSocketService = Object.create(Services.Service);
Services.register('Socket', PollingSocketService);
// Implementation of pubsub (there's only 1 in the example)
var Pubsub = Object.create(Services.Service);
Pubsub.onStart = function() {
return Services.ready('Socket');
}
Pubsub.publish = function() { /* publish stuff */ }
Pubsub.subscribe = function() { /* subscribe to stuff */ }
Services.register('Pubsub', Pubsub);
// Later, in application code
// This is usually called once after all services are registered and your app
// is ready to start. In `window.onload` for instance.
Services.start();
// Anywhere in your app where you need to use a service, you can get access
Services.ready('Pubsub').spread(function(pubsub) {
// `pubsub` is an instance of the Pubsub service implementation
pubsub.publish('up and running!');
});
There is complete API documentation available.
Using the library
Service.js relies heavily on the Q promise library. The AMD build declares the dependency, and the package.json file does as well. If you're just using script tags, you'll need to include the library.
The library also relies on some ECMAScript 5 Object APIs, so if you want it
to work in older browsers you'll need to include a polyfill.
In a browser
Just include build/service.min.js in a script tag. Then Services will be
globally available.
The minified version is < 2k in size and < 1k when gzipped.
If you use AMD
- Copy build/service.amd.js to the appropriate place in your application, rename it service.js.
- Then you can just
require(['service'] function(Services) {}to your heart's content.
In Node.js
npm install service-js
Then in your app all you need to do is require it:
var Services = require('service-js');
Development
Running tests
make test
Building a release
make release
Files will end up in the build directory.
