ref: better paginate & order api

README.md

@@ -597,7 +597,7 @@ In your GraphQL queries, you can use the `offset` and `limit` parameters:
 You can also enable pagination for nested relationships:
 
 ```python
-@strawchemy.type(User, include="all", child_pagination=True)
+@strawchemy.type(User, include="all", paginate="all")
 class UserType:
     pass
 ```

src/strawchemy/config/base.py

@@ -43,14 +43,18 @@ 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."""
+    pagination: bool = False
+    """Enable/disable pagination on list resolvers."""
+    order_by: bool = False
+    """Enable/disable order by on list 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)
 

src/strawchemy/dto/base.py

@@ -32,7 +32,7 @@
     DTOMissing,
     DTOSkip,
     DTOUnset,
-    ExcludeFields,
+    FieldIterable,
     IncludeFields,
     Purpose,
     PurposeConfig,
@@ -685,7 +685,7 @@ def decorator(
         model: type[ModelT],
         purpose: Purpose,
         include: IncludeFields | None = None,
-        exclude: ExcludeFields | None = None,
+        exclude: FieldIterable | None = None,
         partial: bool | None = None,
         type_map: Mapping[Any, Any] | None = None,
         aliases: Mapping[str, str] | None = None,

src/strawchemy/dto/types.py

@@ -7,7 +7,7 @@
 from enum import Enum
 from typing import TYPE_CHECKING, Any, Literal, TypeAlias, final, get_type_hints
 
-from typing_extensions import override
+from typing_extensions import Self, override
 
 from strawchemy.utils.annotation import get_annotations
 
@@ -23,15 +23,15 @@
     "DTOScope",
     "DTOSkip",
     "DTOUnset",
-    "ExcludeFields",
+    "FieldIterable",
     "IncludeFields",
     "Purpose",
     "PurposeConfig",
 )
 
 DTOScope: TypeAlias = Literal["global", "dto"]
-IncludeFields: TypeAlias = "list[str] | set[str] | Literal['all']"
-ExcludeFields: TypeAlias = "list[str] | set[str]"
+FieldIterable: TypeAlias = "list[str] | set[str] | frozenset[str] | tuple[str, ...]"
+IncludeFields: TypeAlias = "FieldIterable | Literal['all']"
 
 
 @final
@@ -160,7 +160,7 @@ class DTOConfig:
     """Configure the DTO for "read" or "write" operations."""
     include: IncludeFields = field(default_factory=set)
     """Explicitly include fields from the generated DTO."""
-    exclude: ExcludeFields = field(default_factory=set)
+    exclude: FieldIterable = field(default_factory=set)
     """Explicitly exclude fields from the generated DTO. Implies `include="all"`."""
     partial: bool | None = None
     """Make all field optional."""
@@ -185,11 +185,41 @@ def __post_init__(self) -> None:
         if self.exclude:
             self.include = "all"
 
+    @classmethod
+    def from_include(cls, include: IncludeFields | bool | None = None, purpose: Purpose = Purpose.READ) -> Self:
+        """Create a DTOConfig from an include specification.
+
+        Factory method for creating a DTOConfig with a simplified interface, converting
+        an `IncludeFields` specification into a complete configuration object. This is
+        useful for building configs when only the include/exclude specification matters.
+
+        Args:
+            include: The field inclusion specification. Can be:
+                - None: Include no fields (converted to empty set)
+                - "all": Include all fields
+                - list or set of field names: Include only these specific fields
+                Defaults to None.
+            purpose: The purpose of the DTO being configured (READ, WRITE, or COMPLETE).
+                Defaults to Purpose.READ.
+
+        Returns:
+            A new DTOConfig instance with the specified include and purpose settings.
+            All other configuration parameters use their defaults.
+        """
+        match include:
+            case True:
+                include_ = "all"
+            case False | None:
+                include_ = set()
+            case _:
+                include_ = include
+        return cls(purpose, include=include_)
+
     def copy_with(
         self,
         purpose: Purpose | type[DTOUnset] = DTOUnset,
         include: IncludeFields | None = None,
-        exclude: ExcludeFields | None = None,
+        exclude: FieldIterable | None = None,
         partial: bool | None | type[DTOUnset] = DTOUnset,
         unset_sentinel: Any | type[DTOUnset] = DTOUnset,
         type_overrides: Mapping[Any, Any] | type[DTOUnset] = DTOUnset,
@@ -265,3 +295,43 @@ def alias(self, name: str) -> str | None:
         if self.alias_generator is not None:
             return self.alias_generator(name)
         return None
+
+    def is_field_included(self, name: str) -> bool:
+        """Check if a field should be included based on this configuration.
+
+        Evaluates field inclusion using the following rules:
+        1. If include="all": the field is included unless explicitly excluded
+        2. If include is a specific list/set: the field is included only if named
+        3. If include is empty: the field is never included
+        4. Regardless of include, the field is excluded if it's in the exclude set
+
+        This method is used during DTO factory operations to determine which fields
+        from the source model should be included in the generated DTO.
+
+        Args:
+            name: The field name to check for inclusion.
+
+        Returns:
+            True if the field should be included based on the include/exclude rules,
+            False otherwise.
+
+        Examples:
+            # include="all" case
+            config = DTOConfig.from_include("all")
+            config.is_field_included("any_field")  # Returns: True
+
+            # Specific fields case
+            config = DTOConfig.from_include(["field1", "field2"])
+            config.is_field_included("field1")  # Returns: True
+            config.is_field_included("field3")  # Returns: False
+
+            # Empty include case
+            config = DTOConfig.from_include(None)
+            config.is_field_included("any_field")  # Returns: False
+
+            # With exclude
+            config = DTOConfig(Purpose.READ, exclude={"password"})  # include="all"
+            config.is_field_included("name")  # Returns: True
+            config.is_field_included("password")  # Returns: False
+        """
+        return (name in self.include or self.include == "all") and name not in self.exclude

src/strawchemy/dto/utils.py

@@ -19,7 +19,7 @@
     DTOConfig,
     DTOFieldConfig,
     DTOScope,
-    ExcludeFields,
+    FieldIterable,
     IncludeFields,
     Purpose,
     PurposeConfig,
@@ -45,7 +45,7 @@
 def config(
     purpose: Purpose,
     include: IncludeFields | None = None,
-    exclude: ExcludeFields | None = None,
+    exclude: FieldIterable | None = None,
     partial: bool | None = None,
     type_map: Mapping[Any, Any] | None = None,
     aliases: Mapping[str, str] | None = None,

src/strawchemy/mapper.py

@@ -288,7 +288,11 @@ def field(
         repository_type_ = repository_type if repository_type is not None else self.config.repository_type
         execution_options_ = execution_options if execution_options is not None else self.config.execution_options
         pagination = (
-            DefaultOffsetPagination(limit=self.config.pagination_default_limit) if pagination is True else pagination
+            DefaultOffsetPagination(
+                limit=self.config.pagination_default_limit, offset=self.config.pagination_default_offset
+            )
+            if pagination is True
+            else pagination
         )
         if pagination is None:
             pagination = self.config.pagination