Merge pull request #289 from benavlabs/some-bug-fixes

Some bug fixes

Author: igorbenav

docs/advanced/joins.md

@@ -201,9 +201,48 @@ This works for both `get_joined` and `get_multi_joined`.
 
     Note that the final `"_"` in the passed `"tier_"` is stripped.
 
-!!! WARNING "join_prefix and return_as_model Compatibility"
+#### Returning Pydantic Models with `return_as_model`
 
-    When using `return_as_model=True` with `nest_joins=True`, ensure that your `join_prefix` (minus trailing "_") matches the field name in your Pydantic schema. Otherwise, FastCRUD will raise a `ValueError` with clear guidance on how to fix the mismatch.
+By default, `get_joined` returns dictionaries containing the joined data. However, you can use the `return_as_model` parameter to get Pydantic model instances instead:
+
+```python
+# Using a schema that includes joined fields
+class UserWithTier(BaseModel):
+    id: int
+    name: str
+    tier_id: int
+    tier_name: str
+
+# Returns a dictionary (default behavior)
+user_dict = await user_crud.get_joined(
+    db=db,
+    join_model=Tier,
+    join_prefix="tier_",
+    schema_to_select=UserWithTier,
+    return_as_model=False,  # Default
+    id=1,
+)
+# Result: {"id": 1, "name": "Example", "tier_id": 1, "tier_name": "Free"}
+
+# Returns a Pydantic model instance
+user_model = await user_crud.get_joined(
+    db=db,
+    join_model=Tier,
+    join_prefix="tier_",
+    schema_to_select=UserWithTier,
+    return_as_model=True,
+    id=1,
+)
+# Result: UserWithTier(id=1, name="Example", tier_id=1, tier_name="Free")
+```
+
+!!! NOTE "`return_as_model` Usage Notes"
+
+    **Required Parameters**: When `return_as_model=True`, the `schema_to_select` parameter is required. FastCRUD will raise a `ValueError` if you try to use `return_as_model=True` without providing a schema.
+    
+    **Schema Design**: Ensure your schema includes all the fields that will be present in the flattened result, including joined fields with their prefixes.
+    
+    **Nested Joins Compatibility**: When using `return_as_model=True` with `nest_joins=True`, ensure that your `join_prefix` (minus trailing "_") matches the field name in your Pydantic schema. Otherwise, FastCRUD will raise a `ValueError` with clear guidance on how to fix the mismatch.
 
     **❌ This will raise an error:**
     ```python

docs/changelog.md

@@ -5,6 +5,38 @@
 The Changelog documents all notable changes made to FastCRUD. This includes new features, bug fixes, and improvements. It's organized by version and date, providing a clear history of the library's development.
 ___
 
+## [0.19.2] - Nov 15, 2025
+
+#### Added
+- **get_joined Method Overloads** by [@igorbenav](https://github.com/igorbenav)
+  - Added missing `@overload` signatures for `get_joined()` method to support proper type inference
+  - Added `return_as_model` parameter for converting joined results to Pydantic models
+  - Enhanced type safety: returns `SelectSchemaType` when `return_as_model=True`, `dict` when `False`
+  - Consistent API with other CRUD methods like `get()`, `update()`, etc.
+
+#### Improved  
+- **create Method Performance and Consistency** by [@igorbenav](https://github.com/igorbenav)
+  - Removed unnecessary database round-trip by eliminating redundant `get()` call after creation
+  - Added deprecation warnings for upcoming API consistency changes in next major version
+  - Fixed type hints to match actual implementation behavior (removed incorrect `None` return type)
+
+#### Deprecated
+- **create Method Behavior Changes** (Warnings Added)
+  - `create()` without `schema_to_select` will return `None` instead of SQLAlchemy model in next major version
+  - `create()` with `schema_to_select` will properly respect `return_as_model` parameter in next major version
+  - These changes align `create()` behavior with `update()` and other CRUD methods for consistency
+
+#### Fixed
+- **Type Safety Issues** by [@igorbenav](https://github.com/igorbenav)
+  - Fixed `get_joined()` method type annotations to properly reflect actual return types
+  - Corrected `create()` method type hints to remove impossible `None` return type
+  - Enhanced test coverage with 8 new comprehensive tests for `get_joined` return type variations
+
+#### Breaking Changes  
+⚠️ **None** - This release maintains full backward compatibility with 0.19.1. Deprecation warnings provide clear migration path for next major version.
+
+___
+
 ## [0.19.1] - Nov 10, 2025
 
 #### Improved

docs/usage/crud.md

@@ -128,6 +128,15 @@ create(
 new_item = await item_crud.create(db, CreateItemSchema(name="New Item"))
 ```
 
+!!! WARNING "Deprecated Behavior"
+
+    **Upcoming Changes in Next Major Version**: The `create()` method currently behaves inconsistently compared to other CRUD methods like `update()`. It will change:
+    
+    - **Currently without `schema_to_select`**: Returns SQLAlchemy model → **Will return `None`**
+    - **Currently with `schema_to_select`**: Bypasses `return_as_model` parameter → **Will respect `return_as_model` like other methods**
+    
+    This makes `create()` consistent with `update()` behavior. Current usage patterns will trigger deprecation warnings. See [changelog](../changelog.md#0192---nov-15-2025) for details.
+
 !!! WARNING
 
     Note that naive `datetime` such as `datetime.utcnow` is not supported by `FastCRUD` as it was [deprecated](https://github.com/python/cpython/pull/103858).

fastcrud/crud/fast_crud.py

@@ -1,5 +1,6 @@
 from typing import Any, Generic, Union, Optional, Callable, overload, Literal, cast
 from datetime import datetime, timezone
+import warnings
 
 from sqlalchemy import (
     select,
@@ -508,7 +509,7 @@ async def create(
         commit: bool = True,
         schema_to_select: None = None,
         return_as_model: Literal[False] = False,
-    ) -> Optional[dict[str, Any]]: ...
+    ) -> ModelType: ...
 
     @overload
     async def create(
@@ -519,7 +520,7 @@ async def create(
         commit: bool = True,
         schema_to_select: type[SelectSchemaType],
         return_as_model: Literal[False] = False,
-    ) -> Optional[dict[str, Any]]: ...
+    ) -> dict[str, Any]: ...
 
     @overload
     async def create(
@@ -530,7 +531,7 @@ async def create(
         commit: bool = True,
         schema_to_select: Optional[type[SelectSchemaType]] = None,
         return_as_model: bool = False,
-    ) -> Union[ModelType, SelectSchemaType, dict[str, Any], None]: ...
+    ) -> Union[ModelType, SelectSchemaType, dict[str, Any]]: ...
 
     async def create(
         self,
@@ -539,7 +540,7 @@ async def create(
         commit: bool = True,
         schema_to_select: Optional[type[SelectSchemaType]] = None,
         return_as_model: bool = False,
-    ) -> Union[ModelType, SelectSchemaType, dict, None]:
+    ) -> Union[ModelType, SelectSchemaType, dict]:
         """
         Create a new record in the database.
 
@@ -573,18 +574,35 @@ async def create(
             await db.flush()
             await db.refresh(db_object)
 
-        if schema_to_select:
-            if not self._primary_keys:
-                raise ValueError("Cannot fetch created record without a primary key.")
-
-            pks = {pk.name: getattr(db_object, pk.name) for pk in self._primary_keys}
-            return await self.get(
-                db=db,
-                schema_to_select=schema_to_select,
-                return_as_model=return_as_model,
-                **pks,
+        # Add deprecation warnings for upcoming behavior changes
+        if not schema_to_select:
+            warnings.warn(
+                "create() without schema_to_select will return None instead of the SQLAlchemy model "
+                "in the next major version for consistency with other CRUD methods. "
+                "Provide schema_to_select to get data back. "
+                "Return type will change from Union[ModelType, SelectSchemaType, dict] to Optional[Union[SelectSchemaType, dict]].",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        elif schema_to_select and not return_as_model:
+            warnings.warn(
+                "create() with schema_to_select will default to returning dict "
+                "in the next major version for consistency with other CRUD methods. "
+                "Return type will change from Union[ModelType, SelectSchemaType, dict] to Optional[Union[SelectSchemaType, dict]].",
+                DeprecationWarning,
+                stacklevel=2,
             )
 
+        if schema_to_select:
+            # Convert db_object to dict following same pattern as get() method
+            data_dict = {
+                col.key: getattr(db_object, col.key)
+                for col in db_object.__table__.columns
+            }
+            if not return_as_model:
+                return data_dict
+            return schema_to_select(**data_dict)
+
         return db_object
 
     async def select(
@@ -1383,10 +1401,73 @@ async def get_multi(
 
         return response
 
+    @overload
+    async def get_joined(
+        self,
+        db: AsyncSession,
+        *,
+        schema_to_select: type[SelectSchemaType],
+        return_as_model: Literal[True],
+        join_model: Optional[ModelType] = None,
+        join_on: Optional[Union[Join, BinaryExpression]] = None,
+        join_prefix: Optional[str] = None,
+        join_schema_to_select: Optional[type[SelectSchemaType]] = None,
+        join_type: str = "left",
+        alias: Optional[AliasedClass] = None,
+        join_filters: Optional[dict] = None,
+        joins_config: Optional[list[JoinConfig]] = None,
+        nest_joins: bool = False,
+        relationship_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Optional[SelectSchemaType]: ...
+
+    @overload
+    async def get_joined(
+        self,
+        db: AsyncSession,
+        *,
+        schema_to_select: None = None,
+        return_as_model: Literal[False] = False,
+        join_model: Optional[ModelType] = None,
+        join_on: Optional[Union[Join, BinaryExpression]] = None,
+        join_prefix: Optional[str] = None,
+        join_schema_to_select: Optional[type[SelectSchemaType]] = None,
+        join_type: str = "left",
+        alias: Optional[AliasedClass] = None,
+        join_filters: Optional[dict] = None,
+        joins_config: Optional[list[JoinConfig]] = None,
+        nest_joins: bool = False,
+        relationship_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Optional[dict[str, Any]]: ...
+
+    @overload
     async def get_joined(
         self,
         db: AsyncSession,
+        *,
+        schema_to_select: type[SelectSchemaType],
+        return_as_model: Literal[False] = False,
+        join_model: Optional[ModelType] = None,
+        join_on: Optional[Union[Join, BinaryExpression]] = None,
+        join_prefix: Optional[str] = None,
+        join_schema_to_select: Optional[type[SelectSchemaType]] = None,
+        join_type: str = "left",
+        alias: Optional[AliasedClass] = None,
+        join_filters: Optional[dict] = None,
+        joins_config: Optional[list[JoinConfig]] = None,
+        nest_joins: bool = False,
+        relationship_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Optional[dict[str, Any]]: ...
+
+    @overload
+    async def get_joined(
+        self,
+        db: AsyncSession,
+        *,
         schema_to_select: Optional[type[SelectSchemaType]] = None,
+        return_as_model: bool = False,
         join_model: Optional[ModelType] = None,
         join_on: Optional[Union[Join, BinaryExpression]] = None,
         join_prefix: Optional[str] = None,
@@ -1398,7 +1479,25 @@ async def get_joined(
         nest_joins: bool = False,
         relationship_type: Optional[str] = None,
         **kwargs: Any,
-    ) -> Optional[dict[str, Any]]:
+    ) -> Optional[Union[dict[str, Any], SelectSchemaType]]: ...
+
+    async def get_joined(
+        self,
+        db: AsyncSession,
+        schema_to_select: Optional[type[SelectSchemaType]] = None,
+        return_as_model: bool = False,
+        join_model: Optional[ModelType] = None,
+        join_on: Optional[Union[Join, BinaryExpression]] = None,
+        join_prefix: Optional[str] = None,
+        join_schema_to_select: Optional[type[SelectSchemaType]] = None,
+        join_type: str = "left",
+        alias: Optional[AliasedClass] = None,
+        join_filters: Optional[dict] = None,
+        joins_config: Optional[list[JoinConfig]] = None,
+        nest_joins: bool = False,
+        relationship_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Optional[Union[dict[str, Any], SelectSchemaType]]:
         """
         Fetches a single record with one or multiple joins on other models. If `join_on` is not provided, the method attempts
         to automatically detect the join condition using foreign key relationships. For multiple joins, use `joins_config` to
@@ -1409,6 +1508,7 @@ async def get_joined(
         Args:
             db: The SQLAlchemy async session.
             schema_to_select: Pydantic schema for selecting specific columns from the primary model. Required if `return_as_model` is True.
+            return_as_model: If `True`, returns data as a Pydantic model instance based on `schema_to_select`. Defaults to `False`.
             join_model: The model to join with.
             join_on: SQLAlchemy Join object for specifying the `ON` clause of the join. If `None`, the join condition is auto-detected based on foreign keys.
             join_prefix: Optional prefix to be added to all columns of the joined model. If `None`, no prefix is added.
@@ -1422,7 +1522,10 @@ async def get_joined(
             **kwargs: Filters to apply to the primary model query, supporting advanced comparison operators for refined searching.
 
         Returns:
-            A dictionary representing the joined record, or `None` if no record matches the criteria.
+            A dictionary or Pydantic model instance representing the joined record, or `None` if no record matches the criteria:
+
+            - When `return_as_model=True` and `schema_to_select` is provided: `Optional[SelectSchemaType]`
+            - When `return_as_model=False`: `Optional[Dict[str, Any]]`
 
         Raises:
             ValueError: If both single join parameters and `joins_config` are used simultaneously.
@@ -1690,7 +1793,19 @@ async def get_joined(
             else:
                 data_list = []
 
-        return process_joined_data(data_list, join_definitions, nest_joins, self.model)
+        processed_data = process_joined_data(
+            data_list, join_definitions, nest_joins, self.model
+        )
+
+        if processed_data is None or not return_as_model:
+            return processed_data
+
+        if not schema_to_select:
+            raise ValueError(
+                "schema_to_select must be provided when return_as_model is True."
+            )
+
+        return schema_to_select(**processed_data)
 
     @overload
     async def get_multi_joined(