From 0111c97a8087d0de82e5eb3fef3db79f7d0fcf2b Mon Sep 17 00:00:00 2001 From: Joshua Lung Date: Wed, 11 Jan 2023 15:22:04 +0100 Subject: [PATCH 1/6] some basic doc comments --- src/fluent_api/insert_builder.rs | 5 +++++ src/fluent_api/mod.rs | 8 ++++++++ 2 files changed, 13 insertions(+) diff --git a/src/fluent_api/insert_builder.rs b/src/fluent_api/insert_builder.rs index 90430e3..771e293 100644 --- a/src/fluent_api/insert_builder.rs +++ b/src/fluent_api/insert_builder.rs @@ -19,6 +19,7 @@ where Self { db } } + /// Specifies the collection to insert into #[inline] pub fn into(self, collection_id: &str) -> FirestoreInsertDocIdBuilder<'a, D> { FirestoreInsertDocIdBuilder::new(self.db, collection_id.to_string()) @@ -43,6 +44,7 @@ where Self { db, collection_id } } + /// Set the document id #[inline] pub fn document_id(self, document_id: S) -> FirestoreInsertDocObjBuilder<'a, D> where @@ -55,6 +57,7 @@ where ) } + /// Automatically generate a document id #[inline] pub fn generate_document_id(self) -> FirestoreInsertDocObjBuilder<'a, D> { FirestoreInsertDocObjBuilder::new(self.db, self.collection_id, None) @@ -116,6 +119,7 @@ where } } + /// Set the document content #[inline] pub fn document(self, document: Document) -> FirestoreInsertDocExecuteBuilder<'a, D> { FirestoreInsertDocExecuteBuilder::new( @@ -181,6 +185,7 @@ where } } + /// Execute the insert operation pub async fn execute(self) -> FirestoreResult { if let Some(parent) = self.parent { self.db diff --git a/src/fluent_api/mod.rs b/src/fluent_api/mod.rs index f48a782..be45eef 100644 --- a/src/fluent_api/mod.rs +++ b/src/fluent_api/mod.rs @@ -41,26 +41,31 @@ where Self { db } } + /// Select a document from the database #[inline] pub fn select(self) -> FirestoreSelectInitialBuilder<'a, D> { FirestoreSelectInitialBuilder::new(self.db) } + /// Insert a new document into the database #[inline] pub fn insert(self) -> FirestoreInsertInitialBuilder<'a, D> { FirestoreInsertInitialBuilder::new(self.db) } + /// Update a document in the database #[inline] pub fn update(self) -> FirestoreUpdateInitialBuilder<'a, D> { FirestoreUpdateInitialBuilder::new(self.db) } + /// Delete a document in the database #[inline] pub fn delete(self) -> FirestoreDeleteInitialBuilder<'a, D> { FirestoreDeleteInitialBuilder::new(self.db) } + /// List documents in the database #[inline] pub fn list(self) -> FirestoreListingInitialBuilder<'a, D> { FirestoreListingInitialBuilder::new(self.db) @@ -68,6 +73,9 @@ where } impl FirestoreDb { + /// Fluent API + /// + /// The Fluent API simplifies development and the developer experience. The library provides a more high level API starting with v0.12.x. This is the recommended API for all applications to use. #[inline] pub fn fluent(&self) -> FirestoreExprBuilder { FirestoreExprBuilder::new(self) From ae34af5bfe57ec3b1a27a3c3a145dfd5610507d3 Mon Sep 17 00:00:00 2001 From: Joshua Lung Date: Wed, 11 Jan 2023 18:46:53 +0100 Subject: [PATCH 2/6] some more documentation --- src/fluent_api/select_builder.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/fluent_api/select_builder.rs b/src/fluent_api/select_builder.rs index 4942990..99dc496 100644 --- a/src/fluent_api/select_builder.rs +++ b/src/fluent_api/select_builder.rs @@ -58,6 +58,7 @@ where } } + /// Select multiple documents from collection #[inline] pub fn from(self, collection: C) -> FirestoreSelectDocBuilder<'a, D> where @@ -68,6 +69,7 @@ where FirestoreSelectDocBuilder::new(self.db, params) } + /// Select document by Id #[inline] pub fn by_id_in(self, collection: &str) -> FirestoreSelectByIdBuilder<'a, D> { FirestoreSelectByIdBuilder::new(self.db, collection.to_string(), self.return_only_fields) From 56073b2362fa021ef7d0eeb016da60cb4d7612f3 Mon Sep 17 00:00:00 2001 From: jo_kil Date: Wed, 11 Jan 2023 21:51:20 +0100 Subject: [PATCH 3/6] more documentation --- src/db/list_doc.rs | 3 +++ src/db/query_models.rs | 4 ++++ src/fluent_api/listing_builder.rs | 14 ++++++++++++++ src/fluent_api/mod.rs | 10 ++++++++-- 4 files changed, 29 insertions(+), 2 deletions(-) diff --git a/src/db/list_doc.rs b/src/db/list_doc.rs index 2989ff4..bd5a5da 100644 --- a/src/db/list_doc.rs +++ b/src/db/list_doc.rs @@ -27,9 +27,12 @@ pub struct FirestoreListDocParams { pub return_only_fields: Option>, } +/// The result of a list documents call #[derive(Debug, PartialEq, Clone, Builder)] pub struct FirestoreListDocResult { + /// the list of documents pub documents: Vec, + /// the next page token pub page_token: Option, } diff --git a/src/db/query_models.rs b/src/db/query_models.rs index c212df9..6507b54 100644 --- a/src/db/query_models.rs +++ b/src/db/query_models.rs @@ -262,9 +262,12 @@ impl From<&FirestoreQueryParams> for StructuredQuery { } } +/// Used for sorting #[derive(Debug, Eq, PartialEq, Clone, Builder)] pub struct FirestoreQueryOrder { + /// The field name to order by. field_name: String, + /// The direction to order by. direction: FirestoreQueryDirection, } @@ -303,6 +306,7 @@ impl From<&FirestoreQueryOrder> for structured_query::Order { } } +/// Specifies the order to sort by. #[derive(Debug, Eq, PartialEq, Clone)] pub enum FirestoreQueryDirection { Ascending, diff --git a/src/fluent_api/listing_builder.rs b/src/fluent_api/listing_builder.rs index 9b3abdc..35fac2d 100644 --- a/src/fluent_api/listing_builder.rs +++ b/src/fluent_api/listing_builder.rs @@ -45,6 +45,7 @@ where } } + /// Select a collection to list documents from #[inline] pub fn from(self, collection: &str) -> FirestoreListingDocBuilder<'a, D> { let params: FirestoreListDocParams = FirestoreListDocParams::new(collection.to_string()) @@ -91,6 +92,7 @@ where } } + /// Sets the page size for the query #[inline] pub fn page_size(self, value: usize) -> Self { Self { @@ -99,6 +101,15 @@ where } } + /// Order the querry by the given field + /// + /// Usage: + /// ``` + /// .order_by([( + /// path!(MyTestStructure::some_id), + /// FirestoreQueryDirection::Ascending, + /// )]) + /// ``` #[inline] pub fn order_by(self, fields: I) -> Self where @@ -113,6 +124,9 @@ where } } + /// Gets the first page of results + /// + /// Page size can be set with the `page_size` pub async fn get_page(self) -> FirestoreResult { self.db.list_doc(self.params).await } diff --git a/src/fluent_api/mod.rs b/src/fluent_api/mod.rs index be45eef..1af0698 100644 --- a/src/fluent_api/mod.rs +++ b/src/fluent_api/mod.rs @@ -41,7 +41,9 @@ where Self { db } } - /// Select a document from the database + /// Select one or more documents from the database + /// + /// Single documents can be selected by thier IDs, multiple documents can be selected with a query filter. #[inline] pub fn select(self) -> FirestoreSelectInitialBuilder<'a, D> { FirestoreSelectInitialBuilder::new(self.db) @@ -54,6 +56,8 @@ where } /// Update a document in the database + /// + /// Documents can be implicitly created using update when using your own document IDs. Useful to use in batches and transactions. #[inline] pub fn update(self) -> FirestoreUpdateInitialBuilder<'a, D> { FirestoreUpdateInitialBuilder::new(self.db) @@ -65,7 +69,9 @@ where FirestoreDeleteInitialBuilder::new(self.db) } - /// List documents in the database + /// List documents in a collection (or subcollection) + /// + /// This is a convenience method to list all documents in a collection. For more complex queries, use the select method. #[inline] pub fn list(self) -> FirestoreListingInitialBuilder<'a, D> { FirestoreListingInitialBuilder::new(self.db) From 63dd0f6d771e72cecc546e2706218ec97ade9370 Mon Sep 17 00:00:00 2001 From: jo_kil Date: Wed, 11 Jan 2023 22:24:32 +0100 Subject: [PATCH 4/6] more doc (marking unknown stuff with TODO) --- src/fluent_api/select_builder.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/fluent_api/select_builder.rs b/src/fluent_api/select_builder.rs index 99dc496..5ae2fe7 100644 --- a/src/fluent_api/select_builder.rs +++ b/src/fluent_api/select_builder.rs @@ -69,7 +69,7 @@ where FirestoreSelectDocBuilder::new(self.db, params) } - /// Select document by Id + /// Select one or more documents by Id #[inline] pub fn by_id_in(self, collection: &str) -> FirestoreSelectByIdBuilder<'a, D> { FirestoreSelectByIdBuilder::new(self.db, collection.to_string(), self.return_only_fields) @@ -354,6 +354,7 @@ where } } + /// Get multiple documents by their ids. pub async fn batch( self, document_ids: I, @@ -410,6 +411,7 @@ where } } + /// Select documents to listen for changes with the given ids. pub fn batch_listen( self, document_ids: I, @@ -746,6 +748,8 @@ where } } + // Specify the listener + // TODO: what does the `FirestoreListenerTarget` do? #[inline] pub fn add_target( self, From c7a9e8915a1c9292dd4411bc9d5b8a8069332985 Mon Sep 17 00:00:00 2001 From: jo_kil Date: Mon, 6 Feb 2023 16:31:49 +0100 Subject: [PATCH 5/6] Removed possibly unneeded `Sync` --- src/db/listen_changes.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/db/listen_changes.rs b/src/db/listen_changes.rs index 3ec0848..4e55bcf 100644 --- a/src/db/listen_changes.rs +++ b/src/db/listen_changes.rs @@ -228,7 +228,7 @@ where pub async fn start(&mut self, cb: FN) -> FirestoreResult<()> where FN: Fn(FirestoreListenEvent) -> F + Send + Sync + 'static, - F: Future> + Send + Sync + 'static, + F: Future> + Send + 'static, { info!( "Starting a Firestore listener for targets: {:?}...", @@ -297,7 +297,7 @@ where ) where D: FirestoreListenSupport + Clone + Send + Sync, FN: Fn(FirestoreListenEvent) -> F + Send + Sync, - F: Future> + Send + Sync, + F: Future> + Send, { while !shutdown_flag.load(Ordering::Relaxed) { debug!("Start listening on targets {:?}... ", targets_state.len()); From ec3a1d20b13f89df5ebfc7cb49b63e049e290204 Mon Sep 17 00:00:00 2001 From: jo_kil Date: Mon, 6 Feb 2023 16:35:27 +0100 Subject: [PATCH 6/6] Revert "Removed possibly unneeded `Sync`" This reverts commit c7a9e8915a1c9292dd4411bc9d5b8a8069332985. --- src/db/listen_changes.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/db/listen_changes.rs b/src/db/listen_changes.rs index 4e55bcf..3ec0848 100644 --- a/src/db/listen_changes.rs +++ b/src/db/listen_changes.rs @@ -228,7 +228,7 @@ where pub async fn start(&mut self, cb: FN) -> FirestoreResult<()> where FN: Fn(FirestoreListenEvent) -> F + Send + Sync + 'static, - F: Future> + Send + 'static, + F: Future> + Send + Sync + 'static, { info!( "Starting a Firestore listener for targets: {:?}...", @@ -297,7 +297,7 @@ where ) where D: FirestoreListenSupport + Clone + Send + Sync, FN: Fn(FirestoreListenEvent) -> F + Send + Sync, - F: Future> + Send, + F: Future> + Send + Sync, { while !shutdown_flag.load(Ordering::Relaxed) { debug!("Start listening on targets {:?}... ", targets_state.len());