Skip to main content

SimpleStateManager

Overview​

Type: class

A bare-bones state manager.

class SimpleStateManager<State> { }

Constructor​

constructor(defaultState: State, options: SimpleStateManagerOptions)

Parameters​

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

Example​

import { SimpleStateManager } from 'cotton-box'

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

Properties​

defaultState​

The default state.

readonly defaultState: State

name​

The display name. Only used for debugging.

readonly name: string | undefined

Methods​

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​

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​

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​

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​

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​

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​

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()