@resapi/express 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resapi/express",
-  "version": "0.1.0",
+  "version": "0.2.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.2.0"
   },
   "devDependencies": {
     "express": "5.2.1"

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,6 +16,7 @@ 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 expressAll: (t, string, handler) => unit = "all"
 @send external expressPostWith: (t, string, middleware, handler) => unit = "post"
 @send external expressUse: (t, middleware) => unit = "use"
 @send external expressUseAt: (t, string, middleware) => unit = "use"
@@ -34,30 +35,35 @@ 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 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 +72,28 @@ 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)
   }
   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

@@ -30,3 +30,10 @@ 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. */
 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