API @hookstate/core
Index
Interfaces
- DevToolsExtensions
- Plugin
- PluginCallbacks
- PluginCallbacksOnBatchArgument
- PluginCallbacksOnDestroyArgument
- PluginCallbacksOnSetArgument
- PluginStateControl
- StateMethods
- StateMethodsDestroy
Type aliases
- InferredStateKeysType
- InferredStateOrnullType
- Path
- SetInitialStateAction
- SetPartialStateAction
- SetStateAction
- State
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.
Const
postpone
• postpone: keyof symbol
Defined in index.d.ts:41
Special symbol which might be returned by onPromised callback of StateMethods.map function.
Functions
DevTools
▸ DevTools<S>(state
: State‹S›): DevToolsExtensions
Defined in index.d.ts:511
Returns access to the development tools for a given state.
Development tools are delivered as optional plugins.
You can activate development tools from @hookstate/devtools
package,
for example. If no development tools are activated,
it returns an instance of dummy tools, which do nothing, when called.
Type parameters:
▪ S
Type of a value of a state
Parameters:
Name | Type | Description |
---|---|---|
state | State‹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:473
A plugin which allows to opt-out from usage of Javascript proxies for state usage tracking. It is useful for performance tuning.
Returns: Plugin
StateFragment
▸ StateFragment<S>(props
: object): ReactElement
Defined in index.d.ts:451
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 usefull for creating scoped states.
Type parameters:
▪ S
Type of a value of a state
Parameters:
▪ props: object
Name | Type |
---|---|
children | function |
state | State‹S› |
Returns: ReactElement
▸ StateFragment<S>(props
: object): ReactElement
Defined in index.d.ts:463
Allows to use a state without defining a functional react component. See more at StateFragment
Type parameters:
▪ S
Type of a value of a state
Parameters:
▪ props: object
Name | Type |
---|---|
children | function |
state | SetInitialStateAction‹S› |
Returns: ReactElement
createState
▸ createState<S>(initial
: SetInitialStateAction‹S›): State‹S› & StateMethodsDestroy
Defined in index.d.ts:375
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:
Name | Type | Description |
---|---|---|
initial | SetInitialStateAction‹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:436
Alias to useState which provides a workaround for React 20613 bug
Type parameters:
▪ S
Parameters:
Name | Type |
---|---|
source | State‹S› |
Returns: State‹S›
▸ useHookstate<S>(source
: SetInitialStateAction‹S›): State‹S›
Defined in index.d.ts:441
Alias to useState which provides a workaround for React 20613 bug
Type parameters:
▪ S
Parameters:
Name | Type |
---|---|
source | SetInitialStateAction‹S› |
Returns: State‹S›
useState
▸ useState<S>(source
: State‹S›): State‹S›
Defined in index.d.ts:403
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 everytime, when:
- a segment/part of the state data is updated AND only if
- this segement 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:
Name | Type | Description |
---|---|---|
source | State‹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:431
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 segement 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:
Name | Type | Description |
---|---|---|
source | SetInitialStateAction‹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:490
Assigns custom label to identify the state in the development tools
Parameters:
Name | Type | Description |
---|---|---|
name | string | label for development tools |
Returns: void
log
▸ log(str
: string, data?
: any): void
Defined in index.d.ts:494
Logs to the development tools
Parameters:
Name | Type |
---|---|
str | string |
data? | any |
Returns: void
Interface: Plugin
For plugin developers only. Hookstate plugin specification and factory method.
Hierarchy
- Plugin
Index
Properties
Properties
Readonly
id
• id: symbol
Defined in index.d.ts:338
Unique identifier of a plugin.
Optional
Readonly
init
• init? : undefined | function
Defined in index.d.ts:342
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.
Hierarchy
- PluginCallbacks
Index
Properties
Properties
Optional
Readonly
onBatchFinish
• onBatchFinish? : undefined | function
Defined in index.d.ts:326
Optional
Readonly
onBatchStart
• onBatchStart? : undefined | function
Defined in index.d.ts:325
Optional
Readonly
onDestroy
• onDestroy? : undefined | function
Defined in index.d.ts:324
Optional
Readonly
onSet
• onSet? : undefined | function
Defined in index.d.ts:323
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:314
Readonly
path
• path: Path
Defined in index.d.ts:312
Optional
Readonly
state
• state? : StateValueAtRoot
Defined in index.d.ts:313
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:305
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:298
Readonly
path
• path: Path
Defined in index.d.ts:294
Optional
Readonly
previous
• previous? : StateValueAtPath
Defined in index.d.ts:296
Optional
Readonly
state
• state? : StateValueAtRoot
Defined in index.d.ts:295
Optional
Readonly
value
• value? : StateValueAtPath
Defined in index.d.ts:297
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
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:
Name | Type | Description |
---|---|---|
mergeValue | SetPartialStateAction‹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:
Name | Type | Description |
---|---|---|
paths | Path[] | 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:
Name | Type | Description |
---|---|---|
newValue | SetStateAction‹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:
- if
state.value
is an array, the returned result will be an array of numbers, not strings like withObject.keys
. - 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.
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:
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:
Methods
attach
▸ attach(plugin
: function): State‹S›
Defined in index.d.ts:221
Adds plugin to the state.
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.
Parameters:
Name | Type |
---|---|
pluginId | symbol |
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:
Name | Type |
---|---|
s | State‹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:
Name | Type |
---|---|
newValue | SetPartialStateAction‹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:
Name | Type | Description |
---|---|---|
key | K | child 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:
Name | Type | Description |
---|---|---|
newValue | SetStateAction‹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