Skip to main content

AsyncStateManager

Overview​

Type: class

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

class AsyncStateManager<State> extends StateManager<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 { AsyncStateManager } from 'cotton-box'

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

Properties​

defaultState​

Inherited from: StateManager.defaultState

The default state.

readonly defaultState: State

name​

Inherited from: StateManager.name

The display name. Only used for debugging.

readonly name?: string | undefined | null

isInitializing​

Inherited from: StateManager.isInitializing

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

readonly isInitializing: SimpleStateManager<boolean>

Methods​

init​

Inherited from: StateManager.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: StateManager.get

Retrieves the current state value after all preceding and pending state changes have completed.

get(): Promise<State>

Parameters​

get does not take any parameters.

Returns​

get returns a Promise that resolves into the current state value.

Example​

const state = await ExampleState.get()

getSync​

Retrieves the current state value, even if there are still other pending state changes.

getSync(): State

Parameters​

getSync does not take any parameters.

Returns​

getSync returns the current state value.

Example​

const state = ExampleState.getSync()

set​

Inherited from: StateManager.set

Sets the state with a value.

set(newState: State): Promise<void>

Sets the state with a function.

set(setStateFn: AsyncSetStateFn<State>): Promise<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 returns a Promise that resolves into undefined.

Example​

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

reset​

Inherited from: StateManager.reset

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

reset(): Promise<void>

Parameters​

reset does not take any parameters.

Returns​

set returns a Promise that resolves into undefined.

Example​

await ExampleState.reset()

watch​

Inherited from: StateManager.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: StateManager.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: StateManager.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 until the condition is fulfilled.

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: StateManager.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(): Promise<void>

Parameters​

dispose does not take any parameters.

Returns​

dispose returns a Promise that resolves into undefined.

Example​

await ExampleState.dispose()