feat: add find_or_fail method to Model and QueryBuilder

.gitignore

@@ -14,3 +14,4 @@ laravel-repo
 application
 .agents
 .uv_cache
+.claude/

fastapi_startkit/src/fastapi_startkit/exceptions/__init__.py

@@ -30,6 +30,5 @@
     ValidationException,
     AmbiguousError,
     MethodNotAllowedException,
-    ModelNotFoundException,
     ThrottleRequestsException,
 )

fastapi_startkit/src/fastapi_startkit/exceptions/exceptions.py

@@ -144,16 +144,6 @@ class NotificationException(Exception):
     pass
 
 
-class ModelNotFoundException(Exception):
-    is_http_exception = True
-
-    def get_response(self):
-        return "Model Not Found"
-
-    def get_status(self):
-        return 404
-
-
 class AuthorizationException(Exception):
     is_http_exception = True
 

fastapi_startkit/src/fastapi_startkit/masoniteorm/__init__.py

@@ -1,4 +1,5 @@
 from .config.config import MySQLConfig, PostgresConfig, SQLiteConfig
+from .exceptions import ModelNotFoundException
 from .facades import DB
 from .migrations.Migration import Migration
 from .migrations.Migrator import Migrator
@@ -13,6 +14,7 @@
     "MySQLConfig",
     "SQLiteConfig",
     "Model",
+    "ModelNotFoundException",
     "DB",
     "Migration",
     "Migrator",

fastapi_startkit/src/fastapi_startkit/masoniteorm/exceptions.py

@@ -0,0 +1,12 @@
+class ModelNotFoundException(Exception):
+    is_http_exception = True
+
+    def __init__(self, message="Model Not Found"):
+        super().__init__(message)
+        self.message = message
+
+    def get_response(self):
+        return self.message
+
+    def get_status(self):
+        return 404

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

@@ -87,6 +87,16 @@ def limit(self, limit: int) -> "QueryBuilder":
     async def find(self, primary_key: str | int, columns=None):
         return await self.where(self._model.__primary_key__, primary_key).first(columns)
 
+    async def find_or_fail(self, primary_key: str | int, columns=None):
+        from fastapi_startkit.masoniteorm.exceptions import ModelNotFoundException
+
+        result = await self.find(primary_key, columns)
+        if result is None:
+            raise ModelNotFoundException(
+                f"{self._model.__class__.__name__} with primary key {primary_key!r} not found."
+            )
+        return result
+
     async def first(self, columns=None):
         if not columns:
             columns = []

fastapi_startkit/src/fastapi_startkit/masoniteorm/models/model.py

@@ -103,6 +103,10 @@ def or_where_has(cls, relation: str, callback=None) -> "QueryBuilder":
     async def find(cls, primary_key: str | int, columns=None):
         return await cls.query().find(primary_key, columns)
 
+    @classmethod
+    async def find_or_fail(cls, primary_key: str | int, columns=None):
+        return await cls.query().find_or_fail(primary_key, columns)
+
     @classmethod
     async def first(cls, columns=None):
         return await cls.query().first(columns)

fastapi_startkit/tests/masoniteorm/sqlite/models/test_sqlite_model.py

@@ -4,6 +4,7 @@
 from ..fixtures.db import DB
 from ...fixtures.model import User
 from ..test_case import TestCase
+from fastapi_startkit.masoniteorm import ModelNotFoundException
 
 
 class SqliteTestQueryBuilderModel(TestCase):
@@ -43,6 +44,27 @@ async def test_can_find_list(self):
         self.assertEqual(sql, 'SELECT * FROM "users" WHERE "users"."id" = ? LIMIT 1')
         self.assertIn(1, bindings)
 
+    async def test_find_or_fail_returns_model_when_found(self):
+        user = await User.find_or_fail(1)
+        self.assertIsInstance(user, User)
+        self.assertEqual(user.id, 1)
+
+    async def test_find_or_fail_raises_when_not_found(self):
+        with self.assertRaises(ModelNotFoundException):
+            await User.find_or_fail(99999)
+
+    async def test_find_or_fail_exception_has_404_status(self):
+        try:
+            await User.find_or_fail(99999)
+        except ModelNotFoundException as e:
+            self.assertEqual(e.get_status(), 404)
+
+    async def test_find_or_fail_exception_message_contains_key(self):
+        try:
+            await User.find_or_fail(99999)
+        except ModelNotFoundException as e:
+            self.assertIn("99999", str(e))
+
     async def test_can_set_and_retrieve_attribute(self):
         user = await User.first()
         user.name = "updated"