operations.js
Promises (e.g. q and libraries such as async.js are awesome but have limitations when it comes to defining complex dependencies between your chunks of code.
operations.js
is a library that allows us to create well defined operations which are wrappers around javascript functions. We can then express dependencies between them, compose them, place them on queues and cancel them at any point during their execution.
It is inspired by the NSOperation and NSOperationQueue classes in Apple's Cocoa framework.
Main features:
- Define asynchronous chunks of code as operations.
- Define dependencies between these operations.
- Cancellation of operations.
- Composite operations.
- Run these operations in queues.
- Limit number of operations running on each queue.
- Inter-queue dependencies between operations.
Contents
Usage
Single Operations
Operations can be created as follows:
var operation = { ;}; // Fired on completion, errors or otherwise.operation { console; // null console; // 'result'}; operationstart;
We can also give our operations a name:
var operation = 'Do some stuff...' { // Do some stuff...};
This is useful for logging and debugging.
Composite
Operations
var op1 = { // Do something. ;}; var op2 = { // Do something else. ;}; var compositeOperation = op1 op2; console; // true compositeOperation { console; // [undefined, 'result of something else']; console; // ['error', undefined]; console; // true} compositeOperationstart;
Functions
Composite operations can also be constructed using functions:
var { // Do something. console; // Reference to automatically generated Operation object. ;}; var { // Do something else. console; // Reference to automatically generated Operation object. ;}; var compositeOperation = op1 op2;
Cancellation
Operations can be cancelled by calling cancel
. You must handle this within the function that defines your operation, otherwise the operation will just run to completion.
var op1 = { while!thiscancelled // ... do some stuff. if finished ; }; op;
Dependencies
Operations can depend on other operations before starting.
var op1 = { // Do something. ;}; var op2 = { // Do something else. ;}; op2; op1start;op2start;
We can also indicate that a dependency must succeed:
op2; op1start;op2start;
In this case, op2
would fail if op1
failed.
Queues
We can construct queues of operations using an OperationQueue
.
var queue = 2; // Maximum 2 concurrent operations.queue;queuestart;
We can have multiple queues, with dependencies between operations on different queues:
var queue = 'A queue' 2;var anotherQueue = 'Another queue' 4; op2; queue;; queuestart;anotherQueuestart;
Events
Operations
Changes in properties on the observation object can be observed:
operation;
Queues
queue; queue;
Subclassing
For really complex operations it's probably more appropriate to subclass Operation
so that logic can be seperated out into multiple functions.
{ if !this return completion; Operation;} MyOperationprototype = Object; MyOperationprototype { this; this; ;}; MyOperationprototype { // ...}; MyOperationprototype { // ...}; var op = { // Completion.}; opstart;
Logging
We can enable logging at multiple levels enabling us to monitor things such as num operations running, num operations running per queue and the success and failure of operations.
Operation
OperationlogLevel = LogLevelsInfo; // Global log level for operations.op1logLevel = LogLevelsInfo; // Override on a per operation basis.
Example logs:
INFO [Operation]: "My operation" has started.
INFO [Operation]: "My other operation" has started.
INFO [Operation]: "My operation" was cancelled.
INFO [Operation]: "My other operation" failed due to failure/cancellation of dependencies: ["My operation"]
Queue
OperationQueuelogLevel = LogLevelsinfo; // Global log level for queues.queuelogLevel = LogLevelsInfo; // Override on a per queue basis.
Example logs:
INFO [OperationQueue]: "My queue" now has 1 running operation.
INFO [OperationQueue]: "My queue" now has 2 running operations.
INFO [OperationQueue]: "My queue" now has 2 running operations and 1 queued operation.
Testing
When testing code using operations its usually a good idea to ensure that tests do not clobber each other:
Installation
Browser
Include using script tag as normal:
Can also be installed via bower:
bower install operations --save
The classes are made available in the op
property of window
and hence are available globally as follows within the browser:
var Operation = opOperation OperationQueue = opOperationQueue Log = opLog;
NodeJS
Install via npm:
npm install operations --save
And then use as normal:
var operations = Operation = operationsOperation OperationQueue = operationsOperationQueue Log = operationsLog;
Contributing
To get started first clone the repository:
git clone git@github.com:mtford90/operations.js.git
Then install the dependencies:
cd operations.js && npm install && npm install grunt-cli -g
Tests
Run
We can run the tests by using:
grunt test
This will also build tests/index.html
. Opening this up in the browser will run the same tests in said browser.
Watch
We can watch for changes and automatically build and run the tests by using:
grunt watch
This is livereload enabled, so we can automatically run the tests in the browser and in the console for NodeJS at the same time.
Cross browser
Saucelabs is used for cross-browser testing. These tests are automated via a Travis build but can also be executed via a grunt task provided that you have a Saucelabs account.
First of all setup environment variables with your saucelabs username and API key. This can be placed in your .bashrc file:
export SAUCE_USERNAME=...export SAUCE_ACCESS_KEY=...
Then run the grunt task:
grunt testSauce
And then head over to https://saucelabs.com/account where you'll see the tests executing.
AngularJS bindings
Coming soon to a repo near you: https://github.com/mtford90/operations.angular.js