ref: mapper api overhaul

.github/workflows/ci.yaml

@@ -3,6 +3,7 @@ name: 🔂 Tests and linting
 env:
   COLUMNS: 120 # Makes the error summary table printed by pytest-pretty much easier to read
   PROJECT_NAME: "strawchemy"
+  UV_PYTHON_INSTALL_DIR: ${{ github.workspace }}/.uv-python
 
 on:
   push:
@@ -49,6 +50,11 @@ jobs:
           cache: true
           log_level: debug
 
+      - name: Setup uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
       - name: Generate test matrix
         id: set-matrix
         shell: bash
@@ -74,19 +80,24 @@ jobs:
         id: docker-buildx
         uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
 
-      - name: Pip and nox cache
+      - name: nox cache
         id: cache
         uses: actions/cache@9255dc7a253b0ccc959486e2bca901246202afeb # v5
         with:
           path: |
-            ~/.cache
             ~/.nox
             .nox
+            ${{ github.workspace }}/.uv-python
           key:
-            ${{ runner.os }}-nox-${{ matrix.session.session }}-${{ env.pythonLocation }}-${{
+            ${{ runner.os }}-nox-${{ matrix.session.session }}-${{
             hashFiles('**/uv.lock') }}-${{ hashFiles('**/noxfile.py') }}
           restore-keys: |
-            ${{ runner.os }}-nox-${{ matrix.session.session }}-${{ env.pythonLocation }}
+            ${{ runner.os }}-nox-${{ matrix.session.session }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
 
       - name: Setup mise
         uses: jdx/mise-action@146a28175021df8ca24f8ee1828cc2a60f980bd5 # v3
@@ -196,6 +207,11 @@ jobs:
           cache: true
           log_level: debug
 
+      - name: Setup uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
       - name: Install dependencies
         run: mise run uv:install
 

.gitignore

@@ -196,7 +196,6 @@ mise.local.toml
 *.sqlite
 
 .windsurf
-
 CLAUDE.md
-
 .serena
+docs/superpowers

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/pyproject.toml

@@ -5,11 +5,11 @@ description = "Basic test app"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "aiosqlite",
-    "litestar[sqlalchemy,standard]",
-    "pydantic",
-    "sqlalchemy",
-    "strawberry-graphql",
+  "aiosqlite",
+  "litestar[sqlalchemy,standard]",
+  "pydantic",
+  "sqlalchemy",
+  "strawberry-graphql",
 ]
 
 [build-system]

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