Async Guide

What is an Async?

Async are just promises that are executed lazily.

A promise wraps a piece of asynchronous code and resolves the value from the code when it's done.

Here is what a promise would look like.

new Promise(promiseExecutor)
    .then(successHandler)
    .catch(errorHandler)
    .finally(cleanupHandler);

And in Async.apex:

new Async(new CustomAsyncExecutor())
    .then(new SuccessHandler())
    .error(new ErrorHandler())
    .done(new CleanupHandler())
    .fork();

Async Status

Async has three statuses.

Normally a new Async is set with status as pending. When the execution is successful, Async status changes to fulfilled. Otherwise, it changes to rejected.

Async Trigger

Async is a lazy promise and it is only triggered when fork is invoked.

new Async(new AsyncFunc())
    .fork(); // pull the trigger

Async Chaining

We can chain asynchronous codes by returning a new Async in then/error/done.

new Async(new AsyncCode1()) // Code in AsyncCode1 is executed asynchronously
    .then(new AsyncCode2()) // AsyncCode2 needs to return a new Async that wraps the code to be executed asynchronously
    .fork();

Limitations

Async.apex uses Apex queueable jobs behind the scene. So all limitations on Apex queueable jobs also apply to Async.apex.