ref: mapper api overhaul

README.md

@@ -42,6 +42,7 @@ Generates GraphQL types, inputs, queries and resolvers directly from SQLAlchemy
 - [Mapping SQLAlchemy Models](#mapping-sqlalchemy-models)
 - [Resolver Generation](#resolver-generation)
 - [Pagination](#pagination)
+- [Ordering](#ordering)
 - [Filtering](#filtering)
 - [Aggregations](#aggregations)
 - [Mutations](#mutations)
@@ -567,20 +568,25 @@ def farms(self) -> str:
 Strawchemy supports offset-based pagination out of the box.
 
 <details>
-<summary>Pagination example:</summary>
+<summary>Pagination examples</summary>
 
-Enable pagination on fields:
+### Field-Level Pagination
+
+Enable pagination on specific fields:
 
 ```python
 from strawchemy.schema.pagination import DefaultOffsetPagination
 
 
 @strawberry.type
 class Query:
-    # Enable pagination with default settings
+    # Enable pagination with default settings (limit=100, offset=0)
     users: list[UserType] = strawchemy.field(pagination=True)
-    # Customize pagination defaults
-    users_custom_pagination: list[UserType] = strawchemy.field(pagination=DefaultOffsetPagination(limit=20))
+
+    # Customize pagination defaults for this specific field
+    users_custom: list[UserType] = strawchemy.field(
+        pagination=DefaultOffsetPagination(limit=20, offset=10)
+    )
 ```
 
 In your GraphQL queries, you can use the `offset` and `limit` parameters:
@@ -594,10 +600,40 @@ In your GraphQL queries, you can use the `offset` and `limit` parameters:
 }
 ```
 
-You can also enable pagination for nested relationships:
+### Config-Level Pagination
+
+Enable pagination globally for all list fields:
 
 ```python
-@strawchemy.type(User, include="all", child_pagination=True)
+from strawchemy import Strawchemy, StrawchemyConfig
+
+strawchemy = Strawchemy(
+    StrawchemyConfig(
+        "postgresql",
+        pagination="all",  # Enable on all list fields
+        pagination_default_limit=100,  # Default limit
+        pagination_default_offset=0,  # Default offset
+    )
+)
+
+
+@strawchemy.type(User, include="all")
+class UserType:
+    pass
+
+
+@strawberry.type
+class Query:
+    # This field automatically has pagination enabled
+    users: list[UserType] = strawchemy.field()
+```
+
+### Type-level pagination
+
+Enable pagination for nested relationships from a specific type:
+
+```python
+@strawchemy.type(User, include="all", paginate="all")
 class UserType:
     pass
 ```
@@ -619,6 +655,118 @@ Then in your GraphQL queries:
 
 </details>
 
+## Ordering
+
+Strawchemy provides flexible ordering capabilities for query results.
+
+<details>
+<summary>Ordering examples</summary>
+
+### Field-Level Ordering
+
+Define ordering inputs and use them on specific fields:
+
+```python
+# Create order by input
+@strawchemy.order(User, include="all")
+class UserOrderBy:
+    pass
+
+
+@strawberry.type
+class Query:
+    users: list[UserType] = strawchemy.field(order_by=UserOrderBy)
+```
+
+Query with ordering:
+
+```graphql
+{
+    users(orderBy: [{ name: ASC }, { createdAt: DESC }]) {
+        id
+        name
+        createdAt
+    }
+}
+```
+
+Available ordering options:
+
+- `ASC` - Ascending order
+- `DESC` - Descending order
+- `ASC_NULLS_FIRST` - Ascending with nulls first
+- `ASC_NULLS_LAST` - Ascending with nulls last
+- `DESC_NULLS_FIRST` - Descending with nulls first
+- `DESC_NULLS_LAST` - Descending with nulls last
+
+### Type-Level Ordering
+
+Enable ordering automatically on a type:
+
+```python
+@strawchemy.type(User, include="all", order="all")
+class UserType:
+    pass
+```
+
+This automatically generates and applies an order by input for all fields using this type.
+
+### Config-Level Ordering
+
+Enable ordering globally for all list fields:
+
+```python
+from strawchemy import Strawchemy, StrawchemyConfig
+
+strawchemy = Strawchemy(
+    StrawchemyConfig(
+        "postgresql",
+        order_by="all",  # Enable ordering on all list fields
+    )
+)
+
+
+@strawchemy.type(User, include="all")
+class UserType:
+    pass
+
+
+@strawberry.type
+class Query:
+    # This field automatically has ordering enabled
+    users: list[UserType] = strawchemy.field()
+```
+
+With this configuration, all list fields will automatically have an `orderBy` argument without needing to specify it per
+field.
+
+### Nested Relationship Ordering
+
+Order nested relationships:
+
+```python
+@strawchemy.type(User, include="all", order="all")
+class UserType:
+    pass
+```
+
+Query with nested ordering:
+
+```graphql
+{
+    users(orderBy: [{ name: ASC }]) {
+        id
+        name
+        posts(orderBy: [{ title: ASC }]) {
+            id
+            title
+        }
+    }
+}
+```
+
+</details>
+
 ## Filtering
 
 Strawchemy provides powerful filtering capabilities.
@@ -1950,18 +2098,20 @@ Configuration is made by passing a `StrawchemyConfig` to the `Strawchemy` instan
 
 ### Configuration Options
 
-| Option                     | Type                                                        | Default                    | Description                                                                                                                              |
-|----------------------------|-------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
-| `dialect`                  | `SupportedDialect`                                          |                            | Database dialect to use. Supported dialects are "postgresql", "mysql", "sqlite".                                                         |
-| `session_getter`           | `Callable[[Info], Session]`                                 | `default_session_getter`   | Function to retrieve SQLAlchemy session from strawberry `Info` object. By default, it retrieves the session from `info.context.session`. |
-| `auto_snake_case`          | `bool`                                                      | `True`                     | Automatically convert snake cased names to camel case in GraphQL schema.                                                                 |
-| `repository_type`          | `type[Repository] \| StrawchemySyncRepository`              | `StrawchemySyncRepository` | Repository class to use for auto resolvers.                                                                                              |
-| `filter_overrides`         | `OrderedDict[tuple[type, ...], type[SQLAlchemyFilterBase]]` | `None`                     | Override default filters with custom filters. This allows you to provide custom filter implementations for specific column types.        |
-| `execution_options`        | `dict[str, Any]`                                            | `None`                     | SQLAlchemy execution options for repository operations. These options are passed to the SQLAlchemy `execution_options()` method.         |
-| `pagination_default_limit` | `int`                                                       | `100`                      | Default pagination limit when `pagination=True`.                                                                                         |
-| `pagination`               | `bool`                                                      | `False`                    | Enable/disable pagination on list resolvers by default.                                                                                  |
-| `default_id_field_name`    | `str`                                                       | `"id"`                     | Name for primary key fields arguments on primary key resolvers.                                                                          |
-| `deterministic_ordering`   | `bool`                                                      | `True`                     | Force deterministic ordering for list resolvers.                                                                                         |
+| Option                      | Type                                                        | Default                    | Description                                                                                                                              |
+|-----------------------------|-------------------------------------------------------------|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `dialect`                   | `SupportedDialect`                                          |                            | Database dialect to use. Supported dialects are "postgresql", "mysql", "sqlite".                                                         |
+| `session_getter`            | `Callable[[Info], Session]`                                 | `default_session_getter`   | Function to retrieve SQLAlchemy session from strawberry `Info` object. By default, it retrieves the session from `info.context.session`. |
+| `auto_snake_case`           | `bool`                                                      | `True`                     | Automatically convert snake cased names to camel case in GraphQL schema.                                                                 |
+| `repository_type`           | `type[Repository] \| StrawchemySyncRepository`              | `StrawchemySyncRepository` | Repository class to use for auto resolvers.                                                                                              |
+| `filter_overrides`          | `OrderedDict[tuple[type, ...], type[SQLAlchemyFilterBase]]` | `None`                     | Override default filters with custom filters. This allows you to provide custom filter implementations for specific column types.        |
+| `execution_options`         | `dict[str, Any]`                                            | `None`                     | SQLAlchemy execution options for repository operations. These options are passed to the SQLAlchemy `execution_options()` method.         |
+| `default_id_field_name`     | `str`                                                       | `"id"`                     | Name for primary key fields arguments on primary key resolvers.                                                                          |
+| `deterministic_ordering`    | `bool`                                                      | `True`                     | Force deterministic ordering for list resolvers.                                                                                         |
+| `pagination`                | `Literal["all"] \| None`                                    | `None`                     | Enable/disable pagination on list resolvers by default. Set to `"all"` to enable pagination on all list fields.                          |
+| `order_by`                  | `Literal["all"] \| None`                                    | `None`                     | Enable/disable order by on list resolvers by default. Set to `"all"` to enable ordering on all list fields.                              |
+| `pagination_default_limit`  | `int`                                                       | `100`                      | Default pagination limit when `pagination=True`.                                                                                         |
+| `pagination_default_offset` | `int`                                                       | `0`                        | Default pagination offset when `pagination=True`.                                                                                        |
 
 ### Example
 
@@ -1980,8 +2130,10 @@ strawchemy = Strawchemy(
         "postgresql",
         session_getter=get_session_from_context,
         auto_snake_case=True,
-        pagination=True,
+        pagination="all",
         pagination_default_limit=50,
+        pagination_default_offset=0,
+        order_by="all",
         default_id_field_name="pk",
     )
 )

examples/testapp/testapp/types.py

@@ -7,7 +7,7 @@
 from strawchemy import Strawchemy, StrawchemyAsyncRepository, StrawchemyConfig
 from testapp.models import Customer, Milestone, Project, Ticket
 
-strawchemy = Strawchemy(StrawchemyConfig("sqlite", repository_type=StrawchemyAsyncRepository))
+strawchemy = Strawchemy(StrawchemyConfig("sqlite", repository_type=StrawchemyAsyncRepository, include=["name"]))
 
 # Ticket
 
@@ -20,7 +20,7 @@ class TicketOrder: ...
 class TicketFilter: ...
 
 
-@strawchemy.type(Ticket, include="all", filter_input=TicketFilter, order_by=TicketOrder, override=True)
+@strawchemy.type(Ticket, include="all", filter_input=TicketFilter, order=TicketOrder, override=True)
 class TicketType: ...
 
 
@@ -55,7 +55,7 @@ class ProjectOrder: ...
 class ProjectFilter: ...
 
 
-@strawchemy.type(Project, include="all", filter_input=ProjectFilter, order_by=ProjectOrder, override=True)
+@strawchemy.type(Project, include="all", filter_input=ProjectFilter, order=ProjectOrder, override=True)
 class ProjectType: ...
 
 
@@ -66,7 +66,7 @@ class ProjectCreate: ...
 # Milestone
 
 
-@strawchemy.type(Milestone, include="all", override=True)
+@strawchemy.type(Milestone, include={"name"}, override=True, distinct_on=["age"], paginate=["projects"])
 class MilestoneType: ...
 
 

src/strawchemy/config/base.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from functools import cached_property
 from typing import TYPE_CHECKING, Any
 
 from strawchemy.dto.inspectors import SQLAlchemyGraphQLInspector
+from strawchemy.dto.types import DTOConfig, FieldIterable, IncludeFields
 from strawchemy.repository.strawberry import StrawchemySyncRepository
 from strawchemy.utils.strawberry import default_session_getter
 
@@ -43,17 +45,39 @@ class StrawchemyConfig:
     """Override default filters with custom filters."""
     execution_options: dict[str, Any] | None = None
     """SQLAlchemy execution options for strawberry operations."""
-    pagination_default_limit: int = 100
-    """Default pagination limit when `pagination=True`."""
-    pagination: bool = False
-    """Enable/disable pagination on list resolvers."""
     default_id_field_name: str = "id"
     """Name for primary key fields arguments on primary key resolvers."""
     deterministic_ordering: bool = True
     """Force deterministic ordering for list resolvers."""
+    include: IncludeFields = "all"
+    """Globally included fields."""
+    exclude: FieldIterable | None = None
+    """Globally included fields."""
+    pagination: IncludeFields | None = None
+    """Enable/disable pagination on list resolvers."""
+    order_by: IncludeFields | None = None
+    """Enable/disable order by on list resolvers."""
+    distinct_on: IncludeFields | None = None
+    """Enable/disable order by onelist resolvers."""
+    pagination_default_limit: int = 100
+    """Default pagination limit when `pagination=True`."""
+    pagination_default_offset: int = 0
+    """Default pagination offset when `pagination=True`."""
 
     inspector: SQLAlchemyGraphQLInspector = field(init=False)
 
     def __post_init__(self) -> None:
         """Initializes the SQLAlchemyGraphQLInspector after the dataclass is created."""
         self.inspector = SQLAlchemyGraphQLInspector(self.dialect, filter_overrides=self.filter_overrides)
+
+    @cached_property
+    def order_config(self) -> DTOConfig:
+        return DTOConfig.from_include(self.order_by)
+
+    @cached_property
+    def distinct_on_config(self) -> DTOConfig:
+        return DTOConfig.from_include(self.distinct_on)
+
+    @cached_property
+    def pagination_config(self) -> DTOConfig:
+        return DTOConfig.from_include(self.pagination)