Introduction

Command factory

Stores have a simple wrapper function that acts as a type-safe factory for creating new commands.

To create a store factory:

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';

const createCommand = createCommandFactory<State>();

const myCommand = createCommand(({ at, get, path, payload, state }) => {
	return [];
});

createCommand ensures that the wrapped command has the correct typing and the passed CommandRequest functions get typed to the State interface provided to createCommandFactory. While it is possible to manually type commands, the examples in this guide use createCommand.

path

The path is a string that describes the location where an operation gets applied. The path function is part of the CommandRequest and is accessible inside of a Command.

In this example the path describes a location in the store. The State is the same as defined above in interface.d.ts. The State interface gets used by the Store to understand the shape of the state data.

To define a path for the current user name:

const store = new Store<State>();
const { path } = store;

path('users', 'current', 'name');

This path refers to the string value located at /users/current/name. path gets used to transverse the hierarchy in a type-safe way, ensuring that only the property names defined in the State interface get used.

at

The at function gets used in conjunction with path to identify a location in an array. This example leverages the at function.

const store = new Store<State>();
const { at, path } = store;

at(path('users', 'list'), 1);

This path refers to the User located at /users/list at offset 1.

add operation

Adds a value to an object or inserts it into an array.

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';
import { add } from '@dojo/framework/stores/state/operations';

const createCommand = createCommandFactory<State>();
const myCommand = createCommand(({ at, get, path, payload, state }) => {
	const user = { id: '0', name: 'Paul' };

	return [add(at(path('users', 'list'), 0), user)];
});

This adds user to the beginning of the user list.

remove operation

Removes a value from an object or an array.

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';
import { add, remove } from '@dojo/framework/stores/state/operations';

const createCommand = createCommandFactory<State>();
const myCommand = createCommand(({ at, get, path, payload, state }) => {
	const user = { id: '0', name: 'Paul' };

	return [
		add(path('users'), {
			current: user,
			list: [user]
		}),
		remove(at(path('users', 'list'), 0))
	];
});

This example adds an initial state for users and removes the first user in the list.

replace operation

Replaces a value. Equivalent to a remove followed by an add.

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';
import { add, replace } from '@dojo/framework/stores/state/operations';

const createCommand = createCommandFactory<State>();
const myCommand = createCommand(({ at, get, path, payload, state }) => {
	const users = [{ id: '0', name: 'Paul' }, { id: '1', name: 'Michael' }];
	const newUser = { id: '2', name: 'Shannon' };

	return [
		add(path('users'), {
			current: user[0],
			list: users
		}),
		replace(at(path('users', 'list'), 1), newUser)
	];
});

This example replaces the second user in the list with newUser.

get

The get function returns a value from the store at a specified path or undefined if a value does not exist at that location.

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';
import { remove, replace } from '@dojo/framework/stores/state/operations';

const createCommand = createCommandFactory<State>();

const updateCurrentUser = createCommand(async ({ at, get, path }) => {
	const token = get(path('auth', 'token'));

	if (!token) {
		return [remove(path('users', 'current'))];
	} else {
		const user = await fetchCurrentUser(token);
		return [replace(path('users', 'current'), user)];
	}
});

This example checks for the presence of an authentication token and works to update the current user information.

payload

The payload is an object literal passed into a command when it is called from a process. The payload's type may be defined when constructing the command.

import { createCommandFactory } from '@dojo/framework/stores/process';
import { State } from './interfaces';
import { remove, replace } from '@dojo/framework/stores/state/operations';

const createCommand = createCommandFactory<State>();

const addUser = createCommand<User>(({ at, path, payload }) => {
	return [add(at(path('users', 'list'), 0), payload)];
});

This example adds the user provided in the payload to the beginning of /users/list.

Asynchronous commands

Commands can be synchronous or asynchronous. Asynchronous commands should return a Promise to indicate when they finish. Operations are collected and applied atomically after each command completes successfully.

Creating a process

First, create a couple commands responsible for obtaining a user token and use that token to load a User. Then create a process that uses those commands. Every process must be identified by a unique process ID. This ID is used internally in the store.

import { createCommandFactory, createProcess } from "@dojo/framework/stores/process";
import { State } from './interfaces';
import { add, replace } from "@dojo/framework/stores/state/operations";

const createCommand = createCommandFactory<State>();

const fetchUser = createCommand(async ({ at, get, payload: { username, password } }) => {
	const token = await fetchToken(username, password);

	return [
		add(path('auth', 'token'), token);
	];
}

const loadUserData = createCommand(async ({ path }) => {
	const token = get(path('auth', 'token'));
	const user = await fetchCurrentUser(token);
	return [
		replace(path('users', 'current'), user)
	];
});

export const login = createProcess('login', [ fetchUser, loadUserData ]);

payload type

The process executor's payload is inferred from the payload type of the commands. If the payloads differ then it is necessary to explicitly define the payload type.

const createCommand = createCommandFactory<State>();

const commandOne = createCommand<{ one: string }>(({ payload }) => {
	return [];
});

const commandTwo = createCommand<{ two: string }>(({ payload }) => {
	return [];
});

const process = createProcess<State, { one: string; two: string }>('example', [commandOne, commandTwo]);

process(store)({ one: 'one', two: 'two' });