Advice on creating asynchronous calls that depend on each other

Question

I am attempting to create a library to make API calls to a web application (jira, if you care to know) I have my api calls working no problem, but I am looking to make the code a bit more readable and use-able. I have tried searching for my needs, but it turns out I am not sure what I need to be searching for.

I am having an issue with Asynchronous calls that depend on each other, I understand that I have to wait until the callback is ran to run my next item, but I am not sure of the best way to design this.

I really would like to make Chaining a feature of my api, which I would hope to look like this:

createProject(jsonProjectStuff)
  .setLeadUser("myusername")
  .createBoard("boardName")
     .setBoardPermissions(boardPermissionJSONvar)
  .addRole(personRoleJSONvar);

with this example, everything would have to wait on the createProject as it will return the project. createBoard doesn't rely on the project normally, but used in this context it should be "assigned" to the project made, setting the board permissions only relies on the createBoard to work. addRole is specific to the project again.

the questions I have are:

1. Is this possible to switch context like this and keep data in-between them without the need to run the function from the response hard coded?
2. If this is possible, is this a good idea? If not I am open to other schemes.

I can think of a couple ways to make it work, including registering the function calls with a dependency tree and then fulfilling promises as we go, although that is mostly conceptual for me at this point as I am trying to decide the best.

Edit 2/19/2016

So I have looked into this more and I have decided on a selective "then" only when it creating a new item doesn't relate directly to the parent.

//Numbers are ID, string is Name
copyProject(IDorName)
  .setRoles(JSONItem)
  .setOwner("Project.Owner")
  .setDefaultEmail("noreply@fake.com")
  .then(
     copyBoard(IDorName)
       .setName("Blah blah Name {project.key}"),

     saveFilterAs(IDorName, "Board {project.key}", 
                  "project = {project.key} ORDER BY Rank ASC")
       .setFilterPermissions({shareValuesJSON})
   )

I like this solution a lot, the only thing I am unsure of how to do is the string "variables", I suppose it could be "Blah blah Name " + this.project.key either way I am unsure of how to give copyBoard or saveFilterAs access to it via the "then" function.

Any thoughts?

Answer 1

I've been using Nightmare (a headless browser) lately.

It has a fluent API that uses a nice design pattern.

Calling the API doesn't directly execute the actions, it only queues them and when you are ready to execute you must call the end function which returns a promise. The promise is resolved when the queue has completed its async execution.

For example, in your situation

createProject(jsonProjectStuff)
    .setLeadUser("myusername")
    .createBoard("boardName")
    .setBoardPermissions(boardPermissionJSONvar)
    .addRole(personRoleJSONvar)
    .end() // Execute the queue of operations.
    .then() => {
        // All operations completed.
    ))
    .catch(err => {
        // An error occurred.
    });

I feel like this pattern is quite elegant. It allows you to have a fluent API to build a sequence of actions. Then when you are ready to execute said operations you call end (or whatever). The sequence of operations are then completed asynchronously and you use the promise to handle completion and errors.