@antelopejs/dms-frontend 0.9.2 → 0.10.0

package/templates/vue/server/client-manifest.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { viteManifestOf } from "./generated-files.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const BUILT_TEMPLATE_PATH = join(PROJECT_ROOT, "dist/client/index.html");
@@ -14,7 +15,9 @@ const SOURCE_TEMPLATE_PATH = join(PROJECT_ROOT, "index.html");
  * Read once and kept: both files are build output and cannot change while
  * the server is up.
  */
+/** @type {import("vite").Manifest | undefined} */
 let clientManifest;
+/** @type {string | undefined} */
 let productionTemplate;
 
 /**
@@ -31,13 +34,22 @@ export function productionHtmlTemplate() {
   return productionTemplate;
 }
 
+/** @returns {import("vite").Manifest | undefined} */
 function productionClientManifest() {
   if (clientManifest) return clientManifest;
   if (!existsSync(CLIENT_MANIFEST_PATH)) return undefined;
-  clientManifest = JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8"));
+  clientManifest = viteManifestOf(
+    JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8")),
+  );
   return clientManifest;
 }
 
+/**
+ * @param {import("vite").Manifest} manifest
+ * @param {string} key
+ * @param {Set<string>} styles
+ * @param {Set<string>} visited
+ */
 function collectManifestStyles(manifest, key, styles, visited) {
   if (visited.has(key)) return;
   visited.add(key);
@@ -56,11 +68,16 @@ function collectManifestStyles(manifest, key, styles, visited) {
  * component, so the lookup needs no guessing from names. A component bundled
  * into another chunk is no key of its own: its stylesheet comes with that
  * chunk's, reached through the `imports` of the component that loaded it.
+ *
+ * @param {Iterable<string>} [modules]
+ * @returns {Set<string>}
  */
 function renderedModuleStyles(modules = []) {
   const manifest = productionClientManifest();
+  /** @type {Set<string>} */
   const styles = new Set();
   if (!manifest) return styles;
+  /** @type {Set<string>} */
   const visited = new Set();
   for (const id of modules)
     collectManifestStyles(manifest, id, styles, visited);
@@ -72,6 +89,9 @@ function renderedModuleStyles(modules = []) {
  * template does not link already, so that none of them waits for its chunk's
  * JavaScript to arrive: the HTML would otherwise paint unstyled and shift once
  * it does. A component the render did not reach gets no link.
+ *
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
  */
 export function renderedModuleStyleTags(modules, template) {
   return [...renderedModuleStyles(modules)]
@@ -85,6 +105,8 @@ export function renderedModuleStyleTags(modules, template) {
  * rendered with: the browser fetches it next to the entry rather than once the
  * entry runs and asks for it, which would put a round trip before hydration.
  * Nothing without a production build (Vite serves the sources in development).
+ *
+ * @param {string | undefined} locale
  */
 export function localeCatalogPreloadTag(locale) {
   const manifest = productionClientManifest();

package/templates/vue/server/content.mjs

@@ -17,9 +17,13 @@ const DYNAMIC_BROTLI_QUALITY = 4;
  * client gets each part when it is written, not when a block fills.
  *
  * Implicit identity is a fallback, not a preference over compression.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ streaming?: boolean }} [options]
  */
 export function acceptedEncoder(request, { streaming = false } = {}) {
   const accepted = request.headers["accept-encoding"] ?? "";
+  /** @type {Map<string, number>} */
   const qualities = new Map();
   for (const entry of accepted.split(",")) {
     const [token, ...parameters] = entry.trim().toLowerCase().split(";");
@@ -37,6 +41,7 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
       Math.min(qualities.get(token.trim()) ?? 1, quality),
     );
   }
+  /** @param {string} token */
   const quality = (token) => qualities.get(token) ?? qualities.get("*") ?? 0;
   const br = quality("br");
   const gzip = quality("gzip");
@@ -61,12 +66,24 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
     };
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string | Buffer} content
+ */
 function responseEncoder(request, content) {
   if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
   return acceptedEncoder(request);
 }
 
-/** Send a generated body, compressed when the client accepts it. */
+/**
+ * Send a generated body, compressed when the client accepts it.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {import("node:http").OutgoingHttpHeaders} headers
+ * @param {string | Buffer} content
+ */
 export async function writeContent(
   request,
   response,

package/templates/vue/server/dev-private-files.mjs

@@ -28,6 +28,10 @@ export const DEV_FS_DENY = [
  * file, a module's server entry, or a file under a `server/` directory of a
  * module materialized under `root`. Compared without case, as a
  * case-insensitive file system would serve them.
+ *
+ * @param {string} file
+ * @param {string} root
+ * @returns {boolean}
  */
 export function isPrivateFile(file, root) {
   const name = (resolve(file).split(/[\\/]/).at(-1) ?? "").toLowerCase();
@@ -39,12 +43,22 @@ export function isPrivateFile(file, root) {
   );
 }
 
+/**
+ * @param {string} id
+ * @returns {string}
+ */
 function stripQuery(id) {
   const query = id.search(/[?#]/);
   return query === -1 ? id : id.slice(0, query);
 }
 
-/** The file a request URL names under `root`, `undefined` when it names none. */
+/**
+ * The file a request URL names under `root`, `undefined` when it names none.
+ *
+ * @param {string | undefined} url
+ * @param {string} root
+ * @returns {string | undefined}
+ */
 function requestedFile(url, root) {
   let pathname;
   try {
@@ -74,6 +88,8 @@ function requestedFile(url, root) {
  *
  * The middleware is registered directly, not returned: it runs before Vite's
  * middlewares.
+ *
+ * @returns {import("vite").Plugin}
  */
 export function denyPrivateFiles() {
   let root = process.cwd();

package/templates/vue/server/dev-styles.mjs

@@ -8,6 +8,13 @@ const SFC_STYLE = /[?&]vue&type=style/;
 const STYLE_EXTENSION =
   /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
 
+/**
+ * A stylesheet module of the development server's graph: its URL, and the id
+ * its tag is matched by.
+ *
+ * @typedef {{ url: string, id: string }} StyleModule
+ */
+
 /**
  * The workspace's generated entry stylesheet. `main.ts` is its only importer,
  * so it never enters the SSR module graph, yet it carries Tailwind, Nuxt UI and
@@ -25,6 +32,16 @@ const ENTRY_STYLESHEET_ID = join(PROJECT_ROOT, "dms-main.css")
   .split(sep)
   .join("/");
 
+/**
+ * @typedef {{ urlToModuleMap: ReadonlyMap<string, { id: string | null } | undefined> }} StyleGraph
+ * @typedef {{
+ *   environments?: { ssr?: { moduleGraph?: StyleGraph } },
+ *   moduleGraph?: StyleGraph,
+ *   transformRequest(url: string): Promise<{ code: string } | null>,
+ * }} StyleServer
+ */
+
+/** @param {StyleServer} devServer */
 function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
 }
@@ -39,6 +56,10 @@ function ssrModuleGraph(devServer) {
  */
 const TRAILING_LANG = /&(lang\.[^&?]*)$/;
 
+/**
+ * @param {string} url
+ * @returns {string}
+ */
 function directUrl(url) {
   if (SFC_STYLE.test(url) && TRAILING_LANG.test(url)) {
     return url.replace(TRAILING_LANG, "&direct&$1");
@@ -46,6 +67,10 @@ function directUrl(url) {
   return `${url}${url.includes("?") ? "&" : "?"}direct`;
 }
 
+/**
+ * @param {StyleServer} devServer
+ * @returns {StyleModule[]}
+ */
 function styleModules(devServer) {
   const graph = ssrModuleGraph(devServer);
   if (!graph) return [];
@@ -54,6 +79,7 @@ function styleModules(devServer) {
     .map(([url, module]) => ({ url, id: module?.id ?? url }));
 }
 
+/** @param {StyleModule} module */
 function linkTag({ url, id }) {
   return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
 }
@@ -64,6 +90,10 @@ function linkTag({ url, id }) {
  * stylesheet. They are small; inline them instead. A block that could close its
  * own tag is dropped rather than escaped — CSS has no escape that is valid in
  * every position, and a scoped component rule is not worth the risk.
+ *
+ * @param {StyleServer} devServer
+ * @param {StyleModule} module
+ * @returns {Promise<string>}
  */
 async function inlineTag(devServer, { url, id }) {
   const result = await devServer
@@ -87,6 +117,9 @@ async function inlineTag(devServer, { url, id }) {
  * stylesheet, which is why this module is development-only and lives beside
  * client-manifest.mjs rather than inside server.mjs, whose size the linter
  * caps.
+ *
+ * @param {StyleServer} devServer
+ * @returns {Promise<string>}
  */
 export async function developmentStyleTags(devServer) {
   const modules = styleModules(devServer);
@@ -106,6 +139,11 @@ export async function developmentStyleTags(devServer) {
  * The style tags a document needs, whichever server is answering it: collected
  * from the live module graph in development, read from the build manifest for
  * the components the render created (`modules`) in production.
+ *
+ * @param {import("vite").ViteDevServer | undefined} devServer
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
+ * @returns {Promise<string>}
  */
 export async function documentStyleTags(devServer, modules, template) {
   return devServer

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(