API @hookstate/core
Table of contents
Interfaces
- Configuration
- DevToolsExtensions
- Extension
- Plugin
- PluginCallbacks
- PluginCallbacksOnDestroyArgument
- PluginCallbacksOnSetArgument
- PluginStateControl
- SetActionDescriptor
- StateMethods
- StateMethodsDestroy
- __State
Type Aliases
- DeepReturnType
- ExtensionFactory
- InferStateExtensionType
- InferStateKeysType
- InferStateOrnullType
- InferStateValueType
- InferredStateKeysType
- InferredStateOrnullType
- Path
- SetInitialStateAction
- SetPartialStateAction
- SetStateAction
- State
- StateExtensionUnknown
- __KeysOfType
Variables
Functions
- DevTools
- Downgraded
- StateFragment
- configure
- createHookstate
- createState
- extend
- hookstate
- hookstateMemo
- suspend
- useHookstate
- useHookstateCallback
- useHookstateEffect
- useHookstateImperativeHandle
- useHookstateInsertionEffect
- useHookstateLayoutEffect
- useHookstateMemo
- useMemoIntercept
- useState
Type Aliases
DeepReturnType
Ƭ DeepReturnType<V>: V extends (...args: any) => infer R ? DeepReturnType<R> : V
Type parameters
| Name |
|---|
V |
Defined in
index.ts:320
ExtensionFactory
Ƭ ExtensionFactory<S, I, E>: (typemarker?: __State<S, I>) => Extension<S, I, E>
Type parameters
| Name |
|---|
S |
I |
E |
Type declaration
▸ (typemarker?): Extension<S, I, E>
Parameters
| Name | Type |
|---|---|
typemarker? | __State<S, I> |
Returns
Extension<S, I, E>
Defined in
index.ts:456
InferStateExtensionType
Ƭ InferStateExtensionType<V>: DeepReturnType<V> extends __State<infer _, infer E> ? E : DeepReturnType<V> extends Extension<infer _, infer _, infer E> ? E : V
Type parameters
| Name |
|---|
V |
Defined in
index.ts:316
InferStateKeysType
Ƭ InferStateKeysType<S>: S extends ReadonlyArray<infer _> ? ReadonlyArray<number> : S extends null ? undefined : S extends object ? ReadonlyArray<string> : undefined
Return type of StateMethods.keys.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
Defined in
index.ts:63
InferStateOrnullType
Ƭ InferStateOrnullType<S, E>: S extends undefined ? undefined : S extends null ? null : State<S, E>
Return type of StateMethods.map().
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
E |
Defined in
index.ts:76
InferStateValueType
Ƭ InferStateValueType<V>: DeepReturnType<V> extends __State<infer S, infer _> ? S : V
Type parameters
| Name |
|---|
V |
Defined in
index.ts:314
InferredStateKeysType
Ƭ InferredStateKeysType<S>: InferStateKeysType<S>
Type parameters
| Name |
|---|
S |
Defined in
index.ts:70
InferredStateOrnullType
Ƭ InferredStateOrnullType<S, E>: InferStateOrnullType<S, E>
Type parameters
| Name |
|---|
S |
E |
Defined in
index.ts:81
Path
Ƭ Path: ReadonlyArray<string | number>
'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]
Defined in
index.ts:23
SetInitialStateAction
Ƭ SetInitialStateAction<S>: S | Promise<S> | () => S | Promise<S>
Type of an argument of hookstate and useHookstate.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
Defined in
index.ts:48
SetPartialStateAction
Ƭ SetPartialStateAction<S>: S extends ReadonlyArray<infer U> ? ReadonlyArray<U> | Record<number, U> | (prevValue: S) => ReadonlyArray<U> | Record<number, U> : S extends object | string ? Partial<S> | (prevValue: S) => Partial<S> : React.SetStateAction<S>
Type of an argument of StateMethods.merge.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
Defined in
index.ts:37
SetStateAction
Ƭ SetStateAction<S>: S | Promise<S> | (prevState: S) => S | Promise<S>
Type of an argument of StateMethods.set.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
Defined in
index.ts:30
State
Ƭ State<S, E>: StateMethods<S, E> & E & S extends ReadonlyArray<infer U> ? ReadonlyArray<State<U, E>> : S extends object ? Omit<{ readonly [K in keyof Required<S>]: State<S[K], E> }, keyof StateMethods<S, E> | keyof StateMethodsDestroy | __KeysOfType<S, Function> | keyof E> : {}
Type of a result of hookstate and useHookstate functions
Typeparam
S Type of a value of a state
Learn more about global states... Learn more about local states... Learn more about nested states...
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Defined in
index.ts:331
StateExtensionUnknown
Ƭ StateExtensionUnknown: any
Defined in
index.ts:366
__KeysOfType
Ƭ __KeysOfType<T, U, B>: { [P in keyof T]: B extends true ? T[P] extends U ? U extends T[P] ? P : never : never : T[P] extends U ? P : never }[keyof T]
Returns an interface stripped of all keys that don't resolve to U, defaulting to a non-strict comparison of T[key] extends U. Setting B to true performs a strict type comparison of T[key] extends U & U extends T[key]
Type parameters
| Name | Type |
|---|---|
T | T |
U | U |
B | false |
Defined in
index.ts:294
Variables
__state
• Const __state: typeof __state
Defined in
index.ts:308
none
• Const none: any
Special symbol which might be used to delete properties from an object calling StateMethods.set or StateMethods.merge.
Defined in
index.ts:56
Functions
DevTools
▸ DevTools<S, E>(state): DevToolsExtensions
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.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
E |
Parameters
| Name | Type | Description |
|---|---|---|
state | State<S, E> | A state to relate to the extension. |
Returns
Interface to interact with the development tools for a given state.
Downgraded
▸ Downgraded(): Plugin
A plugin which allows to opt-out from usage of Javascript proxies for state usage tracking. It is useful for performance tuning.
Returns
StateFragment
▸ StateFragment<S, E>(props): never
Type parameters
| Name |
|---|
S |
E |
Parameters
| Name | Type |
|---|---|
props | Object |
props.children | (state: State<S, E>) => ReactElement<any, string | JSXElementConstructor<any>> |
props.extension | ExtensionFactory<S, E, any> |
props.state | __State<S, E> |
props.suspend? | boolean |
Returns
never
▸ StateFragment<S, E>(props): React.ReactElement
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.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
E |
Parameters
| Name | Type |
|---|---|
props | Object |
props.children | (state: State<S, E>) => ReactElement<any, string | JSXElementConstructor<any>> |
props.state | __State<S, E> |
props.suspend? | boolean |
Returns
React.ReactElement
▸ StateFragment<S, E>(props): React.ReactElement
Allows to use a state without defining a functional react component. See more at StateFragment
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
E |
Parameters
| Name | Type |
|---|---|
props | Object |
props.children | (state: State<S, E>) => ReactElement<any, string | JSXElementConstructor<any>> |
props.extension? | ExtensionFactory<S, {}, E> |
props.state | SetInitialStateAction<S> |
props.suspend? | boolean |
Returns
React.ReactElement
configure
▸ configure(config): void
Parameters
| Name | Type |
|---|---|
config | Partial<Configuration> |
Returns
void
createHookstate
▸ createHookstate<S>(initial): State<S, {}>
Type parameters
| Name |
|---|
S |
Parameters
| Name | Type |
|---|---|
initial | SetInitialStateAction<S> |
Returns
State<S, {}>
createState
▸ createState<S>(initial): State<S, {}> & StateMethodsDestroy
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.
Typeparam
S Type of a value of the state
Type parameters
| Name |
|---|
S |
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 useHookstate function and
use the returned result in the component's logic.
extend
▸ extend<S, E, E1, E2, E3, E4, E5>(e1?, e2?, e3?, e4?, e5?): ExtensionFactory<S, E, E5 & E4 & E3 & E2 & E1>
Type parameters
| Name | Type |
|---|---|
S | S |
E | E |
E1 | extends Object = {} |
E2 | extends Object = {} |
E3 | extends Object = {} |
E4 | extends Object = {} |
E5 | extends Object = {} |
Parameters
| Name | Type |
|---|---|
e1? | ExtensionFactory<S, E, E1> |
e2? | ExtensionFactory<S, E1 & E, E2> |
e3? | ExtensionFactory<S, E2 & E1 & E, E3> |
e4? | ExtensionFactory<S, E3 & E2 & E1 & E, E4> |
e5? | ExtensionFactory<S, E4 & E3 & E2 & E1 & E, E5> |
Returns
ExtensionFactory<S, E, E5 & E4 & E3 & E2 & E1>
hookstate
▸ hookstate<S, E>(source, extension?): never
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
source | __State<S, E> |
extension? | ExtensionFactory<S, E, any> |
Returns
never
▸ hookstate<S, E>(initial, extension?): State<S, E>
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
initial | SetInitialStateAction<S> |
extension? | ExtensionFactory<S, {}, E> |
Returns
State<S, E>
hookstateMemo
▸ hookstateMemo<T>(Component, propsAreEqual?): React.MemoExoticComponent<T>
Type parameters
| Name | Type |
|---|---|
T | extends ComponentType<any> |
Parameters
| Name | Type |
|---|---|
Component | T |
propsAreEqual? | (prevProps: Readonly<ComponentProps<T>>, nextProps: Readonly<ComponentProps<T>>) => boolean |
Returns
React.MemoExoticComponent<T>
suspend
▸ suspend<S, E>(state): undefined | FunctionComponentElement<any>
Type parameters
| Name |
|---|
S |
E |
Parameters
| Name | Type |
|---|---|
state | State<S, E> |
Returns
undefined | FunctionComponentElement<any>
useHookstate
▸ useHookstate<S, E>(source, extension?): never
Warning
Initializing a local state to a promise without using
an initializer callback function, which returns a Promise,
is almost always a mistake. So, it is blocked.
Use useHookstate(() => your_promise) instead of useHookstate(your_promise).
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
source | Promise<S> |
extension? | ExtensionFactory<S, {}, E> |
Returns
never
▸ useHookstate<S, E>(source, extension): never
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
source | __State<S, E> |
extension | ExtensionFactory<S, E, any> |
Returns
never
▸ useHookstate<S, E>(source): State<S, E>
Alias to useHookstate which provides a workaround for React 20613 bug
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
source | __State<S, E> |
Returns
State<S, E>
▸ useHookstate<S, E>(source, extension?): State<S, E>
Alias to useHookstate which provides a workaround for React 20613 bug
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Parameters
| Name | Type |
|---|---|
source | SetInitialStateAction<S> |
extension? | ExtensionFactory<S, {}, E> |
Returns
State<S, E>
useHookstateCallback
▸ useHookstateCallback<T>(callback, deps): T
Type parameters
| Name | Type |
|---|---|
T | extends Function |
Parameters
| Name | Type |
|---|---|
callback | T |
deps | DependencyList |
Returns
T
useHookstateEffect
▸ useHookstateEffect(effect, deps?): void
Parameters
| Name | Type |
|---|---|
effect | EffectCallback |
deps? | DependencyList |
Returns
void
useHookstateImperativeHandle
▸ useHookstateImperativeHandle<T, R>(ref, init, deps?): void
Type parameters
| Name |
|---|
T |
R |
Parameters
| Name | Type |
|---|---|
ref | undefined | Ref<T> |
init | () => R |
deps? | DependencyList |
Returns
void
useHookstateInsertionEffect
▸ useHookstateInsertionEffect(effect, deps?): void
Parameters
| Name | Type |
|---|---|
effect | EffectCallback |
deps? | DependencyList |
Returns
void
useHookstateLayoutEffect
▸ useHookstateLayoutEffect(effect, deps?): void
Parameters
| Name | Type |
|---|---|
effect | EffectCallback |
deps? | DependencyList |
Returns
void
useHookstateMemo
▸ useHookstateMemo<T>(factory, deps): T
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
factory | () => T |
deps | undefined | DependencyList |
Returns
T
useMemoIntercept
▸ useMemoIntercept<T>(factory, deps): T
Type parameters
| Name |
|---|
T |
Parameters
| Name | Type |
|---|---|
factory | () => T |
deps | undefined | DependencyList |
Returns
T
useState
▸ useState<S>(source): never
Warning
Initializing a local state to a promise without using
an initializer callback function, which returns a Promise,
is almost always a mistake. So, it is blocked.
Use useHookstate(() => your_promise) instead of useHookstate(your_promise).
Type parameters
| Name |
|---|
S |
Parameters
| Name | Type |
|---|---|
source | Promise<S> |
Returns
never
▸ useState<S>(source): State<S, {}>
Enables a functional React component to use a state, either created by hookstate (global state) or derived from another call to useHookstate (scoped state).
The useHookstate 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 useHookstate multiple times for multiple states.
The same state can be used by multiple different components.
Type parameters
| Name |
|---|
S |
Parameters
| Name | Type | Description |
|---|---|---|
source | State<S, {}> | a reference to the state to hook into The useHookstate 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): State<S, {}>
This function enables a functional React component to use a state,
created per component by useHookstate (local state).
In this case useHookstate 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 hookstate.
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,
useHookstate 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
| Name |
|---|
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: Configuration
Table of contents
Properties
Properties
interceptDependencyListsMode
• interceptDependencyListsMode: "always" | "development" | "never"
Defined in
index.ts:2261
isDevelopmentMode
• isDevelopmentMode: boolean
Defined in
index.ts:2262
promiseDetector
• promiseDetector: (p: any) => boolean
Type declaration
▸ (p): boolean
Parameters
| Name | Type |
|---|---|
p | any |
Returns
boolean
Defined in
index.ts:2263
Interface: DevToolsExtensions
Return type of DevTools.
Table of contents
Methods
Methods
label
▸ label(name): void
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, data?): void
Logs to the development tools
Parameters
| Name | Type |
|---|---|
str | string |
data? | any |
Returns
void
Interface: Extension<S, I, E>
Type parameters
| Name |
|---|
S |
I |
E |
Table of contents
Properties
Properties
onCreate
• Optional Readonly onCreate: (state: State<S, {}>, extensionsCallbacks: { [K in string | number | symbol]: Function }) => { readonly [K in string | number | symbol]: Function }
Type declaration
▸ (state, extensionsCallbacks): { readonly [K in string | number | symbol]: Function }
Parameters
| Name | Type |
|---|---|
state | State<S, {}> |
extensionsCallbacks | { [K in string | number | symbol]: Function } |
Returns
{ readonly [K in string | number | symbol]: Function }
Defined in
index.ts:438
onDestroy
• Optional Readonly onDestroy: (state: State<S, E & I>) => void
Type declaration
▸ (state): void
Parameters
| Name | Type |
|---|---|
state | State<S, E & I> |
Returns
void
Defined in
index.ts:453
onInit
• Optional Readonly onInit: (state: State<S, E & I>, extensionsCallbacks: { [K in string | number | symbol]: Function }) => void
Type declaration
▸ (state, extensionsCallbacks): void
Parameters
| Name | Type |
|---|---|
state | State<S, E & I> |
extensionsCallbacks | { [K in string | number | symbol]: Function } |
Returns
void
Defined in
index.ts:444
onPremerge
• Optional Readonly onPremerge: (state: State<any, E & I>, value: any) => void
Type declaration
▸ (state, value): void
Parameters
| Name | Type |
|---|---|
state | State<any, E & I> |
value | any |
Returns
void
Defined in
index.ts:451
onPreset
• Optional Readonly onPreset: (state: State<any, E & I>, value: any) => void
Type declaration
▸ (state, value): void
Parameters
| Name | Type |
|---|---|
state | State<any, E & I> |
value | any |
Returns
void
Defined in
index.ts:450
onSet
• Optional Readonly onSet: (state: State<any, E & I>, descriptor: SetActionDescriptor) => void
Type declaration
▸ (state, descriptor): void
Parameters
| Name | Type |
|---|---|
state | State<any, E & I> |
descriptor | SetActionDescriptor |
Returns
void
Defined in
index.ts:452
Interface: Plugin
For plugin developers only. Hookstate plugin specification and factory method.
Table of contents
Properties
Properties
id
• Readonly id: symbol
Unique identifier of a plugin.
Defined in
index.ts:429
init
• Optional Readonly init: (state: State<any, {}>) => PluginCallbacks
Type declaration
▸ (state): PluginCallbacks
Initializer for a plugin when it is attached for the first time.
Parameters
| Name | Type |
|---|---|
state | State<any, {}> |
Returns
Defined in
index.ts:433
Interface: PluginCallbacks
For plugin developers only. Set of callbacks, a plugin may subscribe to.
Table of contents
Properties
Properties
onDestroy
• Optional Readonly onDestroy: (arg: PluginCallbacksOnDestroyArgument) => void
Type declaration
▸ (arg): void
Parameters
| Name | Type |
|---|---|
arg | PluginCallbacksOnDestroyArgument |
Returns
void
Defined in
index.ts:416
onSet
• Optional Readonly onSet: (arg: PluginCallbacksOnSetArgument) => void
Type declaration
▸ (arg): void
Parameters
| Name | Type |
|---|---|
arg | PluginCallbacksOnSetArgument |
Returns
void
Defined in
index.ts:415
Interface: PluginCallbacksOnDestroyArgument
For plugin developers only. PluginCallbacks.onDestroy argument type.
Table of contents
Properties
Properties
state
• Optional Readonly state: any
Defined in
index.ts:405
Interface: PluginCallbacksOnSetArgument
For plugin developers only. PluginCallbacks.onSet argument type.
Table of contents
Properties
Properties
merged
• Optional Readonly merged: any
Defined in
index.ts:397
path
• Readonly path: Path
Defined in
index.ts:373
previous
• Optional Readonly previous: any
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 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;
})
Defined in
index.ts:395
state
• Optional Readonly state: any
Defined in
index.ts:374
value
• Optional Readonly value: any
Defined in
index.ts:396
Interface: PluginStateControl<S>
For plugin developers only. An instance to manipulate the state in more controlled way.
Typeparam
S Type of a value of a state
Type parameters
| Name |
|---|
S |
Table of contents
Methods
Methods
getUntracked
▸ getUntracked(): S
Get state value, but do not leave the traces of reading it.
Returns
S
mergeUntracked
▸ mergeUntracked(mergeValue): Path[]
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): void
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): Path[]
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: SetActionDescriptor
Table of contents
Properties
Properties
actions
• Optional actions: Record<string | number, "I" | "U" | "D">
Defined in
index.ts:1119
path
• path: Path
Defined in
index.ts:1118
Interface: StateMethods<S, E>
An interface to manage a state in Hookstate.
Typeparam
S Type of a value of a state
Type parameters
| Name | Type |
|---|---|
S | S |
E | {} |
Hierarchy
__State<S,E>↳
StateMethods
Table of contents
Properties
Methods
Properties
[___state]
• [___state]: [S, E]
Inherited from
Defined in
index.ts:310
error
• Readonly error: any
If a state was set to a promise and the promise was rejected, this property will return the error captured from the promise rejection
Defined in
index.ts:185
keys
• Readonly keys: InferStateKeysType<S>
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.valueis an array, the returned result will be an array of numbers, not strings like withObject.keys. - if
state.valueis not an object, the returned result will be undefined.
Defined in
index.ts:147
ornull
• ornull: InferStateOrnullType<S, E>
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.
Defined in
index.ts:252
path
• Readonly path: Path
'Javascript' object 'path' to an element relative to the root object in the state. For example:
const state = useHookstate([{ name: 'First Task' }])
state.path IS []
state[0].path IS [0]
state.[0].name.path IS [0, 'name']
Defined in
index.ts:136
promise
• Readonly promise: undefined | Promise<State<S, E>>
Defined in
index.ts:179
promised
• Readonly promised: boolean
True if state value is not yet available (eg. equal to a promise)
Defined in
index.ts:176
value
• Readonly value: S
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 = useHookstate<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
Defined in
index.ts:170
Methods
attach
▸ attach(plugin): State<S, E>
Adds plugin to the state.
Parameters
| Name | Type |
|---|---|
plugin | () => Plugin |
Returns
State<S, E>
▸ attach(pluginId): [PluginCallbacks | Error, PluginStateControl<S>]
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>]
get
▸ get(options?): S
Unwraps and returns the underlying state value referred by path of this state instance.
It returns the same result as StateMethods.value method.
If the additional option noproxy is set, the method will return
the original data object without wrapping it by proxy.
All properties of the object will be marked as used and on change will trigger the rerender.
If the additional option stealth is set, the method will not mark
the object as used and it will not trigger the rerender if it is changed.
It might be helpful to use it during debugging, for example:
console.log(state.get({ stealth: true })).
If you use it, make sure you know what you are doing.
Parameters
| Name | Type |
|---|---|
options? | Object |
options.noproxy? | boolean |
options.stealth? | boolean |
Returns
S
merge
▸ merge(newValue): void
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
mergeargument 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): State<S[K], E>
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
| Name | Type |
|---|---|
K | extends string | number | symbol |
Parameters
| Name | Type | Description |
|---|---|---|
key | K | child property name or index |
Returns
State<S[K], E>
set
▸ set(newValue): void
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.
Table of contents
Methods
Methods
destroy
▸ destroy(): void
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
Interface: __State<S, E>
Type parameters
| Name |
|---|
S |
E |
Hierarchy
__State
Table of contents
Properties
Properties
[___state]
• [___state]: [S, E]
Defined in
index.ts:310