diff --git a/README.md b/README.md index 68f2a35..fa36464 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ async fn main() { .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned()) .build() .unwrap() - .execute::() + .stream_items::(); while let Some(result) = rec_stream.next().await { let rec = result.unwrap(); diff --git a/ferrtable-test/src/main.rs b/ferrtable-test/src/main.rs index c12c9da..5c19d8b 100644 --- a/ferrtable-test/src/main.rs +++ b/ferrtable-test/src/main.rs @@ -1,5 +1,5 @@ use ferrtable::Client; -use futures::prelude::*; +use futures::StreamExt as _; use serde::{Deserialize, Serialize}; use crate::settings::Settings; @@ -45,15 +45,20 @@ async fn main() { .unwrap(); println!("Testing Client::list_records()..."); - let mut records = client + let records = client .list_records() .with_base_id(settings.base_id.clone()) .with_table_id(settings.table_id.clone()) .build() .unwrap() - .execute::(); - while let Some(res) = records.next().await { - dbg!(res.unwrap().fields); + .stream_items::() + .collect::>() + .await + .into_iter() + .collect::, _>>() + .unwrap(); + for rec in records { + dbg!(rec.fields); } println!("All tests succeeded."); diff --git a/ferrtable/src/client.rs b/ferrtable/src/client.rs index 16040f4..dd7ef85 100644 --- a/ferrtable/src/client.rs +++ b/ferrtable/src/client.rs @@ -44,11 +44,34 @@ impl Client { }) } - /// Constructs a builder for inserting up to 10 records at a time into a - /// table. + /// Creates multiple records. Note that table names and table ids can be + /// used interchangeably. We recommend using table IDs so you don't need + /// to modify your API request when your table name changes. /// - /// Specify the base and table IDs with its `.with_base_id()` and - /// `.with_table_id()` methods. + /// Your request body should include an array of up to 10 record objects. + /// + /// Returns a unique array of the newly created record ids if the call + /// succeeds. + /// + /// # Examples + /// + /// ```no_run + /// client + /// .create_records([ + /// HashMap<&str, &str>::from([ + /// ("name", "Steal Improbability Drive"), + /// ("notes", "Just for fun, no other reason."), + /// ("status", "In progress"), + /// ]), + /// ]) + /// .with_base_id("***".to_owned()) + /// .with_table_id("***".to_owned()) + /// .build() + /// .unwrap() + /// .execute() + /// .await + /// .unwrap(); + /// ``` pub fn create_records(&self, records: I) -> CreateRecordsQueryBuilder where T: Serialize, @@ -59,10 +82,28 @@ impl Client { .with_records(records.into_iter().collect()) } - /// Constructs a builder for listing records in a table or view. + /// List records in a table. Note that table names and table ids can be used + /// interchangeably. We recommend using table IDs so you don't need to modify + /// your API request when your table name changes. /// - /// Specify the base and table IDs with its `.with_base_id()` and - /// `.with_table_id()` methods. + /// # Examples + /// + /// ## Consuming as Stream + /// + /// ```no_run + /// let mut rec_stream = client + /// .list_records() + /// .with_base_id("***") + /// .with_table_id("***") + /// .build() + /// .unwrap() + /// .stream_items::>(); + /// + /// while let Some(result) = rec_stream.next().await { + /// let rec = result.unwrap(); + /// dbg!(rec.fields); + /// } + /// ``` pub fn list_records(&self) -> ListRecordsQueryBuilder { ListRecordsQueryBuilder::default().with_client(self.clone()) } diff --git a/ferrtable/src/list_records.rs b/ferrtable/src/list_records.rs index bf0b828..6e70779 100644 --- a/ferrtable/src/list_records.rs +++ b/ferrtable/src/list_records.rs @@ -88,35 +88,7 @@ macro_rules! handle_stream_err { } impl ListRecordsQuery { - /// Execute the API request. - /// - /// Currently, failures return a one-size-fits-all error wrapping the - /// underlying `reqwest::Error`. This may be improved in future releases - /// to better differentiate between network, serialization, deserialization, - /// and API errors. - /// - /// Pagination is handled automatically, and items are returned as a - /// seemingly continuous stream of Results. If an error is encountered while - /// fetching a page, the Err will be yielded immediately and no further - /// items will be returned. - /// - /// # Examples - /// - /// ``` - /// let mut rec_stream = client - /// .list_records() - /// .with_base_id("***") - /// .with_table_id("***") - /// .build() - /// .unwrap() - /// .execute::>() - /// - /// while let Some(result) = rec_stream.next().await { - /// let rec = result.unwrap(); - /// dbg!(rec.fields); - /// } - /// ``` - pub fn execute( + pub fn stream_items( self, ) -> Pin, ExecutionError>>>> where