glow

A Grit plugin to make async property access simple. Based on Heavy Flow.

GLOW

A fluid flow-control plugin for Grit, based on Heavy Flow.

Watch

function alertNameAsync(model) {
    var firstName = model.siphon('firstName');
    var lastName = model.siphon('lastName');

    flow.wait(firstName, lastName, function(finish, cancel) {
        alert('' + firstName.data() + ' ' + lastName.data());
        finish();
    });
}

Even if looking up firstName and lastName takes six async network requests and a 3000 millisecond timeout, that alert will run. And despite being non-blocking, it all looks beautifully synchronous.

You can also chain siphon from the flow control objects returned by siphon calls. So, for example:

function alertChildName(model) {
    var firstName = model.siphon('child').siphon('firstName');
    var lastName = model.siphon('child').siphon('lastName');

    flow.wait(firstName, lastName, function(finish, cancel) {
        alert('' + firstName.data() + ' ' + lastName.data());
        finish();
    });
}

Sometimes, though, you might not want to access a property until something has happened, or dependencies have been satisfied. Glow gives you a fluid interface for more fine-grained async access, even with multiple dependencies.

function alertDependent(dependency1, dependency2, model) {
    var mystery = grit.waitFor(dependency1, dependency2).andGet('ham').from(model);

    flow.wait(mystery, function(finish, cancel) {
        alert('Request finished but what is this?\n' + mystery.data());
        finish();
    });
}

waitFor chains return the same type of flow-control objects as siphon calls do -- the only difference is that waitFor allows you to specify dependencies fluidly. This means that siphon is available on any objects returned from a waitFor chain, so that you can chain siphon calls onto dependent chains. For example:

function chainedCall(dependency, model) {
    var points = grit.waitFor(dependency).andGet('user').from(model).siphon('points');
    flow.wait(points, function(finish, cancel) {
        alert('' + points.data());
        finish();
    });
}

API

• siphon(property) is a method added to Grit's Model class. siphon returns a Heavy Flow flow-control object, much like what you'd get from a flow.wait() call. siphon objects will run immediately, with no dependencies, and will finish as soon as the given property is successfully fetched from the model. If the property access fails, the flow control object will cancel. siphon is also available directly from flow control objects created by a siphon or Glow waitFor fluid interface call, so that you can chain siphon calls together to get properties from child models.

• waitFor(dependencies...).andGet(property).from(model) is the fluid interface for fine-grained access of properties on models. Like siphon, the fluid chain will return a Heavy Flow flow-control object; however, it will only run once all dependencies have been satisfied. siphon is available on any flow-control objects returned from a waitFor chain. The model argument can be a Grit Model (or subclass), but can also be a function that returns a model when called. If a function is passed in, the function will only be called after the dependencies are satisfied, which allows you to use data from the dependencies inside the model function.

• waitFor.nothing().andGet(property).from(model) is similar to the above, but does not wait for any dependencies. The only difference between this and the much more concise siphon(property) method is that the model argument can be a function that returns a model, like the above, rather than a model accessible at definition time.

LICENSE

GPL v3. See LICENSE.txt and "GNU General Public License".txt for details.