@resapi/express 0.1.0 → 0.3.0

package/README.md

@@ -8,4 +8,4 @@ npm install @resapi/core @resapi/express express
 
 Add `"@resapi/core"` and `"@resapi/express"` to `dependencies` in `rescript.json`. Modules are under the `ResApiExpress` namespace. Requires Express 5 (tested with 5.2).
 
-See the [README](https://github.com/Seaside-Logic/resapi#readme) and [API reference](https://github.com/Seaside-Logic/resapi/blob/main/docs/api.md).
+See the [README](https://github.com/Seaside-Logic/resapi#readme) and [API reference](https://github.com/Seaside-Logic/resapi/blob/main/site/content/api.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resapi/express",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Express server adapter for resAPI contracts.",
   "license": "MIT",
   "homepage": "https://resapi.dev",
@@ -32,7 +32,7 @@
     "rescript": "^12.3.1"
   },
   "dependencies": {
-    "@resapi/core": "^0.1.0"
+    "@resapi/core": "^0.3.0"
   },
   "devDependencies": {
     "express": "5.2.1"

package/src/EndpointHandler.res

@@ -15,7 +15,7 @@ type route = {
   run: (Req.t, Res.t) => promise<unit>,
 }
 
-// Router.register mounts POST routes behind `express.text`, so the body is the raw string. A body
+// Router.register mounts POST and PUT routes behind `express.text`, so the body is the raw string. A body
 // already parsed by an upstream `express.json()` is used as it is. No body at all parses as "".
 let rawBody = req =>
   switch req->Req.body->Nullable.toOption {

package/src/Reject.res

@@ -0,0 +1,12 @@
+// Auth rejections in resAPI's error shape, for middleware. See Reject.resi.
+let send = (res, ~status, ~kind, ~reason) => {
+  let {status, body} = ResApi.Dispatch.errorResponse(
+    ~status,
+    ~kind,
+    ~message=reason->Option.getOr(""),
+  )
+  res->Res.status(status)->Res.json(body)
+}
+
+let unauthenticated = (res, ~reason=?) => res->send(~status=401, ~kind="unauthenticated", ~reason)
+let forbidden = (res, ~reason=?) => res->send(~status=403, ~kind="forbidden", ~reason)

package/src/Reject.resi

@@ -0,0 +1,8 @@
+// Auth rejections for middleware, in resAPI's error shape, so the typed client sees them as
+// `Unauthorized({status, reason})`. Call one instead of `next()`: `Reject.unauthenticated(res)`.
+
+/** Sends 401 `{"error": {"kind": "unauthenticated", "message": <reason or "">, "path": []}}`. */
+let unauthenticated: (Res.t, ~reason: string=?) => unit
+
+/** Sends 403 `{"error": {"kind": "forbidden", "message": <reason or "">, "path": []}}`. */
+let forbidden: (Res.t, ~reason: string=?) => unit

package/src/Req.res

@@ -10,3 +10,10 @@ type t
 @send @return(nullable) external header: (t, string) => option<string> = "get"
 @get external method: t => string = "method"
 @get external path: t => string = "path"
+
+@get_index external field: (t, string) => Nullable.t<'a> = ""
+@set_index external setField: (t, string, 'a) => unit = ""
+
+let set = (req, key, value) => req->setField(ResApi.Key.name(key), value)
+let get = (req, key) => req->field(ResApi.Key.name(key))->Nullable.toOption
+let getOrThrow = (req, key) => req->get(key)->ResApi.Key.orThrow(key)

package/src/Req.resi

@@ -0,0 +1,24 @@
+// Express's request object.
+type t
+
+/** Path parameters, already percent-decoded by Express. */
+@get external params: t => dict<string> = "params"
+
+/** Set by body-parsing middleware: a string from `express.text`, parsed JSON from `express.json`. */
+@get external body: t => Nullable.t<JSON.t> = "body"
+
+@send @return(nullable) external header: (t, string) => option<string> = "get"
+@get external method: t => string = "method"
+@get external path: t => string = "path"
+
+/** Stores a value on the request under `key` (as `req[name]`), usually in middleware. The name shares
+    `req` with Express's own fields: a getter such as `query` or `path` throws, and a field Express writes,
+    such as `params` or `body`, gets overwritten. Pick a name Express doesn't use. */
+let set: (t, ResApi.Key.t<'a>, 'a) => unit
+
+/** The value under `key` (`req[name]`), or `None` when it's unset, `undefined` or `null`. */
+let get: (t, ResApi.Key.t<'a>) => option<'a>
+
+/** For routes behind the middleware that sets `key`. Throws when the value is missing: a logged 500
+    that reveals nothing, inside a typed endpoint. */
+let getOrThrow: (t, ResApi.Key.t<'a>) => 'a

package/src/Router.res

@@ -16,7 +16,10 @@ type server
 @module("express") external text: {"type": string => bool} => middleware = "text"
 @send external expressGet: (t, string, handler) => unit = "get"
 @send external expressPost: (t, string, handler) => unit = "post"
+@send external expressPut: (t, string, handler) => unit = "put"
+@send external expressAll: (t, string, handler) => unit = "all"
 @send external expressPostWith: (t, string, middleware, handler) => unit = "post"
+@send external expressPutWith: (t, string, middleware, handler) => unit = "put"
 @send external expressUse: (t, middleware) => unit = "use"
 @send external expressUseAt: (t, string, middleware) => unit = "use"
 
@@ -34,30 +37,40 @@ let rethrowAsError = exn =>
     )
   }
 
-let guard = (handler: handler): handler =>
+let catchExceptions = (handler: handler): handler =>
   async (req, res) =>
     try await handler(req, res) catch {
     | exn => rethrowAsError(exn)
     }
 
 let get = (router, path, handler) => {
-  router->expressGet(path, guard(handler))
+  router->expressGet(path, catchExceptions(handler))
   router
 }
 
 let post = (router, path, handler) => {
-  router->expressPost(path, guard(handler))
+  router->expressPost(path, catchExceptions(handler))
+  router
+}
+
+let put = (router, path, handler) => {
+  router->expressPut(path, catchExceptions(handler))
+  router
+}
+
+let all = (router, path, handler) => {
+  router->expressAll(path, catchExceptions(handler))
   router
 }
 
 let use = (router, ~path=?, middleware: middleware) => {
-  let guarded = (req, res, next) =>
+  let wrapped = (req, res, next) =>
     try middleware(req, res, next) catch {
     | exn => rethrowAsError(exn)
     }
   switch path {
-  | None => router->expressUse(guarded)
-  | Some(path) => router->expressUseAt(path, guarded)
+  | None => router->expressUse(wrapped)
+  | Some(path) => router->expressUseAt(path, wrapped)
   }
   router
 }
@@ -66,10 +79,29 @@ let use = (router, ~path=?, middleware: middleware) => {
 // upstream parser already read.
 let rawText = text({"type": _ => true})
 
+// Express has no public route list, so `register` records what it mounted, for assertRegistered.
+let registered: WeakMap.t<t, array<string>> = WeakMap.make()
+
+let routeName = (method, path) => `${ResApi.Endpoint.methodName(method)} ${path}`
+
 let register = (router, route: EndpointHandler.route) => {
+  let names = registered->WeakMap.get(router)->Option.getOr([])
+  registered->WeakMap.set(router, [...names, routeName(route.method, route.path)])->ignore
   switch route.method {
   | Get => router->expressGet(route.path, route.run)
   | Post => router->expressPostWith(route.path, rawText, route.run)
+  | Put => router->expressPutWith(route.path, rawText, route.run)
   }
   router
 }
+
+let assertRegistered = (router, endpoints: array<ResApi.Endpoint.any>) => {
+  let names = registered->WeakMap.get(router)->Option.getOr([])
+  let missing =
+    endpoints
+    ->Array.map(endpoint => routeName(endpoint.method, endpoint.path))
+    ->Array.filter(name => !(names->Array.includes(name)))
+  if missing != [] {
+    JsError.throwWithMessage(`Endpoints without a route: ${missing->Array.join(", ")}`)
+  }
+}

package/src/Router.resi

@@ -23,10 +23,18 @@ type server
 /** A rejected handler goes to Express's error handler. */
 let get: (t, string, handler) => t
 let post: (t, string, handler) => t
+let put: (t, string, handler) => t
 
 /** Runs for every request whose path starts with `~path` (default all), including unmatched routes.
     The first `use` is the outermost layer. */
 let use: (t, ~path: string=?, middleware) => t
 
-/** POST endpoints get a raw-text body parser (100kb limit). A body already parsed upstream is used as is. */
+/** POST and PUT endpoints get a raw-text body parser (100kb limit). A body already parsed upstream is used as is. */
 let register: (t, EndpointHandler.route) => t
+
+/** A plain route for every HTTP method. For unmatched requests, add a last `use` (Express has no
+    separate not-found handler). */
+let all: (t, string, handler) => t
+
+/** For tests: throws, naming each endpoint in the list that wasn't mounted with `register`. */
+let assertRegistered: (t, array<ResApi.Endpoint.any>) => unit