typed handler returns and resource trait

Author: saviorand

.gitignore

@@ -10,4 +10,5 @@
 *.egg-info
 
 # magic environments
-.magic
+.magic
+*.xml

lightbug.mojo

@@ -1,4 +1,4 @@
-# lightbug_api showcase
+# lightbug_api showcase — metaprogramming ergonomics demo
 # ─────────────────────────────────────────────────────────────────────────────
 # Run:  mojo lightbug.mojo
 # Test: curl http://localhost:8080/
@@ -13,9 +13,11 @@
 #            -d '{"name":"Updated","price":19.99}'
 #       curl -X DELETE http://localhost:8080/items/42
 #       curl http://localhost:8080/v1/status
+#       curl http://localhost:8080/notes
+#       curl http://localhost:8080/notes/1
 # ─────────────────────────────────────────────────────────────────────────────
 
-from lightbug_api import App, GET, POST, PUT, DELETE, mount, HandlerResponse
+from lightbug_api import App, GET, POST, PUT, DELETE, mount, HandlerResponse, Resource, resource
 from lightbug_api.context import Context
 from lightbug_api.response import Response
 from lightbug_http.http.json import JsonSerializable, JsonDeserializable
@@ -55,62 +57,117 @@ struct StatusResponse(JsonSerializable, Movable, Defaultable):
         self.version = ""
 
 
+@fieldwise_init
+struct Note(JsonSerializable, Movable, Defaultable):
+    var id: Int
+    var text: String
+
+    fn __init__(out self):
+        self.id = 0
+        self.text = ""
+
+
 # ------------------------------------------------------------------ handlers
+# Handlers that need full control (non-200 status, redirects, plain text) keep
+# the HandlerResponse return type.  Handlers that just return a model use the
+# model type directly — the framework auto-serialises as JSON 200 OK.
 
 fn index(ctx: Context) raises -> HandlerResponse:
     return Response.text("Welcome to lightbug_api 🔥")
 
 
-fn list_items(ctx: Context) raises -> HandlerResponse:
-    return Response.json(Item(1, "Widget", 9.99))
+# ── Before (old style) ───────────────────────────────────────────────────────
+
+fn list_items(ctx: Context) raises -> Item:          # ← returns Item directly
+    return Item(1, "Widget", 9.99)
 
 
-fn get_item(ctx: Context) raises -> HandlerResponse:
-    # ctx.param("id", 0)          → Int   (path param, typed by default value)
-    # ctx.query("verbose", False) → Bool  (query param, typed by default value)
+fn get_item(ctx: Context) raises -> Item:            # ← returns Item directly
     var id      = ctx.param("id", 0)
     var verbose = ctx.query("verbose", False)
-
     if verbose:
         print("GET /items/", id, " (verbose mode)")
-
-    return Response.json(Item(id, String("Item ", id), 9.99))
+    return Item(id, String("Item ", id), 9.99)
 
 
 fn create_item(ctx: Context) raises -> HandlerResponse:
+    # Still HandlerResponse — needs 201 Created status code
     var body    = ctx.json[CreateItemRequest]()
     var created = Item(100, body.name, body.price)
     return Response.created(created)
 
 
-fn update_item(ctx: Context) raises -> HandlerResponse:
+fn update_item(ctx: Context) raises -> Item:         # ← returns Item directly
     var body = ctx.json[CreateItemRequest]()
     var id   = ctx.param("id", 0)
-    return Response.json(Item(id, body.name, body.price))
+    return Item(id, body.name, body.price)
 
 
 fn delete_item(ctx: Context) raises -> HandlerResponse:
+    # Still HandlerResponse — needs 204 No Content
     var id = ctx.param("id", 0)
     print("Deleting item", id)
     return Response.no_content()
 
 
-fn health(ctx: Context) raises -> HandlerResponse:
-    return Response.json(StatusResponse("ok", "1.0.0"))
+fn health(ctx: Context) raises -> StatusResponse:    # ← returns StatusResponse directly
+    return StatusResponse("ok", "1.0.0")
+
+
+# ── Resource / controller pattern ────────────────────────────────────────────
+# Group CRUD handlers in a struct; `resource[Notes]("notes")` registers all
+# five standard routes under /notes in one call.
+
+struct Notes(Resource):
+    @staticmethod
+    fn index(ctx: Context) raises -> HandlerResponse:
+        return Response.json(Note(0, "all notes"))
+
+    @staticmethod
+    fn show(ctx: Context) raises -> HandlerResponse:
+        var id = ctx.param("id", 0)
+        return Response.json(Note(id, String("note ", id)))
+
+    @staticmethod
+    fn create(ctx: Context) raises -> HandlerResponse:
+        return Response.created(Note(1, "new note"))
+
+    @staticmethod
+    fn update(ctx: Context) raises -> HandlerResponse:
+        var id = ctx.param("id", 0)
+        return Response.json(Note(id, "updated"))
+
+    @staticmethod
+    fn destroy(ctx: Context) raises -> HandlerResponse:
+        return Response.no_content()
 
 
 # --------------------------------------------------------------------- main
 
 fn main() raises:
     var app = App(
+        # Plain-text response — HandlerResponse (unchanged)
         GET("/",              index),
-        GET("/items",         list_items),
-        GET("/items/{id}",    get_item),
+
+        # Typed return — framework auto-serialises Item as JSON 200 OK
+        GET[Item, list_items]("/items"),
+        GET[Item, get_item]("/items/{id}"),
+
+        # 201 Created — still HandlerResponse (needs explicit status)
         POST("/items",        create_item),
-        PUT("/items/{id}",    update_item),
+
+        # Typed return
+        PUT[Item, update_item]("/items/{id}"),
+
+        # 204 No Content — still HandlerResponse
         DELETE("/items/{id}", delete_item),
+
         mount("v1",
-            GET("status", health),
+            # Typed return inside a mount
+            GET[StatusResponse, health]("status"),
         ),
+
+        # Resource controller — five routes registered in one line
+        resource[Notes]("notes"),
     )
     app.run()

lightbug_api/__init__.mojo

@@ -26,6 +26,8 @@ from lightbug_api.routing import (
     abort,
     next,
     _apply_routes,
+    Resource,
+    resource,
 )
 
 

lightbug_api/routing.mojo

@@ -6,6 +6,9 @@ from lightbug_http.http import RequestMethod
 from lightbug_http.http.common_response import InternalError
 from lightbug_http.uri import URIDelimiters
 
+from lightbug_http import OK
+from lightbug_http.http.json import Json
+
 from lightbug_api.context import Context
 
 
@@ -31,6 +34,16 @@ comptime HandlerResponse = Variant[HTTPResponse, String]
 # Use Context to access the request, path params, query params, headers, body.
 comptime Handler = fn (Context) raises -> HandlerResponse
 
+
+# Compile-time adapter: specialises into a concrete Handler for any fn that
+# returns a JSON-serialisable T.  Because `h` is a compile-time parameter the
+# resulting specialisation has zero extra overhead vs writing the wrapper by hand.
+fn _json_adapter[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](
+    ctx: Context,
+) raises -> HandlerResponse:
+    return HandlerResponse(OK(Json(h(ctx))))
+
+
 # ------------------------------------------------------------ middleware types
 
 # Middleware return type:
@@ -583,3 +596,115 @@ fn _apply_routes[is_main: Bool](mut router: RouterBase[is_main], routes: List[Ro
             router.add_router(sub^)
         else:
             router.add_route(r.path, r.handler, RequestMethod(r.method))
+
+
+# ================================================================ Typed route builders
+# Parametric overloads that let handlers return model types directly instead of
+# wrapping everything in ``HandlerResponse``.  ``_json_adapter`` is specialised
+# at compile time so there is zero runtime overhead over hand-written wrappers.
+#
+# Usage::
+#
+#   fn get_item(ctx: Context) raises -> Item:   # no Response.json() needed
+#       return Item(ctx.param("id", 0), "Widget", 9.99)
+#
+#   GET[Item, get_item]("/items/{id}")           # T is often inferable
+
+fn GET[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](path: String) -> Route:
+    """GET route whose handler returns *T* directly — auto-serialised as JSON."""
+    return Route("GET", path, _json_adapter[T, h])
+
+
+fn POST[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](path: String) -> Route:
+    """POST route whose handler returns *T* directly — auto-serialised as JSON."""
+    return Route("POST", path, _json_adapter[T, h])
+
+
+fn PUT[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](path: String) -> Route:
+    """PUT route whose handler returns *T* directly — auto-serialised as JSON."""
+    return Route("PUT", path, _json_adapter[T, h])
+
+
+fn DELETE[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](path: String) -> Route:
+    """DELETE route whose handler returns *T* directly — auto-serialised as JSON."""
+    return Route("DELETE", path, _json_adapter[T, h])
+
+
+fn PATCH[T: Movable & ImplicitlyDestructible, h: fn (Context) raises -> T](path: String) -> Route:
+    """PATCH route whose handler returns *T* directly — auto-serialised as JSON."""
+    return Route("PATCH", path, _json_adapter[T, h])
+
+
+# ================================================================ Resource trait
+# Declare a struct-based CRUD controller and register all five standard routes
+# in one call::
+#
+#   struct Items(Resource):
+#       @staticmethod
+#       fn index(ctx: Context) raises -> HandlerResponse: ...
+#       @staticmethod
+#       fn show(ctx: Context) raises -> HandlerResponse: ...
+#       @staticmethod
+#       fn create(ctx: Context) raises -> HandlerResponse: ...
+#       @staticmethod
+#       fn update(ctx: Context) raises -> HandlerResponse: ...
+#       @staticmethod
+#       fn destroy(ctx: Context) raises -> HandlerResponse: ...
+#
+#   App(resource[Items]("items")).run()
+#   # → GET /items, GET /items/{id}, POST /items, PUT /items/{id}, DELETE /items/{id}
+
+trait Resource:
+    """Struct-based CRUD resource controller.
+
+    Implement all five static methods then register with ``resource[R](fragment)``.
+    Static methods mean no instance is needed — the struct is purely a namespace.
+    """
+
+    @staticmethod
+    fn index(ctx: Context) raises -> HandlerResponse:
+        """GET /  — list all resources."""
+        ...
+
+    @staticmethod
+    fn show(ctx: Context) raises -> HandlerResponse:
+        """GET /{id}  — retrieve one resource."""
+        ...
+
+    @staticmethod
+    fn create(ctx: Context) raises -> HandlerResponse:
+        """POST /  — create a resource."""
+        ...
+
+    @staticmethod
+    fn update(ctx: Context) raises -> HandlerResponse:
+        """PUT /{id}  — replace a resource."""
+        ...
+
+    @staticmethod
+    fn destroy(ctx: Context) raises -> HandlerResponse:
+        """DELETE /{id}  — remove a resource."""
+        ...
+
+
+fn resource[R: Resource](fragment: String) -> Route:
+    """Declare a full CRUD resource mounted at *fragment*.
+
+    Equivalent to::
+
+        mount(fragment,
+            GET("",        R.index),
+            GET("{id}",    R.show),
+            POST("",       R.create),
+            PUT("{id}",    R.update),
+            DELETE("{id}", R.destroy),
+        )
+    """
+    return mount(
+        fragment,
+        GET("",        R.index),
+        GET("{id}",    R.show),
+        POST("",       R.create),
+        PUT("{id}",    R.update),
+        DELETE("{id}", R.destroy),
+    )