Chaining vs. Promises

The Cloud CMS JavaScript driver provides it's own internal chaining library that makes it easier to manage callbacks in asynchronous JS applications.  The chaining library is powerful and bears some similarity to modern promise libraries.  But it is important to bear in mind that it is distinct apart from having some similar method signatures.

One similarity in structure in that both promises and chaining have a then() method to resolve the callback. However, the chaining library's chained methods do not hand back a promise. Rather, they hand back types that implement a Chainable interface. This allows the method signature to change so that you can do things like:

repository.readBranch("master").readNode("custom:approved_documents").then(function() {

Note that in the inner method, the "this" context is actually the node itself.

In a promise-based library, this code might work like this:

   .then(function(node) {

Or with a callback approach, it might work like this:

readRepository(repositoryId, function(err, repository) {
   readBranch(repository, "master", function(err, branch) {
      readNode(branch, "custom:approved_documents", function(err, node) {

Either way, the chaining approach reduces the amount of code by moving important functions onto base types for repository, branch and node. The chaining pattern allows the method signatures to change between method invocations, similar to Java or PHP.

The best place to look for documentation on chaining is usually within the driver itself. There are a number of test cases that related directly to pure chaining behavior independent of Cloud CMS. That said, we haven't promoted or documented the chaining portion of the driver as separate from the driver anywhere. They are one in the same.