mech-async

Provides mechanisms to support asynchronous calls like those in the mech-ajax and mech-mongo libraries.

See Mechanisms Home for more information and other libraries.

Supported Mechanisms:

• async - Support asynchronous calls.
• asyncify - Treats synchronous mechanisms and literals as asynchronous mechanisms.

No Fibers or Promises

The intent of the async mechanism library is to provide an easy way to do asynchronous call backs without the need for fibers or promises.

There is nothing fancy going on behind the scenes. Underneath, these mechanisms work by using traditional javascript callbacks.

Supported Mechanisms

Async Mechanism

A mechanism for supporting asynchronous calls (Ajax, reading files, accessing databases, etc).

Traditionally

Traditionally, asynchronous callbacks are handled using a function. The documentation for mongodb npm has some great examples. Provided is one of the examples:

var MongoClient = require('mongodb').MongoClient;
var url = 'mongodb://localhost:27017/myproject';
MongoClient.connect(url, function(err, db) {
  db.close();
});

Using The Async Mechanism

m.async takes three parameters:

• mech - The mechanism that will invoke an asynchronous call (ajax, mongo, async file access, etc.).
• dest (optional) - The destination where the result of the call is placed (TODO: along with any errors). Scoping is done via cell scoping or traditional stack scoping to name a few.
• bh (optional) - The mechanism to run when the asynchronous call completes.

Example:

// testdata.json on server
{
  "name" : "A Name",
  "age" : 23
}

// Run in a web browser
m.async(
  m.ajax.get("http://www.example.org/testdata.json"),
  m.cellRef("A:1"),
  m.writeLn(m.cellGet("A:1"))
).go; // returns immediately

For the above example, invoking go invokes an asynchronous ajax call: the first parameter. The call returns immediately but without a value.

When the ajax call is complete, m.async is notified and places the results in the mechanism configured in the second parameter.

• cellRef - this example is using the cell scoping mechanism. cellRef(id) returns a reference to cell A:1 where the result of the asynchronous call is then stored (TODO: along with any errors).
• stackRef - we could use stackRef(id) and the result would be placed on the stack.
• other - other scoping mechanisms people might implement. Really, anything you could imagine.

Finally, m.async executes the mechanisms (the policy) configured in the third parameter. This means, any and all behavior that needs to run within the asynchronous call result needs to be placed within the third parameter. This can be anything from tests (in a testing environment) to another asynchronous call.

See mech-ajax for more examples.

Asyncify

Allows synchronous mechanisms to act like asynchronous mechanisms. Note that results are returned immediately.

HINT: Great for testing. Use asyncify for mocking asynchronous calls.

// asyncify any mechanism
m.asyncify(m.add(14, 5)).go; // immediately returns 19

// asyncify a literal
m.asyncify("hello").go; // immediately returns "hello"

m.async will return an immediate value and still behave as if the call was asynchronous.

m.cell("A:1"); // cell to place async call value
m.async(
  m.asyncify(m.add(14, 5)),
  m.cellRef("A:1"),
  m.writeLn(m.cell("A:1"))
).go; // returns 19 immediately

Async will return 19 immediately, the value in cell A:1 (where the results of the asynchronous call are placed) is set to 19 and 19 is written to the console (m.writeLn is the mechanism m.async runs when the asynchronous call is complete).

Setup

Using In Your Projects

Change directory to your node project.

$ npm install --save mech-async

Development

Get Involved!

There are a lot of core mechanisms just waiting to be created. Many of them can be created in a few hours including in-depth tests. Clone mech-library to get started!

Setup

Install:

$ npm install

Continuous test:

$ gulp

Test:

$ gulp webtests

Test Server

Read documentation in gulpfile.js to see how to setup automated web testing.

$ gulp webserver