docs updated

Author: igorbenav

docs/advanced/joins.md

@@ -201,6 +201,49 @@ This works for both `get_joined` and `get_multi_joined`.
 
     Note that the final `"_"` in the passed `"tier_"` is stripped.
 
+#### Returning Pydantic Models with `return_as_model`
+
+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")
+```
+
+!!! TIP "Schema Design for Joined Data"
+
+    When using `return_as_model=True`, ensure your schema includes all the fields that will be present in the flattened result, including joined fields with their prefixes.
+
+!!! NOTE "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.
+
 !!! WARNING "join_prefix and return_as_model 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.

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).