feat: Update readme (#26)

dotKuro · web-flow · commit 91115742aef4 · 2025-07-14T14:08:53.000+02:00
diff --git a/README.md b/README.md
diff --git a/clippy.toml b/clippy.toml
@@ -0,0 +1 @@
+doc-valid-idents = ["EventSourcingDB", "EventQL", "CloudEvents", ".."]
diff --git a/examples/event_types.rs b/examples/event_types.rs
@@ -0,0 +1,21 @@
+use eventsourcingdb::{client::Client, container::Container};
+use futures::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client.list_event_types().await;
+
+    match result {
+        Err(err) => panic!("{}", err),
+        Ok(mut event_types) => {
+            while let Some(Ok(event_type)) = event_types.next().await {
+                println!("{:?}", event_type)
+            }
+        }
+    }
+}
diff --git a/examples/listing_subjects.rs b/examples/listing_subjects.rs
@@ -0,0 +1,21 @@
+use eventsourcingdb::{client::Client, container::Container};
+use futures::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client.list_subjects(Some("/")).await;
+
+    match result {
+        Err(err) => panic!("{}", err),
+        Ok(mut subjects) => {
+            while let Some(Ok(subject)) = subjects.next().await {
+                println!("{:?}", subject)
+            }
+        }
+    }
+}
diff --git a/examples/observing_events.rs b/examples/observing_events.rs
@@ -0,0 +1,33 @@
+use eventsourcingdb::{
+    client::{Client, request_options::ObserveEventsOptions},
+    container::Container,
+};
+use futures::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client
+        .observe_events(
+            "/books/42",
+            Some(ObserveEventsOptions {
+                recursive: false,
+                from_latest_event: None,
+                lower_bound: None,
+            }),
+        )
+        .await;
+
+    match result {
+        Err(err) => panic!("{}", err),
+        Ok(mut stream) => {
+            while let Some(Ok(event)) = stream.next().await {
+                println!("{:?}", event)
+            }
+        }
+    }
+}
diff --git a/examples/ping.rs b/examples/ping.rs
@@ -0,0 +1,15 @@
+use eventsourcingdb::{client::Client, container::Container};
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client.ping().await;
+    if let Err(err) = result {
+        // handle error
+        panic!("{}", err)
+    }
+}
diff --git a/examples/reading_events.rs b/examples/reading_events.rs
@@ -0,0 +1,35 @@
+use eventsourcingdb::{
+    client::{Client, request_options::ReadEventsOptions},
+    container::Container,
+};
+use futures::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client
+        .read_events(
+            "/books/42",
+            Some(ReadEventsOptions {
+                recursive: false,
+                from_latest_event: None,
+                order: None,
+                lower_bound: None,
+                upper_bound: None,
+            }),
+        )
+        .await;
+
+    match result {
+        Err(err) => panic!("{}", err),
+        Ok(mut stream) => {
+            while let Some(Ok(event)) = stream.next().await {
+                println!("{:?}", event)
+            }
+        }
+    }
+}
diff --git a/examples/registering_event_schema.rs b/examples/registering_event_schema.rs
@@ -0,0 +1,34 @@
+use eventsourcingdb::{client::Client, container::Container};
+use serde_json::json;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client
+        .register_event_schema(
+            "io.eventsourcingdb.library.book-acquired",
+            &json!({
+              "type": "object",
+              "properties": {
+                "title":  { "type": "string" },
+                "author": { "type": "string" },
+                "isbn":   { "type": "string" },
+              },
+              "required": [
+                "title",
+                "author",
+                "isbn",
+              ],
+              "additionalProperties": false,
+            }),
+        )
+        .await;
+
+    if let Err(err) = result {
+        panic!("{}", err)
+    }
+}
diff --git a/examples/running_eventql.rs b/examples/running_eventql.rs
@@ -0,0 +1,23 @@
+use eventsourcingdb::{client::Client, container::Container};
+use futures::StreamExt;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client
+        .run_eventql_query("FROM e IN events PROJECT INTO e")
+        .await;
+
+    match result {
+        Err(err) => panic!("{}", err),
+        Ok(mut stream) => {
+            while let Some(Ok(row)) = stream.next().await {
+                println!("{:?}", row)
+            }
+        }
+    }
+}
diff --git a/examples/verify_api_token.rs b/examples/verify_api_token.rs
@@ -0,0 +1,15 @@
+use eventsourcingdb::{client::Client, container::Container};
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let result = client.verify_api_token().await;
+    if let Err(err) = result {
+        // handle error
+        panic!("{}", err)
+    }
+}
diff --git a/examples/write_events.rs b/examples/write_events.rs
@@ -0,0 +1,27 @@
+use eventsourcingdb::{client::Client, container::Container, event::EventCandidate};
+use serde_json::json;
+
+#[tokio::main]
+async fn main() {
+    let db = Container::start_default().await.unwrap();
+    let base_url = db.get_base_url().await.unwrap();
+    let api_token = db.get_api_token();
+    let client = Client::new(base_url, api_token);
+
+    let event = EventCandidate::builder()
+        .source("https://library.eventsourcingdb.io".to_string())
+        .subject("/books/42".to_string())
+        .ty("io.eventsourcingdb.library.book-acquired")
+        .data(json!({
+          "title": "2001 - A Space Odyssey",
+          "author": "Arthur C. Clarke",
+          "isbn": "978-0756906788",
+        }))
+        .build();
+
+    let result = client.write_events(vec![event.clone()], vec![]).await;
+    match result {
+        Ok(written_events) => println!("{:?}", written_events),
+        Err(err) => panic!("{}", err),
+    }
+}
diff --git a/src/client.rs b/src/client.rs
@@ -203,7 +203,7 @@ impl Client {
     pub async fn read_events<'a>(
         &self,
         subject: &'a str,
-        options: Option<request_options::ReadEventsRequestOptions<'a>>,
+        options: Option<request_options::ReadEventsOptions<'a>>,
     ) -> Result<impl Stream<Item = Result<Event, ClientError>>, ClientError> {
         let response = self
             .request_streaming(ReadEventsRequest { subject, options })
@@ -249,7 +249,7 @@ impl Client {
     pub async fn observe_events<'a>(
         &self,
         subject: &'a str,
-        options: Option<request_options::ObserveEventsRequestOptions<'a>>,
+        options: Option<request_options::ObserveEventsOptions<'a>>,
     ) -> Result<impl Stream<Item = Result<Event, ClientError>>, ClientError> {
         let response = self
             .request_streaming(ObserveEventsRequest { subject, options })
diff --git a/src/client/client_request/observe_events.rs b/src/client/client_request/observe_events.rs
@@ -1,17 +1,15 @@
 use reqwest::Method;
 use serde::Serialize;
 
-use crate::{
-    client::request_options::ObserveEventsRequestOptions, error::ClientError, event::Event,
-};
+use crate::{client::request_options::ObserveEventsOptions, error::ClientError, event::Event};
 
 use super::{ClientRequest, StreamingRequest};
 
 #[derive(Debug, Clone, Serialize)]
 pub struct ObserveEventsRequest<'a> {
     pub subject: &'a str,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub options: Option<ObserveEventsRequestOptions<'a>>,
+    pub options: Option<ObserveEventsOptions<'a>>,
 }
 
 impl ClientRequest for ObserveEventsRequest<'_> {
diff --git a/src/client/client_request/read_events.rs b/src/client/client_request/read_events.rs
@@ -1,15 +1,15 @@
 use reqwest::Method;
 use serde::Serialize;
 
-use crate::{client::request_options::ReadEventsRequestOptions, error::ClientError, event::Event};
+use crate::{client::request_options::ReadEventsOptions, error::ClientError, event::Event};
 
 use super::{ClientRequest, StreamingRequest};
 
 #[derive(Debug, Clone, Serialize)]
 pub struct ReadEventsRequest<'a> {
     pub subject: &'a str,
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub options: Option<ReadEventsRequestOptions<'a>>,
+    pub options: Option<ReadEventsOptions<'a>>,
 }
 
 impl ClientRequest for ReadEventsRequest<'_> {
diff --git a/src/client/request_options.rs b/src/client/request_options.rs
@@ -5,10 +5,10 @@ use serde::Serialize;
 /// Options for reading events from the database
 #[derive(Debug, Default, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-pub struct ReadEventsRequestOptions<'a> {
+pub struct ReadEventsOptions<'a> {
     /// Start reading events from this start event
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub from_latest_event: Option<FromLatestEventOptions<'a>>,
+    pub from_latest_event: Option<ReadFromLatestEventOptions<'a>>,
     /// Lower bound of events to read
     #[serde(skip_serializing_if = "Option::is_none")]
     pub lower_bound: Option<Bound<'a>>,
@@ -25,10 +25,10 @@ pub struct ReadEventsRequestOptions<'a> {
 /// Options for observing events from the database
 #[derive(Debug, Default, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-pub struct ObserveEventsRequestOptions<'a> {
+pub struct ObserveEventsOptions<'a> {
     /// Start reading events from this start event
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub from_latest_event: Option<FromLatestEventOptions<'a>>,
+    pub from_latest_event: Option<ObserveFromLatestEventOptions<'a>>,
     /// Lower bound of events to read
     #[serde(skip_serializing_if = "Option::is_none")]
     pub lower_bound: Option<Bound<'a>>,
@@ -67,25 +67,48 @@ pub struct Bound<'a> {
     pub id: &'a str,
 }
 
-/// The strategy for handling missing events
+/// The strategy for handling missing events while reading
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "kebab-case")]
-pub enum EventMissingStrategy {
+pub enum ReadEventMissingStrategy {
     /// Read all events if the required one is missing
     ReadEverything,
     /// Read no events if the required one is missing
     ReadNothing,
 }
 
-/// Options for reading events from the start reading at
+/// The strategy for handling missing events while observing
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ObserveEventMissingStrategy {
+    /// Observe all events if the required one is missing
+    ObserveEverything,
+    /// Wait for the event until observing
+    WaitForEvent,
+}
+
+/// Options for reading events from the latest event of certain type or subject
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-pub struct FromLatestEventOptions<'a> {
+pub struct ReadFromLatestEventOptions<'a> {
     /// The strategy for handling missing events
-    pub if_event_is_missing: EventMissingStrategy,
+    pub if_event_is_missing: ReadEventMissingStrategy,
     /// The subject the event should be on
     pub subject: &'a str,
     /// The type of the event to read from
     #[serde(rename = "type")]
     pub ty: &'a str,
 }
+
+/// Options for observe events from the latest event of certain type or subject
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ObserveFromLatestEventOptions<'a> {
+    /// The strategy for handling missing events
+    pub if_event_is_missing: ObserveEventMissingStrategy,
+    /// The subject the event should be on
+    pub subject: &'a str,
+    /// The type of the event to observe from
+    #[serde(rename = "type")]
+    pub ty: &'a str,
+}
diff --git a/src/lib.rs b/src/lib.rs
diff --git a/tests/read_events.rs b/tests/read_events.rs

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+doc-valid-idents = ["EventSourcingDB", "EventQL", "CloudEvents", ".."]`