feat: add builders for collection schema and collection fields using bon; restructure library layout

Author: haydenhoang

typesense/Cargo.toml

@@ -29,6 +29,9 @@ reqwest-retry = "0.7.0"
 reqwest = { version = "0.12", features = ["json"] }
 reqwest-middleware = { version = "0.4.2", features = ["json"] }
 thiserror = "1.0"
+bon = "3.7.0"
+strum = { version = "0.26", features = ["derive"] }
+
 
 [dev-dependencies]
 dotenvy = "0.15"

typesense/src/builders/collection_field.rs

@@ -0,0 +1,54 @@
+//! Module with the common definitions for  the
+//! [fields](https://github.com/typesense/typesense/blob/v0.19.0/include/field.)
+//! available in Typesense.
+
+use crate::traits::FieldType;
+use bon::builder;
+use typesense_codegen::models::{Field as TypesenseField, FieldEmbed};
+
+/// Creates a new [`TypesenseField`] builder.
+#[builder(
+    // expose a public builder type named `FieldBuilder` and a public finish_fn `build()`
+    builder_type(name = FieldBuilder, vis = "pub"),
+    finish_fn(name = build, vis = "pub"),
+    // allow passing &str into String params
+    on(String, into)
+)]
+pub fn new_collection_field(
+    #[builder(start_fn)] name: String,
+
+    #[builder(start_fn)] typesense_type: FieldType,
+
+    optional: Option<bool>,
+    facet: Option<bool>,
+    index: Option<bool>,
+    locale: Option<String>,
+    sort: Option<bool>,
+    infix: Option<bool>,
+    num_dim: Option<i32>,
+    drop: Option<bool>,
+    embed: Option<Box<FieldEmbed>>,
+    store: Option<bool>,
+    stem: Option<bool>,
+    range_index: Option<bool>,
+    vec_dist: Option<String>,
+) -> TypesenseField {
+    TypesenseField {
+        name,
+        r#type: typesense_type,
+        optional,
+        facet,
+        index,
+        locale,
+        sort,
+        infix,
+        num_dim,
+        drop,
+        embed,
+        store,
+        stem,
+        range_index,
+        vec_dist,
+        ..Default::default()
+    }
+}

typesense/src/builders/collection_schema.rs

@@ -0,0 +1,137 @@
+//! # Collection
+//!
+//! In Typesense, a group of related documents is called a collection. A collection
+//! is roughly equivalent to a table in a relational database.
+//!
+use bon::builder;
+use typesense_codegen::models::{CollectionSchema, Field, VoiceQueryModelCollectionConfig};
+
+/// Creates a new [`CollectionSchema`] builder.
+///
+/// In Typesense, a collection is a group of related documents, similar to a table
+/// in a relational database. This builder enforces that `name` must be provided
+/// before [`build`](CollectionSchemaBuilder::build) can be called.
+///
+/// # Example
+///
+/// ```
+/// use typesense::builders::new_collection_schema;
+/// let fields = vec![];
+/// let schema = new_collection_schema("companies", fields)
+///     .default_sorting_field("num_employees")
+///     .build();
+/// ```
+#[builder(
+    builder_type(name = CollectionSchemaBuilder, vis = "pub"),
+    finish_fn(name = build, vis = "pub"),
+    state_mod(name = collection_schema_builder, vis = "pub"),
+    on(String, into)
+)]
+pub fn new_collection_schema(
+    /// The name of the collection. Must be unique within the Typesense instance.
+    #[builder(start_fn)]
+    name: String,
+
+    /// The list of fields that describe the schema of documents in this collection.
+    #[builder(start_fn)]
+    fields: Vec<Field>,
+
+    /// The name of the default sorting field for the collection.
+    default_sorting_field: Option<String>,
+
+    /// A list of token separators to use when indexing text fields.
+    token_separators: Option<Vec<String>>,
+
+    /// Whether nested fields are enabled.
+    enable_nested_fields: Option<bool>,
+
+    /// Symbols that should be indexed for this collection.
+    symbols_to_index: Option<Vec<String>>,
+
+    /// Configuration for Typesense’s Voice Query Model.
+    voice_query_model: Option<Box<VoiceQueryModelCollectionConfig>>,
+) -> CollectionSchema {
+    CollectionSchema {
+        name,
+        fields,
+        default_sorting_field,
+        token_separators,
+        enable_nested_fields,
+        symbols_to_index,
+        voice_query_model,
+    }
+}
+
+// custom convenience methods; the typestate module name matches `state_mod`
+impl<S: collection_schema_builder::State> CollectionSchemaBuilder<S> {
+    /// Adds a single [`Field`] to the collection schema.
+    ///
+    /// This is a convenience method for pushing one field at a time.
+    pub fn field(mut self, field: Field) -> Self {
+        self.fields.push(field);
+        self
+    }
+
+    /// Adds multiple [`Field`] values to the collection schema.
+    ///
+    /// This is a convenience method for appending a slice of fields.
+    pub fn fields(mut self, fields: &[Field]) -> Self
+    where
+        Field: Clone,
+    {
+        self.fields.extend_from_slice(fields);
+        self
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use crate::builders::new_collection_field;
+    use serde_json::json;
+
+    #[test]
+    fn collection_schema_serializes_as_expected() {
+        let fields = [
+            ("company_name", "string".to_owned(), None),
+            ("num_employees", "int32".to_owned(), None),
+            ("country", "string".to_owned(), Some(true)),
+        ]
+        .map(|(name, typesense_type, facet)| {
+            if facet.is_some() {
+                new_collection_field(name, typesense_type.into())
+                    .facet(facet.unwrap())
+                    .build()
+            } else {
+                new_collection_field(name, typesense_type.into()).build()
+            }
+        });
+
+        let collection: CollectionSchema =
+            new_collection_schema("companies", fields.clone().to_vec())
+                .fields(&fields)
+                .field(new_collection_field("size", "string".into()).build())
+                .default_sorting_field("num_employees")
+                .build();
+
+        let expected = json!(
+            {
+                "name": "companies",
+                "fields": [
+                  { "name": "company_name", "type": "string" },
+                  { "name": "num_employees", "type": "int32" },
+                  { "name": "country", "type": "string", "facet": true },
+
+                  { "name": "company_name", "type": "string" },
+                  { "name": "num_employees", "type": "int32" },
+                  { "name": "country", "type": "string", "facet": true },
+
+                  { "name": "size", "type": "string" },
+                ],
+                "default_sorting_field": "num_employees"
+            }
+        );
+
+        assert_eq!(serde_json::to_value(&collection).unwrap(), expected)
+    }
+}

typesense/src/builders/mod.rs

@@ -0,0 +1,6 @@
+//! Contain convenient builders for Typesense schemas.
+
+mod collection_field;
+mod collection_schema;
+pub use collection_field::new_collection_field;
+pub use collection_schema::new_collection_schema;

typesense/src/client/multi_search.rs

@@ -3,7 +3,7 @@
 //! A `MultiSearch` instance is created via the main `Client::multi_search()` method.
 
 use crate::{
-    models::SearchResult, Client, Error, MultiSearchParseError, MultiSearchResultExt,
+    models::SearchResult, traits::MultiSearchResultExt, Client, Error, MultiSearchParseError,
     MultiSearchSearchesParameter,
 };
 use serde::de::DeserializeOwned;

typesense/src/collection_schema.rs

@@ -1,3 +1,5 @@
+//! Contains the error types for the Typesense client
+
 use thiserror::Error;
 pub use typesense_codegen::apis::Error as ApiError;