@antelopejs/dms-frontend 0.9.3 → 0.10.0

package/templates/vue/server/email.mjs

@@ -17,8 +17,11 @@ const EMAIL_BUILD_WAIT_MS = 60_000;
  * Settled whenever no email build is running. The version changes with each
  * finished build: Node caches an imported module by URL, so the renderer is
  * imported under a new one to pick up rebuilt templates.
+ *
+ * @type {Promise<void>}
  */
 let emailBuild = Promise.resolve();
+/** @type {(() => void) | undefined} */
 let settleEmailBuild;
 let emailBundleVersion = 0;
 /**
@@ -28,6 +31,7 @@ let emailBundleVersion = 0;
  * finished.
  */
 let rendersInProgress = 0;
+/** @type {(() => void) | undefined} */
 let startPendingBuild;
 
 function emailBuildStarted() {
@@ -44,6 +48,7 @@ function emailBuildSettled() {
   settleEmailBuild = undefined;
 }
 
+/** @param {() => void} start */
 function startBuildOnceRendersFinish(start) {
   if (rendersInProgress) startPendingBuild = start;
   else start();
@@ -107,6 +112,7 @@ async function waitForEmailBuild() {
   }
 }
 
+/** @returns {Promise<typeof import("../email-renderer.ts")>} */
 function loadEmailRenderer() {
   const url = new URL(EMAIL_RENDERER_URL);
   if (emailBundleVersion) url.searchParams.set("v", emailBundleVersion);
@@ -121,9 +127,9 @@ function loadEmailRenderer() {
  * for now waits for this render, which imports templates and reads catalogs
  * from the bundle until it ends.
  *
- * @param template The template's name
- * @param props The template's props
- * @param options `locale`, the language to render in
+ * @param {string} template The template's name
+ * @param {Record<string, unknown>} props The template's props
+ * @param {{ locale?: string }} [options] `locale`, the language to render in
  */
 export async function renderEmailTemplate(template, props, options = {}) {
   await waitForEmailBuild();

package/templates/vue/server/favicon.mjs

@@ -13,6 +13,9 @@ const ICON_LINK = /<link\b[^>]*\srel=(["'])(?:[^"']*\s)?icon(?:\s[^"']*)?\1/i;
  * through `useHead` (light and dark, one per `prefers-color-scheme`)
  * competed with a placeholder carried by the template, and the browser could
  * keep the empty one.
+ *
+ * @param {string} headTags
+ * @returns {string}
  */
 export function withFaviconPlaceholder(headTags) {
   return ICON_LINK.test(headTags)

package/templates/vue/server/generated-files.mjs

@@ -0,0 +1,211 @@
+import { isBoolean, isNumber, isRecord, isString } from "./type-guards.mjs";
+
+/**
+ * @param {unknown} value
+ * @returns {value is import("./public-options.mjs").FrontendRegistry}
+ */
+function isFrontendRegistry(value) {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.modules) &&
+    value.modules.every((module) => isRecord(module) && isString(module.id))
+  );
+}
+
+/**
+ * The module registry the build wrote to `generated-frontend-modules.json`.
+ *
+ * @param {unknown} content The file's JSON
+ * @returns {import("./public-options.mjs").FrontendRegistry}
+ * @throws {Error} When it is not a list of modules that have an id
+ */
+export function frontendRegistryOf(content) {
+  if (!isFrontendRegistry(content))
+    throw new Error(
+      "generated-frontend-modules.json is not a list of modules with an id",
+    );
+  return content;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, Record<string, unknown>>}
+ */
+function isObjectOfObjects(value) {
+  return (
+    isRecord(value) &&
+    !Array.isArray(value) &&
+    Object.values(value).every(
+      (child) => isRecord(child) && !Array.isArray(child),
+    )
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, string[]>}
+ */
+function isObjectOfPaths(value) {
+  return (
+    isRecord(value) &&
+    !Array.isArray(value) &&
+    Object.values(value).every(
+      (path) => Array.isArray(path) && path.every(isString),
+    )
+  );
+}
+
+/**
+ * The server options the build wrote to `generated-server-options.json`: the
+ * private options by module id, and for each variable the path of the secret
+ * it stands for. A part the file leaves out is empty.
+ *
+ * @param {unknown} content The file's JSON
+ * @returns {{
+ *   modules: Record<string, Record<string, unknown>>,
+ *   environment: Record<string, string[]>
+ * }}
+ * @throws {Error} When a part is not what the build writes
+ */
+export function serverOptionsOf(content) {
+  const options =
+    isRecord(content) && !Array.isArray(content) ? content : undefined;
+  const modules = options ? (options.modules ?? {}) : undefined;
+  const environment = options ? (options.environment ?? {}) : undefined;
+  if (!isObjectOfObjects(modules) || !isObjectOfPaths(environment))
+    throw new Error(
+      "generated-server-options.json is not what the build writes",
+    );
+  return { modules, environment };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainRecord(value) {
+  return isRecord(value) && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is string[]}
+ */
+function isTextList(value) {
+  return Array.isArray(value) && value.every(isString);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is import("vite").ManifestChunk}
+ */
+function isManifestChunk(value) {
+  return (
+    isPlainRecord(value) &&
+    isString(value.file) &&
+    [value.css, value.assets, value.imports, value.dynamicImports].every(
+      (list) => list === undefined || isTextList(list),
+    ) &&
+    [value.src, value.name].every(
+      (text) => text === undefined || isString(text),
+    ) &&
+    [value.isEntry, value.isDynamicEntry].every(
+      (flag) => flag === undefined || isBoolean(flag),
+    )
+  );
+}
+
+/**
+ * The manifest `vite build` wrote to `dist/client/.vite/manifest.json`.
+ *
+ * @param {unknown} content The file's JSON
+ * @returns {import("vite").Manifest}
+ * @throws {Error} When it is not an object of chunks
+ */
+export function viteManifestOf(content) {
+  if (!isPlainRecord(content) || !Object.values(content).every(isManifestChunk))
+    throw new Error("the client manifest is not an object of Vite chunks");
+  return content;
+}
+
+/**
+ * The members of an Iconify collection that `iconCollectionOf` checks, the
+ * ones an icon query and a server render read.
+ *
+ * @typedef {Pick<
+ *   Parameters<typeof import("@iconify/utils").getIcons>[0],
+ *   | "prefix"
+ *   | "icons"
+ *   | "aliases"
+ *   | "lastModified"
+ *   | "left"
+ *   | "top"
+ *   | "width"
+ *   | "height"
+ *   | "rotate"
+ *   | "hFlip"
+ *   | "vFlip"
+ * >} IconCollection
+ */
+
+/**
+ * @param {unknown} value An icon, an alias or the collection itself
+ * @returns {boolean} Whether its size and transformation members, all
+ *   optional, have the types Iconify gives them
+ */
+function hasIconifyOptionals(value) {
+  return (
+    isPlainRecord(value) &&
+    [value.left, value.top, value.width, value.height, value.rotate].every(
+      (number) => number === undefined || isNumber(number),
+    ) &&
+    [value.hFlip, value.vFlip, value.hidden].every(
+      (flag) => flag === undefined || isBoolean(flag),
+    )
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {"body" | "parent"} required The member each entry of the table names
+ * @returns {boolean}
+ */
+function isIconifyTable(value, required) {
+  return (
+    isPlainRecord(value) &&
+    Object.values(value).every(
+      (member) =>
+        hasIconifyOptionals(member) &&
+        isPlainRecord(member) &&
+        isString(member[required]),
+    )
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is IconCollection}
+ */
+function isIconCollection(value) {
+  return (
+    hasIconifyOptionals(value) &&
+    isPlainRecord(value) &&
+    isString(value.prefix) &&
+    isIconifyTable(value.icons, "body") &&
+    (value.aliases === undefined || isIconifyTable(value.aliases, "parent")) &&
+    (value.lastModified === undefined || isNumber(value.lastModified))
+  );
+}
+
+/**
+ * An icon collection: the JSON file of an `@iconify-json/<prefix>` package.
+ *
+ * @param {unknown} content The file's JSON
+ * @returns {IconCollection}
+ * @throws {Error} When it is not an Iconify icon set
+ */
+export function iconCollectionOf(content) {
+  if (!isIconCollection(content))
+    throw new Error("the icon collection is not an Iconify icon set");
+  return content;
+}

package/templates/vue/server/homepage.mjs

@@ -1,20 +1,29 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { frontendRegistryOf } from "./generated-files.mjs";
 import { publicOptionsOf } from "./public-options.mjs";
+import { isRecord, isString } from "./type-guards.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const REGISTRY_PATH = join(PROJECT_ROOT, "generated-frontend-modules.json");
-const REGISTRY = existsSync(REGISTRY_PATH)
-  ? JSON.parse(readFileSync(REGISTRY_PATH, "utf8"))
-  : { modules: [] };
+const REGISTRY = frontendRegistryOf(
+  existsSync(REGISTRY_PATH)
+    ? JSON.parse(readFileSync(REGISTRY_PATH, "utf8"))
+    : { modules: [] },
+);
 
+/**
+ * @param {Readonly<Record<string, unknown>>} options
+ * @returns {string | undefined}
+ */
 function findHomepage(options) {
-  if (!options || typeof options !== "object") return undefined;
-  if (typeof options.homepage === "string") return options.homepage;
-  return Object.values(options)
-    .map(findHomepage)
-    .find((homepage) => homepage !== undefined);
+  if (isString(options.homepage)) return options.homepage;
+  for (const child of Object.values(options)) {
+    const homepage = isRecord(child) ? findHomepage(child) : undefined;
+    if (homepage !== undefined) return homepage;
+  }
+  return undefined;
 }
 
 const OPTIONS = publicOptionsOf(REGISTRY);
@@ -29,5 +38,8 @@ const OPTIONS = publicOptionsOf(REGISTRY);
  */
 export const HOMEPAGE =
   REGISTRY.modules
-    .map((module) => findHomepage(OPTIONS[module.id]))
+    .map((module) => {
+      const options = OPTIONS[module.id];
+      return isRecord(options) ? findHomepage(options) : undefined;
+    })
     .find(Boolean) ?? "/";

package/templates/vue/server/html-tag.mjs

@@ -3,6 +3,10 @@ const HTML_ATTRIBUTE = /([^\s=]+)(?:="[^"]*")?/g;
 /**
  * The document's `<html>` tag: the template's attributes, overridden by those
  * the render produced (`lang`, `data-scale`…), so none appears twice.
+ *
+ * @param {string} templateAttributes
+ * @param {string} renderedAttributes
+ * @returns {string}
  */
 export function htmlTag(templateAttributes, renderedAttributes) {
   const rendered = new Set(

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);