::hooks

Compile-time, async hooks in safe Rust.

Quick Start

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.

You can compose hooks in a hook fn with hook_fn!(...) or #[hook]

With hook_fn!(...)

use hooks::prelude::*;

hook_fn!(
    fn use_demo() {
        let (state, updater) = h![hooks::use_shared_set(0)];

        let updater = updater.clone();

        h![hooks::use_effect(move |v: &i32| {
            println!("state = {}", *v);

            if *v < 2 {
              updater.set(*v + 1);
            }
        }, *state)];
    }
);

futures_lite::future::block_on(async {
    let mut hook = use_demo().into_hook();
    while let Some(()) = hook.next_value().await {}
});

With #[hook]

This attribute macro is only available under proc-macro feature. Enable it with cargo add -p hook --features proc-macro. #[hook] allows using hooks without h!(). Any function call or method call with fn name starting with use_ is automatically detected as a hook.

use hooks::prelude::*;

#[hook]
fn use_demo() {
    let (state, updater) = hooks::use_shared_set(0);

    let updater = updater.clone();

    hooks::use_effect(move |v: &i32| {
        println!("state = {}", *v);

        if *v < 2 {
          updater.set(*v + 1);
        }
    }, *state);
}

fn main() {
    futures_lite::future::block_on(async {
        let mut hook = use_demo().into_hook();
        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.

state = 0
state = 1
state = 2

What is a compile-time Hook?

How to write a custom hook?

Please see Hook trait.

How to use hooks in a hook function?

With [hook_fn!] macro, you can just use h![use_another_hook(arg0, arg1)] at top level token trees (not wrapped in token trees like (), [], or {}). The macro will transform the call.

With #[hook] macro, you can just call use_another_hook(arg0, arg1) at top level expressions (not in an inner block like {}). The macro will transform the call. You can see the snapshots for what this macro outputs.

How to conditionally use hooks?

Please see [use_lazy_pinned_hook] and [use_uninitialized_hook].

How to use the hook when not in a hook fn

A hook fn actually returns impl UpdateHookUninitialized. To consume it, you can run use_my_hook().into_hook() to turn it into a Hook, or run use_my_hook().into_hook_values() (which runs use_my_hook().into_hook().into_values()) to get async iterated values.

To consume a Hook, you can use its next value with hook.next_value().await. You can get async iterated values with hook.values() or hook.into_values(), which is a Stream if the hook is [NonLendingHook].

# use hooks::prelude::*;
hook_fn!(
    fn use_demo() -> i32 {
        let (state, updater) = h![use_shared_call(
            0,
            |v| {
                if *v < 2 {
                    *v += 1;
                    true // indicating state is updated
                } else {
                    false // indicating state is not updated
                }
            },
        )];

        let updater = updater.clone();
        h![hooks::use_effect(move |_: &i32| {
            updater.call();
        }, *state)];

        *state
    }
);

// with hook.next_value().await
futures_lite::future::block_on(async {
    let mut hook = use_demo().into_hook();
    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 hook.into_hook_values() and stream.next().await
futures_lite::future::block_on(async {
    use futures_lite::StreamExt;

    let mut values = use_demo().into_hook_values();
    assert_eq!(values.next().await, Some(0));
    assert_eq!(values.next().await, Some(1));
    assert_eq!(values.next().await, Some(2));
    assert_eq!(values.next().await, None);
});

// with hook.into_hook_values() and stream.collect().await
futures_lite::future::block_on(async {
    use futures_lite::StreamExt;

    let values = use_demo().into_hook_values();
    let values = values.collect::<Vec<_>>().await;
    assert_eq!(values, [0, 1, 2]);
});