@resapi/express 0.0.0-stage → 0.1.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.1.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.1.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/Req.res

@@ -0,0 +1,12 @@
+// 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"

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,75 @@
+// 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 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 guard = (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
+}
+
+let post = (router, path, handler) => {
+  router->expressPost(path, guard(handler))
+  router
+}
+
+let use = (router, ~path=?, middleware: middleware) => {
+  let guarded = (req, res, next) =>
+    try middleware(req, res, next) catch {
+    | exn => rethrowAsError(exn)
+    }
+  switch path {
+  | None => router->expressUse(guarded)
+  | Some(path) => router->expressUseAt(path, guarded)
+  }
+  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})
+
+let register = (router, route: EndpointHandler.route) => {
+  switch route.method {
+  | Get => router->expressGet(route.path, route.run)
+  | Post => router->expressPostWith(route.path, rawText, route.run)
+  }
+  router
+}

package/src/Router.resi

@@ -0,0 +1,32 @@
+// 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