feat: configurable JSON serialization with Protocol-based architecture

Refactor the serialization layer to use a JSONSerializer Protocol with
backend support (msgspec, orjson, stdlib), enable custom type_encoders
at the application and function level, and integrate with Litestar's
type_encoders system.

- Replace _serialization.py with utils/serialization.py containing the
  Protocol-based serializer hierarchy (MsgspecSerializer, OrjsonSerializer,
  StdlibSerializer) and DEFAULT_TYPE_ENCODERS for asyncpg/uuid_utils types
- Move schema_dump and type guards into utils/serializers.py
- Wire SQLAlchemyInitPlugin to honor Litestar's app-level type_encoders
- Delete the unreleased advanced_alchemy/_serialization.py and
  advanced_alchemy/service/typing.py modules
- Update all internal callers to import from the new locations
- Add comprehensive function-based unit tests covering encoder/decoder
  helpers, type markers, serializer protocol, and orjson integration
- Add Litestar integration test for type_encoders flow

Fixes: #710

Author: cofin

advanced_alchemy/__init__.py

@@ -13,12 +13,15 @@
     types,
     utils,
 )
+from advanced_alchemy.utils.serialization import decode_json, encode_json
 
 __all__ = (
     "alembic",
     "base",
     "cli",
     "config",
+    "decode_json",
+    "encode_json",
     "exceptions",
     "extensions",
     "filters",

advanced_alchemy/_serialization.py

@@ -84,7 +84,7 @@ async def dump_tables(
 ) -> None:
     from types import new_class
 
-    from advanced_alchemy._serialization import encode_json
+    from advanced_alchemy.utils.serialization import encode_json
 
     try:
         from rich import get_console

advanced_alchemy/alembic/utils.py

@@ -4,7 +4,7 @@
 
 from sqlalchemy import inspect as sa_inspect
 
-from advanced_alchemy._serialization import (
+from advanced_alchemy.utils.serialization import (
     decode_complex_type,
     decode_json,
     encode_complex_type,

advanced_alchemy/cache/serializers.py

@@ -1,8 +1,8 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Callable, Literal, Optional, Union
 
-from advanced_alchemy._serialization import decode_json, encode_json
 from advanced_alchemy.utils.dataclass import Empty
+from advanced_alchemy.utils.serialization import decode_json, encode_json
 
 if TYPE_CHECKING:
     from collections.abc import Mapping

advanced_alchemy/config/engine.py

@@ -12,13 +12,13 @@
 from sqlalchemy.exc import OperationalError
 from typing_extensions import Literal
 
-from advanced_alchemy._serialization import decode_json, encode_json
 from advanced_alchemy.base import metadata_registry
 from advanced_alchemy.config import EngineConfig as _EngineConfig
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
 from advanced_alchemy.exceptions import ImproperConfigurationError
-from advanced_alchemy.service import schema_dump
+from advanced_alchemy.utils.serialization import decode_json, encode_json
+from advanced_alchemy.utils.serializers import schema_dump
 
 if TYPE_CHECKING:
     from flask import Flask, Response

advanced_alchemy/extensions/flask/config.py

@@ -34,8 +34,11 @@
     StatementTypeT,
 )
 from advanced_alchemy.service import ModelDictListT, ModelDictT, ModelDTOT, ModelOrRowMappingT, ModelT, OffsetPagination
+from advanced_alchemy.utils.serialization import DEFAULT_TYPE_ENCODERS
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from click import Group
     from litestar.config.app import AppConfig
     from litestar.types import BeforeMessageSendHookHandler
@@ -44,6 +47,56 @@
 
 __all__ = ("SQLAlchemyInitPlugin",)
 
+
+def _get_aa_type_encoders() -> dict[type, "Callable[[Any], Any]"]:
+    """Get Advanced Alchemy's built-in type encoders.
+
+    These encoders handle database-specific types that need special
+    serialization. They are added to Litestar's type_encoders with
+    lower precedence than user-defined encoders.
+
+    Returns:
+        Dictionary of type to encoder function mappings.
+    """
+    encoders: dict[type, Callable[[Any], Any]] = {**DEFAULT_TYPE_ENCODERS}
+
+    # asyncpg UUID type (PostgreSQL asyncpg driver)
+    with contextlib.suppress(ImportError):
+        from asyncpg.pgproto import pgproto  # pyright: ignore[reportMissingImports]
+
+        encoders[pgproto.UUID] = str
+
+    # uuid_utils UUID type (fast UUID implementation)
+    with contextlib.suppress(ImportError):
+        import uuid_utils  # pyright: ignore[reportMissingImports]
+
+        encoders[uuid_utils.UUID] = str  # pyright: ignore[reportUnknownMemberType]
+
+    return encoders
+
+
+def _get_aa_type_decoders() -> list[tuple["Callable[[Any], bool]", "Callable[[type, Any], Any]"]]:
+    """Get Advanced Alchemy's built-in type decoders.
+
+    These decoders handle database-specific types that need special
+    deserialization during request parsing.
+
+    Returns:
+        List of (predicate, decoder) tuples for Litestar's type_decoders.
+    """
+    decoders: list[tuple[Callable[[Any], bool], Callable[[type, Any], Any]]] = []
+
+    # uuid_utils UUID type decoder
+    with contextlib.suppress(ImportError):
+        import uuid_utils  # pyright: ignore[reportMissingImports]
+
+        decoders.append(
+            (lambda x: x is uuid_utils.UUID, lambda t, v: t(str(v)))  # pyright: ignore[reportUnknownMemberType]
+        )
+
+    return decoders
+
+
 signature_namespace_values: dict[str, Any] = {
     "BeforeAfter": BeforeAfter,
     "OnBeforeAfter": OnBeforeAfter,
@@ -125,20 +178,24 @@ def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
             app_config: The :class:`AppConfig <.config.app.AppConfig>` instance.
         """
         self._validate_config()
+
+        # Add AA built-in type encoders/decoders
+        # These are added BEFORE user encoders so user config takes precedence
+        aa_encoders = _get_aa_type_encoders()
+        aa_decoders = _get_aa_type_decoders()
+
+        # Merge: AA built-ins first, then user encoders override
+        app_config.type_encoders = {**aa_encoders, **(app_config.type_encoders or {})}
+        app_config.type_decoders = [*aa_decoders, *(app_config.type_decoders or [])]
+
         with contextlib.suppress(ImportError):
             from asyncpg.pgproto import pgproto  # pyright: ignore[reportMissingImports]
 
             signature_namespace_values.update({"pgproto.UUID": pgproto.UUID})
-            app_config.type_encoders = {pgproto.UUID: str, **(app_config.type_encoders or {})}
         with contextlib.suppress(ImportError):
             import uuid_utils  # pyright: ignore[reportMissingImports]
 
             signature_namespace_values.update({"uuid_utils.UUID": uuid_utils.UUID})  # pyright: ignore[reportUnknownMemberType]
-            app_config.type_encoders = {uuid_utils.UUID: str, **(app_config.type_encoders or {})}  # pyright: ignore[reportUnknownMemberType]
-            app_config.type_decoders = [
-                (lambda x: x is uuid_utils.UUID, lambda t, v: t(str(v))),  # pyright: ignore[reportUnknownMemberType]
-                *(app_config.type_decoders or []),
-            ]
         configure_exception_handler = False
         for config in self.config:
             if config.set_default_exception_handler:

advanced_alchemy/extensions/litestar/plugins/init/plugin.py

@@ -29,12 +29,12 @@
 from typing_extensions import Literal
 
 from advanced_alchemy._listeners import set_async_context
-from advanced_alchemy._serialization import decode_json, encode_json
 from advanced_alchemy.base import metadata_registry
 from advanced_alchemy.config import EngineConfig as _EngineConfig
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
-from advanced_alchemy.service import schema_dump
+from advanced_alchemy.utils.serialization import decode_json, encode_json
+from advanced_alchemy.utils.serializers import schema_dump
 
 logger = logging.getLogger("advanced_alchemy.extensions.sanic")
 

advanced_alchemy/extensions/sanic/config.py

@@ -15,13 +15,13 @@
 from starlette.requests import Request
 from typing_extensions import Literal
 
-from advanced_alchemy._serialization import decode_json, encode_json
 from advanced_alchemy.base import metadata_registry
 from advanced_alchemy.config import EngineConfig as _EngineConfig
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
 from advanced_alchemy.routing.context import reset_routing_context
-from advanced_alchemy.service import schema_dump
+from advanced_alchemy.utils.serialization import decode_json, encode_json
+from advanced_alchemy.utils.serializers import schema_dump
 
 if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncSession

advanced_alchemy/extensions/starlette/config.py

@@ -67,9 +67,9 @@
     was_attribute_set,
 )
 from advanced_alchemy.repository.typing import MISSING, ModelT, OrderingPair, PrimaryKeyType, T
-from advanced_alchemy.service.typing import schema_dump
 from advanced_alchemy.utils.dataclass import Empty, EmptyType
 from advanced_alchemy.utils.deprecation import warn_deprecation
+from advanced_alchemy.utils.serializers import schema_dump
 from advanced_alchemy.utils.text import slugify
 
 if TYPE_CHECKING: