API @hookstate/core

Index

Interfaces

Type aliases

Variables

Functions

Type aliases

InferredStateKeysType

Ƭ InferredStateKeysType: S extends ReadonlyArray<infer _> ? ReadonlyArray<number> : S extends null ? undefined : S extends object ? ReadonlyArray<keyof S> : undefined

Defined in index.d.ts:54

Return type of StateMethods.keys.

InferredStateOrnullType

Ƭ InferredStateOrnullType: S extends undefined ? undefined : S extends null ? null : State<S>

Defined in index.d.ts:60

Return type of StateMethods.map().

Path

Ƭ Path: ReadonlyArray‹string | number›

Defined in index.d.ts:17

'JSON path' from root of a state object to a nested property. Return type of StateMethod.path.

For example, an object { a: [{ b: 1 }, { 1000: 'value' }, '3rd'] }, has got the following paths pointing to existing properties:

  • []
  • ['a']
  • ['a', 0]
  • ['a', 0, 'b']
  • ['a', 1]
  • ['a', 1, 1000]
  • ['a', 2]

SetInitialStateAction

Ƭ SetInitialStateAction: S | Promise‹S› | function

Defined in index.d.ts:35

Type of an argument of createState and useState.

SetPartialStateAction

Ƭ SetPartialStateAction: S extends ReadonlyArray<> ? ReadonlyArray<U> | Record<number, U> | function : S extends object | string ? Partial<S> | function : React.SetStateAction<S>

Defined in index.d.ts:29

Type of an argument of StateMethods.merge.

SetStateAction

Ƭ SetStateAction: S | Promise‹S› | function

Defined in index.d.ts:23

Type of an argument of StateMethods.set.

State

Ƭ State: StateMixin & S extends object ? { readonly [K in keyof Required<S>]: State<S[K]> } : StateMethods

Defined in index.d.ts:254

Type of a result of createState and useState functions

Variables

Const none

• none: any

Defined in index.d.ts:48

Special symbol which might be used to delete properties from an object calling StateMethods.set or StateMethods.merge.

Learn more...

Const postpone

• postpone: keyof symbol

Defined in index.d.ts:41

Special symbol which might be returned by onPromised callback of StateMethods.map function.

Learn more...

Functions

DevTools

▸ DevTools<S>(state: State‹S›): DevToolsExtensions

Defined in index.d.ts:532

Returns access to the development tools for a given state. Development tools are delivered as optional plugins. You can activate development tools from @hookstate/devtoolspackage, for example. If no development tools are activated, it returns an instance of dummy tools, which do nothing, when called.

Learn more...

Type parameters:

▪ S

Type of a value of a state

Parameters:

NameTypeDescription
stateState‹S›A state to relate to the extension.

Returns: DevToolsExtensions

Interface to interact with the development tools for a given state.

Downgraded

▸ Downgraded(): Plugin

Defined in index.d.ts:494

A plugin which allows to opt-out from usage of Javascript proxies for state usage tracking. It is useful for performance tuning.

Learn more...

Returns: Plugin

StateFragment

▸ StateFragment<S>(props: object): ReactElement

Defined in index.d.ts:472

Allows to use a state without defining a functional react component. It can be also used in class-based React components. It is also particularly useful for creating scoped states.

Learn more...

Type parameters:

▪ S

Type of a value of a state

Parameters:

▪ props: object

NameType
childrenfunction
stateState‹S›

Returns: ReactElement

▸ StateFragment<S>(props: object): ReactElement

Defined in index.d.ts:484

Allows to use a state without defining a functional react component. See more at StateFragment

Learn more...

Type parameters:

▪ S

Type of a value of a state

Parameters:

▪ props: object

NameType
childrenfunction
stateSetInitialStateAction‹S›

Returns: ReactElement

createState

▸ createState<S>(initial: SetInitialStateAction‹S›): State‹S› & StateMethodsDestroy

Defined in index.d.ts:396

Creates new state and returns it.

You can create as many global states as you need.

When you the state is not needed anymore, it should be destroyed by calling destroy() method of the returned instance. This is necessary for some plugins, which allocate native resources, like subscription to databases, broadcast channels, etc. In most cases, a global state is used during whole life time of an application and would not require destruction. However, if you have got, for example, a catalog of dynamically created and destroyed global states, the states should be destroyed as advised above.

Type parameters:

▪ S

Type of a value of the state

Parameters:

NameTypeDescription
initialSetInitialStateAction‹S›Initial value of the state. It can be a value OR a promise, which asynchronously resolves to a value, OR a function returning a value or a promise.

Returns: State‹S› & StateMethodsDestroy

(#state) instance, which can be used directly to get and set state value outside of React components. When you need to use the state in a functional React component, pass the created state to useState function and use the returned result in the component's logic.

useHookstate

▸ useHookstate<S>(source: State‹S›): State‹S›

Defined in index.d.ts:457

Alias to useState which provides a workaround for React 20613 bug

Type parameters:

▪ S

Parameters:

NameType
sourceState‹S›

Returns: State‹S›

▸ useHookstate<S>(source: SetInitialStateAction‹S›): State‹S›

Defined in index.d.ts:462

Alias to useState which provides a workaround for React 20613 bug

Type parameters:

▪ S

Parameters:

NameType
sourceSetInitialStateAction‹S›

Returns: State‹S›

useState

▸ useState<S>(source: State‹S›): State‹S›

Defined in index.d.ts:424

Enables a functional React component to use a state, either created by createState (global state) or derived from another call to useState (scoped state).

The useState forces a component to rerender every time, when:

  • a segment/part of the state data is updated AND only if
  • this segment was used by the component during or after the latest rendering.

For example, if the state value is { a: 1, b: 2 } and a component uses only a property of the state, it will rerender only when the whole state object is updated or when a property is updated. Setting the state value/property to the same value is also considered as an update.

A component can use one or many states, i.e. you may call useState multiple times for multiple states.

The same state can be used by multiple different components.

Type parameters:

▪ S

Parameters:

NameTypeDescription
sourceState‹S›a reference to the state to hook into The useState is a hook and should follow React's rules of hooks.

Returns: State‹S›

an instance of State, which must be used within the component (during rendering or in effects) or it's children.

▸ useState<S>(source: SetInitialStateAction‹S›): State‹S›

Defined in index.d.ts:452

This function enables a functional React component to use a state, created per component by useState (local state). In this case useState behaves similarly to React.useState, but the returned instance of State has got more features.

When a state is used by only one component, and maybe it's children, it is recommended to use local state instead of global, which is created by createState.

Local (per component) state is created when a component is mounted and automatically destroyed when a component is unmounted.

The same as with the usage of a global state, useState forces a component to rerender when:

  • a segment/part of the state data is updated AND only if
  • this segment was used by the component during or after the latest rendering.

You can use as many local states within the same component as you need.

Type parameters:

▪ S

Parameters:

NameTypeDescription
sourceSetInitialStateAction‹S›An initial value state.

Returns: State‹S›

an instance of State, which must be used within the component (during rendering or in effects) or it's children.

Interfaces

Interface: DevToolsExtensions

Return type of DevTools.

Hierarchy

  • DevToolsExtensions

Index

Methods

Methods

label

▸ label(name: string): void

Defined in index.d.ts:511

Assigns custom label to identify the state in the development tools

Parameters:

NameTypeDescription
namestringlabel for development tools

Returns: void

log

▸ log(str: string, data?: any): void

Defined in index.d.ts:515

Logs to the development tools

Parameters:

NameType
strstring
data?any

Returns: void

Interface: Plugin

For plugin developers only. Hookstate plugin specification and factory method.

Learn more...

Hierarchy

  • Plugin

Index

Properties

Properties

Readonly id

• id: symbol

Defined in index.d.ts:359

Unique identifier of a plugin.

Optional Readonly init

• init? : undefined | function

Defined in index.d.ts:363

Initializer for a plugin when it is attached for the first time.

Interface: PluginCallbacks

For plugin developers only. Set of callbacks, a plugin may subscribe to.

Learn more...

Hierarchy

  • PluginCallbacks

Index

Properties

Properties

Optional Readonly onBatchFinish

• onBatchFinish? : undefined | function

Defined in index.d.ts:347

Optional Readonly onBatchStart

• onBatchStart? : undefined | function

Defined in index.d.ts:346

Optional Readonly onDestroy

• onDestroy? : undefined | function

Defined in index.d.ts:345

Optional Readonly onSet

• onSet? : undefined | function

Defined in index.d.ts:344

Interface: PluginCallbacksOnBatchArgument

For plugin developers only. PluginCallbacks.onBatchStart/Finish argument type.

Hierarchy

  • PluginCallbacksOnBatchArgument

Index

Properties

Properties

Optional Readonly context

• context? : AnyContext

Defined in index.d.ts:335

Readonly path

• path: Path

Defined in index.d.ts:333

Optional Readonly state

• state? : StateValueAtRoot

Defined in index.d.ts:334

Interface: PluginCallbacksOnDestroyArgument

For plugin developers only. PluginCallbacks.onDestroy argument type.

Hierarchy

  • PluginCallbacksOnDestroyArgument

Index

Properties

Properties

Optional Readonly state

• state? : StateValueAtRoot

Defined in index.d.ts:326

Interface: PluginCallbacksOnSetArgument

For plugin developers only. PluginCallbacks.onSet argument type.

Hierarchy

  • PluginCallbacksOnSetArgument

Index

Properties

Properties

Optional Readonly merged

• merged? : StateValueAtPath

Defined in index.d.ts:319

Readonly path

• path: Path

Defined in index.d.ts:294

Optional Readonly previous

• previous? : StateValueAtPath

Defined in index.d.ts:317

A note about previous values and merging: State values are muteable in Hookstate for performance reasons. This causes a side effect in the merge operation. While merging, the previous state object is mutated as the desired changes are applied. This means the value of previous will reflect the merged changes as well, matching the new state value rather than the previous state value. As a result, the previous property is unreliable when merge is used. The merged property can be used to detect which values were merged in but it will not inform you whether those values are different from the previous state.

As a workaround, you can batch state updates or replace merge calls with the immutable-style set operation like so:

state.set(p => {
let copy = p.clone(); /// here it is up to you to define how to clone the current state
copy.field = 'new value for field';
delete copy.fieldToDelete;
return copy;
})

Optional Readonly state

• state? : StateValueAtRoot

Defined in index.d.ts:295

Optional Readonly value

• value? : StateValueAtPath

Defined in index.d.ts:318

Interface: PluginStateControl <S>

For plugin developers only. An instance to manipulate the state in more controlled way.

Type parameters

▪ S

Type of a value of a state

Learn more...

Hierarchy

  • PluginStateControl

Index

Methods

Methods

getUntracked

▸ getUntracked(): S

Defined in index.d.ts:73

Get state value, but do not leave the traces of reading it.

Returns: S

mergeUntracked

▸ mergeUntracked(mergeValue: SetPartialStateAction‹S›): Path[]

Defined in index.d.ts:85

Merge new state value, but do not trigger rerender.

Parameters:

NameTypeDescription
mergeValueSetPartialStateAction‹S›new partial value to merge with the current state value and set.

Returns: Path[]

rerender

▸ rerender(paths: Path[]): void

Defined in index.d.ts:91

Trigger rerender for hooked states, where values at the specified paths are used.

Parameters:

NameTypeDescription
pathsPath[]paths of the state variables to search for being used by components and rerender

Returns: void

setUntracked

▸ setUntracked(newValue: SetStateAction‹S›): Path[]

Defined in index.d.ts:79

Set new state value, but do not trigger rerender.

Parameters:

NameTypeDescription
newValueSetStateAction‹S›new value to set to a state.

Returns: Path[]

Interface: StateMethods <S>

An interface to manage a state in Hookstate.

Type parameters

▪ S

Type of a value of a state

Hierarchy

  • StateMethods

Index

Properties

Methods

Properties

Readonly error

• error: StateErrorAtRoot | undefined

Defined in index.d.ts:151

If a state was set to a promise and the promise was rejected, this property will return the error captured from the promise rejection

Readonly keys

• keys: InferredStateKeysType‹S›

Defined in index.d.ts:120

Return the keys of nested states. For a given state of State type, state.keys will be structurally equal to Object.keys(state), with two minor difference:

  1. if state.value is an array, the returned result will be an array of numbers, not strings like with Object.keys.
  2. if state.value is not an object, the returned result will be undefined.

ornull

• ornull: InferredStateOrnullType‹S›

Defined in index.d.ts:215

If state value is null or undefined, returns state value. Otherwise, it returns this state instance but with null and undefined removed from the type parameter.

Learn more...

Readonly path

• path: Path

Defined in index.d.ts:110

'Javascript' object 'path' to an element relative to the root object in the state. For example:

const state = useState([{ name: 'First Task' }])
state.path IS []
state[0].path IS [0]
state.[0].name.path IS [0, 'name']

Readonly promised

• promised: boolean

Defined in index.d.ts:146

True if state value is not yet available (eg. equal to a promise)

Readonly value

• value: S

Defined in index.d.ts:142

Unwraps and returns the underlying state value referred by path of this state instance.

It returns the same result as StateMethods.get method.

This property is more useful than get method for the cases, when a value may hold null or undefined values. Typescript compiler does not handle elimination of undefined with get(), like in the following examples, but value does:

const state = useState<number | undefined>(0)
const myvalue: number = state.value
? state.value + 1
: 0; // <-- compiles
const myvalue: number = state.get()
? state.get() + 1
: 0; // <-- does not compile

Methods

attach

▸ attach(plugin: function): State‹S›

Defined in index.d.ts:221

Adds plugin to the state.

Learn more...

Parameters:

▪ plugin: function

▸ (): Plugin

Returns: State‹S›

▸ attach(pluginId: symbol): [PluginCallbacks | Error, PluginStateControl‹S›]

Defined in index.d.ts:231

For plugin developers only. It is a method to get the instance of the previously attached plugin. If a plugin has not been attached to a state, it returns an Error as the first element. A plugin may trhow an error to indicate that plugin has not been attached.

Learn more...

Parameters:

NameType
pluginIdsymbol

Returns: [PluginCallbacks | Error, PluginStateControl‹S›]

batch

▸ batch<R, C>(action: function, context?: Exclude‹C, Function›): R

Defined in index.d.ts:207

Runs the provided action callback with optimised re-rendering. Updating state within a batch action does not trigger immediate rerendering. Instead, all required rerendering is done once the batch is finished.

[Learn more about batching...](https://hookstate.js.org/docs/performance-batched-updates

Type parameters:

▪ R

▪ C

Parameters:

▪ action: function

callback function to execute in a batch

▸ (s: State‹S›): R

Parameters:

NameType
sState‹S›

▪Optional context: Exclude‹C, Function›

custom user's value, which is passed to plugins

Returns: R

get

▸ get(): S

Defined in index.d.ts:158

Unwraps and returns the underlying state value referred by path of this state instance.

It returns the same result as StateMethods.value method.

Returns: S

merge

▸ merge(newValue: SetPartialStateAction‹S›): void

Defined in index.d.ts:185

Similarly to set method updates state value.

  • If current state value is an object, it does partial update for the object.
  • If state value is an array and the argument is an array too, it concatenates the current value with the value of the argument and sets it to the state.
  • If state value is an array and the merge argument is an object, it does partial update for the current array value.
  • If current state value is a string, it concatenates the current state value with the argument converted to string and sets the result to the state.

Parameters:

NameType
newValueSetPartialStateAction‹S›

Returns: void

nested

▸ nested<K>(key: K): State‹S[K]›

Defined in index.d.ts:195

Returns nested state by key. state.nested('myprop') returns the same as state.myprop or state['myprop'], but also works for properties, which names collide with names of state methods.

Learn more about nested states...

Type parameters:

▪ K: keyof S

Parameters:

NameTypeDescription
keyKchild property name or index

Returns: State‹S[K]›

set

▸ set(newValue: SetStateAction‹S›): void

Defined in index.d.ts:173

Sets new value for a state. If this.path === [], it is similar to the setState variable returned by React.useState hook. If this.path !== [], it sets only the segment of the state value, pointed out by the path. Unlike merge method, this method will not accept partial updates. Partial updates can be also done by walking the nested states and setting those.

Parameters:

NameTypeDescription
newValueSetStateAction‹S›new value to set to a state. It can be a value, a promise resolving to a value (only if this.path is []), or a function returning one of these. The function receives the current state value as an argument.

Returns: void

Interface: StateMethodsDestroy

Mixin for the StateMethods for a State, which can be destroyed by a client.

Hierarchy

  • StateMethodsDestroy

Index

Methods

Methods

destroy

▸ destroy(): void

Defined in index.d.ts:243

Destroys an instance of a state, so it can clear the allocated native resources (if any) and can not be used anymore after it has been destroyed.

Returns: void

Edit this page