@antelopejs/dms-frontend 0.9.2 → 0.10.0

package/templates/vue/server/icons.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { getIcons } from "@iconify/utils";
 import { ICON_API_PATH } from "../icon-api.mjs";
 import { writeContent } from "./content.mjs";
+import { iconCollectionOf } from "./generated-files.mjs";
 
 const WORKSPACE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const JSON_TYPE = "application/json";
@@ -24,14 +25,39 @@ const COLLECTION_PACKAGES = join("node_modules", "@iconify-json");
 const ICON_CACHE_CONTROL =
   "public, max-age=604800, stale-while-revalidate=86400";
 const ERROR_CACHE_CONTROL = "no-store";
+
+/**
+ * An Iconify icon collection: the JSON file of an `@iconify-json/<prefix>`
+ * package.
+ *
+ * @typedef {import("./generated-files.mjs").IconCollection} IconCollection
+ */
+
+/**
+ * The answer to an icon query, to send.
+ *
+ * @typedef {{
+ *   status: number,
+ *   headers: Record<string, string>,
+ *   body: string
+ * }} IconAnswer
+ */
+
+/** @type {Map<string, Promise<IconCollection | undefined>>} */
 const collections = new Map();
 /**
  * Kept by renderer module: a development server evaluates a new one after a
  * layer changes, and each must find the collections loaded before it
  * renders.
+ *
+ * @type {WeakMap<typeof import("../ssr-renderer.ts"), Promise<void>>}
  */
 const rendererCollections = new WeakMap();
 
+/**
+ * @param {string} prefix
+ * @returns {string[]}
+ */
 function collectionSpecifiers(prefix) {
   return [
     `@iconify-json/${prefix}/icons.json`,
@@ -42,6 +68,10 @@ function collectionSpecifiers(prefix) {
 /**
  * The file of an icon collection from the first source installed under its
  * name; a source not installed is skipped and the next one tried.
+ *
+ * @param {string} root
+ * @param {string} prefix
+ * @returns {string | undefined}
  */
 function resolveCollectionFile(root, prefix) {
   const require = createRequire(join(root, "package.json"));
@@ -53,15 +83,24 @@ function resolveCollectionFile(root, prefix) {
   return undefined;
 }
 
+/**
+ * @param {string} root
+ * @param {string} prefix
+ * @returns {Promise<IconCollection | undefined>}
+ */
 async function loadCollection(root, prefix) {
   const file = resolveCollectionFile(root, prefix);
   if (!file) return undefined;
-  return JSON.parse(await readFile(file, "utf8"));
+  return iconCollectionOf(JSON.parse(await readFile(file, "utf8")));
 }
 
 /**
  * Parsed once per collection: a collection file is several megabytes, and
  * one page asks for icons of the same few collections many times.
+ *
+ * @param {string} root
+ * @param {string} prefix
+ * @returns {Promise<IconCollection | undefined>}
  */
 function collection(root, prefix) {
   const key = join(root, prefix);
@@ -77,6 +116,8 @@ function collection(root, prefix) {
  * Every `@iconify-json/<prefix>` collection installed in the workspace under
  * `root`, the ones the server render draws from. The workspace hoists every
  * dependency, a module's collections included.
+ *
+ * @param {string} root
  */
 export async function installedCollections(root) {
   const prefixes = await readdir(join(root, COLLECTION_PACKAGES)).catch(
@@ -94,6 +135,9 @@ export async function installedCollections(root) {
  * Hand a server renderer the installed collections, once per renderer module,
  * before its first render. A collection that fails to load leaves the render
  * with the bundled icons only.
+ *
+ * @param {typeof import("../ssr-renderer.ts")} renderer
+ * @param {string} [root]
  */
 export function provideIconCollections(renderer, root = WORKSPACE_ROOT) {
   if (!rendererCollections.has(renderer))
@@ -101,16 +145,23 @@ export function provideIconCollections(renderer, root = WORKSPACE_ROOT) {
       renderer,
       installedCollections(root)
         .then((loaded) => renderer.registerDmsIconCollections(loaded))
-        .catch((error) =>
-          console.error(
-            "DMS icon collections not loaded; server renders draw bundled icons only",
-            error,
-          ),
+        .catch(
+          /** @param {unknown} error */ (error) =>
+            console.error(
+              "DMS icon collections not loaded; server renders draw bundled icons only",
+              error,
+            ),
         ),
     );
   return rendererCollections.get(renderer);
 }
 
+/**
+ * @param {number} status
+ * @param {string} cacheControl
+ * @param {IconCollection | null | { message: string }} payload
+ * @returns {IconAnswer}
+ */
 function jsonResponse(status, cacheControl, payload) {
   return {
     status,
@@ -119,10 +170,19 @@ function jsonResponse(status, cacheControl, payload) {
   };
 }
 
+/**
+ * @param {number} status
+ * @param {string} message
+ * @returns {IconAnswer}
+ */
 function errorResponse(status, message) {
   return jsonResponse(status, ERROR_CACHE_CONTROL, { message });
 }
 
+/**
+ * @param {URL} url
+ * @returns {string[] | undefined}
+ */
 function requestedIcons(url) {
   const names = (url.searchParams.get("icons") ?? "")
     .split(ICON_NAME_SEPARATOR)
@@ -132,7 +192,12 @@ function requestedIcons(url) {
   return [...new Set(names)];
 }
 
-/** Whether the generated server answers `pathname` with `iconResponse`. */
+/**
+ * Whether the generated server answers `pathname` with `iconResponse`.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
 export function isIconRequest(pathname) {
   return pathname.startsWith(ICON_API_PATH);
 }
@@ -142,6 +207,11 @@ export function isIconRequest(pathname) {
  * `root`: the subset of `@iconify-json/<prefix>` (or `@iconify/json`) holding
  * the requested icons, and a `not_found` list for the others, as
  * `api.iconify.design` does. Returns the status, headers and body to send.
+ *
+ * @param {string} root
+ * @param {string | undefined} method
+ * @param {URL} url
+ * @returns {Promise<IconAnswer>}
  */
 export async function iconResponse(root, method, url) {
   if (!READ_METHODS.has(method)) {
@@ -163,6 +233,9 @@ export async function iconResponse(root, method, url) {
 /**
  * Serve an Iconify API query from the collections installed in the workspace,
  * the same way under `ajs dms dev` and `ajs dms start`: both run this server.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
  */
 export async function handleIcons(request, response) {
   const url = new URL(request.url, "http://frontend.local");

package/templates/vue/server/in-place-render.mjs

@@ -9,6 +9,11 @@ const IN_PLACE_RENDERS = 2;
 /**
  * The key of a backend read a later render of the same request may reuse: a
  * plain JSON `GET`, without hooks that would expect to see the response.
+ *
+ * @param {string} path
+ * @param {import("ofetch").FetchOptions} options
+ * @param {Headers} headers
+ * @returns {string | undefined}
  */
 function reusableReadKey(path, options, headers) {
   const method = (options.method ?? "GET").toUpperCase();
@@ -23,6 +28,13 @@ function reusableReadKey(path, options, headers) {
   ]);
 }
 
+/**
+ * The reads of a request's server renders, with the switch that lets a later
+ * render reuse the completed ones.
+ *
+ * @typedef {((path: string, options?: import("ofetch").FetchOptions) => Promise<unknown>) & { reuseCompletedReads: () => void }} ServerReads
+ */
+
 /**
  * The backend reads of a request's server renders, sent with the request's
  * `backendHeaders()` and the read's own. After `reuseCompletedReads()`, a later
@@ -31,10 +43,18 @@ function reusableReadKey(path, options, headers) {
  *
  * A read returns a copy: the render that read it may still change the object it
  * got. A body that cannot be copied is read again.
+ *
+ * @param {() => HeadersInit} backendHeaders
+ * @returns {ServerReads}
  */
 export function serverReads(backendHeaders) {
+  /** @type {Map<string, unknown>} */
   const completed = new Map();
   let reuse = false;
+  /**
+   * @param {string} path
+   * @param {import("ofetch").FetchOptions} [options]
+   */
   const read = (path, options = {}) => {
     const headers = new Headers(backendHeaders());
     new Headers(options.headers).forEach((value, name) => {
@@ -43,6 +63,7 @@ export function serverReads(backendHeaders) {
     const key = reusableReadKey(path, options, headers);
     if (reuse && key && completed.has(key))
       return Promise.resolve(structuredClone(completed.get(key)));
+    /** @type {Promise<unknown>} */
     const reading = ofetch(path, {
       ...options,
       baseURL: process.env.DMS_API_BASE_URL,
@@ -67,6 +88,11 @@ export function serverReads(backendHeaders) {
  * Whether a document request renders `location` in place of redirecting to
  * it: a `GET` whose page only completes its query (`?workspace=`), on the
  * same path. Any other redirect keeps its own response.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string | undefined} from
+ * @param {string} location
+ * @returns {boolean}
  */
 function rendersInPlace(request, from, location) {
   if (request.method !== "GET" || location.includes("#")) return false;
@@ -87,6 +113,15 @@ function rendersInPlace(request, from, location) {
  *
  * A page that completes its query as it renders is rendered at that query in
  * the same request, rather than answered with a redirect.
+ *
+ * @template {{ url: string | undefined, props: unknown }} Page
+ * @template {{ redirect?: string }} Rendered
+ * @param {import("node:http").IncomingMessage} request
+ * @param {Page} page
+ * @param {ServerReads} fetch
+ * @param {(page: Page) => Promise<Rendered>} render
+ * @param {(props: Page["props"], url: URL) => Promise<Page["props"]>} propsAt
+ * @returns {Promise<{ rendered: Rendered, served: Page }>}
  */
 export async function renderInPlace(request, page, fetch, render, propsAt) {
   let rendered = await render(page);

package/templates/vue/server/inertia.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 const CLIENT_MANIFEST_PATH = fileURLToPath(
   new URL("../dist/client/.vite/manifest.json", import.meta.url),
 );
+/** @type {string | undefined} */
 let productionAssetVersion;
 
 /**
@@ -27,6 +28,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,6 +40,32 @@ 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 | undefined,
+ *   version: string,
+ *   onceProps?: OnceProps
+ * }} InertiaPage
+ */
+
+/**
+ * @param {string | undefined} url
+ * @param {Record<string, unknown> | undefined} props
+ * @param {string} [version]
+ * @param {OnceProps} [onceProps]
+ * @returns {InertiaPage}
+ */
 export function createInertiaPage(
   url,
   props,
@@ -51,6 +82,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 +99,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 +120,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 +149,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,7 +170,12 @@ 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 (
@@ -130,6 +184,11 @@ export function isFrontendVisit(request) {
   );
 }
 
+/**
+ * @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,40 @@ import {
   relayedLocation,
 } from "./proxy-redirects.mjs";
 import { backendUrl } from "./request-target.mjs";
+import {
+  isFunction,
+  isNonNullObject,
+  isNumber,
+  isString,
+} from "./type-guards.mjs";
 import { pipeWebBody } from "./web-body.mjs";
 
+/** @typedef {import("node:http").IncomingMessage} IncomingMessage */
+/** @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 {IncomingMessage} 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 +66,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 +76,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 +96,10 @@ function limitedBody(request, limit) {
   );
 }
 
+/**
+ * @param {IncomingMessage} 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,8 +114,13 @@ 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 (;;) {
@@ -95,8 +136,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 +147,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 +172,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 +183,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 +216,7 @@ function cookieAccess(request, response, moduleId, authOwner) {
   };
 }
 
+/** @param {unknown} value */
 function frozenCopy(value) {
   return Object.freeze(structuredClone(value ?? {}));
 }
@@ -165,10 +229,11 @@ 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;
@@ -182,16 +247,20 @@ export function createServerEvent(context) {
       context.module.id,
       context.authOwner,
     ),
-    backend: (path, init = {}) => backend(path, request, init),
-    backendUrl: (path) => backendUrl(path),
+    backend: (/** @type {string} */ path, init = {}) =>
+      backend(path, request, init),
+    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 ?? []),
@@ -203,19 +272,26 @@ export function createServerEvent(context) {
   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" &&
+    (isNonNullObject(value) &&
+      isNumber(value.status) &&
+      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,6 +303,11 @@ 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 {IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {unknown} result
+ * @param {(path: string) => boolean} isProxiedPath
  */
 async function writeServerResponse(request, response, result, isProxiedPath) {
   const answer = asResponse(result);
@@ -261,7 +342,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) {