feat(orm): type QueryBuilder.get() as Collection[TModel]

Make the ORM Collection generic (Collection[T]) with TYPE_CHECKING-only
element-access stubs (first/__iter__/__getitem__), and annotate
QueryBuilder.get()/get_models() to return Collection[TModel]. So
`User.where(...).get()` now types as Collection[User] instead of Any,
and element access (iteration, indexing, first()) yields User.

- load() gets one `# type: ignore` (runs only on model collections, but
  the ORM Collection is legitimately generic over non-model values too).
- chunk_by_id uses results[-1] (equivalent; non-emptiness already
  guaranteed) so the last row is cleanly typed.

Stubs are typing-only; runtime behaviour is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tmgbedu

fastapi_startkit/src/fastapi_startkit/masoniteorm/collection/Collection.py

@@ -1,7 +1,19 @@
+from typing import TYPE_CHECKING, Any, Generator, Generic, TypeVar
+
 from fastapi_startkit.support.collection import Collection as BaseCollection
 
+T = TypeVar("T")
+
+
+class Collection(BaseCollection, Generic[T]):
+    if TYPE_CHECKING:
+        # Typing-only element-access overrides so a Collection[User] yields
+        # User (not Any) on iteration, indexing, and first(). Runtime behaviour
+        # is supplied unchanged by the base class.
+        def first(self, callback=None) -> "T | None": ...
+        def __iter__(self) -> "Generator[T, Any, None]": ...
+        def __getitem__(self, item) -> "T": ...
 
-class Collection(BaseCollection):
     def with_relationship_autoloading(self):
         pass
 
@@ -27,6 +39,7 @@ async def load(self, *relations):
                     if isinstance(result_set, Collection):
                         relationship.register_related(relation, model, map_related)
                     else:
-                        model.add_relation({relation: map_related or None})
+                        # load() only runs on model collections; T is generic.
+                        model.add_relation({relation: map_related or None})  # type: ignore
 
         return self

fastapi_startkit/src/fastapi_startkit/masoniteorm/models/builder.py

@@ -18,6 +18,7 @@
 from fastapi_startkit.masoniteorm.query.support import SupportMixin
 
 if TYPE_CHECKING:
+    from fastapi_startkit.masoniteorm.collection import Collection
     from fastapi_startkit.masoniteorm.connections.connection import Connection
     from fastapi_startkit.masoniteorm.models.model import Model
 
@@ -158,7 +159,7 @@ async def first(self, columns=None) -> "TModel | None":
         results = await self.select(columns).limit(1).get()
         return results.first()
 
-    async def get(self, columns=None):
+    async def get(self, columns=None) -> "Collection[TModel]":
         # TODO: apply scopes
         if not columns:
             columns = []
@@ -458,7 +459,8 @@ async def chunk_by_id(self, count: int, column: str = None, alias: str = None, d
 
             yield results
 
-            last_id = results.last().get_attributes().get(alias)
+            # count_results != 0 above guarantees a last row.
+            last_id = results[-1].get_attributes().get(alias)
             if last_id is None:
                 raise RuntimeError(
                     f"The chunk_by_id operation was aborted because the [{alias}] "