diff --git a/src/http.rs b/src/http.rs index abd2fc0..d281227 100644 --- a/src/http.rs +++ b/src/http.rs @@ -613,6 +613,59 @@ impl ResponseOutparam { } /// Send an outgoing request +/// +/// # Examples +/// +/// Get the example.com home page: +/// +/// ```no_run +/// use spin_sdk::http::{Request, Response}; +/// +/// # #[tokio::main] +/// # async fn main() -> anyhow::Result<()> { +/// let request = Request::get("example.com").build(); +/// let response: Response = spin_sdk::http::send(request).await?; +/// println!("{}", response.body().len()); +/// # Ok(()) +/// # } +/// ``` +/// +/// Use the `http` crate Request type to send a data transfer value: +/// +/// ```no_run +/// use hyperium::Request; +/// +/// #[derive(serde::Serialize)] +/// struct User { +/// name: String, +/// } +/// +/// impl spin_sdk::http::conversions::TryIntoBody for User { +/// type Error = serde_json::Error; +/// +/// fn try_into_body(self) -> Result, Self::Error> { +/// serde_json::to_vec(&self) +/// } +/// } +/// +/// # #[tokio::main] +/// # async fn main() -> anyhow::Result<()> { +/// let user = User { +/// name: "Alice".to_owned(), +/// }; +/// +/// let request = hyperium::Request::builder() +/// .method("POST") +/// .uri("https://example.com/users") +/// .header("content-type", "application/json") +/// .body(user)?; +/// +/// let response: hyperium::Response<()> = spin_sdk::http::send(request).await?; +/// +/// println!("{}", response.status().is_success()); +/// # Ok(()) +/// # } +/// ``` pub async fn send(request: I) -> Result where I: TryIntoOutgoingRequest, diff --git a/src/key_value.rs b/src/key_value.rs index 7a62a8f..b589f4a 100644 --- a/src/key_value.rs +++ b/src/key_value.rs @@ -3,6 +3,18 @@ //! This module provides a generic interface for key-value storage, which may be implemented by the host various //! ways (e.g. via an in-memory table, a local file, or a remote database). Details such as consistency model and //! durability will depend on the implementation and may vary from one to store to the next. +//! +//! # Examples +//! +//! Open the default store and set the 'message' key: +//! +//! ```no_run +//! # fn main() -> anyhow::Result<()> { +//! let store = spin_sdk::key_value::Store::open_default()?; +//! store.set("message", "Hello world".as_bytes())?; +//! # Ok(()) +//! # } +//! ``` use super::wit::v2::key_value; @@ -10,7 +22,43 @@ use super::wit::v2::key_value; use serde::{de::DeserializeOwned, Serialize}; #[doc(inline)] -pub use key_value::{Error, Store}; +pub use key_value::Error; + +/// An open key-value store. +/// +/// # Examples +/// +/// Open the default store and set the 'message' key: +/// +/// ```no_run +/// # fn main() -> anyhow::Result<()> { +/// let store = spin_sdk::key_value::Store::open_default()?; +/// store.set("message", "Hello world".as_bytes())?; +/// # Ok(()) +/// # } +/// ``` +/// +/// Open a named store and list all the keys defined in it: +/// +/// ```no_run +/// # fn main() -> anyhow::Result<()> { +/// let store = spin_sdk::key_value::Store::open("finance")?; +/// let keys = store.get_keys()?; +/// # Ok(()) +/// # } +/// ``` +/// +/// Open the default store and delete the 'message' key: +/// +/// ```no_run +/// # fn main() -> anyhow::Result<()> { +/// let store = spin_sdk::key_value::Store::open_default()?; +/// store.delete("message")?; +/// # Ok(()) +/// # } +/// ``` +#[doc(inline)] +pub use key_value::Store; impl Store { /// Open the default store. @@ -24,6 +72,31 @@ impl Store { impl Store { #[cfg(feature = "json")] /// Serialize the given data to JSON, then set it as the value for the specified `key`. + /// + /// # Examples + /// + /// Open the default store and save a customer information document against the customer ID: + /// + /// ```no_run + /// # use serde::{Deserialize, Serialize}; + /// #[derive(Deserialize, Serialize)] + /// struct Customer { + /// name: String, + /// address: Vec, + /// } + /// + /// # fn main() -> anyhow::Result<()> { + /// let customer_id = "CR1234567"; + /// let customer = Customer { + /// name: "Alice".to_owned(), + /// address: vec!["Wonderland Way".to_owned()], + /// }; + /// + /// let store = spin_sdk::key_value::Store::open_default()?; + /// store.set_json(customer_id, &customer)?; + /// # Ok(()) + /// # } + /// ``` pub fn set_json( &self, key: impl AsRef, @@ -34,6 +107,27 @@ impl Store { #[cfg(feature = "json")] /// Deserialize an instance of type `T` from the value of `key`. + /// + /// # Examples + /// + /// Open the default store and retrieve a customer information document by customer ID: + /// + /// ```no_run + /// # use serde::{Deserialize, Serialize}; + /// #[derive(Deserialize, Serialize)] + /// struct Customer { + /// name: String, + /// address: Vec, + /// } + /// + /// # fn main() -> anyhow::Result<()> { + /// let customer_id = "CR1234567"; + /// + /// let store = spin_sdk::key_value::Store::open_default()?; + /// let customer = store.get_json::(customer_id)?; + /// # Ok(()) + /// # } + /// ``` pub fn get_json( &self, key: impl AsRef,