Add support for returning join table results (#72)

* Add support for returning join table results

* Update JoinConfig descriptions

Author: wu-clan

.gitignore

@@ -7,3 +7,4 @@ venv/
 dist/
 .pytest_cache/
 .ruff_cache/
+.claude/

docs/advanced/filter.md

@@ -8,9 +8,9 @@ SQLAlchemy CRUD Plus 支持 30+ 种过滤操作符，用于构建复杂的查询
 # 使用过滤条件查询
 users = await user_crud.select_models(
     session,
-    name="张三",           # 等于
-    age__gt=18,           # 大于
-    email__like="%@qq.com" # 模糊匹配
+    name="张三",  # 等于
+    age__gt=18,  # 大于
+    email__like="%@qq.com"  # 模糊匹配
 )
 ```
 
@@ -20,12 +20,12 @@ users = await user_crud.select_models(
 # 数值比较
 users = await user_crud.select_models(
     session,
-    age__gt=30,         # 大于 30
-    age__ge=18,         # 大于等于 18
-    age__lt=65,         # 小于 65
-    age__le=60,         # 小于等于 60
-    id__eq=1,           # 等于 1
-    status__ne=0        # 不等于 0
+    age__gt=30,  # 大于 30
+    age__ge=18,  # 大于等于 18
+    age__lt=65,  # 小于 65
+    age__le=60,  # 小于等于 60
+    id__eq=1,  # 等于 1
+    status__ne=0  # 不等于 0
 )
 ```
 
@@ -35,9 +35,9 @@ users = await user_crud.select_models(
 # 包含查询
 users = await user_crud.select_models(
     session,
-    id__in=[1, 2, 3, 4, 5],     # ID 在列表中
-    status__not_in=[0, -1],     # 状态不在列表中
-    age__between=[18, 65]       # 年龄在 18-65 之间
+    id__in=[1, 2, 3, 4, 5],  # ID 在列表中
+    status__not_in=[0, -1],  # 状态不在列表中
+    age__between=[18, 65]  # 年龄在 18-65 之间
 )
 ```
 
@@ -47,12 +47,12 @@ users = await user_crud.select_models(
 # 字符串匹配
 users = await user_crud.select_models(
     session,
-    name__like='%张%',              # 包含"张"
-    name__not_like='%test%',        # 不包含"test"
-    name__ilike='%ADMIN%',          # 不区分大小写包含
-    email__startswith='admin',      # 以"admin"开头
-    email__endswith='@qq.com',      # 以"@qq.com"结尾
-    bio__contains='程序员',          # 包含"程序员"
+    name__like='%张%',  # 包含"张"
+    name__not_like='%test%',  # 不包含"test"
+    name__ilike='%ADMIN%',  # 不区分大小写包含
+    email__startswith='admin',  # 以"admin"开头
+    email__endswith='@qq.com',  # 以"@qq.com"结尾
+    bio__contains='程序员',  # 包含"程序员"
 )
 ```
 
@@ -62,8 +62,8 @@ users = await user_crud.select_models(
 # NULL 值处理
 users = await user_crud.select_models(
     session,
-    deleted_at__is=None,            # 为 NULL
-    profile_id__is_not=None,        # 不为 NULL
+    deleted_at__is=None,  # 为 NULL
+    profile_id__is_not=None,  # 不为 NULL
 )
 ```
 
@@ -102,9 +102,9 @@ users = await user_crud.select_models(
     session,
     is_active=True,  # 必须是活跃用户
     __or__={
-        'level__ge': 5,              # 等级大于等于5
-        'is_vip': True,              # 或者是VIP
-        'total_spent__gt': 1000      # 或者消费大于1000
+        'level__ge': 5,  # 等级大于等于5
+        'is_vip': True,  # 或者是VIP
+        'total_spent__gt': 1000  # 或者消费大于1000
     }
 )
 ```
@@ -113,40 +113,40 @@ users = await user_crud.select_models(
 
 ### 比较操作符
 
-| 操作符 | 说明 | 示例 |
-|--------|------|------|
-| `__gt` | 大于 | `age__gt=18` |
-| `__ge` | 大于等于 | `age__ge=18` |
-| `__lt` | 小于 | `age__lt=65` |
-| `__le` | 小于等于 | `age__le=65` |
-| `__eq` | 等于 | `id__eq=1` |
-| `__ne` | 不等于 | `status__ne=0` |
+| 操作符    | 说明   | 示例             |
+|--------|------|----------------|
+| `__gt` | 大于   | `age__gt=18`   |
+| `__ge` | 大于等于 | `age__ge=18`   |
+| `__lt` | 小于   | `age__lt=65`   |
+| `__le` | 小于等于 | `age__le=65`   |
+| `__eq` | 等于   | `id__eq=1`     |
+| `__ne` | 不等于  | `status__ne=0` |
 
 ### 包含操作符
 
-| 操作符 | 说明 | 示例 |
-|--------|------|------|
-| `__in` | 在列表中 | `id__in=[1,2,3]` |
-| `__not_in` | 不在列表中 | `id__not_in=[1,2,3]` |
-| `__between` | 在范围内 | `age__between=[18,65]` |
+| 操作符         | 说明    | 示例                     |
+|-------------|-------|------------------------|
+| `__in`      | 在列表中  | `id__in=[1,2,3]`       |
+| `__not_in`  | 不在列表中 | `id__not_in=[1,2,3]`   |
+| `__between` | 在范围内  | `age__between=[18,65]` |
 
 ### 字符串操作符
 
-| 操作符 | 说明 | 示例 |
-|--------|------|------|
-| `__like` | 模糊匹配 | `name__like='%张%'` |
-| `__not_like` | 模糊不匹配 | `name__not_like='%test%'` |
-| `__ilike` | 不区分大小写模糊匹配 | `name__ilike='%ZHANG%'` |
-| `__not_ilike` | 不区分大小写模糊不匹配 | `name__not_ilike='%TEST%'` |
-| `__startswith` | 开头匹配 | `email__startswith='admin'` |
-| `__endswith` | 结尾匹配 | `email__endswith='@qq.com'` |
-| `__contains` | 包含 | `name__contains='张'` |
+| 操作符            | 说明          | 示例                          |
+|----------------|-------------|-----------------------------|
+| `__like`       | 模糊匹配        | `name__like='%张%'`          |
+| `__not_like`   | 模糊不匹配       | `name__not_like='%test%'`   |
+| `__ilike`      | 不区分大小写模糊匹配  | `name__ilike='%ZHANG%'`     |
+| `__not_ilike`  | 不区分大小写模糊不匹配 | `name__not_ilike='%TEST%'`  |
+| `__startswith` | 开头匹配        | `email__startswith='admin'` |
+| `__endswith`   | 结尾匹配        | `email__endswith='@qq.com'` |
+| `__contains`   | 包含          | `name__contains='张'`        |
 
 ### 空值操作符
 
-| 操作符 | 说明 | 示例 |
-|--------|------|------|
-| `__is` | 为空检查 | `deleted_at__is=None` |
+| 操作符        | 说明    | 示例                        |
+|------------|-------|---------------------------|
+| `__is`     | 为空检查  | `deleted_at__is=None`     |
 | `__is_not` | 不为空检查 | `deleted_at__is_not=None` |
 
 ## 实际应用示例
@@ -155,31 +155,31 @@ users = await user_crud.select_models(
 
 ```python
 async def search_users(
-    session: AsyncSession,
-    keyword: str = None,
-    age_min: int = None,
-    age_max: int = None,
-    is_active: bool = None
+        session: AsyncSession,
+        keyword: str = None,
+        age_min: int = None,
+        age_max: int = None,
+        is_active: bool = None
 ):
     filters = {}
-    
+
     # 关键词搜索（姓名或邮箱）
     if keyword:
         filters['__or__'] = {
             'name__like': f'%{keyword}%',
             'email__like': f'%{keyword}%'
         }
-    
+
     # 年龄范围
     if age_min is not None:
         filters['age__ge'] = age_min
     if age_max is not None:
         filters['age__le'] = age_max
-    
+
     # 状态筛选
     if is_active is not None:
         filters['is_active'] = is_active
-    
+
     return await user_crud.select_models(session, **filters)
 ```
 
@@ -208,7 +208,7 @@ SQLAlchemy CRUD Plus 自动检测模型主键，支持单个主键和复合主
 ```python
 class UserRole(Base):
     __tablename__ = 'user_roles'
-    
+
     # 复合主键
     user_id: Mapped[int] = mapped_column(primary_key=True)
     role_id: Mapped[int] = mapped_column(primary_key=True)
@@ -247,11 +247,11 @@ user_roles = await user_role_crud.select_models(session, user_id=1)
 # 为常用查询字段创建索引
 class User(Base):
     __tablename__ = 'users'
-    
+
     email: Mapped[str] = mapped_column(String(100), unique=True, index=True)
     is_active: Mapped[bool] = mapped_column(default=True, index=True)
     created_at: Mapped[datetime] = mapped_column(DateTime, index=True)
-    
+
     # 复合索引
     __table_args__ = (
         Index('idx_user_active_created', 'is_active', 'created_at'),

docs/advanced/transaction.md

@@ -37,7 +37,7 @@ async with async_session() as session:
         raise e
 ```
 
-## flush 和 commit 参数
+## flush 和 commit
 
 ### flush 参数
 

docs/index.md

@@ -1,6 +1,6 @@
 # SQLAlchemy CRUD Plus
 
-SQLAlchemy CRUD Plus 是基于 SQLAlchemy 2.0 的异步 CRUD 操作库，提供简洁的 API 和强大的查询功能。
+基于 SQLAlchemy 2.0 构建的高级异步 CRUD SDK
 
 ## 特性