API

TwoAndEight

The abstract class that all stores must extend if you would like to use the following utility methods. The class also auto-binds your actions so you don’t need to use arrow functions or bind methods in the constructor.

class Store extends TwoAndEight {
  // ...
}

Fields

Custom fields are your state, and should only be mutated in your actions.

Methods

Custom methods are your actions, and should be used to mutate state.

There are also some in-built actions. All in-built actions will always be prefixed with a $ to avoid clashing with your own action names.

$emit

$emit(): void

Emit to subscribers early instead of waiting until the end of the action. This is useful in asynchronous actions where you may want subscribers to update before the async event has finished.

class Store extends TwoAndEight {
  isFetching = false

  async actionName() {
    this.isFetching = true
    this.$emit()
    await fetchThing()
    this.isFetching = false
  }
}

$reset

$reset(stateName?: string): void

Call this to reset the state to its original value. Use a state name to reset a single field of state, or call it without any arguments to reset all state to their original values.

this.$reset()
this.$reset('stateName')

class Store extends TwoAndEight {
  counter = 0

  resetCounter() {
    this.$reset('counter')
  }

  resetAll() {
    this.$reset()
  }
}

createReactStore

createReactStore(store: Store extends TwoAndEight): useStore

Enhances a store instance, returning a React Hook with API utilities attached. This should only be called outside of components.

const useStore = createReactStore(new Store())

const Component = () => {
  const actionName = useStore('actionName')
  const stateName = useStore('stateName')
  // ...
}

useStore.store

useStore.store: Store

A re-export of the store, useful in subscribers where hooks are not available.

useStore.subscribe

useStore.subscribe(callback: () => void): () => void

Subscribes to state updates; registers a callback that fires whenever an action emits. This can be used to trigger events when all or certain state changes.

useStore.subscribe(() => {
  writeCounterToFile(useStore.store.counter)
})

Note that this will be called on every emitted state from the store. If you’d like to optimise, it is advisable to use if statements and an external cache:

let counterCache = useStore.store.counter

useStore.subscribe(() => {
  if (useStore.store.counter !== counterCache) {
    writeCounterToFile(useStore.store.counter)
    counterCache = useStore.store.counter
  }
})

createStore

createStore(store: Store extends TwoAndEight): store

This is the vanilla store creator used by createReactStore. You should only need this if you are creating other, non-React, integrations with a 2n8 store.

store.store

store.store: Store

A re-export of the store, useful in subscribers where hooks are not available.

store.subscribe

store.subscribe(callback: () => void): () => void

Subscribes to state updates; registers a callback that fires whenever an action emits. This can be used to trigger events when all or certain state changes.

store.getInitialState

store.getInitialState(): Store

Returns the initial state snapshot, before any mutations have occurred.

clone

clone(value: unknown): value

This is the internal value cloning tool used by the library. It is re-exported for your convenience, in case you need to clone an external object or array in an action to stop it being mutated when the state changes.