Registering State

Import

import { register } from "carry-on-store";

Define initial state

Initial state can be set by passing state to the register function. It is optional to register initial state.

State as a function

State can be defined by a function accepting one parameter. The parameter passed is a plain object containing the keys id, get, and set.

id is the store instance identifier. It will be undefined for the default store.

get is a function that actions use to query the current state.

set is a function that actions use to change state values.

The function must return an object representing the initial state:

const state = ({ id, get, set }) => ({
  counter: 0,
  inc: () =>
    set(state => {
      state.counter += 1;
    })
});

State as an object

State can also be defined as a plain object if there are no actions that require setting and querying state.

const state = {
  field1: "value1",
  field2: "value2",
  nested: {
    field1: "value1",
    field2: "value2"
  }
};

Actions

Actions are defined by functions inside the state object:

const state = ({ id, get, set }) => ({
  action1() {},
  action2() {},
  action3() {}
});

Get

When an action only needs read access to the current state, it uses the get function:

const state = ({ id, get, set }) => ({
  logValue() {
    get(state => {
      console.log("value is", state.value);
    });
  }
});

A shorter alternative:

const state = ({ id, get, set }) => ({
  logValue() {
    console.log("value is", get().value);
  }
});

Set

An action uses the set function to change state values.

const state = ({ id, get, set }) => ({
  field: "",
  setField(val) {
    set(state => {
      state.field = val;
    });
  }
});

Registration

State can be registered with a store instance at any time. If the store is not connected, the registration will be queued until the store is connected.

Register on default store:

Live Editor

register({ state: { counter: 0 } }); render(<StateInspector />);

register({ state: { counter: 0 } });

render(<StateInspector />);

Result

Loading...

Register on a named store:

Live Editor

const storeId = "Store1"; register({ state: { field1: "value1" } }, storeId); // or register(storeId, { state: { field2: "value2" } }); render(<StateInspector from="Store1" />);

const storeId = "Store1";

register({ state: { field1: "value1" } }, storeId);

// or

register(storeId, { state: { field2: "value2" } });

render(<StateInspector from="Store1" />);

Result

Loading...

Multiple registrations

Multiple calls

When register is called multiple times it merges state, potentially into a connected store:

Live Editor

const storeId = "multiCalls"; register(storeId, { state: { field1: "value1" } }); register(storeId, { state: { field2: "value2" } }); render(<StateInspector from={storeId} />);

const storeId = "multiCalls";

register(storeId, { state: { field1: "value1" } });

register(storeId, { state: { field2: "value2" } });

render(<StateInspector from={storeId} />);

Result

Loading...

Array of registrations

When registering more than one state, an array of registrations can be passed:

Live Editor

const storeId = "arrayOfRegistrations"; const state1 = { field1: "value1" }; const state2 = { field2: "value2" }; register(storeId, [{ state: state1 }, { state: state2 }]); render(<StateInspector from={storeId} />);

const storeId = "arrayOfRegistrations";

const state1 = { field1: "value1" };

const state2 = { field2: "value2" };

register(storeId, [{ state: state1 }, { state: state2 }]);

render(<StateInspector from={storeId} />);

Result

Loading...