async-orm-kit 1.0.0__py3-none-any.whl

async_orm_kit/query/planning/factory.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from .passes import (
+    AggregateStrategyPass,
+    CartesianDetectionPass,
+    DepthSplittingPass,
+    JoinPromotionPass,
+    PathStrategyConflictPass,
+    RedundantPathPass,
+)
+from .planner import QueryPlanner
+from .protocols import JoinGraphMutable
+
+
+def create_default_planner(
+    graph_mut: JoinGraphMutable,
+    max_joinedload_depth: int = 2,
+) -> QueryPlanner:
+    """
+    Build the standard planning pipeline.
+
+    Pass order matters:
+    1. Join promotion   — mutates graph, must run first
+    2. Aggregate check  — may demote joinedload → selectinload
+    3. Depth splitting  — splits deep joinedloads
+    4. Cartesian detect — demotes sibling collections
+    5. Path conflicts   — normalize overlapping loader strategies
+    6. Redundant paths  — remove loader prefixes already covered by longer paths
+
+    Each pass operates on the output of the previous one.
+    """
+    return (
+        QueryPlanner()
+        .add_pass(JoinPromotionPass(graph_mut))
+        .add_pass(AggregateStrategyPass())
+        .add_pass(DepthSplittingPass(max_joinedload_depth))
+        .add_pass(CartesianDetectionPass())
+        .add_pass(PathStrategyConflictPass())
+        .add_pass(RedundantPathPass())
+    )

async_orm_kit/query/planning/passes/__init__.py

@@ -0,0 +1,15 @@
+from .cartesian_detection import CartesianDetectionPass
+from .depth_splitting import DepthSplittingPass
+from .join_promotion import JoinPromotionPass
+from .path_conflicts import PathStrategyConflictPass
+from .redundant_path import RedundantPathPass
+from .strategy_selection import AggregateStrategyPass
+
+__all__ = [
+    "JoinPromotionPass",
+    "CartesianDetectionPass",
+    "RedundantPathPass",
+    "AggregateStrategyPass",
+    "DepthSplittingPass",
+    "PathStrategyConflictPass",
+]

async_orm_kit/query/planning/passes/base.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from ..directives import LoadDirective, QueryContext
+from ..protocols import JoinGraphReadable
+
+
+@dataclass
+class PassResult:
+    """
+    Every pass returns a PassResult so the orchestrator
+    can log, audit, and test each pass independently.
+    """
+
+    pass_name: str
+    directives: list[LoadDirective] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    mutations: list[str] = field(default_factory=list)  # for audit
+
+    @property
+    def had_effect(self) -> bool:
+        return bool(self.directives or self.warnings or self.mutations)
+
+
+class PlanningPass(ABC):
+    """
+    Abstract base for a single planning pass.
+
+    Each pass:
+    - Receives the current state (graph + context + prior directives)
+    - Returns a PassResult describing what it did
+    - Does NOT hold mutable state between calls (stateless)
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult: ...

async_orm_kit/query/planning/passes/cartesian_detection.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+from ..directives import LoadDirective, LoadStrategy, QueryContext
+from ..protocols import JoinGraphReadable
+from .base import PassResult, PlanningPass
+
+
+class CartesianDetectionPass(PlanningPass):
+    """
+    Detect multiple collection joinedloads from the same parent
+    and demote all but the first to selectinload.
+
+    Why? If Parent has 10 Books and 5 Reviews, and both are
+    joinedload, the result is 50 rows. Each additional collection
+    multiplies the row count.
+    """
+
+    name = "cartesian_detection"
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+
+        # Group collection joinedloads by parent path
+        parent_to_collections: dict[str, list[int]] = defaultdict(list)
+
+        for idx, directive in enumerate(current_directives):
+            if directive.strategy != LoadStrategy.JOINEDLOAD:
+                continue
+
+            rel = graph.resolve_relationship(directive.path)
+            if rel is None or not rel.uselist:
+                continue
+
+            parent_path = self._parent_of(directive.path)
+            parent_to_collections[parent_path].append(idx)
+
+        # For each parent with multiple collection joins, demote extras
+        new_directives = list(current_directives)
+
+        for parent, indices in parent_to_collections.items():
+            if len(indices) <= 1:
+                continue
+
+            result.warnings.append(
+                f"Cartesian risk from parent '{parent}': "
+                f"{len(indices)} collection joinedloads. "
+                f"Demoting all but first to selectinload."
+            )
+
+            # Keep the first, demote the rest
+            for idx in indices[1:]:
+                old = new_directives[idx]
+                new_directives[idx] = LoadDirective(
+                    path=old.path,
+                    strategy=LoadStrategy.SELECTINLOAD,
+                    reason=f"Cartesian prevention — sibling collection "
+                    f"already using joinedload from '{parent}'",
+                    original_strategy=old.strategy,
+                )
+
+        result.directives = new_directives
+        return result
+
+    @staticmethod
+    def _parent_of(path: str) -> str:
+        parts = path.rsplit("__", 1)
+        return parts[0] if len(parts) > 1 else "<root>"

async_orm_kit/query/planning/passes/depth_splitting.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from ..directives import LoadDirective, LoadStrategy, QueryContext
+from ..protocols import JoinGraphReadable
+from .base import PassResult, PlanningPass
+
+
+class DepthSplittingPass(PlanningPass):
+    """
+    Split deep joinedload paths into a joinedload head
+    and selectinload tail.
+
+    Prevents excessively wide SQL SELECTs from deep join chains.
+    """
+
+    name = "depth_splitting"
+
+    def __init__(self, max_joinedload_depth: int = 2):
+        if isinstance(max_joinedload_depth, bool) or not isinstance(
+            max_joinedload_depth, int
+        ):
+            raise TypeError("max_joinedload_depth must be an integer.")
+        if max_joinedload_depth < 1:
+            raise ValueError("max_joinedload_depth must be at least 1.")
+        self._max_depth = max_joinedload_depth
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+        new_directives: list[LoadDirective] = []
+        seen_paths = set()
+
+        for directive in current_directives:
+            if directive.strategy != LoadStrategy.JOINEDLOAD:
+                new_directives.append(directive)
+                continue
+
+            depth = directive.path.count("__") + 1
+
+            if depth <= self._max_depth:
+                new_directives.append(directive)
+                continue
+
+            parts = directive.path.split("__")
+
+            # Head
+            head_path = "__".join(parts[: self._max_depth])
+            if head_path not in seen_paths:
+                new_directives.append(
+                    LoadDirective(
+                        path=head_path,
+                        strategy=LoadStrategy.JOINEDLOAD,
+                        reason=f"Head of deep path (depth ≤ {self._max_depth})",
+                        original_strategy=directive.strategy,
+                    )
+                )
+                seen_paths.add(head_path)
+
+            # Tail segments
+            for i in range(self._max_depth, len(parts)):
+                tail_path = "__".join(parts[: i + 1])
+                if tail_path not in seen_paths:
+                    new_directives.append(
+                        LoadDirective(
+                            path=tail_path,
+                            strategy=LoadStrategy.SELECTINLOAD,
+                            reason=f"Tail segment (depth {i + 1} > {self._max_depth})",
+                            original_strategy=LoadStrategy.JOINEDLOAD,
+                        )
+                    )
+                    seen_paths.add(tail_path)
+
+        result.directives = new_directives
+        return result

async_orm_kit/query/planning/passes/join_promotion.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from ...relations.enums import JoinType
+from ..directives import LoadDirective, QueryContext
+from ..protocols import JoinGraphMutable, JoinGraphReadable, JoinNodeReadable
+from .base import PassResult, PlanningPass
+
+
+class JoinPromotionPass(PlanningPass):
+    """
+    Promote LEFT → INNER for joins mandated by WHERE clauses.
+
+    This is the ONLY pass that mutates the JoinGraph, and it
+    does so through the narrow JoinGraphMutable protocol.
+    """
+
+    name = "join_promotion"
+
+    def __init__(self, graph_mut: JoinGraphMutable):
+        # Separate mutable reference — explicit about what this pass can do
+        self._graph_mut = graph_mut
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+
+        for node in graph.join_order:
+            if not self._should_promote(node):
+                continue
+
+            if not self._ancestors_support_inner(node):
+                continue
+
+            self._graph_mut.set_join_type(node.path, JoinType.INNER)
+            result.mutations.append(
+                f"Promoted {node.path}: LEFT → INNER (filter-mandated)"
+            )
+
+        return result
+
+    def _should_promote(self, node: JoinNodeReadable) -> bool:
+        """All conditions must be met for safe promotion."""
+        if node.join_type != JoinType.LEFT:
+            return False
+        if not node.used_in_filter:
+            return False
+        if node.used_in_negation:
+            return False
+        if node.used_in_or_context:
+            return False
+        if node.has_nullable_check:
+            return False
+        return True
+
+    def _ancestors_support_inner(self, node: JoinNodeReadable) -> bool:
+        """
+        Only promote if all ancestors are INNER or will be promoted.
+
+        We can't have: A (LEFT) → B (INNER)
+        If A is NULL, B can't match, eliminating the row despite LEFT JOIN.
+        """
+        current = node.parent
+        while current is not None and current.path != "":
+            # Ancestor is already INNER — OK
+            if current.join_type == JoinType.INNER:
+                current = current.parent
+                continue
+
+            # Ancestor is LEFT but will be promoted — OK
+            if self._should_promote(current):
+                current = current.parent
+                continue
+
+            # Ancestor is LEFT and won't be promoted — BLOCK
+            return False
+
+        return True

async_orm_kit/query/planning/passes/path_conflicts.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from ..directives import LoadDirective, LoadStrategy, QueryContext
+from ..protocols import JoinGraphReadable
+from .base import PassResult, PlanningPass
+
+
+class PathStrategyConflictPass(PlanningPass):
+    """Resolve strategy conflicts at shared prefixes of eager-loader chains.
+
+    A directive's strategy is the default for its complete path. SQLAlchemy
+    supports mixed strategies within one chain (for example,
+    ``joinedload(User.profile).selectinload(Profile.posts)``), so overlapping
+    directives should not be flattened to one strategy.
+
+    This pass resolves the strategy for each path segment:
+    - An explicit directive for the exact prefix wins.
+    - Otherwise, the nearest explicit descendant determines the prefix.
+    - If equally-near descendants disagree, select-in loading is chosen for
+      that shared prefix because it avoids collection row multiplication.
+
+    The leaf strategy remains the directive's requested strategy.
+    """
+
+    name = "path_strategy_conflicts"
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+        active = [
+            directive
+            for directive in current_directives
+            if directive.strategy
+            in {
+                LoadStrategy.JOINEDLOAD,
+                LoadStrategy.SELECTINLOAD,
+            }
+        ]
+        explicit = {directive.path: directive for directive in active}
+        resolved: list[LoadDirective] = []
+
+        for directive in current_directives:
+            if directive.strategy not in {
+                LoadStrategy.JOINEDLOAD,
+                LoadStrategy.SELECTINLOAD,
+            }:
+                resolved.append(directive)
+                continue
+
+            parts = directive.path.split("__")
+            strategies: list[LoadStrategy] = []
+            for depth in range(1, len(parts) + 1):
+                prefix = "__".join(parts[:depth])
+                exact = explicit.get(prefix)
+                if exact is not None:
+                    strategies.append(exact.strategy)
+                    continue
+
+                descendants = [
+                    candidate
+                    for candidate in active
+                    if candidate.path.startswith(prefix + "__")
+                ]
+                nearest_depth = min(
+                    len(candidate.path.split("__")) for candidate in descendants
+                )
+                nearest_strategies = {
+                    candidate.strategy
+                    for candidate in descendants
+                    if len(candidate.path.split("__")) == nearest_depth
+                }
+                strategies.append(
+                    next(iter(nearest_strategies))
+                    if len(nearest_strategies) == 1
+                    else LoadStrategy.SELECTINLOAD
+                )
+
+            segment_strategies = tuple(strategies)
+            default_chain = tuple(directive.strategy for _ in parts)
+            if segment_strategies == default_chain:
+                resolved.append(directive)
+            else:
+                resolved.append(
+                    LoadDirective(
+                        path=directive.path,
+                        strategy=directive.strategy,
+                        reason=directive.reason,
+                        original_strategy=directive.original_strategy,
+                        segment_strategies=segment_strategies,
+                    )
+                )
+                result.warnings.append(
+                    f"Resolved mixed eager-loading strategies for {directive.path!r}: "
+                    + " -> ".join(strategy.name for strategy in segment_strategies)
+                )
+
+        if result.warnings:
+            result.directives = resolved
+        return result

async_orm_kit/query/planning/passes/redundant_path.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from ..directives import LoadDirective, LoadStrategy, QueryContext
+from ..protocols import JoinGraphReadable
+from .base import PassResult, PlanningPass
+
+
+class RedundantPathPass(PlanningPass):
+    """
+    Remove loading paths that are strict prefixes of longer
+    loader paths — the longer chained loader already traverses them.
+
+    A JOIN used by WHERE/ORDER BY does not populate an ORM relationship.
+    Therefore graph membership alone must never suppress eager loading.
+    """
+
+    name = "redundant_path"
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+        new_directives: list[LoadDirective] = []
+
+        # Collect all active (non-skip) paths for prefix detection
+        active_paths = {
+            d.path for d in current_directives if d.strategy != LoadStrategy.SKIP
+        }
+
+        for directive in current_directives:
+            if directive.strategy == LoadStrategy.SKIP:
+                new_directives.append(directive)
+                continue
+
+            # A filter/order JOIN is not a relationship loader. Do not skip
+            # paths merely because the JoinGraph contains the same path.
+
+            # A strict prefix is loaded by the longer chained loader.
+            if self._is_covered_prefix(directive.path, active_paths):
+                new_directives.append(
+                    LoadDirective(
+                        path=directive.path,
+                        strategy=LoadStrategy.SKIP,
+                        reason="Prefix of a longer eager-loading path",
+                        original_strategy=directive.strategy,
+                    )
+                )
+                continue
+
+            new_directives.append(directive)
+
+        result.directives = new_directives
+        return result
+
+    @staticmethod
+    def _is_covered_prefix(path: str, all_paths: set[str]) -> bool:
+        """
+        'a__b' is covered if 'a__b__c' exists in all_paths.
+
+        But 'a__b' is NOT covered by 'a__b_extra' (must be
+        a real path segment boundary).
+        """
+        prefix = path + "__"
+        return any(p.startswith(prefix) for p in all_paths if p != path)

async_orm_kit/query/planning/passes/strategy_selection.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from ..directives import LoadDirective, LoadStrategy, QueryContext
+from ..protocols import JoinGraphReadable
+from .base import PassResult, PlanningPass
+
+
+class AggregateStrategyPass(PlanningPass):
+    """
+    When the query uses aggregates, demote joinedload to
+    selectinload to prevent GROUP BY expansion.
+
+    joinedload + aggregates forces every loaded column into
+    GROUP BY, which:
+    - Makes the query slower (more grouping columns)
+    - Can produce incorrect counts (cartesian with joined tables)
+    """
+
+    name = "aggregate_strategy"
+
+    def execute(
+        self,
+        graph: JoinGraphReadable,
+        context: QueryContext,
+        current_directives: list[LoadDirective],
+    ) -> PassResult:
+        result = PassResult(pass_name=self.name)
+
+        # Only applies when aggregates are present on full model queries
+        if not context.has_aggregates:
+            return result
+
+        new_directives: list[LoadDirective] = []
+
+        for directive in current_directives:
+            if directive.strategy == LoadStrategy.JOINEDLOAD:
+                new_directives.append(
+                    LoadDirective(
+                        path=directive.path,
+                        strategy=LoadStrategy.SELECTINLOAD,
+                        reason="Aggregate context — preventing GROUP BY expansion",
+                        original_strategy=directive.strategy,
+                    )
+                )
+            else:
+                new_directives.append(directive)
+
+        result.directives = new_directives
+        return result