@harlem/extension-compose

Harlem Compose Extension

The compose extension adds the ability to create simple read/write operations without having to explicitly define a mutation. This extension also helps to reduce boilerplate code in components when definining writable computeds that simply change a single state value.

Getting Started

Follow the steps below to get started using the compose extension.

Installation

Before installing this extension make sure you have installed harlem.

yarn add @harlem/extension-compose
# or
npm install @harlem/extension-compose

Registration

To get started simply register this extension with the store you wish to extend.

import composeExtension from '@harlem/extension-compose';

import {
    createStore
} from 'harlem';

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

const {
    state,
    getter,
    mutation,
    useState,
    computeState
} = createStore('example', STATE, {
    extensions: [
        composeExtension()
    ]
});

The compose extension adds several new methods to the store instance (highlighted above).

Usage

Basic

The most basic way to use the compose extension is to use the computeState method. The computeState method creates a writable computed by which you can read/write state directly. Take the following store as an example:

// store.ts
const {
    state,
    computeState
} = createStore('example', {
    details: {
        name: ''
    }
}, {
    extensions: [
        composeExtension()
    ]
});

If all you need to do is update the name field it can be cumbersome to write a mutation and a computed (in your component) just to update a simple field. Without the compose extension your code might look something like this:

// store.ts
const setName = mutation('set-name', (state, name) => state.details.name = name);

And in your component:

<template>
    <input type="text" v-model="name" />
</template>

<script lang="ts" setup>
import {
    state,
    setName
} from './store';

const name = computed({
    get: () => state.details.name,
    set: name => setName(name)
});
</script>

While it isn't a lot of code, it can still be cumbersome to write for lots of places where all you are doing is directly reading/writing state. The equivalent code using the compose extension would be:

// store.ts
// No mutation necessary :)

And in your component:

<template>
    <input type="text" v-model="name" />
</template>

<script lang="ts" setup>
import {
    computeState
} from './store';

const name = computeState(state => state.details.name);
</script>

This drastically simplifies basic read/write operations. For auditability purposes you can even still specify the mutation name so you can see it in the devtools - just specify the mutation name as the second argument to the computeState method:

const name = computeState(state => state.details.name, 'set-name');

If no mutation name is specified, one will be automatically generated from the path. In this case it would be: compose:root/details/name.

Advanced

The more advanced usage of the compose extension is using the useState method. The useState method is designed to mimic React's useState method (or SolidJS's createSignal). The useState method returns a tuple with a get method and a set method. Given the same store structure as above:

const [
    getName,
    setName
] = useState(state => state.details.name);

getName();
setName('Phil');

This is useful for having more granular control over the read/write cycle as opposed to a computed automatically updating when any dependencies change (in this case, name on state).

As with computeState, useState also accepts a mutation name as a second argument:

const [
    getName,
    setName
] = useState(state => state.details.name, 'set-name');

Considerations

Please keep the following points in mind when using this extension:

Avoid transforms in the accessor function

// This will work
computeState(state => state.details.name);

// This will not
computeState(state => state.details.name.split(' '));

Data structures still have readonly properties

const details = computeState(state => state.details);

// This will work
details.value = {
    name: 'Phil'
};

// This will not
details.value.name = 'Phil'
// Properties of the details object are still readonly
// This is the same for arrays, maps, sets etc.

Avoid explicitly defining indexes in the accessor function

// Although this is technically possible, it is strongly discouraged
const firstRoleId = computeState(state => state.details.roles[0].id);

// This will always update the id of the first item in the array
firstRoleId.value = 5;

Avoid traversing multiple branches of state in the accessor function

// This will generate an incorrect read/write path
const name = computeState(state => {
    const something = state.something.id;
    return state.details.name;
});

// Internally, Harlem uses a proxy object to determine which path in state you are traversing to
// Traversing multiple state paths in the accessor function will assume you are trying to access:
// something/id/details/name
// As opposed to just:
// details/name