State Designer / Core

This package includes the core functions of State Designer, a JavaScript state management library. Click here to learn more.

You can use this package in any JavaScript or TypeScript project.

For React projects, see @state-designer/react.

Installation

npm install @state-designer/core

# or

yarn add @state-designer/core

Usage

Using State Designer involves three steps:

1. Create a state with a configuration object.
2. Subscribe to the state's updates.
3. Send events to the state.

1. Creating a State

To create a new state, call the createState function and pass it a configuration object.

A configuration object defines everything about the state:

• what data it controls;
• how it should respond to events ; and
• how its child states are organized

const state = createState({
  data: { items: 0 },
  on: {
    ADDED_ITEM: {
      unless: (data) => data.items >= 10,
      do: (data) => void data.items++,
    },
    RESET: (data) => void (data.items = 0),
  },
})

The example below is just the start of what you can add to a state's configuration object. Click here to learn more.

2. Subscribing to Updates

To subscribe to a state's updates, call the state's onUpdate method and pass it a callback function to call with each new update.

An update includes:

• The state's current data
• An array of the state's active states
• The full state tree

state.onUpdate(({ data }) => {
  document.getElementById('itemsCount').textContent = data.items.toString()
})

3. Sending Events

To send an event to the state, call the state's send method.

The send method takes two arguments:

• The name of the event as a string
• A payload of any type (optional)

document.getElementById('reset_button').onclick = () => {
  state.send('RESET')
}

document.getElementById('plus_two_button').onclick = () => {
  state.send('ADDED_ITEMS', 2)
}

Example

import { createState } from '@state-designer/core'

// Create state
const state = createState({
  data: { items: 0 },
  on: {
    ADDED_ITEMS: {
      unless: (data, payload) => data.items + payload > 10,
      do: (data, payload) => void (data.items += payload),
    },
    RESET: (data) => void (data.items = 0),
  },
})

// Subscribe to updates
state.onUpdate(({ data }) => {
  document.getElementById('itemsCount').textContent = data.items.toString()
})

// Send events
document.getElementById('reset_button').onclick = () => {
  state.send('RESET')
}

document.getElementById('plus_two_button').onclick = () => {
  state.send('ADDED_ITEMS', 2)
}

API

createState

Creates a new state from a configuration object.

const state = createState({
  data: { items: 0 },
  on: {
    CLICKED_PLUS: 'increment',
  },
  actions: {
    increment: (data) => void data.count++,
  },
})

createDesign

Note: This function only exists to provide additional type support in TypeScript projects and in testing where multiple states need to use the same configuration object.

A helper function that creates a configuration object. The configuration provides several additional helpers for creating type-checked actions, events, and other parts of the object.

const config = createDesign({
  data: { items: 0 },
  on: {
    CLICKED_PLUS: 'increment',
  },
  actions: {
    increment: (data) => void data.count++,
  },
})

const state = createState(config)

| Helper | Description | | ------------------------------ | ----------------------------------------- | | createEventHandlerConfig | Creates an event handler config. | | createEventHandlerItemConfig | Creates an event handler item config. | | createAsyncEventHandlerConfig | Creates an async event handler config. | | createRepeatEventHandlerConfig | Creates a repeating event handler config. | | createStateConfig | Creates a state config. | | createActionConfig | Creates an action config. | | createConditionConfig | Creates a condition config. | | createResultConfig | Creates a result config. | | createTimeConfig | Creates a time config. |