DEV Community: Andrew Courtice

Cancelling network requests using Harlem actions

Andrew Courtice — Wed, 10 Nov 2021 07:03:23 +0000

Cancelling asynchronous tasks isn't necessarily a topic that comes up all too often in the JavaScript world but anyone who has ever attempted to come up with an elegant cancellation pattern will know it's a little more difficult to implement than it seems on the surface.

In a lot of cases not cancelling stale asynchronous tasks has few consequences, but in that case of network requests this can lead to unexpected behaviour such as race conditions.

This issue can be further complicated when network requests are spawned from a state management system where the result of the request is assigned to state. If uncancelled requests are allowed to complete, they may finish in an order you may not anticipate and thus corrupt your application state.

Thankfully these days we have the AbortController which can be used as a cancellation token for things like network requests and DOM event listeners.

In this article I will explain how Harlem leverages the AbortController to create a robust and elegant async cancellation pattern through the use of actions.

What is Harlem

I won't go into a great amount of detail here but in a nutshell Harlem is a simple, unopinionated, lightweight and extensible state management solution for Vue 3. It's suitable for applications and architectures of all sizes, and if you're a TypeScript user then you will feel right at home.

Head on over to the Harlem docs to learn more or check out a demo of it in action here.

Installation

Let's start by installing a few packages:

npm install @harlem/core @harlem/extension-action
# or
yarn add @harlem/core @harlem/extension-action

Here's a quick summary of the packages we just added:

@harlem/core: this is the main Harlem package for creating and using a store in Vue
@harlem/extension-action: this extension adds async actions to your store

Harlem has a good selection of official extensions you can use to extend your stores with some powerful features such as cancellable actions, async getters, local/session storage sync, tracing etc.

You can also add the devtools plugin (@harlem/plugin-devtools) for inspecting your stores during development if you wish.

See here for the full list of official extensions and plugins for Harlem.

Once the above packages are installed you'll need to register Harlem with your Vue application:

import App from './app.vue';
import Harlem from '@harlem/core';
import devtoolsPlugin from '@harlem/plugin-devtools'; // Optional

createApp(App)
    .use(Harlem, {
        plugins: [
            devtoolsPlugin() // Optional
        ]
    })
    .mount('#app');

Creating a simple store

Once you've installed the packages and registered Harlem with your app it's time to create a store. Create a store.ts (or js) file somewhere in your app and add the following:

import actionExtension from '@harlem/extension-action';

import {
    createStore
} from '@harlem/core';

const STATE = {
    people: []
};

export const {
    state,
    getter,
    mutation,
    action,
} = createStore('starwars', STATE, {
    extensions: [
        actionExtension()
    ]
});

For more information on stores, getters, mutations etc. check out the Harlem docs.

Creating an action

Once we've got our store we can now add our action:

export const loadStarwarsCharacters = action('load-starwars-characters', async (_, mutate, controller) => {
    const response = await fetch('https://swapi.dev/api/people', {
        signal: controller.signal
    });

    const characters = await response.json();

    mutate(state => {
        state.characters = characters;
    });
});

Notice how we assign controller.signal to the signal property to the body of the fetch request.

Internally Harlem creates a new instance of an AbortController each time the action is run so that when an instance of the action is cancelled, any child actions or network requests can be synchronised and cancelled as well. See here for how Harlem uses the AbortController and makes it compatible with JavaScript's native async/await syntax.

The default behaviour for Harlem actions is to cancel running instances of actions upon subsequent calls. In other words, if you run the action 3 times consecutively and the first 2 instances haven't completed by the time the 3rd instance is started, Harlem will automatically abort the first 2.

To change this behaviour simply specify parallel: true in the action options like so:

export const loadStarwarsCharacters = action('load-starwars-characters', async (_, mutate, controller) => {
    // Our action body
}, {
    parallel: true
});

And that's all there is to it. You've now got a simple store that can handle complex async workflows as a first-class citizen as the application scales up.

For more information about actions in Harlem, how to check their status, advanced cancellation patterns or child actions, check out the actions extension documentation.

Have a great day and happy coding :)

Vue 3 State Management using Harlem

Andrew Courtice — Sat, 07 Nov 2020 05:26:05 +0000

Hi everyone

Recently I shared with you a weather app called Ocula which I built using Vue 3. Today I would like to announce another project I have been working on that was born out of Ocula. The project is called Harlem.

Harlem is a new state management solution for Vue 3 that aims to be intuitive, lightweight, immutable and extensible. I wrote Harlem because I wanted a simple state management solution that I could extend when necessary without having to incur the upfront cost in my bundle size for unused features. To achieve this Harlem is split into 2 distinct categories:

The core package
Plugins that extend core functionality

The core package gives you a nice functional API for managing state in your application by creating stores and using state/getters/mutations to interact with said stores. Let's take a look at an example of how to create a simple store using Harlem:

// store.ts

import {
    createStore
} from '@harlem/core';

const STATE = {
    firstName: 'John',
    lastName: 'Smith'
};

export const {
    state,
    getter,
    mutation,
    on,
    once
} = createStore('user', STATE);

The createStore function returns all the methods necessary to now safely interact with state. By default all access to state is immutable and can only be modified through mutations. This immutability ensures changes to your state are predictable and (most importantly) auditable.

Now that our store is created let's go ahead and define a simple getter for joining the first name and last name to output the user's full name.

// getters.ts

/*
The state parameter here is immutable and cannot be assigned to.
*/
export const fullName = getter('fullname', state => `${state.firstName} ${state.lastName}`);

Let's also define some mutations for updating the first and last name.

// mutations.ts

/*
The <string> generic tells harlem that we are expecting a payload of type string. This is optional and only applicable to TypeScript.

It's also worth noting that the state parameter here is the only place in Harlem that state is mutable.
*/

export const setFirstName = mutation<string>('setFirstName', (state, payload) => {
    state.firstName = payload ?? '';
});

export const setLastName = mutation<string>('setLastName', (state, payload) => {
    state.lastName = payload ?? '';
});

That's all there is to it. You now have managed state that can be imported into Vue components. Here's a quick example of how you could use the above store in a component:

<template>
    <div class="app">
        <h1>Hello {{ fullName }}</h1>
        <input type="text" v-model="firstName" placeholder="First name">
        <input type="text" v-model="lastName" placeholder="Last name">
    </div>
</template>

<script lang="ts">
import {
    defineComponent,
    computed
} from 'vue';

import {
    state,
    fullName,
    setFirstName,
    setLastName
} from './stores/user';

export default defineComponent({

    setup() {
        const firstName = computed({
            get: () => state.firstName,
            set: setFirstName
        });

        const lastName = computed({
            get: () => state.lastName,
            set: setLastName
        });

        return {
            firstName,
            lastName,
            fullName
        };
    }

});
</script>

From here you can extend Harlem through the use of plugins to include Vue devtools integration, server-side rendering, storage sync, transactions, snapshots and resetting.

Head over to the repo to see how to install Harlem, the list of available plugins, or even how to write and publish your own plugin. Alternatively you can go to harlemjs.com to see a live demo.

Thanks for reading and happy coding!

Ocula - A weather app built on Vue 3

Andrew Courtice — Thu, 24 Sep 2020 10:26:59 +0000

Hi Everybody

I wanted to share with you a project that I have been working on over the past few weeks: Ocula.

Ocula is a free PWA weather app written using the latest version of Vue. It is designed to look and feel native on mobile devices while also offering a nice desktop experience.

Some of the features include:

No location restrictions - available worldwide
Daily forecast for up to 7 days
Hourly forecast data for up to 24 hours
Trend charts for hourly temp, rainfall and wind
Interactive weather maps with 6 different map types (radar, precipitation, temp, cloud, wind, pressure)
Frame-by-frame playback for radar images to visualise incoming rain
Dark/Light Themes. Default theme changes based on current time of day
Options to reorder or hide forecast sections, set your preferred map type, units and more
Open-source, privacy friendly, and best of all - free

The app is currently in an alpha phase but I'm hoping to get some early feedback from the community to address some glaring bugs/UX issues.

Head over to app.ocula.io to check out the app and let me know what you think. The source is also available here.

Thanks!