feat(derive): Implement advanced nested and flattened field handling

This commit introduces a comprehensive and robust implementation for handling complex document structures within the `#[derive(Typesense)]` macro, enabling powerful schema generation directly from Rust structs.

The macro now supports the full range of advanced indexing strategies offered by Typesense, including automatic object indexing, field flattening with prefix control, and patterns for manual flattening.

### Key Features & Implementation Details

- **Automatic Object Indexing:**
  - A field containing a nested struct that also derives `Document` is now automatically mapped to a Typesense `object` (or `object[]` for `Vec<T>`).
  - This feature requires `#[typesense(enable_nested_fields = true)]` on the parent collection, which the macro now supports.

- **Automatic Field Flattening with `#[typesense(flatten)]`:**
  - A field marked `#[typesense(flatten)]` has its sub-fields expanded into the parent schema using dot-notation.
  - By default, the Rust field's name is used as the prefix for all sub-fields (e.g., `details: ProductDetails` results in schema fields like `details.part_number`).

- **Prefix Override for Flattening:**
  - The `flatten` attribute can be combined with `rename` to provide a custom prefix for the flattened fields.
  - Usage: `#[typesense(flatten, rename = "custom_prefix")]`
  - This provides powerful schema mapping flexibility, allowing the Rust struct's field name to differ from the prefix used in the Typesense schema.

- **Manual Flattening Pattern (`skip` + `rename`):**
  - A new `#[typesense(skip)]` attribute has been introduced to completely exclude a field from the generated Typesense schema.
  - This enables the powerful pattern of sending both nested and flattened data to Typesense: the nested version can be used for display/deserialization, while a separate set of flattened fields is used for indexing. This is achieved by:
    1.  Marking the nested struct field (e.g., `details: Details`) with `#[typesense(skip)]`.
    2.  Adding corresponding top-level fields to the Rust struct, marked with `#[typesense(rename = "details.field_name")]`.

- **Ergonomic Boolean Attributes:**
  - All boolean attributes (`facet`, `sort`, `index`, `store`, `infix`, `stem`, `optional`, `range_index`) now support shorthand "flag" syntax.
  - For example, `#[typesense(sort)]` is a valid and recommended equivalent to `#[typesense(sort = true)]`, dramatically improving readability and consistency.

- **Robust Error Handling & Validation:**
  - The macro provides clear, compile-time errors for invalid or ambiguous attribute usage.
  - It correctly detects and reports duplicate attributes, whether they are in the same `#[typesense(...)]` block or across multiple attributes on the same field.

### Testing

- **Comprehensive Integration Test (`derive_integration.rs`):**
  - A new, full-lifecycle integration test has been added to validate the entire feature set.
  - The test defines a complex struct using every new attribute and pattern, generates a schema, creates a real collection, and uses the generic client (`collection_of<T>`) to perform and validate a full Create, Read, Update, Delete, and Search lifecycle.
  - A second integration test was added to specifically validate the manual flattening pattern.

- **UI Tests:**
  - `trybuild` UI tests have been added to verify that the macro produces the correct compile-time errors for invalid attribute combinations, such as duplicate attributes.

Author: haydenhoang

typesense/src/field/field_type.rs

@@ -1,5 +1,5 @@
+use crate::document::Document;
 use std::collections::{BTreeMap, HashMap};
-
 /// Type for a field. Currently it is a wrapping to a `String` but it could be extended to a enum
 pub type FieldType = String;
 
@@ -10,6 +10,19 @@ pub trait ToTypesenseField {
     fn to_typesense_type() -> &'static str;
 }
 
+/// Generic implementation for any type that is also a Typesense document.
+impl<T: Document> ToTypesenseField for T {
+    fn to_typesense_type() -> &'static str {
+        "object"
+    }
+}
+
+/// Generic implementation for a Vec of any type that is also a Typesense document.
+impl<T: Document> ToTypesenseField for Vec<T> {
+    fn to_typesense_type() -> &'static str {
+        "object[]"
+    }
+}
 /// macro used internally to add implementations of ToTypesenseField for several rust types.
 #[macro_export]
 macro_rules! impl_to_typesense_field (

typesense/src/field/mod.rs

@@ -20,6 +20,10 @@ pub struct FieldBuilder {
     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>,
 }
 
 impl FieldBuilder {
@@ -89,6 +93,34 @@ impl FieldBuilder {
         self
     }
 
+    /// Set store attribute for field
+    #[inline]
+    pub fn store(mut self, store: Option<bool>) -> Self {
+        self.store = store;
+        self
+    }
+
+    /// Set stem attribute for field
+    #[inline]
+    pub fn stem(mut self, stem: Option<bool>) -> Self {
+        self.stem = stem;
+        self
+    }
+
+    /// Set range_index attribute for field
+    #[inline]
+    pub fn range_index(mut self, range_index: Option<bool>) -> Self {
+        self.range_index = range_index;
+        self
+    }
+
+    /// Set vec_dist attribute for field
+    #[inline]
+    pub fn vec_dist(mut self, vec_dist: Option<String>) -> Self {
+        self.vec_dist = vec_dist;
+        self
+    }
+
     /// Create a `Field` with the current values of the builder,
     /// It can fail if the name or the typesense_type are not defined.
     #[inline]
@@ -105,6 +137,10 @@ impl FieldBuilder {
             num_dim: self.num_dim,
             drop: self.drop,
             embed: self.embed,
+            store: self.store,
+            stem: self.stem,
+            range_index: self.range_index,
+            vec_dist: self.vec_dist,
             ..Default::default()
         }
     }