@mirego/houston

Houston is a library built by Mirego that gives you a Task primitive
to better handle async actions cancelation and concurrency.

> — Houston we have a problem!

> — Don’t panic, we’ll take care of every step of the procedure for you.

Concept

Houston gives you three things to handle complex async flows: Task, TaskInstance and Yieldable.

$3

Tasks are defined as generators with a little twist: yielding a Promise, a TaskInstance or a Yieldable will pause the execution until the operation is completed. You can see it as having an async function replacing await with yield. “Why generators instead of async/await?” you ask, well generators give us the ability to halt execution in the middle of an operation more easily when comes time to cancel a Task.

$3

TaskInstances are basically Promises on steroids: they can be canceled, they can cancel other tasks and yieldables and they can be scheduled to run at the moment you want. They are also promise-like which means they can be awaited just like any other promise.

$3

Yieldables are helper classes that help you wait on specific events: time passing, animationFrame, idleCallback, etc. You can even define your own yieldables if you ever need to wait on something we haven’t thought of!

$3

As we’ve established before, TaskInstances a promise-like and they can be canceled. But what happens when you cancel a TaskInstances?

Canceling a TaskInstance will skip then and catch callbacks but will run finally callbacks so that your cleanup logic is run

Installation

With npm:

``sh
npm install @mirego/houston
`

With Yarn:

`sh
yarn add @mirego/houston
`

Usage

$3

`ts
import { task } from '@mirego/houston';

const helloTask = task<[firstName: string, lastName: string], string>(
function* (firstName, lastName) {
return Hello ${firstName} ${lastName};
}
);

(async () => {
const returnValue = await helloTask.perform('John', 'Doe');

console.log(returnValue); // Outputs "Hello John Doe"
})();
`

$3

`ts
import { task } from '@mirego/houston';

const helloTask = task<[firstName: string, lastName: string], string>(
function* (firstName, lastName) {
return Hello ${firstName} ${lastName};
}
);

(async () => {
try {
const helloTaskInstance = helloTask.perform('John', 'Doe');

// The task could cancel all instances at once
// helloTask.cancelAll();

// Or you can cancel the individual instances
helloTaskInstance.cancel();

await taskInstance;
} catch (_error) {
// Do nothing
} finally {
// We’ll fall here since the task was canceled
}

console.log(returnValue); // Outputs "Hello John Doe"
})();
`

$3

#### The drop modifier

The drop modifier drops tasks that are .perform()ed while another is already running. Dropped tasks' functions are never even called.

Example use case: submitting a form and dropping other submissions if there’s already one running.

`ts
import { task } from '@mirego/houston';

const submitFormTask = task<[data: string]>({ drop: true }, function* (data) {
yield fetch(someURL, { method: 'post', body: data });
});

someForm.addEventListener('submit', async (event: SubmitEvent) => {
const serializedData = getDataFromForm(event.currentTarget);

// Even if the user submits the form multiple times, subsequent calls will simply be canceled.
await submitFormTask.perform(serializedData);
});
`

#### The restartable modifier

The _restartable_ modifier ensures that only one instance of a task is running by canceling any currently-running tasks and starting a new task instance immediately. There is no task overlap, currently running tasks get canceled if a new task starts before a prior one completes.

Example use case: debouncing an action. Paired with the timeout yieldable, a restartable task acts as a debounced function with async capabilities!

`ts
import { task, timeout } from '@mirego/houston';

const debounceAutocompleteTask = task<[query: string]>(
{ restartable: true },
function* (query) {
yield timeout(200);

const response = yield fetch(${someURL}?q=${query});
const json = yield response.json();

updateUI(json);
}
);

someInput.addEventListener('input', (event) => {
debounceAutocompleteTask.perform(event.currentTarget.value);
});
`

#### The enqueue modifier

The _enqueue_ modifier ensures that only one instance of a task is running by maintaining a queue of pending tasks and running them sequentially. There is no task overlap, but no tasks are canceled either.

Example use case: sending analytics

`ts
import { task, timeout } from '@mirego/houston';

const sendAnalyticsTask = task<[event: AnalyticsEvent]>(
{ enqueue: true },
function* (event) {
const response = yield fetch(someURL, { method: 'post', body: event });
}
);

// Somewhere else in the code
someButton.addEventListener('click', () => {
sendAnalyticsTask.perform({ type: 'some-button-click' });
});
`

#### The keepLatest modifier

The _keepLatest_ will drop all but the most recent intermediate .perform(), which is enqueued to run later.

Example use case: you poll the server in a loop, but during the server request, you get some other indication (say, via websockets) that the data is stale and you need to query the server again when the initial request completed.

`ts
import { task, timeout } from '@mirego/houston';

const pollServerTask = task({ keepLatest: true }, function* () {
const response = yield fetch(someURL);
const json = yield response.json();

update(json);
});

setInterval(() => {
pollServerTask.perform();
}, 10_000);

// Somewhere else in the code
pollServerTask.perform();
`

Inspiration

Houston was heavily inspired by ember-concurrency. Since working on non-Ember projects, the one thing we missed was ember-concurrency. Thank you to all the contributors who made this project possible!

License

Houston is © 2024 Mirego and may be freely distributed under the New BSD license. See the LICENSE.md` file.

The planet logo is based on this lovely icon by Vector Place, from the Noun Project. Used under a Creative Commons BY 3.0 license.

About Mirego

Mirego is a team of passionate people who believe that work is a place where you can innovate and have fun. We’re a team of talented people who imagine and build beautiful Web and mobile applications. We come together to share ideas and change the world.

We also love open-source software and we try to give back to the community as much as we can.