@antelopejs/dms-frontend 0.9.2 → 0.10.0

package/templates/vue/server/route-rules.mjs

@@ -1,10 +1,25 @@
 import { compilePathPattern } from "./path-patterns.mjs";
+import { isNonNullObject, isObjectLike, isString } from "./type-guards.mjs";
+
+/** @typedef {import("../server-module.ts").DmsRouteRule} RouteRule */
+/** @typedef {RouteRule & { headers: Record<string, string> }} MergedRouteRule */
+/**
+ * @typedef {object} ResolvedRouteRule
+ * @property {string} id The declaring module
+ * @property {number} priority The declaring module's priority
+ * @property {import("./path-patterns.mjs").CompiledPathPattern} pattern
+ * @property {RouteRule} rule
+ */
 
 const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
-/** Whether a header value holds a control character other than a tab: a CR
- * or an LF would split the answer. */
+/**
+ * Whether a header value holds a control character other than a tab: a CR
+ * or an LF would split the answer.
+ *
+ * @param {string} value
+ */
 function hasControlCharacter(value) {
-  return [...value].some((character) => {
+  return Array.from(value).some((character) => {
     const code = character.charCodeAt(0);
     return (code < 0x20 && code !== 0x09) || code === 0x7f;
   });
@@ -20,19 +35,21 @@ const RESERVED_HEADERS = new Set([
   "x-inertia-version",
 ]);
 
+/** @param {unknown} value */
 function isSeconds(value) {
   return Number.isSafeInteger(value) && value >= 0;
 }
 
+/** @param {unknown} headers */
 function headersRejection(headers) {
   if (headers === undefined) return undefined;
-  if (typeof headers !== "object" || headers === null || Array.isArray(headers))
+  if (!isNonNullObject(headers) || Array.isArray(headers))
     return "headers is not an object";
   for (const [name, value] of Object.entries(headers)) {
     const lower = name.toLowerCase();
     if (
       !HEADER_NAME.test(lower) ||
-      typeof value !== "string" ||
+      !isString(value) ||
       hasControlCharacter(value)
     )
       return `"${name}" is not a header with a text value`;
@@ -42,11 +59,11 @@ function headersRejection(headers) {
   return undefined;
 }
 
+/** @param {unknown} cache */
 function cacheRejection(cache) {
   if (cache === undefined || cache === false) return undefined;
   if (
-    typeof cache !== "object" ||
-    cache === null ||
+    !isNonNullObject(cache) ||
     cache.public !== true ||
     !isSeconds(cache.maxAge) ||
     (cache.staleWhileRevalidate !== undefined &&
@@ -62,11 +79,14 @@ function cacheRejection(cache) {
  * Route rules the modules declare in their `dms.server.ts`: how a page is
  * rendered and which headers its document and Inertia answers carry. They
  * change rendering and caching, never who may see a page.
+ *
+ * @param {string} pattern
+ * @param {unknown} rule
  */
 export function ruleRejection(pattern, rule) {
   if (!compilePathPattern(pattern))
     return "the pattern is not /x, /x/* or /x/**";
-  if (typeof rule !== "object" || rule === null) return "it is not an object";
+  if (!isNonNullObject(rule)) return "it is not an object";
   if (rule.ssr !== undefined && rule.ssr !== false)
     return "ssr is either left out or false";
   return headersRejection(rule.headers) ?? cacheRejection(rule.cache);
@@ -77,10 +97,12 @@ export function ruleRejection(pattern, rule) {
  * specific pattern: a more specific rule overrides `ssr`, `cache` and each
  * header it sets.
  *
- * @param rules The resolved rules, `{ pattern, rule }` each
- * @param pathname The page's path
+ * @param {readonly ResolvedRouteRule[]} rules The resolved rules, `{ pattern, rule }` each
+ * @param {string} pathname The page's path
+ * @returns {MergedRouteRule}
  */
 export function routeRuleFor(rules, pathname) {
+  /** @type {MergedRouteRule} */
   const merged = { headers: {} };
   const matching = rules
     .filter(({ pattern }) => pattern.test(pathname))
@@ -95,6 +117,7 @@ export function routeRuleFor(rules, pathname) {
   return merged;
 }
 
+/** @param {{ maxAge: number, staleWhileRevalidate?: number }} cache */
 function publicCacheControl(cache) {
   const stale =
     cache.staleWhileRevalidate === undefined
@@ -109,10 +132,10 @@ function publicCacheControl(cache) {
  * content language: the answer then holds nobody's data, and `Vary: Cookie`
  * keeps a shared cache from serving it to a visitor who has some.
  *
- * @param rule What `routeRuleFor` returned
- * @param request The page request
- * @param route The page's route, as the backend described it
- * @param status The answer's status: only a 200 is cached
+ * @param {MergedRouteRule} rule What `routeRuleFor` returned
+ * @param {import("node:http").IncomingMessage} request The page request
+ * @param {unknown} route The page's route, as the backend described it: any JSON value, only `publicAccess` is read
+ * @param {number} status The answer's status: only a 200 is cached
  */
 export function ruleHeaders(rule, request, route, status) {
   const headers = { ...rule.headers };
@@ -122,7 +145,8 @@ export function ruleHeaders(rule, request, route, status) {
     request.method === "GET" &&
     !request.headers.cookie &&
     !request.headers["x-content-language"] &&
-    route?.publicAccess === true
+    isObjectLike(route) &&
+    route.publicAccess === true
   ) {
     headers["cache-control"] = publicCacheControl(rule.cache);
     headers.vary = "X-Inertia, Cookie";

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

@@ -0,0 +1,32 @@
+import * as icons from "./icons.mjs";
+
+/** @typedef {import("vite").ViteDevServer} ViteDevServer */
+
+/**
+ * A URL, not a path: on Windows, `import()` reads `C:\...` as a URL whose
+ * scheme is `c:` and refuses it.
+ */
+const BUILT_SSR_RENDERER_URL = new URL(
+  "../dist/ssr/ssr-renderer.js",
+  import.meta.url,
+);
+
+/** @type {Promise<typeof import("../ssr-renderer.ts")> | undefined} */
+let productionSsrRenderer;
+
+/**
+ * The SSR renderer of the workspace: the development server's module, else
+ * the built bundle, loaded once.
+ *
+ * @param {ViteDevServer | undefined} devServer
+ * @returns {Promise<typeof import("../ssr-renderer.ts")>}
+ */
+export async function ssrRenderer(devServer) {
+  /** @type {typeof import("../ssr-renderer.ts")} */
+  // oxlint-disable-next-line typescript/no-unsafe-assignment -- `ssrLoadModule` types every module `Record<string, any>` and the production import takes a URL computed at run time; both load this template's own `ssr-renderer.ts`, the type named above.
+  const renderer = devServer
+    ? await devServer.ssrLoadModule("/ssr-renderer.ts")
+    : await (productionSsrRenderer ??= import(BUILT_SSR_RENDERER_URL.href));
+  await icons.provideIconCollections(renderer);
+  return renderer;
+}

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

@@ -5,6 +5,8 @@ import { extname } from "node:path";
  * What a build or a module's `public/` directory may hold. A type missing
  * here went out as `application/octet-stream`: fonts among them, which a
  * browser then reports as a mismatch against the `font/woff2` it preloaded.
+ *
+ * @type {Record<string, string | undefined>}
  */
 const MIME_TYPES = {
   ".avif": "image/avif",
@@ -46,9 +48,15 @@ const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
  */
 const REVALIDATED_CACHE = "no-cache";
 
+/** @param {string} path */
 const isFile = (path) => existsSync(path) && statSync(path).isFile();
 
-/** The precompressed variant of `file` the client accepts, if the build wrote one. */
+/**
+ * The precompressed variant of `file` the client accepts, if the build wrote one.
+ *
+ * @param {string} file
+ * @param {import("node:http").IncomingMessage} request
+ */
 function acceptedVariant(file, request) {
   const accepted = request.headers["accept-encoding"] ?? "";
   if (accepted.includes("br") && isFile(`${file}.br`))
@@ -61,17 +69,26 @@ function acceptedVariant(file, request) {
 /**
  * Weak, as the bytes of one representation are not compared: the size and
  * modification time of the file sent, so each encoding has its own.
+ *
+ * @param {import("node:fs").Stats} stats
+ * @returns {string}
  */
 function entityTag(stats) {
   return `W/"${stats.size.toString(16)}-${Math.floor(stats.mtimeMs).toString(16)}"`;
 }
 
+/** @param {string} tag */
 const opaqueTag = (tag) => tag.trim().replace(/^W\//, "");
 
 /**
  * RFC 9110 §13.1.2 and §13.1.3: `If-None-Match` first, the date otherwise.
  *
  * The header has a one-second resolution.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string} tag
+ * @param {import("node:fs").Stats} stats
+ * @returns {boolean}
  */
 function isNotModified(request, tag, stats) {
   const noneMatch = request.headers["if-none-match"];
@@ -92,11 +109,17 @@ function isNotModified(request, tag, stats) {
  * Send `file`, a file the caller already resolved and checked (see
  * `publicBuildFile`), as the variant the client accepts, or answer 304 when the
  * client's copy is current. `immutable` for a file named after its content.
+ *
+ * @param {string} file
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {{ immutable: boolean }} options
  */
 export function serveStaticFile(file, request, response, { immutable }) {
   const selected = acceptedVariant(file, request);
   const stats = statSync(selected.file);
   const tag = entityTag(stats);
+  /** @type {import("node:http").OutgoingHttpHeaders} */
   const headers = {
     "cache-control": immutable ? IMMUTABLE_CACHE : REVALIDATED_CACHE,
     etag: tag,

package/templates/vue/server/type-guards.mjs

@@ -0,0 +1,71 @@
+/**
+ * Whether `value` is a string primitive, a boxed `String` excluded.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is string} Whether `typeof value` is `"string"`
+ */
+export function isString(value) {
+  return typeof value === "string";
+}
+
+/**
+ * Whether `value` is a number primitive, `NaN` and the infinities included.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is number} Whether `typeof value` is `"number"`
+ */
+export function isNumber(value) {
+  return typeof value === "number";
+}
+
+/**
+ * Whether `value` is a boolean primitive.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is boolean} Whether `typeof value` is `"boolean"`
+ */
+export function isBoolean(value) {
+  return typeof value === "boolean";
+}
+
+/**
+ * Whether `value` is callable: a function, an arrow, a class or a method.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is Function} Whether `typeof value` is `"function"`
+ */
+export function isFunction(value) {
+  return typeof value === "function";
+}
+
+/**
+ * Whether `value` is an object other than `null`: arrays are objects.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is object} Whether `typeof value` is `"object"` and `value` is not `null`
+ */
+export function isNonNullObject(value) {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Whether `value` can carry properties a caller reads: an object or a
+ * function, `null` excluded. Every property read through it is `unknown`.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is Record<string, unknown>} Whether `value` is an object or a function
+ */
+export function isObjectLike(value) {
+  return isNonNullObject(value) || isFunction(value);
+}
+
+/**
+ * Whether `value` is an object other than `null`, read by its properties:
+ * arrays are objects, functions are not.
+ *
+ * @param {unknown} value The value to test
+ * @returns {value is Record<string, unknown>} Whether `typeof value` is `"object"` and `value` is not `null`
+ */
+export function isRecord(value) {
+  return isNonNullObject(value);
+}

package/templates/vue/server/vite-errors.mjs

@@ -2,12 +2,26 @@ const INTERNAL_ERROR_STATUS = 500;
 const ERROR_CONTENT_TYPE = "text/plain; charset=utf-8";
 const VITE_ERROR = Symbol("dms.viteError");
 
+/**
+ * A request that carries the error Vite's middlewares failed with.
+ *
+ * @typedef {import("node:http").IncomingMessage & { [VITE_ERROR]?: unknown }} ViteRequest
+ */
+
+/**
+ * What Vite's middlewares did with a request.
+ *
+ * @typedef {{ status: "handled" } | { status: "unhandled" } | { status: "failed", error: unknown }} ViteMiddlewareResult
+ */
+
 /**
  * In middleware mode, Vite's own error middleware logs an error, sends it to
  * the client overlay, then passes the request on with no error: a module that
  * fails to transform would fall through to page handling and answer 404. This
  * plugin runs just before it, keeps the error on the request and hands it on,
  * so Vite still logs it and shows the overlay.
+ *
+ * @returns {import("vite").Plugin}
  */
 export function captureViteErrors() {
   return {
@@ -15,10 +29,18 @@ export function captureViteErrors() {
     apply: "serve",
     configureServer(server) {
       return () =>
-        server.middlewares.use((error, request, _response, next) => {
-          request[VITE_ERROR] = error;
-          next(error);
-        });
+        server.middlewares.use(
+          /**
+           * @param {unknown} error
+           * @param {ViteRequest} request
+           * @param {import("node:http").ServerResponse} _response
+           * @param {(error?: unknown) => void} next
+           */
+          (error, request, _response, next) => {
+            request[VITE_ERROR] = error;
+            next(error);
+          },
+        );
     },
   };
 }
@@ -27,10 +49,15 @@ export function captureViteErrors() {
  * Hands a request to Vite's middlewares. Resolves `handled` once Vite answered
  * it, `unhandled` when Vite passed it on, and `failed` with the error when a
  * Vite middleware failed on it.
+ *
+ * @param {import("vite").ViteDevServer} devServer
+ * @param {ViteRequest} request
+ * @param {import("node:http").ServerResponse} response
+ * @returns {Promise<ViteMiddlewareResult>}
  */
 export function runViteMiddlewares(devServer, request, response) {
   return new Promise((resolve) => {
-    devServer.middlewares(request, response, (error) => {
+    devServer.middlewares(request, response, (/** @type {unknown} */ error) => {
       const failure = error ?? request[VITE_ERROR];
       resolve(
         failure

package/templates/vue/server/web-body.mjs

@@ -11,6 +11,9 @@ import { pipeline } from "node:stream/promises";
  *
  * Writes a Web-standard body, a backend answer above all, to a Node response.
  * It lives apart from the proxy and the module routes, which both send one.
+ *
+ * @param {import("node:stream/web").ReadableStream} body
+ * @param {...import("node:stream").Writable} streams
  */
 export async function pipeWebBody(body, ...streams) {
   const response = streams.at(-1);

package/templates/vue/server-module.ts

@@ -101,7 +101,16 @@ export interface DmsServerEvent {
    * overwrites another's, and naming a `dms_*` cookie throws.
    */
   cookies: {
-    readSealed<T = unknown>(name: string): T | undefined;
+    /**
+     * The value a sealed cookie holds, when `accepts` takes it. A cookie that
+     * is absent, does not open, or holds a value `accepts` refuses reads as
+     * `undefined`. `accepts` receives the JSON the cookie was written from and
+     * is never called for an absent or unreadable cookie.
+     */
+    readSealed<T>(
+      name: string,
+      accepts: (value: unknown) => value is T,
+    ): T | undefined;
     writeSealed(
       name: string,
       value: unknown,