@resapi/core 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/core
 
-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.
+Type-safe HTTP contracts for ReScript: endpoint contracts, codecs and a typed client. Part of [resAPI](https://github.com/Seaside-Logic/resapi).
+
+```sh
+npm install @resapi/core
+```
+
+Add `"@resapi/core"` to `dependencies` in `rescript.json`. Modules are under the `ResApi` namespace.
+
+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,31 @@
 {
   "name": "@resapi/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Type-safe HTTP contracts for ReScript: endpoint contracts, codecs and a typed client.",
+  "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/core"
+  },
+  "keywords": [
+    "rescript",
+    "http",
+    "api",
+    "contract",
+    "typed-client"
+  ],
+  "type": "module",
+  "files": [
+    "src/*.res",
+    "src/*.resi",
+    "rescript.json"
+  ],
+  "peerDependencies": {
+    "rescript": "^12.3.1"
+  }
+}

package/rescript.json

@@ -0,0 +1,7 @@
+{
+  "name": "@resapi/core",
+  "sources": {"dir": "src"},
+  "package-specs": {"module": "esmodule", "in-source": true},
+  "suffix": ".res.mjs",
+  "namespace": "ResApi"
+}

package/src/Client.res

@@ -0,0 +1,159 @@
+// Calls an endpoint contract over HTTP. Depends only on contracts and Fetch, never on a server adapter.
+
+type t = {
+  baseUrl: string,
+  fetch: Fetch.Request.t => promise<Fetch.Response.t>,
+  headers: dict<string>,
+}
+
+type error<'e> =
+  | Application({status: int, error: 'e})
+  | Network(string)
+  | Aborted
+  | UnexpectedStatus({status: int, body: string})
+  | InvalidResponse(Codec.error)
+  | InvalidParams(string)
+  | EncodeFailed(string)
+
+@val external globalFetch: Fetch.Request.t => promise<Fetch.Response.t> = "fetch"
+@val external encodeURIComponent: string => string = "encodeURIComponent"
+
+let make = (~baseUrl, ~fetch=globalFetch, ~headers=dict{}) => {baseUrl, fetch, headers}
+
+/** Appends the path to the base URL, keeping any path prefix in the base: `https://x.dev/api/` + `/a` is `https://x.dev/api/a`. */
+let joinUrl = (baseUrl, path) => {
+  let base = baseUrl->String.endsWith("/") ? baseUrl->String.slice(~start=0, ~end=-1) : baseUrl
+  path->String.startsWith("/") ? base ++ path : `${base}/${path}`
+}
+
+let paramValue = (values, name) =>
+  switch values->Dict.get(name) {
+  | Some(JSON.String(s)) => Ok(s)
+  | Some(Number(n)) => Ok(n->Float.toString)
+  | Some(Boolean(b)) => Ok(b ? "true" : "false")
+  | Some(_) => Error(InvalidParams(`Path parameter "${name}" must be a string, number or boolean`))
+  | None => Error(InvalidParams(`Missing path parameter "${name}"`))
+  }
+
+/** Fills `:name` segments from the encoded params object, percent-encoding each value. */
+let buildPath = (path, params: JSON.t) => {
+  let values = switch params {
+  | Object(values) => values
+  | _ => dict{}
+  }
+  path
+  ->String.split("/")
+  ->Array.reduce(Ok([]), (acc, segment) =>
+    acc->Result.flatMap(segments =>
+      segment->String.startsWith(":")
+        ? paramValue(values, segment->String.slice(~start=1))->Result.map(
+            value => [...segments, encodeURIComponent(value)],
+          )
+        : Ok([...segments, segment])
+    )
+  )
+  ->Result.map(segments => segments->Array.join("/"))
+}
+
+let encodeWith = (encode, value) =>
+  try Ok(encode(value)) catch {
+  | JsExn(e) => Error(EncodeFailed(e->JsExn.message->Option.getOr("Encoding failed")))
+  | _ => Error(EncodeFailed("Encoding failed"))
+  }
+
+let parseJson = text =>
+  try Ok(JSON.parseOrThrow(text)) catch {
+  | JsExn(e) => Error({Codec.path: [], message: e->JsExn.message->Option.getOr("Invalid JSON")})
+  }
+
+let decodeResponse = (contract: Endpoint.t<_, _, _, _>, text) =>
+  parseJson(text)
+  ->Result.flatMap(contract.responseCodec.decode)
+  ->Result.mapError(e => InvalidResponse(e))
+
+// A non-2xx body of `{"applicationError": ...}` is a declared error and must decode as one; anything
+// else (framework errors, proxies, plain text) is just an unexpected status.
+let decodeFailure = (contract: Endpoint.t<_, _, _, _>, status, text) =>
+  switch parseJson(text) {
+  | Ok(Object(body)) =>
+    switch body->Dict.get("applicationError") {
+    | Some(json) =>
+      switch contract.errorCodec.decode(json) {
+      | Ok(error) => Error(Application({status, error}))
+      | Error(e) => Error(InvalidResponse({...e, path: ["applicationError", ...e.path]}))
+      }
+    | None => Error(UnexpectedStatus({status, body: text}))
+    }
+  | _ => Error(UnexpectedStatus({status, body: text}))
+  }
+
+// Only the transport is inside the try: codec and status errors are classified elsewhere.
+let fetchText = async (client, request) =>
+  try {
+    let response = await client.fetch(request)
+    Ok((response, await response->Fetch.Response.readText))
+  } catch {
+  | JsExn(e) =>
+    switch e->JsExn.name {
+    | Some("AbortError" | "TimeoutError") => Error(Aborted)
+    | _ => Error(Network(e->JsExn.message->Option.getOr("fetch failed")))
+    }
+  }
+
+// Later sources win. Names are lowercased, because Fetch would otherwise combine `Authorization` and
+// `authorization` into one comma-separated value instead of overriding.
+let mergeHeaders = sources => {
+  let merged = dict{}
+  sources->Array.forEach(source =>
+    source->Dict.forEachWithKey((value, name) => merged->Dict.set(name->String.toLowerCase, value))
+  )
+  merged
+}
+
+let requestInit = (client, contract: Endpoint.t<_, _, _, _>, body, ~headers, ~signal): result<
+  Fetch.Request.init,
+  _,
+> =>
+  switch contract.method {
+  | Get => Ok({method: "GET", headers: mergeHeaders([client.headers, headers]), ?signal})
+  | Post =>
+    encodeWith(contract.bodyCodec.encode, body)->Result.map((json): Fetch.Request.init => {
+      method: "POST",
+      headers: mergeHeaders([client.headers, dict{"content-type": "application/json"}, headers]),
+      body: json->JSON.stringify,
+      ?signal,
+    })
+  }
+
+let send = async (
+  client,
+  contract: Endpoint.t<_, _, _, _>,
+  ~params,
+  ~body,
+  ~headers=dict{},
+  ~signal=?,
+) => {
+  let prepared =
+    encodeWith(contract.paramsCodec.encode, params)
+    ->Result.flatMap(json => buildPath(contract.path, json))
+    ->Result.flatMap(path =>
+      requestInit(client, contract, body, ~headers, ~signal)->Result.map(init => (path, init))
+    )
+  switch prepared {
+  | Error(e) => Error(e)
+  | Ok((path, init)) =>
+    // An invalid baseUrl makes Request throw: a configuration bug, not a request failure.
+    switch await fetchText(client, Fetch.Request.make(joinUrl(client.baseUrl, path), ~init)) {
+    | Error(e) => Error(e)
+    | Ok((response, text)) =>
+      response->Fetch.Response.ok
+        ? decodeResponse(contract, text)
+        : decodeFailure(contract, response->Fetch.Response.status, text)
+    }
+  }
+}
+
+let call = (client, contract, ~params, ~headers=?, ~signal=?) =>
+  send(client, contract, ~params, ~body=(), ~headers?, ~signal?)
+
+let callWithBody = send

package/src/Client.resi

@@ -0,0 +1,43 @@
+// Calls an endpoint contract over HTTP. Depends only on contracts and Fetch, never on a server adapter.
+
+type t
+
+type error<'e> =
+  | Application({status: int, error: 'e})
+  | Network(string)
+  | Aborted
+  | UnexpectedStatus({status: int, body: string})
+  | InvalidResponse(Codec.error)
+  | InvalidParams(string)
+  | EncodeFailed(string)
+
+/** `~fetch` defaults to the global fetch; pass another to call in-process or to fake a server.
+    `~baseUrl` keeps its path prefix: `https://x.dev/api/` + `/a` is `https://x.dev/api/a`.
+    `~headers` are sent with every request. */
+let make: (
+  ~baseUrl: string,
+  ~fetch: Fetch.Request.t => promise<Fetch.Response.t>=?,
+  ~headers: dict<string>=?,
+) => t
+
+/** For contracts without a request body (`'body = unit`).
+
+    `~headers` override the client's headers and resAPI's `content-type`; names are case-insensitive.
+    Aborting `~signal` (or its timeout firing) ends the call with `Error(Aborted)`. */
+let call: (
+  t,
+  Endpoint.t<'p, unit, 'r, 'e>,
+  ~params: 'p,
+  ~headers: dict<string>=?,
+  ~signal: Fetch.AbortSignal.t=?,
+) => promise<result<'r, error<'e>>>
+
+/** For contracts with a request body. `~headers` and `~signal` work as in `call`. */
+let callWithBody: (
+  t,
+  Endpoint.t<'p, 'b, 'r, 'e>,
+  ~params: 'p,
+  ~body: 'b,
+  ~headers: dict<string>=?,
+  ~signal: Fetch.AbortSignal.t=?,
+) => promise<result<'r, error<'e>>>

package/src/Codec.res

@@ -0,0 +1,6 @@
+// The only thing an endpoint needs from a codec. Any backend fits: Sury via @resapi/sury, or a hand-written record.
+type error = {path: array<string>, message: string}
+type t<'a> = {decode: JSON.t => result<'a, error>, encode: 'a => JSON.t}
+
+/** For endpoints without path params or without a request body. */
+let unit = {decode: _ => Ok(), encode: () => JSON.Object(dict{})}

package/src/Dispatch.res

@@ -0,0 +1,87 @@
+// The adapter-neutral server pipeline: decodes a request, runs a typed handler and encodes its result
+// in resAPI's wire format. Server adapters supply the raw params and body and send the result.
+// No server or runtime code here.
+
+type input<'params, 'body> = {params: 'params, body: 'body}
+
+type response = {status: int, body: JSON.t}
+
+type rawBody = Text(promise<string>) | Parsed(JSON.t)
+
+let errorResponse = (~status, ~kind, ~message, ~path=[]) => {
+  status,
+  body: JSON.Encode.object(
+    dict{
+      "error": JSON.Encode.object(
+        dict{
+          "kind": JSON.Encode.string(kind),
+          "message": JSON.Encode.string(message),
+          "path": JSON.Encode.array(path->Array.map(JSON.Encode.string)),
+        },
+      ),
+    },
+  ),
+}
+
+// Declared errors travel as `{"applicationError": <encoded>}`, apart from the framework's `{"error": ...}`.
+let applicationErrorResponse = (contract: Endpoint.t<_, _, _, _>, error) => {
+  let status = contract.errorStatus(error)
+  if status < 400 || status > 599 {
+    JsError.throwWithMessage(
+      `Application error status must be 4xx or 5xx, got ${status->Int.toString}`,
+    )
+  }
+  {status, body: JSON.Encode.object(dict{"applicationError": contract.errorCodec.encode(error)})}
+}
+
+let readJsonBody = async (contract: Endpoint.t<_, _, _, _>, readBody) =>
+  switch contract.method {
+  | Get => Ok(JSON.Null)
+  | Post =>
+    switch readBody() {
+    | Parsed(json) => Ok(json)
+    | Text(text) =>
+      // Awaited outside the try: a failed read is unexpected (500), not malformed JSON.
+      let text = await text
+      try Ok(JSON.parseOrThrow(text)) catch {
+      | JsExn(e) => Error(e->JsExn.message->Option.getOr("Invalid JSON"))
+      }
+    }
+  }
+
+// Params are decoded before the body is read, so a bad URL never costs a body parse.
+let respond = async (contract: Endpoint.t<_, _, _, _>, ~params, ~readBody, ~handle) => {
+  let rawParams = JSON.Object(params->Dict.mapValues(s => JSON.String(s)))
+  switch contract.paramsCodec.decode(rawParams) {
+  | Error({path, message}) => errorResponse(~status=400, ~kind="invalid_params", ~message, ~path)
+  | Ok(params) =>
+    switch await readJsonBody(contract, readBody) {
+    | Error(message) => errorResponse(~status=400, ~kind="malformed_json", ~message)
+    | Ok(json) =>
+      switch contract.bodyCodec.decode(json) {
+      | Error({path, message}) => errorResponse(~status=400, ~kind="invalid_body", ~message, ~path)
+      | Ok(body) =>
+        switch await handle({params, body}) {
+        | Ok(response) => {status: 200, body: contract.responseCodec.encode(response)}
+        | Error(error) => applicationErrorResponse(contract, error)
+        }
+      }
+    }
+  }
+}
+
+let run = async (
+  contract: Endpoint.t<'params, 'body, 'response, 'error>,
+  ~params: dict<string>,
+  ~readBody: unit => rawBody,
+  ~handle: input<'params, 'body> => promise<result<'response, 'error>>,
+) =>
+  try await respond(contract, ~params, ~readBody, ~handle) catch {
+  | exn =>
+    // Log the JS Error itself, not ReScript's wrapper, so the stack trace shows.
+    switch exn {
+    | JsExn(e) => Console.error(e)
+    | exn => Console.error(exn)
+    }
+    errorResponse(~status=500, ~kind="internal", ~message="Internal Server Error")
+  }

package/src/Dispatch.resi

@@ -0,0 +1,19 @@
+// The adapter-neutral server pipeline shared by the first-party adapters (@resapi/hono, @resapi/express).
+// Unstable: this is not an extension API for third-party adapters yet, and it may change in any release.
+
+type input<'params, 'body> = {params: 'params, body: 'body}
+
+type response = {status: int, body: JSON.t}
+
+/** The request body, as the adapter has it. `Parsed` is JSON already parsed by framework middleware. */
+type rawBody = Text(promise<string>) | Parsed(JSON.t)
+
+/** `readBody` is called only for POST, after params decode. `handle` must return one of the contract's
+    declared errors. Any exception from a codec, `handle` or reading the body is logged and answered
+    with a 500 that reveals nothing. */
+let run: (
+  Endpoint.t<'params, 'body, 'response, 'error>,
+  ~params: dict<string>,
+  ~readBody: unit => rawBody,
+  ~handle: input<'params, 'body> => promise<result<'response, 'error>>,
+) => promise<response>

package/src/Endpoint.res

@@ -0,0 +1,55 @@
+// A contract describes an endpoint's wire format and is safe to share with clients:
+// it references no server or runtime code. Server adapters turn contracts into routes.
+// Constructors check the route's params against the params codec and throw on a mismatch (RouteCheck).
+
+type method = Get | Post
+
+type noError
+
+type t<'params, 'body, 'response, 'error> = {
+  method: method,
+  path: string,
+  paramsCodec: Codec.t<'params>,
+  bodyCodec: Codec.t<'body>,
+  responseCodec: Codec.t<'response>,
+  errorCodec: Codec.t<'error>,
+  errorStatus: 'error => int,
+}
+
+// Never encodes (no value exists) and never decodes: an error body for such an endpoint is a protocol error.
+let noErrorCodec: Codec.t<noError> = {
+  decode: _ => Error({path: [], message: "This endpoint declares no application errors"}),
+  encode: _ => JSON.Null,
+}
+
+let get = (path, ~params, ~response) => {
+  RouteCheck.assertValid(path, params)
+  {
+    method: Get,
+    path,
+    paramsCodec: params,
+    bodyCodec: Codec.unit,
+    responseCodec: response,
+    errorCodec: noErrorCodec,
+    errorStatus: _ => 500,
+  }
+}
+
+let post = (path, ~params, ~body, ~response) => {
+  RouteCheck.assertValid(path, params)
+  {
+    method: Post,
+    path,
+    paramsCodec: params,
+    bodyCodec: body,
+    responseCodec: response,
+    errorCodec: noErrorCodec,
+    errorStatus: _ => 500,
+  }
+}
+
+let withErrors = (contract: t<'p, 'b, 'r, noError>, errorCodec: Codec.t<'e>, ~status) => {
+  ...contract,
+  errorCodec,
+  errorStatus: status,
+}

package/src/Endpoint.resi

@@ -0,0 +1,34 @@
+// A contract describes an endpoint's wire format and is safe to share with clients: it references no
+// server or runtime code. Server adapters turn contracts into routes.
+
+type method = Get | Post
+
+/** The error type of an endpoint that declares no application errors. It has no values, so a handler
+    for such an endpoint cannot return `Error(_)`. */
+type noError
+
+/** Read-only outside this module: contracts are built with `get`/`post`, which check the route. */
+type t<'params, 'body, 'response, 'error> = private {
+  method: method,
+  path: string,
+  paramsCodec: Codec.t<'params>,
+  bodyCodec: Codec.t<'body>,
+  responseCodec: Codec.t<'response>,
+  errorCodec: Codec.t<'error>,
+  errorStatus: 'error => int,
+}
+
+/** Throws if the route's `:params` don't match the params codec (see `RouteCheck`). Define contracts
+    at module top level, so a mismatch fails at load. */
+let get: (string, ~params: Codec.t<'p>, ~response: Codec.t<'r>) => t<'p, unit, 'r, noError>
+
+/** Throws if the route's `:params` don't match the params codec (see `RouteCheck`). */
+let post: (
+  string,
+  ~params: Codec.t<'p>,
+  ~body: Codec.t<'b>,
+  ~response: Codec.t<'r>,
+) => t<'p, 'b, 'r, noError>
+
+/** Declares the endpoint's application errors and the HTTP status (4xx or 5xx) each one is sent with. */
+let withErrors: (t<'p, 'b, 'r, noError>, Codec.t<'e>, ~status: 'e => int) => t<'p, 'b, 'r, 'e>

package/src/Fetch.res

@@ -0,0 +1,46 @@
+// Fetch API bindings shared by the client and server adapters.
+
+module AbortSignal = {
+  type t
+
+  /** A signal that aborts after the given number of milliseconds. */
+  @scope("AbortSignal") @val external timeout: int => t = "timeout"
+}
+
+module AbortController = {
+  type t
+
+  @new external make: unit => t = "AbortController"
+  @get external signal: t => AbortSignal.t = "signal"
+  @send external abort: t => unit = "abort"
+}
+
+module Request = {
+  type t
+  type init = {method?: string, headers?: dict<string>, body?: string, signal?: AbortSignal.t}
+
+  @new external make: (string, ~init: init=?) => t = "Request"
+}
+
+module Response = {
+  type t
+  type init = {status?: int, headers?: dict<string>}
+
+  @scope("Response") @val external json: (JSON.t, ~init: init=?) => t = "json"
+  @new external text: (string, ~init: init=?) => t = "Response"
+  @get external status: t => int = "status"
+  @get external ok: t => bool = "ok"
+  @send external readText: t => promise<string> = "text"
+
+  type headers
+  @get external headers: t => headers = "headers"
+  @send @return(nullable) external getHeader: (headers, string) => option<string> = "get"
+
+  /** Mutates in place. Throws on immutable responses, such as one returned by `fetch()`. */
+  @send external setHeader: (headers, string, string) => unit = "set"
+  let setHeader = (response, name, value) => {
+    response->headers->setHeader(name, value)
+    response
+  }
+  let header = (response, name) => response->headers->getHeader(name)
+}

package/src/RouteCheck.res

@@ -0,0 +1,83 @@
+// Checks at contract construction that a route's `:params` and its params codec agree. Works with any
+// Codec.t, without metadata: it probes the codec. Decode an object with every route param set to "x",
+// encode the result back, and compare its keys with the route's params.
+//
+// A codec that refines strings (uuid, int parsing) rejects "x" at a field the route does have. That is
+// inconclusive, not a mismatch: CannotValidate. The decode probe still catches a codec field missing
+// from the route when it is the first error reported, but route params the codec ignores go unnoticed.
+
+type outcome = Valid | Invalid(string) | CannotValidate(string)
+
+let paramName = /^:([A-Za-z_][A-Za-z0-9_]*)$/
+let unsupportedChars = /[:*{}?]/
+
+/** The route's param names, or the first segment this checker doesn't understand
+    (Hono wildcards, regex params, optional params). */
+let parse = (path): result<array<string>, string> =>
+  path
+  ->String.split("/")
+  ->Array.reduce(Ok([]), (acc, segment) =>
+    acc->Result.flatMap(names =>
+      switch paramName->RegExp.exec(segment) {
+      | Some(match) =>
+        switch match[1] {
+        | Some(Some(name)) => Ok([...names, name])
+        | _ => Error(segment)
+        }
+      | None => unsupportedChars->RegExp.test(segment) ? Error(segment) : Ok(names)
+      }
+    )
+  )
+
+let keysOf = (json: JSON.t) =>
+  switch json {
+  | Object(d) => d->Dict.keysToArray
+  | _ => []
+  }
+
+let probe = (names, codec: Codec.t<_>) => {
+  let input = JSON.Object(names->Array.map(n => (n, JSON.String("x")))->Dict.fromArray)
+  switch codec.decode(input) {
+  | Error({path, message})
+    if path->Array.get(0)->Option.mapOr(false, field => names->Array.includes(field)) =>
+    CannotValidate(
+      `params codec rejected the probe value at [${path->Array.join(".")}]: ${message}`,
+    )
+  | Error({path, message}) =>
+    Invalid(
+      `params codec rejected {${names->Array.join(", ")}} at [${path->Array.join(
+          ".",
+        )}]: ${message}`,
+    )
+  | Ok(decoded) =>
+    let keys = keysOf(codec.encode(decoded))
+    let missing = names->Array.filter(n => !(keys->Array.includes(n)))
+    let unexpected = keys->Array.filter(k => !(names->Array.includes(k)))
+    missing == [] && unexpected == []
+      ? Valid
+      : Invalid(
+          `codec lacks [${missing->Array.join(", ")}], route lacks [${unexpected->Array.join(
+              ", ",
+            )}]`,
+        )
+  }
+}
+
+let check = (path, codec) =>
+  switch parse(path) {
+  | Error(segment) =>
+    Invalid(
+      `unsupported route syntax in segment "${segment}" (only literal segments and :name params)`,
+    )
+  | Ok(names) =>
+    switch names->Array.find(n => names->Array.indexOf(n) != names->Array.lastIndexOf(n)) {
+    | Some(name) => Invalid(`duplicate route param :${name}`)
+    | None => probe(names, codec)
+    }
+  }
+
+let assertValid = (path, codec) =>
+  switch check(path, codec) {
+  | Invalid(details) => JsError.throwWithMessage(`Invalid route "${path}": ${details}`)
+  | Valid | CannotValidate(_) => ()
+  }

package/src/RouteCheck.resi

@@ -0,0 +1,10 @@
+// Checks at contract construction that a route's `:params` and its params codec agree.
+
+/** `CannotValidate`: the codec rejected the probe value at a real route param, e.g. because it refines
+    strings. Inconclusive, not a mismatch. */
+type outcome = Valid | Invalid(string) | CannotValidate(string)
+
+let check: (string, Codec.t<'p>) => outcome
+
+/** Throws on Invalid, so a bad top-level contract stops the module (and the Worker) from loading. */
+let assertValid: (string, Codec.t<'p>) => unit