RecoverableState <TStateModel, TPersistedState>
Index
Constructors
constructor
Initialize a new recoverable state object.
Parameters
options: RecoverableStateOptions<TStateModel, TPersistedState>
Configuration options for the recoverable state
Returns RecoverableState<TStateModel, TPersistedState>
Accessors
currentValue
Get the current state.
Throws until the state has been established, by either RecoverableState.initialize or the synchronous RecoverableState.reset - the latter being how a caller that cannot await in its constructor gets a usable state right away.
Returns TStateModel
Methods
initialize
Initialize the recoverable state.
If persistence is enabled, this method loads the saved state and registers the object to listen for PERSIST_STATE events. A state established beforehand by RecoverableState.reset survives if there is no record to restore.
Calling this again after a RecoverableState.teardown starts a new persistence window - the listener is registered again and the record reloaded.
Returns Promise<TStateModel>
The loaded state object
persistState
Persist the current state to the KeyValueStore.
This method is typically called in response to a PERSIST_STATE event, but can also be called directly when needed. It is a no-op if persistence is disabled, if no KeyValueStore is available yet, or if there is no state to write. A failed write only rejects here - the periodic and teardown ones warn instead.
Parameters
optionaleventData: Record<string, unknown>
Optional data associated with a PERSIST_STATE event
Returns Promise<void>
reset
Reset the in-memory state to the default values, leaving any persisted record alone.
Use RecoverableState.resetStore to clear the persisted record as well.
Returns void
resetStore
Clear the persisted state record, leaving the in-memory state alone.
This is a between-lifecycles operation - its point is to stop the next RecoverableState.initialize from restoring the record, so it throws while PERSIST_STATE events are still being handled, where the next one would write the record straight back. Use RecoverableState.reset to reset the state itself, or RecoverableState.teardown before clearing the record.
A no-op if persistence is disabled or no KeyValueStore is available yet.
Returns Promise<void>
teardown
Clean up resources used by the recoverable state.
If persistence is enabled, this method deregisters the object from PERSIST_STATE events and persists the current state one last time, warning rather than throwing if that write fails - cleanup runs when the work is already done, and failing it would bury whatever the caller was doing. The in-memory state is left alone, and RecoverableState.initialize can be called again to open a new persistence window.
Returns Promise<void>
A class for managing persistent recoverable state using a plain JavaScript object.
This class facilitates state persistence to a
KeyValueStore, allowing data to be saved and retrieved across migrations or restarts. It manages the loading, saving, and resetting of state data, with optional persistence capabilities.The state is represented by a plain JavaScript object that can be serialized to and deserialized from JSON. The class automatically hooks into the event system to persist state when needed.