Memoblock

Write super-clean async code, with promises.

Rationale

Promises are a great invention to reduce "right-ward drift" as seen with code using regular node-style callbacks. It also eases error handling, relieving you from the necessity to check for errors after each asynchronous step.

However, I found code that goes further than merely processing return values in a chain (comparable to a regular synchronous function chain) still to noisy and cumbersome for my taste.

Memoblock is based on a chain of functions which each can get and set properties on a single memo object. This memo object essentially takes over the role of what normally be your local function scope. What makes Memoblock special is that any promise you assign to a property in one function, will be resolved to its fulfilled value when the next function is called.

This results in super-clean code, as you can see for yourself in the example below.

Usage

Using Memoblock is incredibly simple. You start a Memoblock with Memoblock.do. You pass it an array consisting of any number of functions. These functions are called in turn with the value of memo as both the function context (this) as well as the first argument for the function.

After any function has executed, the current properties of the memo object are inspected. If some of these properties are promises, Memoblock will wait until they are fullfilled. As soon as all promises are fulfilled, and a new the values of the memo object have been updated, the next function is called.

Memoblock.do returns a promise which is fulfilled when all functions have been executed, and any last promises set to properties of the memo object have been fulfilled as well.

If any promise assigned to a property of the memo object fails, no further functions will be executed, and the promise returned by Memoblock.do will fail.

How it's better

1. No need to define var's up-front in an outer function context. You can set any value you want.
2. No need to think about whether the value you set is a real value or rather a promise for a value. Functions that return a promise appear in the code without any added noise, and are included without any extra effort.
3. No need to assign any fulfilled value (normally passsed to of callback to then) to a variable in the outer function context. This will save you one line of code for any value of promise you need to have available further down in the chain.

Example

In this example, we attempt to build some kind of message piece by piece before sending it.

Memoblock = require "memoblock"
 
Memoblock.do([
  ->
    @name = "Meryn Stol" # real 
    @email = "[e-mail]" # real 
    @subject = consoleAPI.askForLine "Message subject" # promise 
  ->
    @body = consoleAPI.askForText "Message body" # promise 
    @location = locationAPI.guessFriendlyName() # promise 
  ->
    @blurp = "\n\nWritten in #{@location}" # real 
    @body = @body + @blurp
    @signature = signatureAPI.signMessage @name, @email, @subject, @body
  ->
    @date = new Date
  ->
    @mailResult = mailAPI.send @name, @email, @subject, @body + @signature
  ->
    console.log "Successfully sent your message '#{@subject}' at #{@mailResult.getFriendlyTime()}."
]).then null, (err) ->
  console.error err

Tips

Memoblock will only wait for promises set as properties on the memo object. If you want to wait for a promise that doesn't return a value to be fullfilled before moving on to the next step, just assign it to a property of the memo object. The value of the property in the next step will be undefined.

If you start a Memoblock inside an object method, then by default, this will be bound to the memo object.

If you want any other value for this, you can bind the function explicitly to a particular object. In CoffeeScript, you can easily bind the function to the outer context by using =>. You of course then need to have access to the memo object, which you do with (memo) => (or any other name). In JavaScript, you can use function(memo){}.bind(this).

Alternatively, you can assign the outer this to a local variable before you start a memoblock. This variable will then will be accessible as any other. This in particularly attractive in CoffeeScript, beacuse it keeps the super short syntax for assigning properties available.

self = this
Memoblock.do([
  -> @prop1 = "prop1"
  -> @prop2 = "prop2"
])

Credits

The initial structure of this module was generated by Jumpstart, using the Jumpstart Black Coffee template.

License

Memoblock is released under the MIT License.
Copyright (c) 2013 Meryn Stol