feat: Add support for various field operations in dynamic queries

- Introduced new field operations such as IN, GREATER_THAN, LESS_THAN, and LIKE to enhance dynamic query generation capabilities.
- Updated the documentation to include detailed descriptions and examples of supported field operations.
- Modified the `UserRepository` and `ProductRepository` classes to implement new methods for these operations, ensuring consistent usage across repositories.
- Enhanced return types for query methods to use `Optional` for better handling of potential null results.

Author: William-W-Chen

README.md

@@ -10,6 +10,7 @@ Features
 -   Automatic CRUD Repository: PySpringModel automatically generates a CRUD repository for each of your SQLModel entities, providing common database operations such as Create, Read, Update, and Delete.
 -   Managed Sessions: PySpringModel provides a context manager for database sessions, automatically handling session commit and rollback to ensure data consistency.
 -   Dynamic Query Generation: PySpringModel can dynamically generate and execute SQL queries based on method names in your repositories.
+-   Field Operations Support: PySpringModel supports various field operations like IN, NOT IN, greater than, less than, LIKE, and more.
 -   Custom SQL Queries: PySpringModel supports custom SQL queries using the `@Query` decorator for complex database operations.
 -   RESTful API Integration: PySpringModel integrates with the PySpring framework to automatically generate basic table CRUD APIs for your SQLModel entities.
 
@@ -50,6 +51,11 @@ class UserRepository(CrudRepository[int, User]):
     def find_all_by_status(self, status: str) -> List[User]: ...
     def find_all_by_age_and_status(self, age: int, status: str) -> List[User]: ...
 
+    # Field operations
+    def find_all_by_status_in(self, status: List[str]) -> List[User]: ...
+    def find_by_age_gt(self, age: int) -> Optional[User]: ...
+    def find_by_name_like(self, name: str) -> Optional[User]: ...
+    
     # Custom SQL queries using @Query decorator
     @Query("SELECT * FROM user WHERE age > {min_age}")
     def find_users_older_than(self, min_age: int) -> List[User]: ...
@@ -123,6 +129,84 @@ def find_all_by_status_or_age(self, status: str, age: int) -> List[User]: ...
 def get_all_by_name_or_email(self, name: str, email: str) -> List[User]: ...
 ```
 
+### Field Operations
+
+PySpringModel supports various field operations for dynamic query generation:
+
+#### Supported Operations
+
+| Operation | Suffix | Description | Example |
+|-----------|--------|-------------|---------|
+| `EQUALS` | (default) | Field equals value | `find_by_name` |
+| `IN` | `_in` | Field in list of values | `find_by_status_in` |
+| `GREATER_THAN` | `_gt` | Field greater than value | `find_by_age_gt` |
+| `GREATER_EQUAL` | `_gte` | Field greater than or equal to value | `find_by_age_gte` |
+| `LESS_THAN` | `_lt` | Field less than value | `find_by_age_lt` |
+| `LESS_EQUAL` | `_lte` | Field less than or equal to value | `find_by_age_lte` |
+| `LIKE` | `_like` | Field matches pattern | `find_by_name_like` |
+| `NOT_EQUALS` | `_ne` | Field not equals value | `find_by_status_ne` |
+| `NOT_IN` | `_not_in` | Field not in list of values | `find_by_category_not_in` |
+
+#### Field Operation Examples
+
+```py
+class UserRepository(CrudRepository[int, User]):
+    # IN operations
+    def find_all_by_status_in(self, status: List[str]) -> List[User]: ...
+    def find_all_by_id_in(self, id: List[int]) -> List[User]: ...
+    
+    # Comparison operations
+    def find_by_age_gt(self, age: int) -> Optional[User]: ...
+    def find_all_by_age_gte(self, age: int) -> List[User]: ...
+    def find_by_age_lt(self, age: int) -> Optional[User]: ...
+    def find_by_age_lte(self, age: int) -> Optional[User]: ...
+    
+    # Pattern matching
+    def find_by_name_like(self, name: str) -> Optional[User]: ...
+    
+    # Negation operations
+    def find_by_status_ne(self, status: str) -> Optional[User]: ...
+    def find_by_category_not_in(self, category: List[str]) -> List[User]: ...
+    
+    # Combined operations
+    def find_by_age_gt_and_status_in(self, age: int, status: List[str]) -> Optional[User]: ...
+    def find_by_salary_gte_or_category_in(self, salary: float, category: List[str]) -> Optional[User]: ...
+```
+
+#### Usage Examples
+
+```py
+# Create repository instance
+user_repo = UserRepository()
+
+# IN operations
+active_or_pending_users = user_repo.find_all_by_status_in(
+    status=["active", "pending"]
+)
+
+users_by_ids = user_repo.find_all_by_id_in(id=[1, 2, 3, 5])
+
+# Comparison operations
+adults = user_repo.find_all_by_age_gte(age=18)
+young_users = user_repo.find_by_age_lt(age=25)
+senior_users = user_repo.find_by_age_gte(age=65)
+
+# Pattern matching
+johns = user_repo.find_by_name_like(name="%John%")
+
+# Negation operations
+non_active_users = user_repo.find_by_status_ne(status="active")
+non_employees = user_repo.find_by_category_not_in(
+    category=["employee", "intern"]
+)
+
+# Complex combinations
+target_users = user_repo.find_by_age_gt_and_status_in(
+    age=30, 
+    status=["active", "pending"]
+)
+```
+
 ### Custom SQL Queries
 
 For complex queries that can't be expressed through method names, use the `@Query` decorator:
@@ -208,6 +292,11 @@ class UserRepository(CrudRepository[int, User]):
     def find_all_by_status(self, status: str) -> List[User]: ...
     def find_all_by_age_and_status(self, age: int, status: str) -> List[User]: ...
 
+    # Field operations
+    def find_all_by_status_in(self, status: List[str]) -> List[User]: ...
+    def find_by_age_gt(self, age: int) -> Optional[User]: ...
+    def find_by_name_like(self, name: str) -> Optional[User]: ...
+    
     # Custom SQL queries
     @Query("SELECT * FROM user WHERE age > {min_age}")
     def find_users_older_than(self, min_age: int) -> List[User]: ...
@@ -243,9 +332,72 @@ The dynamic query generation follows these naming conventions:
 - **Single field**: `find_by_name` → `WHERE name = ?`
 - **Multiple fields with AND**: `find_by_name_and_email` → `WHERE name = ? AND email = ?`
 - **Multiple fields with OR**: `find_by_name_or_email` → `WHERE name = ? OR email = ?`
-- **Return types**: 
-  - `find_by_*` and `get_by_*` return `Optional[Model]`
-  - `find_all_by_*` and `get_all_by_*` return `List[Model]`
+- **Field operations**: `find_by_age_gt` → `WHERE age > ?`, `find_by_status_in` → `WHERE status IN (?)`
+
+### Parameter Field Mapping
+
+The system supports both exact matching and common plural-to-singular mapping:
+
+- **Exact Matching**: Parameter names match field names exactly
+- **Plural Support**: Parameters can use plural forms (add 's') for better API design
+- **Clear Rules**: No ambiguity - parameters must match exactly or be plural forms
+- **Helpful Errors**: Clear error messages when mapping fails
+
+```python
+class UserRepository(CrudRepository[int, User]):
+    # Method: find_by_name_and_age
+    # Fields extracted: ['name', 'age']
+    
+    # ✅ Valid - Exact parameter names
+    def find_by_name_and_age(self, name: str, age: int) -> Optional[User]: ...
+    
+    # ✅ Valid - Different order but same names
+    def find_by_name_and_age(self, age: int, name: str) -> Optional[User]: ...
+    
+    # ✅ Valid - Plural parameters for better API design
+    def find_by_name_and_age(self, names: List[str], ages: List[int]) -> Optional[User]: ...
+    
+    # ✅ Valid - Mixed singular and plural
+    def find_by_name_and_age(self, name: str, ages: List[int]) -> Optional[User]: ...
+    
+    # ❌ Invalid - Wrong parameter names
+    def find_by_name_and_age(self, username: str, user_age: int) -> Optional[User]: ...  # Should be 'name' and 'age'
+```
+
+**Return types**: 
+- `find_by_*` and `get_by_*` return `Optional[Model]`
+- `find_all_by_*` and `get_all_by_*` return `List[Model]`
+
+### Quality-Focused Approach
+
+The system balances simplicity with API quality:
+
+**✅ Current Approach (Quality + Simplicity)**
+```python
+# Method: find_by_name_and_age
+# Fields: ['name', 'age']
+
+def find_by_name_and_age(self, name: str, age: int) -> Optional[User]: ...
+# ✅ Works: exact parameter names
+
+def find_by_name_and_age(self, names: List[str], ages: List[int]) -> Optional[User]: ...
+# ✅ Works: plural parameters for better API design
+
+def find_by_name_and_age(self, username: str, user_age: int) -> Optional[User]: ...
+# ❌ Fails: clear error about wrong parameter names
+```
+
+**Plural-to-Singular Mapping Rules:**
+- **Exact Match First**: If parameter name exists as a field, use it directly
+- **Regular Plurals**: `names` → `name`, `ages` → `age`
+- **Special Cases**: `statuses` → `status`, `categories` → `category`
+- **No Ambiguity**: Won't map if both singular and plural forms exist as fields
+
+**Key Benefits:**
+- **API Quality**: Plural parameters make APIs more intuitive
+- **Predictable**: Clear rules about what works and what doesn't
+- **Smart Handling**: Properly handles words ending with 's' like 'status'
+- **Maintainable**: Simple logic that's easy to understand
 
 ### Query Decorator Features
 

py_spring_model/docs/query_operators.md

@@ -1,6 +1,6 @@
 # Field Operations Support in PySpringModel
 
-PySpringModel now supports multiple field operations for dynamic query generation, similar to Spring Data JPA. This allows you to find entities using various comparison operators and conditions.
+PySpringModel supports multiple field operations for dynamic query generation, similar to Spring Data JPA. This allows you to find entities using various comparison operators and conditions.
 
 ## Supported Field Operations
 
@@ -24,7 +24,7 @@ To use field operations, append the appropriate suffix to your field name in the
 
 ```python
 from py_spring_model import PySpringModel, Field, CrudRepository
-from typing import List
+from typing import List, Optional
 
 class User(PySpringModel, table=True):
     id: int = Field(default=None, primary_key=True)
@@ -41,16 +41,16 @@ class UserRepository(CrudRepository[int, User]):
     def find_all_by_id_in(self, id: List[int]) -> List[User]: ...
 
     # Comparison operations
-    def find_by_age_gt(self, age: int) -> User: ...
+    def find_by_age_gt(self, age: int) -> Optional[User]: ...
     def find_all_by_age_gte(self, age: int) -> List[User]: ...
-    def find_by_age_lt(self, age: int) -> List[User]: ...
-    def find_by_age_lte(self, age: int) -> List[User]: ...
+    def find_by_age_lt(self, age: int) -> Optional[User]: ...
+    def find_by_age_lte(self, age: int) -> Optional[User]: ...
 
     # Pattern matching
-    def find_by_name_like(self, name: str) -> List[User]: ...
+    def find_by_name_like(self, name: str) -> Optional[User]: ...
 
     # Negation operations
-    def find_by_status_ne(self, status: str) -> List[User]: ...
+    def find_by_status_ne(self, status: str) -> Optional[User]: ...
     def find_by_category_not_in(self, category: List[str]) -> List[User]: ...
 ```
 
@@ -93,7 +93,7 @@ class UserRepository(CrudRepository[int, User]):
         self, 
         age: int, 
         status: List[str]
-    ) -> List[User]: ...
+    ) -> Optional[User]: ...
 
     # Find users by salary >= amount AND category IN list
     def find_by_salary_gte_and_category_in(
@@ -123,14 +123,14 @@ class UserRepository(CrudRepository[int, User]):
         self, 
         age: int, 
         category: List[str]
-    ) -> List[User]: ...
+    ) -> Optional[User]: ...
 
     # Find users by status NE value OR salary >= amount
     def find_by_status_ne_or_salary_gte(
         self, 
         status: str, 
         salary: float
-    ) -> List[User]: ...
+    ) -> Optional[User]: ...
 
 # Usage
 experienced_or_executives = user_repo.find_by_age_gte_or_category_in(
@@ -154,7 +154,7 @@ class UserRepository(CrudRepository[int, User]):
         age: int, 
         status: List[str], 
         category: List[str]
-    ) -> List[User]: ...
+    ) -> Optional[User]: ...
 
 # Usage
 target_users = user_repo.find_by_age_gt_and_status_in_or_category_in(
@@ -269,25 +269,25 @@ class Product(PySpringModel, table=True):
 # Define the repository
 class ProductRepository(CrudRepository[int, Product]):
     # Single field operations
-    def find_by_price_gt(self, price: float) -> List[Product]: ...
-    def find_by_price_gte(self, price: float) -> List[Product]: ...
-    def find_by_stock_lt(self, stock: int) -> List[Product]: ...
-    def find_by_name_like(self, name: str) -> List[Product]: ...
-    def find_by_status_ne(self, status: str) -> List[Product]: ...
-    def find_by_category_in(self, category: List[str]) -> List[Product]: ...
-    def find_by_category_not_in(self, category: List[str]) -> List[Product]: ...
+    def find_by_price_gt(self, price: float) -> Optional[Product]: ...
+    def find_by_price_gte(self, price: float) -> Optional[Product]: ...
+    def find_by_stock_lt(self, stock: int) -> Optional[Product]: ...
+    def find_by_name_like(self, name: str) -> Optional[Product]: ...
+    def find_by_status_ne(self, status: str) -> Optional[Product]: ...
+    def find_by_category_in(self, category: List[str]) -> Optional[Product]: ...
+    def find_by_category_not_in(self, category: List[str]) -> Optional[Product]: ...
 
     # Combined operations
     def find_by_price_gte_and_status_in(
         self, 
         price: float, 
         status: List[str]
-    ) -> List[Product]: ...
+    ) -> Optional[Product]: ...
     def find_by_stock_lt_or_category_in(
         self, 
         stock: int, 
         category: List[str]
-    ) -> List[Product]: ...
+    ) -> Optional[Product]: ...
 
 # Setup database
 engine = create_engine("sqlite:///:memory:")