Dioxus Provider

https://github.com/wheregmis/dioxus-provider
Admin
Dioxus Provider is a data fetching and caching library for Dioxus applications, inspired by...
Tokens:3,313
Snippets:15
Trust Score:7.9
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dioxus Provider

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Add the dioxus-provider crate to your project's Cargo.toml file to include its data fetching and caching capabilities.

```toml
[dependencies]
dioxus-provider = "0.0.1" # Replace with the latest version
```

--------------------------------

### Rust: Combine Dioxus Provider and Dioxus Motion

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Example demonstrating how to use Dioxus Provider for data fetching and Dioxus Motion for UI animations within a Dioxus component. It shows fetching user data and applying a scale animation on click, illustrating seamless integration between the two libraries.

```rust
use dioxus_provider::prelude::*;
use dioxus_motion::prelude::*;

#[component]
fn AnimatedUserCard(user_id: u32) -> Element {
    // Data fetching with dioxus-provider
    let user_data = use_provider(fetch_user(), (user_id,));
    
    // Animation with dioxus-motion
    let scale = use_motion(1.0f32);
    
    match &*user_data.read() {
        ProviderState::Success(user) => rsx! {
            div {
                style: "transform: scale({scale.get_value()})",
                onclick: move |_| {
                    scale.animate_to(1.1, AnimationConfig::spring());
                },
                "Welcome, {user.name}!"
            }
        },
        _ => rsx! { div { "Loading..." } }
    }
}
```

--------------------------------

### Initialize Global Providers

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Initialize the global provider system at your application's entry point. This is a mandatory step for all provider hooks to function correctly.

```rust
use dioxus_provider::global::init_global_providers;
use dioxus::prelude::*;

fn main() {
    // This is required for all provider hooks to work
    init_global_providers();
    launch(app);
}

fn app() -> Element {
    rsx! { /* Your app content */ }
}
```

--------------------------------

### Parameterized Providers

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Explains how providers can accept arguments to fetch dynamic data, such as user profiles by ID. The cache is keyed by these arguments, ensuring that different calls with different parameters are cached independently.

```rust
use dioxus_provider::prelude::*

#[provider]
async fn fetch_user(user_id: u32) -> Result<String, String> {
    Ok(format!("User data for ID: {}", user_id))
}

#[component]
fn UserProfile(user_id: u32) -> Element {
    // Pass arguments as a tuple
    let user = use_provider(fetch_user(), (user_id,));

    match &*user.read() {
        ProviderState::Success(data) => rsx!{ div { "{data}" } },
        // ... other states
        _ => rsx!{ div { "Loading user..." } }
    }
}
```

--------------------------------

### ProviderState Combinator Methods

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Demonstrates the use of combinator methods like `map`, `map_err`, and `and_then` on `ProviderState` for ergonomic state transformations. These methods allow for functional manipulation of the state and error values.

```rust
let state: ProviderState<u32, String> = ProviderState::Success(42);
let mapped = state.map(|v| v.to_string()); // ProviderState<String, String>
let mapped_err = state.map_err(|e| format!("error: {e}"));
let chained = state.and_then(|v| if v > 0 { ProviderState::Success(v * 2) } else { ProviderState::Error("zero".into()) });
```

--------------------------------

### Composable Providers for Parallel Loading

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Introduces composable providers using the `#[provider(compose = [...])]` attribute, allowing multiple data fetching operations to run concurrently. The results of these parallel providers are made available as prefixed variables within the composed provider function.

```rust
// These providers will run in parallel
#[provider(compose = [fetch_user, fetch_permissions, fetch_settings])]
async fn fetch_complete_profile(user_id: u32) -> Result<UserProfile, ProviderError> {
    // Results are automatically available as:
    // - __dioxus_composed_fetch_user_result: Result<User, ProviderError>
    // - __dioxus_composed_fetch_permissions_result: Result<Permissions, ProviderError>
    // - __dioxus_composed_fetch_settings_result: Result<Settings, ProviderError>
    
    let user = __dioxus_composed_fetch_user_result?;
    let permissions = __dioxus_composed_fetch_permissions_result?;
    let settings = __dioxus_composed_fetch_settings_result?;
    
    Ok(UserProfile { user, permissions, settings })
}
```

--------------------------------

### Define a Data Provider

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Create a data provider using the #[provider] attribute on an async function. This function fetches or computes data and can be consumed throughout the application.

```rust
use dioxus_provider::prelude::*;
use std::time::Duration;

// This could be an API call, database query, etc.
#[provider]
async fn get_server_message() -> Result<String, String> {
    // Simulate a network request
    tokio::time::sleep(Duration::from_secs(1)).await;
    Ok("Hello from the server!".to_string())
}
```

--------------------------------

### Use Provider Hook

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Demonstrates how to use the `use_provider` hook to read data from a provider. The hook returns a `Signal<ProviderState<T, E>>` which can be `Loading`, `Success(T)`, or `Error(E)`. Dioxus automatically re-renders components when the data changes.

```rust
use dioxus::prelude::*
use dioxus_provider::prelude::*

#[component]
fn App() -> Element {
    // Use the provider hook to get the data
    let message = use_provider(get_server_message(), ());

    rsx! {
        div {
            h1 { "Dioxus Provider Demo" }
            // Pattern match on the state to render UI
            match &*message.read() {
                ProviderState::Loading { .. } => rsx! { div { "Loading..." } },
                ProviderState::Success(data) => rsx! { div { "Server says: {data}" } },
                ProviderState::Error(err) => rsx! { div { "Error: {err}" } },
            }
        }
    }
}
```

--------------------------------

### Structured Error Handling with Custom Errors

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Demonstrates structured error handling within providers by defining custom error types, such as `UserError`. This allows for more specific and actionable error reporting, with full backward compatibility for string errors.

```rust
use dioxus_provider::prelude::*

#[provider]
async fn fetch_user_data(id: u32) -> Result<User, UserError> {
    if id == 0 {
        return Err(UserError::ValidationFailed {
            field: "id".to_string(),
            reason: "ID cannot be zero".to_string(),
        });
    }
    
    match api_client.get_user(id).await {
        Ok(user) if user.is_suspended() => Err(UserError::Suspended {
            reason: "Account temporarily suspended".to_string(),
        }),
        Ok(user) => Ok(user),
        Err(_) => Err(UserError::NotFound { id }),
    }
}

// Error types available: ProviderError, UserError, ApiError, DatabaseError
// Full backward compatibility with String errors
```

--------------------------------

### Optimistic Mutations

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Enables optimistic updates for a better user experience by updating the UI immediately upon mutation initiation. The changes are rolled back if the mutation fails.

```rust
#[mutation(invalidates = [fetch_todos])]
async fn toggle_todo(id: u32) -> Result<Todo, String> {
    // ... toggle logic ...
}

let (mutation_state, toggle) = use_optimistic_mutation(toggle_todo());
```

--------------------------------

### Stale-While-Revalidate (SWR) Caching

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Implements the Stale-While-Revalidate pattern by serving cached data immediately and re-fetching in the background. This enhances user experience by displaying data without waiting for a fresh fetch.

```rust
#[provider(stale_time = "10s")]
async fn get_dashboard_data() -> Result<String, String> {
    // ... fetch data
    Ok("Dashboard data".to_string())
}
```

--------------------------------

### Cache Expiration (TTL)

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Configures data eviction from the cache after a specified Time-To-Live (TTL). Subsequent requests after expiration will show a loading state while data is re-fetched.

```rust
// This data will be removed from cache after 5 minutes of inactivity
#[provider(cache_expiration = "5m")]
async fn get_analytics() -> Result<String, String> {
    // ... perform expensive analytics query
    Ok("Analytics report".to_string())
}
```

--------------------------------

### Basic Mutations with Cache Invalidation

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Defines mutations using the `#[mutation]` attribute. Mutations automatically invalidate specified provider caches upon successful execution, ensuring UI consistency. The `use_mutation` hook is used to trigger these mutations.

```rust
use dioxus_provider::prelude::*

// Define a mutation that invalidates the todo list when successful
#[mutation(invalidates = [fetch_todos])]
async fn add_todo(title: String) -> Result<Todo, String> {
    // ... add todo logic ...
}

// Use the mutation in a component
let (mutation_state, mutate) = use_mutation(add_todo());
```

--------------------------------

### Multiple Cache Invalidation in Mutations

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Illustrates how a single mutation can be configured to invalidate multiple provider caches simultaneously. This is achieved by listing the provider functions in the `invalidates` attribute of the `#[mutation]` macro.

```rust
#[mutation(invalidates = [fetch_todos, fetch_stats])]
async fn remove_todo(id: u32) -> Result<(), String> {
    // ... remove logic ...
}
```

--------------------------------

### Manual Cache Invalidation

Source: https://github.com/wheregmis/dioxus-provider/blob/main/README.md

Allows manual invalidation of a provider's cache to force a re-fetch of data. This is useful for scenarios where data freshness needs to be explicitly managed.

```rust
use dioxus::prelude::*
use dioxus_provider::prelude::*

#[component]
fn UserDashboard() -> Element {
    let user_data = use_provider(fetch_user(), (1,));
    let invalidate_user = use_invalidate_provider(fetch_user(), (1,));

    rsx! {
        // ... display user_data
        button {
            onclick: move |_| invalidate_user(),
            "Refresh User"
        }
    }
}
```

```rust
let clear_cache = use_clear_provider_cache();
clear_cache();
```
Tokens:
Raw