Mutations ​

Mutations are the foundation of Harlem. A mutation is the only means by which state can be mutated. This is to ensure every change to state is predictable and auditable.

Mutations are simple functions that often take a payload in, mutate state, and (optionally) returns a result.

Defining a Mutation ​

const STATE = {
    name: 'John Smith',
    traits: []
};

const {
    mutation
} = createStore('user', STATE);

// This mutation takes a string payload and updates the name field
export const setName = mutation('setName', (state, payload: string) => {
    state.name = payload;
});

// This mutation takes a string payload, adds a trait to the list and returns it's id
export const addTrait = mutation('addTrait', (state, payload: string) => {
    const traitId = Symbol(payload);

    state.traits.push({
        id: traitId,
        value: payload
    });

    return traitId;
});

Harlem's default behaviour is to clone payloads before they are exposed to the mutation. Cloning the payload ensures the object is pure and strips any nested reactive references. For this reason it is recommended to use only simple objects as payloads.

Usage in components ​

To use a mutation just import it like any other function and call it with the expected payload type (if specified).

<template>
    <div class="app">
        <h1>Hello {{ name }}</h1>
        <input type="text" v-model="name" placeholder="Name">
    </div>
</template>

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

import {
    state,
    setName
} from './stores/user';

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