Skip to main content

StateManager

Overview​

Type: class

A state manager with lifecycle management and enforces set-state functions to be executed based on order of invocation.

class StateManager<State> extends SimpleStateManager<State> { }

Constructor​

constructor(defaultState: State, options: StateManagerOptions)

Parameters​

  • defaultState — The default state.
    Type: any
    Required: Yes
  • options — Additional options for the State Manager.
    Type: StateManagerOptions
    Required: No — (default value: {})

Example​

import { StateManager } from 'cotton-box'

const ExampleState = new StateManager('...')

Properties​

defaultState​

Inherited from: SimpleStateManager.defaultState

The default state.

readonly defaultState: State

name​

Inherited from: SimpleStateManager.name

The display name. Only used for debugging.

readonly name: string | undefined

isInitializing​

A distinct SimpleStateManager that keeps track whether the main State Manager is under initialization.

readonly isInitializing: SimpleStateManager<boolean>

Methods​

init​

Perform initialization independent of the init lifecycle hook.

Also see: StateManagerInitArgs

init(initFn: (args: StateManagerInitArgs<State>) => void | Promise<void>): Promise<void>

Parameters​

  • initFn — The initialization callback, similar to the init lifecycle hook.
    Type: Function
    Required: Yes

Returns​

init returns a Promise that resolves into undefined.

Example​

await ExampleState.init(({ commit }) => {
  const someValue = localStorage.get('some-value')
  commit(someValue)
})

get​

Inherited from: SimpleStateManager.get

Retrieves the current state value.

get(): State

Parameters​

get does not take any parameters.

Returns​

get returns the current state value.

Example​

const state = ExampleState.get()

set​

Inherited from: SimpleStateManager.set

Sets the state with a value.

set(newState: State): void

Sets the state with a function.

set(setStateFn: SetStateFn<State>): void

Parameters​

set takes either one of the following parameters:

  • newState — The new state.
    Type: any
    Required: Yes (either one)
  • setStateFn — A function that accepts the current state and default state as parameters and returns a new state.
    Type: SetStateFn
    Required: Yes (either one)

Returns​

set does not return anything.

Example​

// Assuming that state is of type `number`
ExampleState.set(42)
ExampleState.set((previousState) => previousState + 1)

reset​

Inherited from: SimpleStateManager.reset

Resets the State Manager back to it's default value.

reset(): void

Parameters​

reset does not take any parameters.

Returns​

reset does not return anything.

Example​

ExampleState.reset()

watch​

Inherited from: SimpleStateManager.watch

Watch for state changes.

watch(callback: (state: State) => void): () => void

Parameters​

  • callback — The callback that will be invoked each time the state changes.
    Type: Function
    Required: Yes

Returns​

watch returns an "unwatch" function that when called, will remove the watcher. The "unwatch" function does not take any parameters and does not return anything.

Example​

const unwatch = ExampleState.watch((state) => { console.log(state) })
// ··· then after some time ···
unwatch()

unwatchAll​

Inherited from: SimpleStateManager.unwatchAll

Removes all existing watchers referencing to this State Manager. Watchers that added after calling this method will not be affected.

unwatchAll(): void

Parameters​

unwatchAll does not take any parameters.

Returns​

unwatchAll does not return anything.

Example​

ExampleState.unwatchAll()

wait​

Inherited from: SimpleStateManager.wait

Waits for the state to match the expected value. If the state already matches the expectedValue, the Promise will be resolved immediately.

wait(expectedValue: State): Promise<State>

Waits for the evaluator to evaluate to true. The evaluator will be called immediately to check if the condition is fulfilled. If not, it will be called again each time the state changes.

wait(evaluator: WaitEvaluator<State>): Promise<State>

Parameters​

wait takes either one of the following parameters:

  • expectedValue — The value to wait for.
    Type: any
    Required: Yes (either one)
  • evaluator — Determines whether the state fulfills a certain condition.
    Type: WaitEvaluator
    Required: Yes (either one)

Returns​

wait returns a Promise that resolves into a snapshot of the state value that matches the expectedValue or allows the evaluator to return true.

Example​

// Promise will resolve when the state value becomes `42`.
await ExampleState.wait(42)

// Promise will resolve when the function returns `true`.
await ExampleState.wait((state) => fulfillsSomeCondition(state))

dispose​

Inherited from: SimpleStateManager.dispose

Disposes the State Manager when it is no longer in use. This will remove all watchers and prevent new ones from being added.

dispose(): void

Parameters​

dispose does not take any parameters.

Returns​

dispose does not return anything.

Example​

ExampleState.dispose()