Crates.io | yewlish-fetch |
lib.rs | yewlish-fetch |
version | 0.3.0 |
source | src |
created_at | 2024-10-10 10:51:18.386003 |
updated_at | 2024-11-25 07:15:52.748652 |
description | A macro for generating Yew fetch API bindings. |
homepage | |
repository | https://github.com/patchwork-body/yewlish.git |
max_upload_size | |
id | 1403699 |
size | 102,839 |
yewlish-fetch is a Rust crate that provides a derive macro for generating Yew fetch API bindings. It simplifies the process of making HTTP requests in Yew applications by generating client code based on an enum definition.
FetchSchema
macro to generate client code.To use yewlish-fetch in your project, add the following to your Cargo.toml
:
[dependencies]
yewlish-fetch = "0.2.3"
# required peer-dependencies
yewlish-fetch-utils = "0.2.2"
web-sys = {version = "0.3.72", features = ["AbortController"]}
in case you want to use web sockets, make sure you have web-sys
with WebSocket
feature enabled.
web-sys = {version = "0.3.72", features = ["AbortController", "WebSocket"]}
Ensure that your project is set up to run in a browser environment, as this library is designed for web applications using Yew.
Here’s a simple example of how to use yewlish-fetch to define an API schema and make a request:
use yew::prelude::*;
use yewlish_fetch::{FetchSchema, FetchService, FetchError, FetchResponse};
use serde::{Serialize, Deserialize};
#[derive(Default, Serialize, PartialEq, Clone)]
struct PostSlugs {
id: u32,
}
#[derive(Default, Serialize, PartialEq, Clone)]
struct GetPostCommentsQuery {
id: u32,
}
#[derive(Default, Deserialize, Debug, Serialize, PartialEq, Clone)]
struct PostBody {
id: u32,
title: String,
body: String,
#[serde(rename = "userId")]
user_id: u32,
}
#[derive(Default, Debug, Deserialize, Serialize, PartialEq, Clone)]
struct CommentBody {
id: u32,
name: String,
email: String,
body: String,
#[serde(rename = "postId")]
post_id: u32,
}
// Define a schema for your API by creating an enum and deriving FetchSchema.
#[derive(FetchSchema)]
enum Api {
// Define your API endpoints using the #[get], #[post], #[put], #[patch], or #[delete] attributes.
// The `res` attribute specifies the response type for the endpoint.
#[get("/posts", res = Vec<PostBody>)]
// Each variant will be used to generate a client function for making requests.
GetPosts,
// You can also define path parameters using the `slugs` attribute.
#[get("/posts/{id}", slugs = PostSlugs, res = PostBody)]
GetPost,
#[get("/posts/{id}/comments", slugs = PostSlugs, res = Vec<CommentBody>)]
GetPostComments,
// Define query parameters using the `query` attribute.
#[get("/comments", query = GetPostCommentsQuery, res = Vec<CommentBody>)]
GetComments,
// Define request body parameters using the `body` attribute.
#[post("/posts", body = PostBody, res = PostBody)]
CreatePost,
#[put("/posts/{id}", slugs = PostSlugs, body = PostBody, res = PostBody)]
UpdatePost,
#[patch("/posts/{id}", slugs = PostSlugs, body = PostBody, res = PostBody)]
PatchPost,
#[delete("/posts/{id}", slugs = PostSlugs)]
DeletePost,
}
#[derive(Properties, Clone, PartialEq)]
struct AppWrapperProps {
children: Children,
}
#[function_component(AppWrapper)]
fn app_wrapper(props: &AppWrapperProps) -> Html {
// Create a new ApiFetchClient instance with the base URL of your API.
let client =
ApiFetchClient::new("https://jsonplaceholder.typicode.com").with_middlewares(
// Add middleware functions to modify requests before they are sent.
vec![
Rc::new(|_request_init, headers| {
let headers = headers.clone();
// Of course this is a dummy middleware, but it's just for testing purposes
let future = async move {
headers
.borrow_mut()
.set("Authorization", "Bearer token")
.unwrap();
};
Box::pin(future)
}),
]
);
// ApiFetchClientProvider is a context provider that allows you to access the client instance in child components.
html! {
<ApiFetchClientProvider client={client}>
{for props.children.iter()}
</ApiFetchClientProvider>
}
}
#[function_component(GetPosts)]
fn get_posts() -> Html {
// `Api::GetPosts` variant definition will generate four hook versions:
// - `use_get_posts`
// - `use_get_posts_async`
// - `use_get_posts_with_options`
// - `use_get_posts_with_options_async`
let posts = use_get_posts_async();
// `posts` is a `UseGetPostsAsyncHandle` (generated struct) instance that contains
// - the response `data: UseStateHandle<Option<#res>>` (deserialized json according to defined `res = Vec<PostBody>`)
// - error `error: UseStateHandle<Option<FetchError>>`
// - loading state `loading: UseStateHandle<bool>`
// - optional trigger (only when the async version of the hook is used) `trigger: Callback<#method_params_struct_name>` (in this case `Callback<GetPostsParams>`)
if let Some(error) = (*posts.error).clone() {
return html! { format!("Error fetching posts: {error:?}") }
}
html! {
<>
<button onclick={Callback::from(move |_event: MouseEvent| {
posts.trigger.emit(GetPostsParams::default());
})}>{ "Fetch" }</button>
{if *posts.loading {
html! { "Loading..." }
} else {
html! {
<ul>
{for (*posts.data).clone().unwrap_or_default().iter().map(|post| html! {
<li key={post.id}>
<p>{&post.title}</p>
<p>{&post.body}</p>
</li>
})}
</ul>
}
}}
</>
}
}
#[function_component(App)]
fn app() -> Html {
html! {
<AppWrapper>
<GetPosts />
</AppWrapper>
}
}
Yewlish Fetch is built on several key components:
FetchSchema Derive Macro
Client Layer
Cache System
State Management
The full documentation for Yewlish Fetch is available on docs.rs. It includes detailed examples and API references to help you get the most out of this library.
Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on GitHub.
Yewlish Fetch is dual-licensed under the MIT and Apache 2.0 licenses. You may choose to use either license at your option.
This project is inspired by the need for robust fetch utilities in the Yew ecosystem. Special thanks to the Yew community for their continued support and contributions to the framework.
For any questions or inquiries, feel free to reach out to the author:
Kirill Korotkov Email: personal.gugfug@gmail.com