@antelopejs/dms-frontend 0.9.3 → 0.10.1

package/templates/vue/server/inertia.mjs

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { isObjectLike, isString } from "./type-guards.mjs";
 
 const CLIENT_MANIFEST_PATH = fileURLToPath(
   new URL("../dist/client/.vite/manifest.json", import.meta.url),
 );
+/** @type {string | undefined} */
 let productionAssetVersion;
 
 /**
@@ -27,6 +29,10 @@ export function assetVersion() {
   return productionAssetVersion;
 }
 
+/**
+ * @param {InertiaPage} page
+ * @returns {string}
+ */
 export function inertiaAppHtml(page) {
   const serialized = JSON.stringify(page).replaceAll("/", "\\/");
   return `<script data-page="app" type="application/json">${serialized}</script><div id="app"></div>`;
@@ -35,12 +41,51 @@ export function inertiaAppHtml(page) {
 /** The one Inertia component every DMS page renders through. */
 export const DMS_PAGE_COMPONENT = "DmsDynamicPage";
 
+/**
+ * The once props a page declares, by key: the prop each stands for, and when
+ * the browser's copy expires (`null`: never).
+ *
+ * @typedef {Record<string, { prop: string, expiresAt: number | null }>} OnceProps
+ */
+
+/**
+ * The Inertia page object of a visit.
+ *
+ * @typedef {{
+ *   component: string,
+ *   props: Record<string, unknown>,
+ *   url: string,
+ *   version: string,
+ *   onceProps?: OnceProps
+ * }} InertiaPage
+ */
+
+/**
+ * Whether the page has the props the server render needs: the path and the
+ * page the backend described. A full visit carries both; the page payload is
+ * the backend's JSON, read as the renderer reads it.
+ *
+ * @param {InertiaPage} page
+ * @returns {page is InertiaPage & import("../ssr-renderer.ts").DmsSsrPage}
+ */
+export function isSsrPage(page) {
+  return isString(page.props.path) && isObjectLike(page.props.page);
+}
+
+/**
+ * @param {string} url
+ * @param {Record<string, unknown> | undefined} props
+ * @param {string} [version]
+ * @param {OnceProps} [onceProps]
+ * @returns {InertiaPage}
+ */
 export function createInertiaPage(
   url,
   props,
   version = assetVersion(),
   onceProps,
 ) {
+  /** @type {InertiaPage} */
   const page = {
     component: DMS_PAGE_COMPONENT,
     props: { ...props, errors: props?.errors ?? {} },
@@ -51,6 +96,11 @@ export function createInertiaPage(
   return page;
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string} name
+ * @returns {string[]}
+ */
 function headerList(request, name) {
   return String(request.headers[name] ?? "")
     .split(",")
@@ -63,6 +113,9 @@ function headerList(request, name) {
  * A partial reload (`router.reload({ only, except })`) of the page on screen
  * names them: a nested path selects its top-level prop, which is sent whole,
  * and only a top-level name excludes one.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {{ partial: boolean, wants: (prop: string) => boolean }}
  */
 export function requestedProps(request) {
   const partial =
@@ -81,11 +134,16 @@ export function requestedProps(request) {
   };
 }
 
-/** The once props the browser already holds, unexpired, by key. */
+/**
+ * The once props the browser already holds, unexpired, by key.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ */
 export function heldOnceProps(request) {
   return new Set(headerList(request, "x-inertia-except-once-props"));
 }
 
+/** @param {string} [version] */
 export function inertiaHeaders(version = assetVersion()) {
   return {
     "cache-control": PRIVATE_CACHE_CONTROL,
@@ -105,6 +163,11 @@ export function htmlHeaders() {
   };
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @returns {boolean}
+ */
 export function handleAssetVersionMismatch(request, response) {
   if (
     !request.headers["x-inertia"] ||
@@ -121,15 +184,25 @@ export function handleAssetVersionMismatch(request, response) {
   return true;
 }
 
-/** A page visit: a document or Inertia request, as opposed to an API call. */
+/**
+ * A page visit: a document or Inertia request, as opposed to an API call.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {boolean}
+ */
 export function isFrontendVisit(request) {
   if (request.method !== "GET") return false;
   return (
     Boolean(request.headers["x-inertia"]) ||
-    request.headers.accept?.includes("text/html")
+    request.headers.accept?.includes("text/html") === true
   );
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} location
+ */
 export function redirectFrontendVisit(request, response, location) {
   const vary = { vary: "X-Inertia" };
   if (!request.headers["x-inertia"]) {

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

@@ -23,14 +23,42 @@ import {
   relayedLocation,
 } from "./proxy-redirects.mjs";
 import { backendUrl } from "./request-target.mjs";
+import {
+  isFunction,
+  isNumber,
+  isObjectLike,
+  isRecord,
+  isString,
+} from "./type-guards.mjs";
 import { pipeWebBody } from "./web-body.mjs";
 
+/** @typedef {import("node:http").IncomingMessage} IncomingMessage */
+/** @typedef {import("./request-target.mjs").ServerRequest} ServerRequest */
+/** @typedef {import("node:http").ServerResponse} ServerResponse */
+/** @typedef {import("../server-module.ts").DmsServerEvent} ServerEvent */
+/** @typedef {import("../server-module.ts").DmsSession} Session */
+/** @typedef {(session: Session | undefined) => import("../server-module.ts").DmsPublicSession} SessionView */
+/**
+ * What an event is made from.
+ *
+ * @typedef {object} EventContext
+ * @property {ServerRequest} request
+ * @property {ServerResponse} response
+ * @property {Pick<import("./module-route-types.mjs").ServerRoute, "bodyLimit">} route
+ * @property {Readonly<Record<string, string>>} params
+ * @property {{ id: string, options?: unknown, privateOptions?: unknown }} module
+ * @property {{ authEstablishEndpoints?: readonly string[] }} [app]
+ * @property {SessionView} [view] What a session shows a page
+ * @property {string} [authOwner] The module that owns sign-in
+ */
+
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
 const COOKIE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 /** The sealed cookies of the module that owns sign-in: session, accounts, flows. */
 const RESERVED_COOKIE_PREFIX = "dms_";
 const BODY_TOO_LARGE = "Request body too large";
 
+/** @param {IncomingMessage} request */
 function requestOrigin(request) {
   const host = request.headers.host;
   try {
@@ -40,6 +68,7 @@ function requestOrigin(request) {
   }
 }
 
+/** @param {IncomingMessage} request */
 function requestHeaders(request) {
   const headers = new Headers();
   for (const [name, value] of Object.entries(request.headers)) {
@@ -49,12 +78,17 @@ function requestHeaders(request) {
   return headers;
 }
 
-/** The request body as a Web stream that errors past `limit` bytes. */
+/**
+ * The request body as a Web stream that errors past `limit` bytes.
+ *
+ * @param {IncomingMessage} request
+ * @param {number} limit
+ */
 function limitedBody(request, limit) {
   let size = 0;
   return Readable.toWeb(request).pipeThrough(
     new TransformStream({
-      transform(chunk, controller) {
+      transform(/** @type {Uint8Array} */ chunk, controller) {
         size += chunk.byteLength;
         if (size > limit)
           controller.error(new RequestBodyError(413, BODY_TOO_LARGE));
@@ -64,6 +98,10 @@ function limitedBody(request, limit) {
   );
 }
 
+/**
+ * @param {ServerRequest} request
+ * @param {EventContext["route"]} route
+ */
 function webRequest(request, route) {
   const url = new URL(request.url, requestOrigin(request));
   const hasBody = !["GET", "HEAD"].includes(request.method);
@@ -78,14 +116,23 @@ function webRequest(request, route) {
   });
 }
 
+/**
+ * @param {Request} webRequestValue
+ * @returns {Promise<unknown>}
+ */
 async function readJson(webRequestValue) {
   if (!webRequestValue.body) return {};
+  /** @type {Uint8Array[]} */
   const chunks = [];
   const reader = webRequestValue.body.getReader();
   for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
+    const read = await reader.read();
+    if (read.done) break;
+    /** @type {unknown} */
+    const chunk = read.value;
+    if (!(chunk instanceof Uint8Array))
+      throw new RequestBodyError(400, "Invalid request body");
+    chunks.push(chunk);
   }
   if (!chunks.length) return {};
   try {
@@ -95,8 +142,9 @@ async function readJson(webRequestValue) {
   }
 }
 
+/** @param {unknown} name */
 function checkedCookieName(name) {
-  if (typeof name !== "string" || !COOKIE_NAME.test(name))
+  if (!isString(name) || !COOKIE_NAME.test(name))
     throw new Error(`Invalid cookie name: ${String(name)}`);
   if (name === SESSION_COOKIE)
     throw new Error(
@@ -105,6 +153,12 @@ function checkedCookieName(name) {
   return name;
 }
 
+/**
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {SessionView | undefined} view
+ * @returns {ServerEvent["session"]}
+ */
 function sessionAccess(request, response, view) {
   return {
     read: () => readSession(request),
@@ -124,6 +178,10 @@ function sessionAccess(request, response, view) {
  * module's are prefixed with its id and a dot, which no name of the owner's
  * holds, so no module reads or overwrites another's, nor the owner's session
  * and account cookies.
+ *
+ * @param {unknown} name
+ * @param {string} moduleId
+ * @param {string | undefined} authOwner
  */
 function moduleCookieName(name, moduleId, authOwner) {
   const checked = checkedCookieName(name);
@@ -131,15 +189,26 @@ function moduleCookieName(name, moduleId, authOwner) {
   if (checked.startsWith(RESERVED_COOKIE_PREFIX))
     throw new Error(
       `The ${RESERVED_COOKIE_PREFIX}* cookies belong to the module that owns sign-in` +
-        `${authOwner ? ` (${authOwner})` : ""}: choose another name than ${name}`,
+        `${authOwner ? ` (${authOwner})` : ""}: choose another name than ${checked}`,
     );
   return `${String(moduleId).replaceAll(/[^A-Za-z0-9_-]/g, "-")}.${checked}`;
 }
 
+/**
+ * @param {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {string} moduleId
+ * @param {string | undefined} authOwner
+ * @returns {ServerEvent["cookies"]}
+ */
 function cookieAccess(request, response, moduleId, authOwner) {
-  const named = (name) => moduleCookieName(name, moduleId, authOwner);
+  const named = (/** @type {unknown} */ name) =>
+    moduleCookieName(name, moduleId, authOwner);
   return {
-    readSealed: (name) => readSealedCookie(request, named(name)),
+    readSealed: (name, accepts) => {
+      const value = readSealedCookie(request, named(name));
+      return value !== undefined && accepts(value) ? value : undefined;
+    },
     writeSealed: (name, value, options = {}) =>
       writeSealedCookie(
         response,
@@ -153,6 +222,7 @@ function cookieAccess(request, response, moduleId, authOwner) {
   };
 }
 
+/** @param {unknown} value */
 function frozenCopy(value) {
   return Object.freeze(structuredClone(value ?? {}));
 }
@@ -165,15 +235,24 @@ function frozenCopy(value) {
  * the defaults every route gets once (same-origin on unsafe methods, a body
  * limit, `no-store`). See `server-module.ts` for the types a module reads.
  *
- * @param context `{ request, response, route, params, module, app, view,
+ * @param {EventContext} context `{ request, response, route, params, module, app, view,
  *   authOwner }`, where `module` is `{ id, options, privateOptions }`, `app`
  *   the deployment's read-only data, `view` what a session shows a page and
  *   `authOwner` the id of the module that owns sign-in
+ * @returns {ServerEvent}
  */
 export function createServerEvent(context) {
   const { request, response, route, params } = context;
-  const event = {
-    request: webRequest(request, route),
+  const webRequestValue = webRequest(request, route);
+  // SAFETY: `server-module.ts` lets a handler name the JSON shape it expects from the backend and from the client, as `Response.json()` does; the server parses that JSON and hands it on unchecked, which these two members are the only place to state.
+  const parsedJson = /** @type {Pick<ServerEvent, "backend" | "readJson">} */ ({
+    backend: (/** @type {string} */ path, init = {}) =>
+      backend(path, request, init),
+    readJson: () => readJson(webRequestValue),
+  });
+  return {
+    ...parsedJson,
+    request: webRequestValue,
     params: Object.freeze({ ...params }),
     session: sessionAccess(request, response, context.view),
     cookies: cookieAccess(
@@ -182,40 +261,48 @@ export function createServerEvent(context) {
       context.module.id,
       context.authOwner,
     ),
-    backend: (path, init = {}) => backend(path, request, init),
-    backendUrl: (path) => backendUrl(path),
+    backendUrl: (/** @type {string} */ path) => backendUrl(path),
     clientIp: () => clientIp(request),
     module: Object.freeze({
       id: context.module.id,
       options: frozenCopy(context.module.options),
       privateOptions: frozenCopy(context.module.privateOptions),
     }),
-    renderEmail: (template, props, options = {}) =>
-      renderEmailTemplate(template, props, options),
+    renderEmail: (
+      /** @type {string} */ template,
+      /** @type {Record<string, unknown>} */ props,
+      options = {},
+    ) => renderEmailTemplate(template, props, options),
     app: Object.freeze({
       authEstablishEndpoints: Object.freeze([
         ...(context.app?.authEstablishEndpoints ?? []),
       ]),
     }),
+    url: new URL(webRequestValue.url),
   };
-  event.url = new URL(event.request.url);
-  event.readJson = () => readJson(event.request);
-  return event;
 }
 
+/** @param {unknown} value */
 function isResponse(value) {
   return (
     value instanceof Response ||
-    (typeof value === "object" &&
-      value !== null &&
-      typeof value.status === "number" &&
-      typeof value.headers?.get === "function" &&
+    (isRecord(value) &&
+      isNumber(value.status) &&
+      isObjectLike(value.headers) &&
+      isFunction(value.headers.get) &&
       "body" in value)
   );
 }
 
+/**
+ * @param {any} result What a handler answered: any value, of which only
+ *   `isResponse` looks
+ * @returns {Response}
+ */
 function asResponse(result) {
-  if (isResponse(result)) return result;
+  if (isResponse(result))
+    // oxlint-disable-next-line typescript/no-unsafe-return -- `isResponse` also accepts a `Response` of another realm by its members (`status`, `headers.get`, `body`), so it cannot be a `value is Response` predicate without claiming members it does not check.
+    return result;
   if (result === undefined || result === null)
     return new Response(null, { status: 204 });
   return Response.json(result);
@@ -227,11 +314,17 @@ function asResponse(result) {
  * answer the handler relays goes out as the proxy relays one: its `Location`
  * on the frontend's origin when the frontend proxies its path, no cookie of
  * another site its fetch reached.
+ *
+ * @param {ServerRequest} request
+ * @param {ServerResponse} response
+ * @param {unknown} result
+ * @param {(path: string) => boolean} isProxiedPath
  */
 async function writeServerResponse(request, response, result, isProxiedPath) {
   const answer = asResponse(result);
   const cookies = [response.getHeader("set-cookie") ?? []]
     .flat()
+    .map(String)
     .concat(relayableCookies(answer));
   answer.headers.forEach((value, name) => {
     if (name === "set-cookie") return;
@@ -261,7 +354,7 @@ async function writeServerResponse(request, response, result, isProxiedPath) {
  * through reaches the server's error handling with the cookies written so
  * far.
  *
- * @param context See `createServerEvent`, plus `isProxiedPath(pathname)`:
+ * @param {Omit<EventContext, "route"> & { route: import("./module-route-types.mjs").ServerRoute, isProxiedPath: (path: string) => boolean }} context See `createServerEvent`, plus `isProxiedPath(pathname)`:
  *   whether the frontend sends that path to the backend
  */
 export async function answerModuleRoute(context) {

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

@@ -0,0 +1,78 @@
+export {};
+
+/** @typedef {import("../server-module.ts").DmsServerMethod} ServerMethod */
+/**
+ * What `registerAuth` declared. The server binds each hook to the declared
+ * object, so a hook may use `this`.
+ *
+ * @typedef {object} AuthDeclaration
+ * @property {string} [signInPath]
+ * @property {readonly string[]} [signInExempt]
+ * @property {(event: import("../server-module.ts").DmsServerEvent, session: import("../server-module.ts").DmsSession) => Promise<import("../server-module.ts").DmsSession | undefined>} [refreshSession]
+ * @property {(session: import("../server-module.ts").DmsSession) => import("../server-module.ts").DmsPublicSession} [publicSession]
+ */
+/** @typedef {import("../server-module.ts").DmsRouteRule} RouteRule */
+/**
+ * A module that has a `dms.server.ts`.
+ *
+ * @typedef {object} ServerModuleDeclaration
+ * @property {string} id
+ * @property {number} [priority]
+ * @property {import("../server-module.ts").DmsServerSetup} setup
+ */
+/**
+ * One `registerRoute` call.
+ *
+ * @typedef {object} RouteRegistration
+ * @property {ServerMethod | readonly ServerMethod[]} method
+ * @property {string} path
+ * @property {import("../server-module.ts").DmsServerHandler} handler
+ * @property {import("../server-module.ts").DmsServerRouteOptions} [options]
+ */
+/**
+ * What a module's setup declared, by kind, in declaration order.
+ *
+ * @typedef {object} ModuleDeclared
+ * @property {RouteRegistration[]} routes
+ * @property {AuthDeclaration[]} auth
+ * @property {Readonly<Record<string, RouteRule>>[]} rules
+ * @property {{ pattern: string, options?: import("./backend-proxies.mjs").ProxyOptions }[]} proxies
+ */
+/** @typedef {ServerModuleDeclaration & { declared: ModuleDeclared }} DeclaredModule */
+/**
+ * A route a module serves, one per method.
+ *
+ * @typedef {object} ServerRoute
+ * @property {string} path The normalized path
+ * @property {string} pathIdentity The path with its parameters made anonymous
+ * @property {string[]} params The parameter names, in path order
+ * @property {RegExp} matcher
+ * @property {string} id The serving module
+ * @property {number} priority
+ * @property {number} order The declaration's rank in its module
+ * @property {string} method
+ * @property {import("../server-module.ts").DmsServerHandler} handler
+ * @property {boolean} sameOrigin
+ * @property {number} bodyLimit
+ * @property {boolean} overridesBackend
+ */
+/**
+ * The auth hooks of the module that provides them.
+ *
+ * @typedef {object} AuthProvider
+ * @property {string} id
+ * @property {number} priority
+ * @property {string} [signInPath]
+ * @property {import("./path-patterns.mjs").CompiledPathPattern[]} [signInExempt]
+ * @property {AuthDeclaration["refreshSession"]} refreshSession
+ * @property {AuthDeclaration["publicSession"]} publicSession
+ */
+/**
+ * What the modules declared, ready to serve.
+ *
+ * @typedef {object} ServerDeclarations
+ * @property {ServerRoute[]} routes
+ * @property {AuthProvider | undefined} auth
+ * @property {import("./route-rules.mjs").ResolvedRouteRule[]} rules
+ * @property {import("./backend-proxies.mjs").BackendProxy[]} proxies
+ */