</img>

What is Chained

Chained (home) is an experiment and a prototype library for Javascript I developed in the past weeks. It is meant to show a concept and to provide some limited but useful functionality. All the examples below are written in Coffeescript (and I guess that this makes me a hippie, right?).

Chained allows to chain functions explicitly — both those that return promises and those who don’t — without using then-based constructs.

For example, here’s how you could create a chained computation that:

Here, we have chained together promise-based functions (like get from jQuery) and normal functions with additional parameters (like map and filter from underscore). All function invocations receive an implicit argument that is the value computed by the previous link in the chain.

The function defined in getUser implements a processing pipeline (à la streaming). It starts with the link to be retrieved by specifying it with _():

_("https://npmjs.org/~#{user}")

this value is then passed to get() of jQuery. Chained knows that jQuery has a get method since we introduced its scope with

using(jQuery) 

at the beginning1.

The result of get() — i.e. the webpage — is sent to extractLinks (from linklib) when the associated promise is resolved. The rest of the computation proceeds as you can intuitively imagine.

If an exception is thrown in any of the links of the processing chain then the following links are not executed, just as you would expect from promises.

We can add additional arguments (besides the implicit one) to method invocations; for example the filter function (from underscore) is invoked as:

…
.filter( -> /package/.test(arguments[0]) )
…

where the lambda function is passed effectively as the second parameter to underscore.filter (the first being the implicit parameter).

So we nailed a few things here:

Where’s the catch?

We are exploiting ECMA6/harmony implementation of introspection. You need an ECMA6/harmony implementation, either in node (node --harmony) or in your browser (Firefox is ok at the moment) to make it work.

Does it work in the browser?

Yes, check out this example Domain Specific Language for form validation directly built with Chained. Warning: it needs a recent build of Firefox. In principle also a harmony-enabled Chrome should work, but I did not try it.

How to install it?

On node:

npm install chained

In the browser, download it from Github and include these files:

You should be good to go.

Implementation

The idea for Chained came while tinkering with domain specific languages. DSLs provide the developer with the vocabulary of a problem domain to express a programmatic solution that could be understood by a problem domain expert2.

I will not cover all the general concepts of DSLs here. For an in depth overview, I’d suggest to look at these resources:

Internal DSLs are built using the syntactic and semantic features of another language; they are used in the context of a broader application for which they address a narrow but important problem.

My quest was to find a way to implement a DSL in Javascript. Let’s see what features are needed by a general purpose language like Javascript to support the definition of internal DSLs:

At some point, it became clear to me that DSLs’ method chaining can be used to implicitly structure promise based chains. In fact, you could build a promise-chain by handling a sequence of method missing exceptions.

As a byproduct, it is straightforward to use the same technique to chain normal functions, without any exogenous construct like then.

The roadblocks

Javascript and its relatives (such as Coffee and LiveScript) have almost all the characteristics to build a sophisticated DSL. The only problem is that they lack of a method missing exception; at least until Harmony came out.

Dylan Barrell already demonstrated that with the new reflection API, it is possible to manage missing methods. His technique exploits the concept of Proxies. Think about a Proxy like a wrapper around your original object that is able to intercept calls to methods that are not defined. Chained is based on Dylan’s work.

The basic idea

The basic idea goes as follows:

  1. We create an object that can handle missing methods through an appropriate mechanism. Let’s call it o.

  2. o contains a promise property. Whenever a method missing is invoked on o:

     o.m()
    

    we catch it and handle it with the following handler:

     handleMethodMissing = (m) -> 
         this.promise = this.promise.then( (it) -> scope[m](it) )
         return this
    

    now, note that:

  3. We need a way to fire the very first promise off. In Chained, we use the function _() both for creating o and to resolve the first promise of the chain with the value passed to it:

     _(v) = -> 
          o = new methodMissingObject()
          o.deferred = defer()
          o.promise = o.deferred.promise
          o.deferred.resolve(v)
          return o
    

API

The API is pretty simple at the moment; however, I think it offers a good level of flexibility to be leveraged.

chain.using(module)
Extends the scope within which all missing methods are searched for. You can include multiple modules:
using(jQuery)
using(underscore)
o = chain._(value)
returns a deferred object whose promise property will eventually be resolved to value. The object handles missing methods by chaining them using Q.

Deferred object methods and properties

Given the deferred object o, the following methods apply; remember that they return again a deferred object:

o.foo(...)
if o eventually resolves to v, this is essentially equivalent to building a deferred foo(v, ...).
o._(foo)
specify a one shot function foo to be chained with the rest, without extending the scope with using.
o._forEach(bar)
if o will eventually resolve to an array, apply bar to each element; the combined promise is created with Q.all.
o.promise
this is a Q promise corresponding to the deferred o.

License

MIT

  1. The using clause extends the scope within which Chained looks for functions to be chained. 

  2. Make, SQL, CSS are all famous examples of DSLs widely used by developers.