Add find_one_and_update method to Document class for atomic operations with object return

[Hambaobao]

Problem

Currently, Beanie doesn't provide a convenient way to perform atomic find_one_and_update operations while returning a Beanie Document object. Users have to choose between:

1. Using get_pymongo_collection().find_one_and_update() - atomic but returns raw dict
2. Using find_one() + save() - returns object but not atomic

This forces developers to either sacrifice atomicity or deal with manual dict-to-object conversion.

Current Workaround

# Option 1: Atomic but returns dict
result = await MyDocument.get_pymongo_collection().find_one_and_update(
    {"field": "value"},
    {"$set": {"status": "updated"}},
    return_document=ReturnDocument.AFTER
)
doc = MyDocument.model_validate(result) if result else None

# Option 2: Returns object but not atomic  
doc = await MyDocument.find_one({"field": "value"})
if doc:
    doc.status = "updated"
    await doc.save()

Proposed Solution

Add find_one_and_update method to the Document class that:

• Performs atomic find and update operations
• Returns a Document object (or None if no match)
• Follows similar API pattern as PyMongo but with Beanie's ORM benefits

Suggested API

@classmethod
async def find_one_and_update(
    cls,
    filter_dict: Dict[str, Any],
    update_dict: Dict[str, Any],
    *,
    return_document: ReturnDocument = ReturnDocument.BEFORE,
    upsert: bool = False,
    sort: Optional[List[Tuple[str, int]]] = None,
    projection: Optional[Dict[str, Any]] = None,
    **kwargs
) -> Optional["Document"]:
    """
    Find a single document and update it atomically.
    
    Args:
        filter_dict: Query filter
        update_dict: Update operations
        return_document: Whether to return document before or after update
        upsert: Whether to insert if no match found
        sort: Sort specification
        projection: Fields to include/exclude
        **kwargs: Additional PyMongo options
        
    Returns:
        Updated Document object or None if no match
    """

Use Cases

• Implementing distributed locks or semaphores
• Atomic status updates in job queues
• Race-condition-free counter increments
• Any scenario requiring atomic find-and-modify operations

Benefits

• Maintains atomicity while preserving Beanie's ORM features
• Reduces boilerplate code
• Improves type safety
• Consistent with Beanie's design philosophy

This would greatly improve the developer experience when working with atomic operations in Beanie applications.