docs(fetch): document form_data
+//! Provides a simplified (and incomplete) interface to the `FormData` Web API,
+//! in order to facilitate the creation of multipart request bodies for seed's
+//! Fetch API.
+//!
+//! ## Example
+//!
+//! ```
+//! let form_data = FormData::new()
+//! .with_str("first-name", "Bob")
+//! .with_str("last-name", "Jones");
+//!
+//! Request::new("/api/")
+//! .method(Method::Post)
+//! .form_data(form_data)
+//! .fetch()
+//!
+//! ```
+//!
+//! See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData) for
+//! details on the behavior of the underlying API.
+
use crate::fetch::{FetchError, Result};
use serde::Serialize;
use wasm_bindgen::JsValue;
@@ -5,25 +26,38 @@ use wasm_bindgen::JsValue;
pub struct FormData(web_sys::FormData);
impl FormData {
+ /// Creates a new empty `FormData` object.
pub fn new() -> Self {
Self::default()
}
+ /// Appends a blob value.
+ #[allow(clippy::missing_panics_doc)]
+ pub fn append_blob(&mut self, name: &str, blob: &web_sys::Blob) {
self.0.append_with_blob(name, blob).unwrap();
}
+ /// The builder-style variant of `append_blob`.
pub fn with_blob(mut self, name: &str, blob: &web_sys::Blob) -> Self {
self.append_blob(name, blob);
self
}
+ /// Appends a string value.
+ #[allow(clippy::missing_panics_doc)]
pub fn append_str(&mut self, name: &str, str: &str) {
self.0.append_with_str(name, str).unwrap();
}
+ /// The builder-style variant of `append_str`,
pub fn with_str(mut self, name: &str, str: &str) -> Self {
self.append_str(name, str);
self
}
+ /// Appends a json value.
+ ///
+ /// ## Errors
+ /// Will return `Err` if serialization fails.
+ #[allow(clippy::missing_panics_doc)]
pub fn append_json<T>(&mut self, name: &str, data: &T) -> Result<()>
where
T: Serialize + ?Sized,
@@ -32,6 +66,10 @@ impl FormData {
self.0.append_with_str(name, &str).unwrap();
Ok(())
}
+ /// The builder-style variant of `append_json`
+ ///
+ /// ## Errors
+ /// Will return `Err` if serialization fails.
pub fn with_json<T>(mut self, name: &str, data: &T) -> Result<Self>
where
T: Serialize + ?Sized,
