::hooks
Compile-time, async hooks in safe Rust.
Run cargo add hooks to add hooks to your project.
Note that this project is still in alpha, and it may have BREAKING CHANGES.
Please see changelogs before upgrading.
```rust use hooks::hook;
fn usedemo() { let (state, updater) = hooks::usestate(0);
let updater = updater.clone();
hooks::use_effect(move |v: &i32| {
println!("state = {}", *v);
if *v < 2 {
updater.set(*v + 1);
}
}, *state);
}
fn main() { futureslite::future::blockon(async { use hooks::HookExt;
let mut hook = use_demo();
while let Some(()) = hook.next_value(()).await {}
});
} ```
You will see the following logs. Then the program exits gracefully because it knows there won't be new values.
txt
state = 0
state = 1
state = 2
Hook?
To understand the concepts behind this crate,
you can expand this section and read the details.
Hooks, introduced by React 16.8, is a way to bring state into functional components. Hooks can make stateless functional components stateful, and reactive.
Conventional hook implementations uses a global state to record hook calls and their states.
Thus, the order of hook calls must not change; conditional hook calls are also forbidden.
Developers must follow Rules of Hooks
to write a valid custom hook.
yew.rs also uses a global
CURRENT_HOOK
to implement hooks.
We can see the above implementation relies on runtime behavior of a hook fn.
The hook runner must run the hook fn once to know what is initialized.
We call this runtime hooks.
Rust language has powerful static type systems,
it can do a lot of things at compile time.
We can abstract hook behavior as a Hook trait, and then
the fns that returns impl Hook are hook functions.
We can have a [hook] macro to help developers write custom hooks.
We call this kind of hook implementation as compile-time hooks.
This crate defines and implements compile-time hooks for you.
When a type implements [Hook<Args>], it defines three behaviors:
What arguments does this hook accept?
It accepts Args as argument of [Hook::use_hook].
When using this hook, what does it output?
[Hook::use_hook] returns [HookLifetime::Value].
This crate uses GAT (Generic Associated Types) to allow the output type borrowing from the hook itself.
To support rust versions before 1.65, this crate uses
better GAT pattern introduced by Sabrina Jewson. Thanks to her!
Due to this pattern, an extra trait [HookLifetime] is needed.
When should we re-use this hook?
Hooks have states. When the state doesn't change, we don't need to re-call use_hook to get the new output.
We can wait for the hook's state to change with [HookPollNextUpdate::poll_next_update],
or by just awaiting hook.next_update().
To wait for the next value when state changes,
you can use HookExt::next_value* methods.
Please see [Hook#how-to-impl-hook] trait.
With [hook] macro, you can just call use_another_hook(arg0, arg1) at
top level (not in an inner block like match, if, or while).
The macro will transform the call.
You can see the snapshots for what this macro outputs.
Please see [use_lazy_pinned_hook] and [use_default_pinned_hook].
To consume a hook, you can use it with HookExt::next_value*.
If a hook accepts () as Args, then it is an [AsyncIterableHook].
You can turn it into a IterHook by calling
hook.into_iter() or hook.iter_mut().
An IterHook is actually a LendingAsyncIterator.
If the output type doesn't borrow from the hook itself.
It is also an AsyncIterator or Stream.
```rust
fn usedemo() -> i32 { let (state, updater) = hooks::usestate(0);
let updater = updater.clone();
hooks::use_effect(move |_: &i32| {
updater.replace_maybe_with_fn_pointer(
|v| if *v < 2 { Some(*v + 1) } else { None }
);
}, *state);
*state
}
// with HookExt::nextvalue futureslite::future::block_on(async { use hooks::HookExt;
let mut hook = use_demo();
assert_eq!(hook.next_value(()).await, Some(0));
assert_eq!(hook.next_value(()).await, Some(1));
assert_eq!(hook.next_value(()).await, Some(2));
assert_eq!(hook.next_value(()).await, None);
});
// with AsyncIterableHook::intoiter futureslite::future::block_on(async { use hooks::AsyncIterableHook;
let mut hook = use_demo().into_iter();
assert_eq!(hook.next_value().await, Some(0));
assert_eq!(hook.next_value().await, Some(1));
assert_eq!(hook.next_value().await, Some(2));
assert_eq!(hook.next_value().await, None);
});
// with AsyncIterableHook::intoiter and Stream futureslite::future::blockon(async { use hooks::AsyncIterableHook; use futureslite::StreamExt;
let mut hook = use_demo().into_iter();
let values = hook.collect::<Vec<_>>().await;
assert_eq!(values, [0, 1, 2]);
}); ```