chore(client): further formatting and added documentation

Author: Snapstromegon

Cargo.toml

@@ -11,21 +11,21 @@ testcontainer = ["dep:testcontainers"]
 [dependencies]
 chrono = { version = "0.4.41", features = ["serde"] }
 cloudevents-sdk = { version = "0.8.0", features = ["reqwest"], optional = true }
-url = "2.5.4"
+futures = "0.3.31"
+futures-util = "0.3.31"
+jsonschema = "0.30.0"
 reqwest = { version = "0.12.15", features = ["json", "stream"] }
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.140"
 testcontainers = { version = "0.24.0", features = [
   "http_wait",
 ], optional = true }
 thiserror = "2.0.12"
-jsonschema = "0.30.0"
-futures-util = "0.3.31"
+tokio = { version = "1.44.2", features = ["io-util"] }
 tokio-util = { version = "0.7.15", features = ["io"] }
 tokio-stream = { version = "0.1.17", features = ["io-util"] }
-futures = "0.3.31"
-tokio = { version = "1.44.2", features = ["io-util"] }
 typed-builder = "0.21.0"
+url = "2.5.4"
 
 [dev-dependencies]
 eventsourcingdb-client-rust = { path = ".", features = ["testcontainer"] }

src/client.rs

@@ -20,22 +20,20 @@
 mod client_request;
 mod precondition;
 
+use crate::{
+    error::ClientError,
+    event::{Event, EventCandidate, ManagementEvent},
+};
 use client_request::{
     ClientRequest, ListEventTypesRequest, ListSubjectsRequest, OneShotRequest, PingRequest,
     RegisterEventSchemaRequest, StreamingRequest, VerifyApiTokenRequest, WriteEventsRequest,
     list_event_types::EventType,
 };
-
 use futures::Stream;
 pub use precondition::Precondition;
 use reqwest;
 use url::Url;
 
-use crate::{
-    error::ClientError,
-    event::{Event, EventCandidate, ManagementEvent},
-};
-
 /// Client for an [EventsourcingDB](https://www.eventsourcingdb.io/) instance.
 #[derive(Debug)]
 pub struct Client {
@@ -84,8 +82,6 @@ impl Client {
     ///
     /// This function will return a [`reqwest::RequestBuilder`] which can be used to send the request.
     ///
-    /// This function will return a [`reqwest::RequestBuilder`] which can be used to send the request.
-    ///
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
     fn build_request<R: ClientRequest>(
@@ -203,6 +199,34 @@ impl Client {
 
     /// Registers an event schema with the DB instance.
     ///
+    /// ```
+    /// use eventsourcingdb_client_rust::event::EventCandidate;
+    /// use futures::StreamExt;
+    /// # use serde_json::json;
+    /// # tokio_test::block_on(async {
+    /// # let container = eventsourcingdb_client_rust::container::Container::start_default().await.unwrap();
+    /// let db_url = "http://localhost:3000/";
+    /// let api_token = "secrettoken";
+    /// # let db_url = container.get_base_url().await.unwrap();
+    /// # let api_token = container.get_api_token();
+    /// let client = eventsourcingdb_client_rust::client::Client::new(db_url, api_token);
+    /// let event_type = "io.eventsourcingdb.test";
+    /// let schema = json!({
+    ///     "type": "object",
+    ///     "properties": {
+    ///         "id": {
+    ///             "type": "string"
+    ///         },
+    ///         "name": {
+    ///             "type": "string"
+    ///         }
+    ///     },
+    ///     "required": ["id", "name"]
+    /// });
+    /// client.register_event_schema(event_type, &schema).await.expect("Failed to list event types");
+    /// # })
+    /// ```
+    ///
     /// # Errors
     /// This function will return an error if the request fails or if the provided schema is invalid.
     pub async fn register_event_schema(
@@ -216,6 +240,44 @@ impl Client {
 
     /// List all subjects in the DB instance.
     ///
+    /// To get all subjects in the DB, just pass `None` as the `base_subject`.
+    /// ```
+    /// use eventsourcingdb_client_rust::event::EventCandidate;
+    /// use futures::StreamExt;
+    /// # use serde_json::json;
+    /// # tokio_test::block_on(async {
+    /// # let container = eventsourcingdb_client_rust::container::Container::start_default().await.unwrap();
+    /// let db_url = "http://localhost:3000/";
+    /// let api_token = "secrettoken";
+    /// # let db_url = container.get_base_url().await.unwrap();
+    /// # let api_token = container.get_api_token();
+    /// let client = eventsourcingdb_client_rust::client::Client::new(db_url, api_token);
+    /// let mut subject_stream = client.list_subjects(None).await.expect("Failed to list event types");
+    /// while let Some(subject) = subject_stream.next().await {
+    ///     println!("Found Type {}", subject.expect("Error while reading types"));
+    /// }
+    /// # })
+    /// ```
+    ///
+    /// To get all subjects under /test in the DB, just pass `Some("/test")` as the `base_subject`.
+    /// ```
+    /// use eventsourcingdb_client_rust::event::EventCandidate;
+    /// use futures::StreamExt;
+    /// # use serde_json::json;
+    /// # tokio_test::block_on(async {
+    /// # let container = eventsourcingdb_client_rust::container::Container::start_default().await.unwrap();
+    /// let db_url = "http://localhost:3000/";
+    /// let api_token = "secrettoken";
+    /// # let db_url = container.get_base_url().await.unwrap();
+    /// # let api_token = container.get_api_token();
+    /// let client = eventsourcingdb_client_rust::client::Client::new(db_url, api_token);
+    /// let mut subject_stream = client.list_subjects(Some("/test")).await.expect("Failed to list event types");
+    /// while let Some(subject) = subject_stream.next().await {
+    ///     println!("Found Type {}", subject.expect("Error while reading types"));
+    /// }
+    /// # })
+    /// ```
+    ///
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
     pub async fn list_subjects(
@@ -232,6 +294,24 @@ impl Client {
 
     /// List all event types in the DB instance.
     ///
+    /// ```
+    /// use eventsourcingdb_client_rust::event::EventCandidate;
+    /// use futures::StreamExt;
+    /// # use serde_json::json;
+    /// # tokio_test::block_on(async {
+    /// # let container = eventsourcingdb_client_rust::container::Container::start_default().await.unwrap();
+    /// let db_url = "http://localhost:3000/";
+    /// let api_token = "secrettoken";
+    /// # let db_url = container.get_base_url().await.unwrap();
+    /// # let api_token = container.get_api_token();
+    /// let client = eventsourcingdb_client_rust::client::Client::new(db_url, api_token);
+    /// let mut type_stream = client.list_event_types().await.expect("Failed to list event types");
+    /// while let Some(ty) = type_stream.next().await {
+    ///     println!("Found Type {}", ty.expect("Error while reading types").name);
+    /// }
+    /// # })
+    /// ```
+    /// 
     /// # Errors
     /// This function will return an error if the request fails or if the URL is invalid.
     pub async fn list_event_types(