// bsync

bsync makes using fibers and futures unbelievably easy. the syntax is dope and simple, particularly so if you're using CoffeeScript.

for the sake of convenience, bsync also wraps a variety of functions from caolan/async, making the syntax more usable from CoffeeScript (those double callback invocations were always sort of a mess in Coffee).

bsync relies upon laverdet/node-fibers for its under-the-hood magic.

examples

caolan/async wrappers

using one of bsync's wrappers for the functions in caolan/async, we end up with syntax that looks almost identical to the core javascript collection methods (like, say, Array.map), but with the huge bonus that it's still asynchronous!

bsync     = require 'bsync'
{fffiber} = bsync

fffiber ->
  try
    data = [12, 3, 4, 50]
    mapped = bsync.map data, (item, cb) -> cb(null, item * 10)
    console.log "Finished with bsync.map:", mapped
  catch err
    console.error "Error mapping random data to random other data:", err

any asynchronous function taking a callback with one return value

one of node's core fs functions:

fs                = require 'fs'
{fffiber, wwwait} = require 'bsync'

fffiber ->
  try
    exists = wwwait (resolve) -> fs.exists some_file, resolve
    console.log "The file #{some_file}", (exists ? 'exists' : 'does not exist')
  catch err
    console.error "Error in fs.exists:", err

using wwwait to grab image data using the imagemagick module:

imagemagick       = require 'imagemagick'
{fffiber, wwwait} = require 'bsync'

fffiber ->
  try
    {width, height} = wwwait (resolve) -> imagemagick.identify my_image_path, resolve
    console.log "The image dimensions are #{width}x#{height}"
  catch err
    console.error "Error in imagemagick module:", err

any asynchronous function taking a callback with multiple return values

wwwait can also take an array of argument names as its first parameter. this will cause it to spit out an object with callback values mapped to those names. coupled with CoffeeScript's destructuring assignment syntax, this makes for some EXTREMELY readable code.

mikeal's request module has a function request() that takes a callback with the signature callback(err, status, body). to capture status AND body, we can do the following:

request           = require 'request'
{fffiber, wwwait} = require 'bsync'

fffiber ->
  try
    {status, body} = wwwait ['status', 'body'], (resolve) -> request 'http://google.com', resolve
    console.log "The request returned status #{status}.  Body: #{body}"
  catch err
    console.error "Request spat out an error:", err

waiting on multiple fffutures at the same time

notice the difference between wwwait and wait (wait is simply the same wait() method as you'll find in the fibers/futures module).

request         = require 'request'
{wait, fffiber} = require 'bsync'

fffiber ->
  try
    img1 = fffuture ['status', 'image_data'], (resolve) -> request 'http://blah/image1.png', resolve
    img2 = fffuture ['status', 'image_data'], (resolve) -> request 'http://blah/image2.png', resolve
    img3 = fffuture ['status', 'image_data'], (resolve) -> request 'http://blah/image3.png', resolve
    wait [ img1, img2, img3 ]

    images = []
    images.push img1.get()
    images.push img2.get()
    images.push img3.get()

    if images[0].status is 200
      console.log "image1.png downloaded successfully"
      fs.writeFile './image1.png', images[0].image_data
      # etc ...
  catch err
    # ...

or for maximum compactness (same example as above):

request         = require 'request'
{wait, fffiber} = require 'bsync'

fffiber ->
  try
    wait futures = (fffuture ['status', 'image_data'], (resolve) ->
      request "http://blah/image#{i}.png", resolve) for i in [1...3]

    images = future.get() for future in futures

    for image, i in images when image.status is 200
      console.log "image#{i + 1}.png downloaded successfully"
      fs.writeFile "./image#{i + 1}.png", image.image_data
    # etc ...
  catch err
    # ...

kinda unbelievable, eh? love that coffeescript...

authors/contributors

bryn austin bellomy < [email protected] >

license (wtfpl v2)

DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE Version 2, December 2004

Copyright (C) 2004 Sam Hocevar <[email protected]>

Everyone is permitted to copy and distribute verbatim or modified copies of this license document, and changing it is allowed as long as the name is changed.

DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. You just DO WHAT THE FUCK YOU WANT TO.