@antelopejs/dms-frontend 0.9.3 → 0.10.0

package/templates/vue/server/module-routes.mjs

@@ -2,6 +2,21 @@ import { resolveBackendProxies } from "./backend-proxies.mjs";
 import { compilePathPattern } from "./path-patterns.mjs";
 import { matchPublicEndpoint } from "./public-endpoints.mjs";
 import { ruleRejection } from "./route-rules.mjs";
+import {
+  isBoolean,
+  isFunction,
+  isNonNullObject,
+  isString,
+} from "./type-guards.mjs";
+
+/** @typedef {(message: string) => void} Warn */
+/**
+ * @import {
+ *   AuthProvider, DeclaredModule, ModuleDeclared, RouteRegistration,
+ *   ServerDeclarations, ServerModuleDeclaration, ServerRoute
+ * } from "./module-route-types.mjs"
+ * @import { PublicEndpoint } from "./public-endpoints.mjs"
+ */
 
 const METHODS = new Set([
   "GET",
@@ -29,6 +44,8 @@ const MODULE_API_PREFIX = /^\/api\/_[A-Za-z0-9-]+(?:\/|$)/;
  * Whether `pathname` names one of the files the renderer serves: Vite's URLs,
  * the built assets and the dependencies. No server route is ever there, and a
  * development page requests hundreds of them.
+ *
+ * @param {string} pathname
  */
 export function isRendererFilePath(pathname) {
   return ["/@", "/assets/", "/node_modules/"].some((prefix) =>
@@ -36,20 +53,25 @@ export function isRendererFilePath(pathname) {
   );
 }
 
-/** Whether a module route may serve `pathname`: never the renderer's own. */
+/**
+ * Whether a module route may serve `pathname`: never the renderer's own.
+ *
+ * @param {string} pathname
+ */
 export function mayHaveModuleRoute(pathname) {
   return !RESERVED_PREFIXES.some(
     (prefix) => pathname === prefix.slice(0, -1) || pathname.startsWith(prefix),
   );
 }
 
+/** @param {string} path */
 function normalizedPath(path) {
   return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
 }
 
+/** @param {string} path */
 function pathRejection(path) {
-  if (typeof path !== "string" || !path.startsWith("/"))
-    return "a path starts with /";
+  if (!isString(path) || !path.startsWith("/")) return "a path starts with /";
   const normalized = normalizedPath(path);
   if (!mayHaveModuleRoute(normalized))
     return `${RESERVED_PREFIXES.join(", ")} are the renderer's own paths`;
@@ -71,14 +93,11 @@ function pathRejection(path) {
   return undefined;
 }
 
+/** @param {RouteRegistration["options"]} options */
 function optionsRejection(options) {
   if (options === undefined) return undefined;
-  if (typeof options !== "object" || options === null)
-    return "its options are not an object";
-  if (
-    options.sameOrigin !== undefined &&
-    typeof options.sameOrigin !== "boolean"
-  )
+  if (!isNonNullObject(options)) return "its options are not an object";
+  if (options.sameOrigin !== undefined && !isBoolean(options.sameOrigin))
     return "sameOrigin is not a boolean";
   if (
     options.bodyLimit !== undefined &&
@@ -90,11 +109,14 @@ function optionsRejection(options) {
 
 /**
  * Two declarations of one path whatever their parameters are named share a
- * shape.
+ * path identity.
+ *
+ * @param {string} path
  */
 function compilePath(path) {
   const normalized = normalizedPath(path);
   const segments = normalized === "/" ? [] : normalized.slice(1).split("/");
+  /** @type {string[]} */
   const params = [];
   const pattern = segments
     .map((segment) => {
@@ -106,7 +128,7 @@ function compilePath(path) {
     .join("");
   return {
     path: normalized,
-    shape: segments
+    pathIdentity: segments
       .map((segment) => (PARAM_SEGMENT.test(segment) ? ":" : segment))
       .join("/"),
     params,
@@ -114,8 +136,14 @@ function compilePath(path) {
   };
 }
 
-/** What a module's setup declares, by kind, in declaration order. */
+/**
+ * What a module's setup declares, by kind, in declaration order.
+ *
+ * @param {ServerModuleDeclaration["setup"]} setup
+ * @returns {ModuleDeclared}
+ */
 function collectDeclarations(setup) {
+  /** @type {ModuleDeclared} */
   const declared = { routes: [], auth: [], rules: [], proxies: [] };
   setup({
     registerRoute: (method, path, handler, options) =>
@@ -128,27 +156,37 @@ function collectDeclarations(setup) {
   return declared;
 }
 
+/** @param {unknown} method */
 function methodsOf(method) {
+  /** @type {readonly unknown[]} */
   const methods = Array.isArray(method) ? method : [method];
   return methods.length && methods.every((name) => METHODS.has(name))
     ? methods
     : undefined;
 }
 
+/** @param {RouteRegistration} registration */
 function registrationRejection(registration) {
   if (!methodsOf(registration.method))
     return `the method is not one of ${[...METHODS].join(", ")}`;
-  if (typeof registration.handler !== "function")
-    return "its handler is not a function";
+  if (!isFunction(registration.handler)) return "its handler is not a function";
   return (
     pathRejection(registration.path) ?? optionsRejection(registration.options)
   );
 }
 
+/**
+ * @param {RouteRegistration["method"]} method
+ * @param {string} path
+ */
 function describeRoute(method, path) {
   return `"${[method].flat().join(", ")} ${path}"`;
 }
 
+/**
+ * @param {string} id
+ * @param {ServerRoute} route
+ */
 function backendShadowWarning(id, route) {
   if (
     !BACKEND_PREFIX.test(route.path) ||
@@ -163,6 +201,11 @@ function backendShadowWarning(id, route) {
   );
 }
 
+/**
+ * @param {string} id
+ * @param {ServerRoute} route
+ * @param {PublicEndpoint[]} publicEndpoints
+ */
 function publicEndpointWarning(id, route, publicEndpoints) {
   const sample = route.path.replaceAll(/\/:[^/]+/g, "/x");
   if (!matchPublicEndpoint(route.method, sample, publicEndpoints))
@@ -173,7 +216,12 @@ function publicEndpointWarning(id, route, publicEndpoints) {
   );
 }
 
-/** Runs a module's setup; a setup that throws declares nothing. */
+/**
+ * Runs a module's setup; a setup that throws declares nothing.
+ *
+ * @param {ServerModuleDeclaration} declaration
+ * @param {Warn} warn
+ */
 function declarationsOfModule(declaration, warn) {
   try {
     return collectDeclarations(declaration.setup);
@@ -185,6 +233,11 @@ function declarationsOfModule(declaration, warn) {
   }
 }
 
+/**
+ * @param {DeclaredModule} module
+ * @param {Warn} warn
+ * @returns {ServerRoute[]}
+ */
 function routesOfModule(module, warn) {
   const { id, priority = 0 } = module;
   return module.declared.routes.flatMap((registration, order) => {
@@ -210,6 +263,10 @@ function routesOfModule(module, warn) {
   });
 }
 
+/**
+ * @param {{ id: string, priority?: number }} left
+ * @param {{ id: string, priority?: number }} right
+ */
 function byPriority(left, right) {
   return (
     (right.priority ?? 0) - (left.priority ?? 0) ||
@@ -217,6 +274,10 @@ function byPriority(left, right) {
   );
 }
 
+/**
+ * @param {ServerRoute} kept
+ * @param {ServerRoute} shadowed
+ */
 function shadowWarning(kept, shadowed) {
   const settled =
     kept.priority === shadowed.priority
@@ -228,6 +289,7 @@ function shadowWarning(kept, shadowed) {
   );
 }
 
+/** @param {ServerRoute} route */
 function parameterCount(route) {
   return route.params.length;
 }
@@ -235,10 +297,15 @@ function parameterCount(route) {
 /**
  * Whether one request path can match both routes: as many segments, and at
  * each position the same literal or a parameter on either side.
+ *
+ * @param {ServerRoute} left
+ * @param {ServerRoute} right
  */
 function routesOverlap(left, right) {
-  const leftSegments = left.shape === "" ? [] : left.shape.split("/");
-  const rightSegments = right.shape === "" ? [] : right.shape.split("/");
+  const leftSegments =
+    left.pathIdentity === "" ? [] : left.pathIdentity.split("/");
+  const rightSegments =
+    right.pathIdentity === "" ? [] : right.pathIdentity.split("/");
   return (
     leftSegments.length === rightSegments.length &&
     leftSegments.every(
@@ -250,7 +317,12 @@ function routesOverlap(left, right) {
   );
 }
 
-/** `first` is tried before `second`: it answers what both can match. */
+/**
+ * `first` is tried before `second`: it answers what both can match.
+ *
+ * @param {ServerRoute} first
+ * @param {ServerRoute} second
+ */
 function overlapWarning(first, second) {
   const settled =
     parameterCount(first) < parameterCount(second)
@@ -265,6 +337,7 @@ function overlapWarning(first, second) {
   );
 }
 
+/** @param {ServerRoute} route */
 function rootParameterWarning(route) {
   return (
     `Frontend module ${route.id} serves ${describeRoute(route.method, route.path)}, whose first ` +
@@ -276,10 +349,13 @@ function rootParameterWarning(route) {
 /**
  * Reports what the order of `routes` settles silently: two modules' routes
  * that can match one request, and a route that catches every first segment.
+ *
+ * @param {ServerRoute[]} routes
+ * @param {Warn} warn
  */
 function warnOverlaps(routes, warn) {
   for (const [index, route] of routes.entries()) {
-    if (route.shape.startsWith(":")) warn(rootParameterWarning(route));
+    if (route.pathIdentity.startsWith(":")) warn(rootParameterWarning(route));
     for (const later of routes.slice(index + 1))
       if (
         later.method === route.method &&
@@ -290,11 +366,17 @@ function warnOverlaps(routes, warn) {
   }
 }
 
+/**
+ * @param {DeclaredModule[]} modules
+ * @param {Warn} warn
+ * @param {PublicEndpoint[]} publicEndpoints
+ */
 function resolveRoutes(modules, warn, publicEndpoints) {
+  /** @type {Map<string, ServerRoute>} */
   const kept = new Map();
   for (const module of modules) {
     for (const route of routesOfModule(module, warn)) {
-      const key = `${route.method} ${route.shape}`;
+      const key = `${route.method} ${route.pathIdentity}`;
       const current = kept.get(key);
       if (current) {
         warn(shadowWarning(current, route));
@@ -319,14 +401,15 @@ function resolveRoutes(modules, warn, publicEndpoints) {
 
 const AUTH_HOOKS = ["refreshSession", "publicSession"];
 
+/** @param {unknown} auth */
 function authRejection(auth) {
-  if (typeof auth !== "object" || auth === null) return "it is not an object";
+  if (!isNonNullObject(auth)) return "it is not an object";
   for (const hook of AUTH_HOOKS)
-    if (auth[hook] !== undefined && typeof auth[hook] !== "function")
+    if (auth[hook] !== undefined && !isFunction(auth[hook]))
       return `${hook} is not a function`;
   if (
     auth.signInPath !== undefined &&
-    (typeof auth.signInPath !== "string" ||
+    (!isString(auth.signInPath) ||
       !compilePathPattern(auth.signInPath) ||
       auth.signInPath.includes("*"))
   )
@@ -345,8 +428,12 @@ function authRejection(auth) {
 /**
  * The auth hooks: those of the highest-priority module that registers them.
  * A module registering them twice, or after another one, is reported.
+ *
+ * @param {DeclaredModule[]} modules
+ * @param {Warn} warn
  */
 function resolveAuth(modules, warn) {
+  /** @type {AuthProvider | undefined} */
   let provider;
   for (const module of modules) {
     for (const auth of module.declared.auth) {
@@ -379,12 +466,16 @@ function resolveAuth(modules, warn) {
 /**
  * The route rules: of two declarations of the same pattern, the module of
  * higher priority keeps it, with a warning.
+ *
+ * @param {DeclaredModule[]} modules
+ * @param {Warn} warn
  */
 function resolveRules(modules, warn) {
+  /** @type {Map<string, import("./route-rules.mjs").ResolvedRouteRule>} */
   const kept = new Map();
   for (const module of modules) {
     for (const rules of module.declared.rules) {
-      if (typeof rules !== "object" || rules === null) {
+      if (!isNonNullObject(rules)) {
         warn(
           `Frontend module ${module.id} declares route rules that are ignored: they are not an object.`,
         );
@@ -435,12 +526,13 @@ function resolveRules(modules, warn) {
  * request reaches. Pure: the server hands it the declarations it loaded, and
  * `module-event.mjs` runs the handler a request reaches.
  *
- * @param declarations `{ id, priority, setup }` per module with a dms.server.ts
- * @param warn Reports a declaration problem
- * @param publicEndpoints The deployment's public endpoints (#108), to report a
+ * @param {readonly ServerModuleDeclaration[]} declarations `{ id, priority, setup }` per module with a dms.server.ts
+ * @param {Warn} warn Reports a declaration problem
+ * @param {PublicEndpoint[]} [publicEndpoints] The deployment's public endpoints (#108), to report a
  *   module route answering one
- * @param manifestProxies `{ module, path, auth? }`, the backend proxies the
+ * @param {readonly import("./backend-proxies.mjs").ManifestProxy[]} [manifestProxies] `{ module, path, auth? }`, the backend proxies the
  *   backend modules declare in the manifest
+ * @returns {ServerDeclarations}
  */
 export function resolveServerDeclarations(
   declarations,
@@ -466,7 +558,12 @@ export function resolveServerDeclarations(
   };
 }
 
+/**
+ * @param {ServerRoute} route
+ * @param {RegExpExecArray} match
+ */
 function decodedParams(route, match) {
+  /** @type {Record<string, string>} */
   const params = {};
   for (const [index, name] of route.params.entries()) {
     try {
@@ -483,9 +580,9 @@ function decodedParams(route, match) {
  *
  * A `HEAD` no route declares is the `GET`'s, without its body.
  *
- * @param routes What `resolveServerDeclarations` returned
- * @param method The request's method
- * @param pathname The request's normalized path, without its query string
+ * @param {ServerRoute[]} routes What `resolveServerDeclarations` returned
+ * @param {string} method The request's method
+ * @param {string} pathname The request's normalized path, without its query string
  */
 export function matchModuleRoute(routes, method, pathname) {
   const reached = matchMethod(routes, method, pathname);
@@ -493,6 +590,12 @@ export function matchModuleRoute(routes, method, pathname) {
   return matchMethod(routes, "GET", pathname);
 }
 
+/**
+ * @param {ServerRoute[]} routes
+ * @param {string} method
+ * @param {string} pathname
+ * @returns {{ route: ServerRoute, params: Record<string, string> } | undefined}
+ */
 function matchMethod(routes, method, pathname) {
   for (const route of routes) {
     if (route.method !== method) continue;
@@ -507,8 +610,12 @@ function matchMethod(routes, method, pathname) {
 /**
  * The methods the module routes answer on `pathname`: a path a module route
  * serves is that module's for every method, the others answered `405`.
+ *
+ * @param {ServerRoute[]} routes
+ * @param {string} pathname
  */
 export function moduleRouteMethods(routes, pathname) {
+  /** @type {Set<string>} */
   const methods = new Set();
   for (const route of routes)
     if (route.matcher.test(pathname)) methods.add(route.method);

package/templates/vue/server/module-server.mjs

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import { allowedEstablishEndpoints } from "./auth/establish-endpoints.mjs";
 import { serverAuth } from "./auth-hooks.mjs";
 import { answerModuleRoute } from "./module-event.mjs";
+import { isNonNullObject, isString } from "./type-guards.mjs";
 import {
   matchModuleRoute,
   mayHaveModuleRoute,
@@ -16,7 +17,30 @@ import {
 } from "./public-endpoints.mjs";
 import { reachesBackend } from "./request-routing.mjs";
 
+import { frontendRegistryOf, serverOptionsOf } from "./generated-files.mjs";
 import { publicOptionsOf } from "./public-options.mjs";
+/** @typedef {import("./module-route-types.mjs").ServerModuleDeclaration} ServerModuleDeclaration */
+/**
+ * What a handler of a module reads besides its request.
+ *
+ * @typedef {object} ModuleContext
+ * @property {{ id: string, options: unknown, privateOptions: unknown }} module
+ * @property {{ authEstablishEndpoints: readonly string[] }} app
+ * @property {string | undefined} authOwner The module that owns sign-in
+ */
+/**
+ * A deployment's data, which the server hands to a set of server modules.
+ *
+ * @typedef {object} Deployment
+ * @property {Record<string, unknown>} [publicOptions] Each module's public options by id
+ * @property {Record<string, unknown>} [privateOptions] Each module's private options by id
+ * @property {() => readonly string[]} [authEstablishEndpoints]
+ * @property {import("./public-endpoints.mjs").PublicEndpoint[]} [publicEndpoints]
+ * @property {import("./backend-proxies.mjs").ManifestProxy[]} [backendProxies]
+ * @property {(message: string) => void} warn
+ */
+/** @typedef {ReturnType<typeof createServerModules>} ServerModules */
+
 const WORKSPACE_ROOT = new URL("../", import.meta.url);
 const SOURCE_LOADER = "/server-modules.generated.ts";
 const BUILT_LOADER = new URL(
@@ -32,11 +56,20 @@ const SERVER_OPTIONS_FILE = new URL(
   WORKSPACE_ROOT,
 );
 
+/** @type {Promise<ServerModuleDeclaration[]> | undefined} */
 let builtDeclarations;
+/** @type {ServerModuleDeclaration[]} */
 let lastDeclarations = [];
+/** @type {string | undefined} */
 let lastLoadError;
+/** @type {WeakMap<ServerModuleDeclaration[], ServerModules>} */
 const resolved = new WeakMap();
 
+/**
+ * @param {URL} url
+ * @param {unknown} fallback
+ * @returns {unknown} The file's JSON, the fallback when it cannot be read
+ */
 function readJsonFile(url, fallback) {
   try {
     return JSON.parse(readFileSync(url, "utf8"));
@@ -47,18 +80,29 @@ function readJsonFile(url, fallback) {
 
 const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
-/** The object holding `path`'s last key, when every key up to it is own. */
+/**
+ * The object holding `path`'s last key, when every key up to it is own.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ */
 function holderOf(target, path) {
   let node = target;
   for (const key of path.slice(0, -1)) {
     if (UNSAFE_KEYS.has(key) || !Object.hasOwn(node, key)) return undefined;
     node = node[key];
-    if (typeof node !== "object" || node === null) return undefined;
+    if (!isNonNullObject(node)) return undefined;
   }
   return UNSAFE_KEYS.has(path.at(-1)) ? undefined : node;
 }
 
-/** Sets `value` at `path` when the object holding it exists but lacks it. */
+/**
+ * Sets `value` at `path` when the object holding it exists but lacks it.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ * @param {string} value
+ */
 function fillPath(target, path, value) {
   const holder = holderOf(target, path);
   const key = path.at(-1);
@@ -66,7 +110,13 @@ function fillPath(target, path, value) {
     holder[key] = value;
 }
 
-/** Sets `value` at `path` only where the build left an empty string. */
+/**
+ * Sets `value` at `path` only where the build left an empty string.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string[]} path
+ * @param {string} value
+ */
 function fillEmptied(target, path, value) {
   const holder = holderOf(target, path);
   const key = path.at(-1);
@@ -79,10 +129,10 @@ function fillEmptied(target, path, value) {
  * the environment variable of a secret (`DMS_HTML_RENDER_SECRET`,
  * `DMS_OAUTH_RELAY_SECRET`) only fills in a section that carries none.
  *
- * @param modules The private options by module id, as the manifest published
+ * @param {Record<string, Record<string, unknown>>} modules The private options by module id, as the manifest published
  *   them
- * @param environment The variables by the path of the secret they stand for
- * @param env The process environment
+ * @param {Record<string, string[]>} environment The variables by the path of the secret they stand for
+ * @param {NodeJS.ProcessEnv} env The process environment
  */
 export function privateOptionsWithFallbacks(modules, environment, env) {
   for (const options of Object.values(modules))
@@ -91,10 +141,16 @@ export function privateOptionsWithFallbacks(modules, environment, env) {
   return modules;
 }
 
-/** Each string leaf of `value`, array items included, with its path. */
+/**
+ * Each string leaf of `value`, array items included, with its path.
+ *
+ * @param {unknown} value
+ * @param {string[]} [path]
+ * @returns {Generator<[string[], string]>}
+ */
 function* stringLeaves(value, path = []) {
-  if (typeof value === "string") yield [path, value];
-  else if (typeof value === "object" && value !== null)
+  if (isString(value)) yield [path, value];
+  else if (isNonNullObject(value))
     for (const [key, child] of Object.entries(value))
       yield* stringLeaves(child, [...path, key]);
 }
@@ -107,19 +163,20 @@ function* stringLeaves(value, path = []) {
  * a value the build emptied is filled, array items included: a value the
  * manifest carries wins, and no option or section is added or replaced.
  *
- * @param modules The private options by module id
- * @param json The variable's value; nothing is filled when unset
- * @param warn Reports a value that is not a JSON object, never its content
+ * @param {Record<string, Record<string, unknown>>} modules The private options by module id
+ * @param {string | undefined} json The variable's value; nothing is filled when unset
+ * @param {(message: string) => void} warn Reports a value that is not a JSON object, never its content
  */
 export function privateOptionsFromJson(modules, json, warn) {
   if (!json) return modules;
+  /** @type {unknown} */
   let given;
   try {
     given = JSON.parse(json);
   } catch {
     given = undefined;
   }
-  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+  if (!isNonNullObject(given) || Array.isArray(given)) {
     warn("DMS_PRIVATE_OPTIONS is not a JSON object of options by module id");
     return modules;
   }
@@ -131,10 +188,10 @@ export function privateOptionsFromJson(modules, json, warn) {
   return modules;
 }
 
+/** @param {NodeJS.ProcessEnv} [env] */
 function readPrivateOptions(env = process.env) {
-  const { modules = {}, environment = {} } = readJsonFile(
-    SERVER_OPTIONS_FILE,
-    {},
+  const { modules, environment } = serverOptionsOf(
+    readJsonFile(SERVER_OPTIONS_FILE, {}),
   );
   return privateOptionsFromJson(
     privateOptionsWithFallbacks(modules, environment, env),
@@ -144,14 +201,22 @@ function readPrivateOptions(env = process.env) {
 }
 
 function readPublicOptions() {
-  return publicOptionsOf(readJsonFile(REGISTRY_FILE, { modules: [] }));
+  return publicOptionsOf(
+    frontendRegistryOf(readJsonFile(REGISTRY_FILE, { modules: [] })),
+  );
 }
 
+/**
+ * @param {import("vite").ViteDevServer | undefined} devServer
+ * @returns {Promise<ServerModuleDeclaration[]>}
+ */
 async function loadDeclarations(devServer) {
   if (devServer)
+    // oxlint-disable-next-line typescript/no-unsafe-return -- `ssrLoadModule` types every module `Record<string, any>`; the loader is the generated `server-modules.generated.ts`, which exports `serverModules`.
     return (await devServer.ssrLoadModule(SOURCE_LOADER)).serverModules;
   if (!existsSync(fileURLToPath(BUILT_LOADER))) return [];
   builtDeclarations ??= import(BUILT_LOADER.href).then(
+    // oxlint-disable-next-line typescript/no-unsafe-return -- the build of that same generated module is imported by a URL computed at run time, so it is untyped.
     (loaded) => loaded.serverModules,
   );
   return builtDeclarations;
@@ -161,6 +226,8 @@ async function loadDeclarations(devServer) {
  * The declarations to serve. A module entry that fails to load in development
  * (a syntax error being typed) is reported once, and the last routes that
  * loaded keep answering meanwhile.
+ *
+ * @param {import("vite").ViteDevServer | undefined} devServer
  */
 async function currentDeclarations(devServer) {
   try {
@@ -181,8 +248,8 @@ async function currentDeclarations(devServer) {
  *
  * `authOwner` is the module whose sealed cookies are the `dms_*` ones.
  *
- * @param declarations `{ id, priority, setup }` per module with a dms.server.ts
- * @param deployment `{ publicOptions, privateOptions, authEstablishEndpoints,
+ * @param {readonly ServerModuleDeclaration[]} declarations `{ id, priority, setup }` per module with a dms.server.ts
+ * @param {Deployment} deployment `{ publicOptions, privateOptions, authEstablishEndpoints,
  *   publicEndpoints, backendProxies, warn }`: each module's options by id,
  *   the session-opening endpoints as a function (the environment can change
  *   them), the public endpoints, the backend proxies the manifest declares
@@ -198,7 +265,7 @@ export function createServerModules(declarations, deployment) {
     deployment.publicEndpoints ?? [],
     deployment.backendProxies ?? [],
   );
-  const context = (id) => ({
+  const context = (/** @type {string} */ id) => ({
     module: {
       id,
       options: deployment.publicOptions?.[id],
@@ -216,7 +283,11 @@ export function createServerModules(declarations, deployment) {
   };
 }
 
-/** Resolved once per set of declarations: in development, once per edit. */
+/**
+ * Resolved once per set of declarations: in development, once per edit.
+ *
+ * @param {ServerModuleDeclaration[]} declarations
+ */
 function serverModules(declarations) {
   let modules = resolved.get(declarations);
   if (!modules) {
@@ -245,7 +316,7 @@ function serverModules(declarations) {
  * next request; in production from the bundle `ajs dms build` makes
  * (`dist/server-modules`). A workspace built before the feature has none.
  *
- * @param devServer Vite in development, `undefined` in production
+ * @param {import("vite").ViteDevServer | undefined} devServer Vite in development, `undefined` in production
  */
 export async function loadServerModules(devServer) {
   return serverModules(await currentDeclarations(devServer));
@@ -256,10 +327,10 @@ export async function loadServerModules(devServer) {
  * module route serves is the module's for every method: another method is
  * answered `405`.
  *
- * @param request The Node request
- * @param response The Node response
- * @param pathname The request's normalized path
- * @param modules What `loadServerModules` or `createServerModules` returned
+ * @param {import("node:http").IncomingMessage} request The Node request
+ * @param {import("node:http").ServerResponse} response The Node response
+ * @param {string} pathname The request's normalized path
+ * @param {ServerModules} modules What `loadServerModules` or `createServerModules` returned
  * @returns Whether a module route answered
  */
 export async function handleModuleRoute(request, response, pathname, modules) {