Using setImmediate function for API

This is a common question about using setImmediate (or other similar solutions) for API purposes. I am writing a node.js library that does server negotiation behind the scenes. The client code of this library looks like this:

var request = myLib
    .createRequest()
    .setRequestProperty('someProperty', someValue)
    .setAnotherRequestProperty('anotherProperty', anotherValue)
    .performRequest(function callback() {
         var someValue = request.someValue;
         var requestResult = request.result;
         // Some logic based on requestResult and someValue
    });

      

        
        
        
      

    

The problem starts when my library doesn't need to do or wait for any negotiations with the server, so it can immediately call the callback passed to performRequest

. The internal library code might look like this:

Request.prototype.performRequest = function performRequest(callback) {
    if (this._canPerformImmediately()) {
        callback();
        return this;
    }

    this._performServerRequest().then(callback);
    return this;
};

      

        
        
        
      

    

What happens is that the request is still undefined (since the callback is called before the outer statement contains the request's destination is complete).

I wonder how to correctly define the API in such cases. I see some possibilities:

• Determine that the callback can be called synchronously (as described above), and therefore the client code cannot use the variable request
  
  as in the client code example above. However, I have seen code that looks like above, so I think this is not a solution.

• Determine that the callback can be called synchronously and that the request is passed to the callback as well, so the client code could be (note the use request_
  
  instead of request
  
  ):

  .performRequest(function callback(request_) {
      var someValue = request_.someValue;
      var someResult = request_.result;
      // Some logic based on requestResult and someValue
  }
  
        
  
          
          
          
        
  
      

  ( EDIT : The request can also be passed as an argument this
  
  ).

  But then again, since I saw some code that seems like the first example, I guess this is not a solution either.

• Ensure the callback is called ASYNCHRONOUSLY. Then we can use the setImmediate functions . The internal implementation would then look like (Note the call setImmediate
  
  ):

  Request.prototype.performRequest = function performRequest(callback) {
      if (this._canPerformImmediately()) {
          setImmediate(callback);
          return this;
      }
  
      this._performServerRequest().then(callback);
      return this;
  };
  
        
  
          
          
          
        
  
      

• Any other suggestions?

It seems that the setImmediate alternative is the most appealing, but I haven't been able to find a discussion about using it just to look at the API. I've seen discussions about performance like here and here , but no API considerations.

So my question is, what is the correct way to implement such a library?