@resapi/express 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seaside Logic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @resapi/express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Express](https://expressjs.com) 5 server adapter for [resAPI](https://github.com/Seaside-Logic/resapi) contracts.
+
+```sh
+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).

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@resapi/express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Express server adapter for resAPI contracts.",
+  "license": "MIT",
+  "homepage": "https://resapi.dev",
+  "bugs": {
+    "url": "https://github.com/Seaside-Logic/resapi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seaside-Logic/resapi.git",
+    "directory": "packages/express"
+  },
+  "keywords": [
+    "rescript",
+    "http",
+    "api",
+    "contract",
+    "typed-client",
+    "express",
+    "node"
+  ],
+  "type": "module",
+  "files": [
+    "src/*.res",
+    "src/*.resi",
+    "rescript.json"
+  ],
+  "peerDependencies": {
+    "express": "^5.2.1",
+    "rescript": "^12.3.1"
+  },
+  "dependencies": {
+    "@resapi/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "express": "5.2.1"
+  }
+}

package/rescript.json

@@ -0,0 +1,8 @@
+{
+  "name": "@resapi/express",
+  "sources": {"dir": "src"},
+  "dependencies": ["@resapi/core"],
+  "package-specs": {"module": "esmodule", "in-source": true},
+  "suffix": ".res.mjs",
+  "namespace": "ResApiExpress"
+}

package/src/EndpointHandler.res

@@ -0,0 +1,39 @@
+// Turns a contract into a route: the request runs through core's Dispatch pipeline, and the result is
+// sent with `res.status().json()`. The handler's types are closed over, so routes of any contract types share one type.
+open ResApi
+
+type input<'params, 'body> = Dispatch.input<'params, 'body> = {params: 'params, body: 'body}
+
+type handler<'params, 'body, 'response, 'error> = (
+  Req.t,
+  input<'params, 'body>,
+) => promise<result<'response, 'error>>
+
+type route = {
+  method: Endpoint.method,
+  path: string,
+  run: (Req.t, Res.t) => promise<unit>,
+}
+
+// Router.register mounts POST 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 {
+  | None => Dispatch.Text(Promise.resolve(""))
+  | Some(JSON.String(text)) => Text(Promise.resolve(text))
+  | Some(json) => Parsed(json)
+  }
+
+let make = (contract: Endpoint.t<_, _, _, _>, handler: handler<_, _, _, _>) => {
+  method: contract.method,
+  path: contract.path,
+  run: async (req, res) => {
+    let {status, body} = await Dispatch.run(
+      contract,
+      ~params=req->Req.params,
+      ~readBody=() => rawBody(req),
+      ~handle=input => handler(req, input),
+    )
+    res->Res.status(status)->Res.json(body)
+  },
+}

package/src/EndpointHandler.resi

@@ -0,0 +1,24 @@
+// Turns a contract into a route: the request runs through core's Dispatch pipeline, and the result is
+// sent with `res.status().json()`.
+
+type input<'params, 'body> = ResApi.Dispatch.input<'params, 'body> = {params: 'params, body: 'body}
+
+/** `Error(e)` must be one of the contract's declared application errors (see `Endpoint.withErrors`). */
+type handler<'params, 'body, 'response, 'error> = (
+  Req.t,
+  input<'params, 'body>,
+) => promise<result<'response, 'error>>
+
+/** Mount with `Router.register`. */
+type route = private {
+  method: ResApi.Endpoint.method,
+  path: string,
+  run: (Req.t, Res.t) => promise<unit>,
+}
+
+/** Invalid input is a 400, and any exception from a codec or the handler is logged and answered with a
+    500 that reveals nothing. */
+let make: (
+  ResApi.Endpoint.t<'params, 'body, 'response, 'error>,
+  handler<'params, 'body, 'response, 'error>,
+) => route

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

@@ -0,0 +1,19 @@
+// 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"
+
+@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/Res.res

@@ -0,0 +1,7 @@
+// Express's response object.
+type t
+
+@send external status: (t, int) => t = "status"
+@send external json: (t, JSON.t) => unit = "json"
+@send external send: (t, string) => unit = "send"
+@send external setHeader: (t, string, string) => t = "set"

package/src/Router.res

@@ -0,0 +1,99 @@
+// A router is the Express app itself, so any Express API missing here can be bound against `t` with one
+// more external. Express 5 sends a rejected handler promise to its error handler (by default: log, then
+// a 500; outside production the body shows the stack, as Express always does).
+
+type t
+
+type handler = (Req.t, Res.t) => promise<unit>
+
+type next = unit => unit
+
+type middleware = (Req.t, Res.t, next) => unit
+
+type server
+
+@module("express") external make: unit => t = "default"
+@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"
+
+@send external listen: (t, int, unit => unit) => server = "listen"
+@send external close: server => unit = "close"
+
+// Express's error handler logs `err.stack`, which a raw ReScript exception lacks: it logs as
+// "[object Object]". Rethrowing it as an Error keeps the log readable. JS errors pass untouched.
+let rethrowAsError = exn =>
+  switch exn {
+  | JsExn(e) => JsExn.throw(e)
+  | exn =>
+    JsError.throwWithMessage(
+      `Uncaught ReScript exception: ${exn->JSON.stringifyAny->Option.getOr("unknown")}`,
+    )
+  }
+
+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, catchExceptions(handler))
+  router
+}
+
+let post = (router, path, 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 wrapped = (req, res, next) =>
+    try middleware(req, res, next) catch {
+    | exn => rethrowAsError(exn)
+    }
+  switch path {
+  | None => router->expressUse(wrapped)
+  | Some(path) => router->expressUseAt(path, wrapped)
+  }
+  router
+}
+
+// Reads any request body as raw text, so Dispatch reports malformed JSON itself. It skips a body an
+// 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

@@ -0,0 +1,39 @@
+// A router is the Express app itself, so any Express API missing here can be bound against `t` with one
+// more external.
+
+type t
+
+/** Handlers are always async: `async (_req, res) => res->Res.send("hi")`. */
+type handler = (Req.t, Res.t) => promise<unit>
+
+type next = unit => unit
+
+/** Native Express middleware: call `next()` to continue, or answer through `res`. Express's own
+    middleware (`express.json()`, `express.static(...)`) binds to this type directly. */
+type middleware = (Req.t, Res.t, next) => unit
+
+type server
+
+@module("express") external make: unit => t = "default"
+
+/** Starts a Node HTTP server. Port 0 picks a free port. */
+@send external listen: (t, int, unit => unit) => server = "listen"
+@send external close: server => unit = "close"
+
+/** A rejected handler goes to Express's error handler. */
+let get: (t, string, handler) => t
+let post: (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. */
+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