A function executes once all its arguments are evaluated. console.log executes once its single argument wait.for(...) is evaluated. Hence: No, it will not execute immediately.

wait.for, waits for fs.readfile to callback, and returns "data" from callback(err,data)

wait.for(fs.readfile,'/etc/passwd') == fs.readfileSync('/etc/passwd')

wait.for allows you to call any async function as if it were a sync function, without blocking node's event loop. It works inside a fiber. Check the examples.

Right, but how the heck is this achieved? Could you show a line or two of example pseudo code that demonstrates the core of this functionality?

-pseudo code-

  function wait.for ( asyncFn, params ) {

    //call the async fn, returns immediately
    asyncFn(params, function(err,data){
               //here the data is ready
               thisFiber.err = err;
               thisFiber.data = data;
               thisFiber.resume(); //resume execution (after yield())
    });

    //we're in a fiber, so we can yield() to node's event loop 
    thisFiber.yield(); //pause here, give back control to node's event loop
    
    // the next line will be executed when thisFiber.resume() is called
    if (thisFiber.err) throw thisFiber.err; // throw into the caller of wait.for
    return thisFiber.data; //ok
  }

It uses Fibers (https://github.com/laverdet/node-fibers). I don't know much about it, but you have to wrap all your code in a call to `Fiber()`, which is written in C++.

Fiber() is under the hood, and I hope ES6 generators -when stable- will provide similar tools, so wait.for could be based on ES6 generators.

You don't have to wrap all your code in a call to `Fiber()`

full classic node-server sample:

    var http=require('http'), wait=require('wait.for');

    http.createServer(function(req, res) {
      wait.launchFiber(handleRequest,req, res); //run in a Fiber, keep node spinning
    }).listen(8080);


   //in a fiber
   function handleRequest(req, res) {
     try {
       res.writeHead(200, {'Content-Type': 'text/html'});
       res.end(
       "<h1>Demo page</h1>" 
       + "<p>"+ wait.for(fs.readFile,'/etc/somefile') +"</p>"
       + "<p>"+ wait.for(fs.readFile,'/etc/otherfile') +"</p>");
     }
     catch(err) {
      res.end('error '+e.message); 
     }
   }

in your example below, you do have to wrap it in a call to `Fiber()`, although you've disguised it as `launchFiber`, which you pass `handleRequest` to (I would call that wrapping `handleRequest`.

That is probably a worthwhile tradeoff, but the first time I read through it, that mechanic wasn't obvious to me.

It's not 'disguised', it's abstracted. launchFiber does what it's name implies: launchs a fiber. How it is achieved 'internally', it's irrelevant as long the abstraction is not leaky.

Today launchFiber is calling the fn inside a Fiber(), tomorrow could be launching the fiber by means of a generator.

The idea was to create a very simple abstraction to avoid callback hell, adding low or no complexity, and keeping the flexibility to use all the existing async fns with a callback or just "wait" for the results.

fibers are lightweight threads, employing a sort of non-preemptive multitasking paradigm. it basically spawns a 'thread' that will be resumed only when the callback has returned, which returns the data passed to the callback.

the code is here: https://github.com/luciotato/waitfor/blob/master/waitfor.js, but it does require fibers.

The code is open source and only 72 lines long (with comments and whitespace).