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/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/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 f48a782..1af0698 100644 --- a/src/fluent_api/mod.rs +++ b/src/fluent_api/mod.rs @@ -41,26 +41,37 @@ where Self { db } } + /// 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) } + /// 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 + /// + /// 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) } + /// Delete a document in the database #[inline] pub fn delete(self) -> FirestoreDeleteInitialBuilder<'a, D> { FirestoreDeleteInitialBuilder::new(self.db) } + /// 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) @@ -68,6 +79,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) diff --git a/src/fluent_api/select_builder.rs b/src/fluent_api/select_builder.rs index 4942990..5ae2fe7 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 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) @@ -352,6 +354,7 @@ where } } + /// Get multiple documents by their ids. pub async fn batch( self, document_ids: I, @@ -408,6 +411,7 @@ where } } + /// Select documents to listen for changes with the given ids. pub fn batch_listen( self, document_ids: I, @@ -744,6 +748,8 @@ where } } + // Specify the listener + // TODO: what does the `FirestoreListenerTarget` do? #[inline] pub fn add_target( self,