@antelopejs/dms-frontend 0.9.3 → 0.10.1

package/templates/vue/backend-boundary.mjs

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { isRecord, isString } from "./server/type-guards.mjs";
+
+const BACKEND_SOURCE = "src";
+const QUERY_OR_HASH = /[?#].*$/;
+
+/**
+ * @param {string} manifest
+ * @returns {string | undefined}
+ */
+function manifestName(manifest) {
+  try {
+    /** @type {unknown} */
+    const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+    return isRecord(parsed) && isString(parsed.name) ? parsed.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @typedef {{ root: string, name: string }} BackendPackage
+ */
+
+/**
+ * The backend package that holds `directory`: the nearest `package.json` above
+ * it, when it names one of `backendPackages`.
+ *
+ * @param {string} directory
+ * @param {ReadonlySet<string>} backendPackages
+ * @param {Map<string, BackendPackage | null>} known
+ * @returns {BackendPackage | null}
+ */
+function owningBackend(directory, backendPackages, known) {
+  const cached = known.get(directory);
+  if (cached !== undefined) return cached;
+  const manifest = join(directory, "package.json");
+  const parent = dirname(directory);
+  /** @type {BackendPackage | null} */
+  let owner = null;
+  if (existsSync(manifest)) {
+    const name = manifestName(manifest);
+    owner =
+      name !== undefined && backendPackages.has(name)
+        ? { root: directory, name }
+        : null;
+  } else if (parent !== directory) {
+    owner = owningBackend(parent, backendPackages, known);
+  }
+  known.set(directory, owner);
+  return owner;
+}
+
+/**
+ * The real path of a resolved module id under the `src` of a backend package,
+ * and that package's name, or `undefined`. The package that owns the file
+ * decides, not where it lies, so a backend linked or installed into the
+ * workspace is caught as well as its source checkout. Virtual ids and ids that
+ * are not files are ignored.
+ *
+ * @param {string} id
+ * @param {ReadonlySet<string>} backendPackages
+ * @param {Map<string, BackendPackage | null>} known
+ * @returns {{ file: string, name: string } | undefined}
+ */
+function backendSourceFile(id, backendPackages, known) {
+  const path = id.replace(QUERY_OR_HASH, "");
+  if (!isAbsolute(path)) return undefined;
+  let file;
+  try {
+    file = realpathSync(path);
+  } catch {
+    return undefined;
+  }
+  const owner = owningBackend(dirname(file), backendPackages, known);
+  if (owner === null) return undefined;
+  return relative(owner.root, file).split(sep)[0] === BACKEND_SOURCE
+    ? { file, name: owner.name }
+    : undefined;
+}
+
+/**
+ * @param {ReadonlySet<string>} backendPackages
+ * @returns {import("vite").Plugin}
+ */
+function boundaryCheck(backendPackages) {
+  /** @type {Map<string, BackendPackage | null>} */
+  const known = new Map();
+  return {
+    name: "dms-backend-boundary",
+    enforce: "pre",
+    async resolveId(source, importer, options) {
+      const resolved = await this.resolve(source, importer, {
+        ...options,
+        skipSelf: true,
+      });
+      if (resolved === null) return null;
+      const backend = backendSourceFile(resolved.id, backendPackages, known);
+      if (backend === undefined) return resolved;
+      const from =
+        importer === undefined
+          ? "an entry point"
+          : importer.replace(QUERY_OR_HASH, "");
+      return this.error(
+        `Backend boundary: ${from} imports ${backend.file}, which is under the src of ${backend.name}. ` +
+          "The frontend reaches the backend only through its HTTP interface.",
+      );
+    },
+  };
+}
+
+/**
+ * Fail the build, a worker build and the dev server when a module of the
+ * frontend resolves to a file under the `src` of a backend package: the package
+ * that holds a module's layer, as the registry names it. The browser and the
+ * server renderer reach the backend only through its HTTP interface.
+ *
+ * The check reads what the whole resolution chain returns, so an alias, a
+ * symlink and an id marked external are all seen through. Vite builds workers
+ * with their own plugin list, so the plugin adds the check there too.
+ *
+ * @param {readonly string[]} backendPackages
+ * @returns {import("vite").Plugin}
+ */
+export function rejectBackendSources(backendPackages) {
+  const names = new Set(backendPackages);
+  return {
+    ...boundaryCheck(names),
+    config: () => ({ worker: { plugins: () => [boundaryCheck(names)] } }),
+  };
+}

package/templates/vue/client-chunking.mjs

@@ -18,6 +18,8 @@
  * quarter to four fifths, but every group is loaded whole by each page that
  * uses any of it, and the anonymous pages pay 70 to 115 KB of Brotli for code
  * only the signed-in shell uses.
+ *
+ * @type {import("vite").Rolldown.CodeSplittingOptions}
  */
 export const clientCodeSplitting = {
   groups: [{ name: "entry", tags: ["$initial"] }],

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

@@ -2,11 +2,20 @@ import { relative, sep } from "node:path";
 
 const SERVER_ENTRY = /(?:^|[\\/])dms\.server\.[cm]?[jt]sx?$/;
 
+/**
+ * @param {string} id
+ * @returns {string}
+ */
 function stripQuery(id) {
   const query = id.indexOf("?");
   return query === -1 ? id : id.slice(0, query);
 }
 
+/**
+ * @param {string} file
+ * @param {readonly string[]} moduleRoots
+ * @returns {boolean}
+ */
 function insideModuleServerDirectory(file, moduleRoots) {
   return moduleRoots.some((root) => {
     const path = relative(root, file);
@@ -20,6 +29,10 @@ function insideModuleServerDirectory(file, moduleRoots) {
  * Whether `id`, a resolved module id, is server code: a module's server entry
  * (`dms.server.*`) or a file under a `server/` directory of a module. Installed
  * packages never are: `node_modules` has its own `server` directories.
+ *
+ * @param {string} id
+ * @param {readonly string[]} moduleRoots
+ * @returns {boolean}
  */
 export function isServerSource(id, moduleRoots) {
   if (id.startsWith("\0")) return false;
@@ -44,6 +57,9 @@ export function isServerSource(id, moduleRoots) {
  * import; the guard sits in the module graph instead, where every resolved file
  * passes. Kept beside vite.config.ts rather than inside it so the plugin can be
  * exercised on its own, the way head-order.mjs is.
+ *
+ * @param {readonly string[]} moduleRoots
+ * @returns {import("vite").Plugin}
  */
 export function rejectServerSourcesInClient(moduleRoots) {
   let ssrBuild = false;

package/templates/vue/compress-assets.mjs

@@ -16,10 +16,14 @@ const MINIMUM_SIZE_BYTES = 1_024;
 const compressBrotli = promisify(brotliCompress);
 const compressGzip = promisify(gzip);
 
+/**
+ * @param {string} directory
+ * @returns {Promise<string[]>}
+ */
 async function assetFiles(directory) {
   const entries = await readdir(directory, { withFileTypes: true });
   const files = await Promise.all(
-    entries.map((entry) => {
+    entries.map(async (entry) => {
       const path = join(directory, entry.name);
       return entry.isDirectory() ? assetFiles(path) : [path];
     }),
@@ -27,6 +31,10 @@ async function assetFiles(directory) {
   return files.flat();
 }
 
+/**
+ * @param {string} path
+ * @returns {Promise<void>}
+ */
 async function compressAsset(path) {
   if (!COMPRESSIBLE_EXTENSIONS.has(extname(path))) return;
   const content = await readFile(path);

package/templates/vue/entry-weight.mjs

@@ -10,11 +10,20 @@ export const TRANSLATIONS_OWNER = "translations";
 
 const LOCALE_CATALOG = /[\\/]locales\.generated[\\/]/;
 
+/**
+ * @param {string} id
+ * @returns {string}
+ */
 function stripQuery(id) {
   const query = id.indexOf("?");
   return query === -1 ? id : id.slice(0, query);
 }
 
+/**
+ * @param {string} root
+ * @param {string} file
+ * @returns {boolean}
+ */
 function isInside(root, file) {
   const path = relative(root, file);
   return Boolean(path) && !path.startsWith("..") && !path.startsWith(sep);
@@ -26,7 +35,9 @@ function isInside(root, file) {
  * what every page shares (the renderer's runtime, the UI and icon libraries,
  * an installed package).
  *
+ * @param {string} id
  * @param {{ root: string, name?: string, packageName?: string, id: string }[]} modules
+ * @returns {string}
  */
 export function entryOwner(id, modules) {
   if (id.startsWith("\0")) return SHARED_OWNER;
@@ -42,20 +53,29 @@ export function entryOwner(id, modules) {
 /**
  * The files a page loads before its first line runs: the entry chunks and
  * their static imports, transitively, by file name.
+ *
+ * @param {import("vite").Rollup.OutputBundle} bundle
+ * @returns {import("vite").Rollup.OutputChunk[]}
  */
 function entryClosure(bundle) {
   const chunks = Object.values(bundle).filter(
+    /**
+     * @param {import("vite").Rollup.OutputChunk | import("vite").Rollup.OutputAsset} output
+     * @returns {output is import("vite").Rollup.OutputChunk}
+     */
     (output) => output.type === "chunk",
   );
   const byName = new Map(chunks.map((chunk) => [chunk.fileName, chunk]));
-  const seen = new Set();
+  /** @type {Map<string, import("vite").Rollup.OutputChunk>} */
+  const seen = new Map();
+  /** @param {import("vite").Rollup.OutputChunk | undefined} chunk */
   const visit = (chunk) => {
     if (!chunk || seen.has(chunk.fileName)) return;
-    seen.add(chunk.fileName);
+    seen.set(chunk.fileName, chunk);
     for (const file of chunk.imports ?? []) visit(byName.get(file));
   };
   for (const chunk of chunks) if (chunk.isEntry) visit(chunk);
-  return [...seen].map((file) => byName.get(file));
+  return [...seen.values()];
 }
 
 /**
@@ -64,10 +84,13 @@ function entryClosure(bundle) {
  * rendered for each (`renderedLength`, before minification): an estimate that
  * needs nothing the bundle does not already hold.
  *
+ * @param {import("vite").Rollup.OutputBundle} bundle
+ * @param {{ root: string, name?: string, packageName?: string, id: string }[]} modules
  * @returns {{ files: string[], bytes: number, owners: Record<string, number> }}
  */
 export function attributeEntry(bundle, modules) {
   const files = entryClosure(bundle);
+  /** @type {Record<string, number>} */
   const owners = {};
   let bytes = 0;
   for (const chunk of files) {
@@ -109,6 +132,9 @@ export function attributeEntry(bundle, modules) {
  *
  * The weight is recorded once the bundle is written: plugins that generate the
  * bundle after this one still rewrite the chunks' code.
+ *
+ * @param {{ root: string, name?: string, packageName?: string, id: string }[]} modules
+ * @returns {import("vite").Plugin}
  */
 export function recordEntryWeight(modules) {
   let ssrBuild = false;

package/templates/vue/frontend-build.ts

@@ -31,10 +31,11 @@ export interface DmsFrontendBuild {
 
   /**
    * Adds Vite plugins to the application's build, for `ajs dms dev`,
-   * `ajs dms build` and the preview alike.
+   * `ajs dms build` and the preview alike, and to the bundle of each web worker
+   * it starts with `new Worker(new URL(...))`.
    *
-   * `create` runs in the build process each time Vite loads its configuration,
-   * and returns real Vite plugin objects (an array, each with a `name`; false,
+   * `create` runs in the build process each time Vite loads its configuration
+   * and once more for each worker bundle, and returns real Vite plugin objects (an array, each with a `name`; false,
    * null and undefined entries are skipped and nested arrays flattened, as in a
    * Vite configuration) or nothing. It is synchronous: a Promise is refused,
    * because the configuration is built synchronously. The plugins come after

package/templates/vue/frontend-module.ts

@@ -34,6 +34,7 @@ export type {
   DmsFetchTransformContext,
   UseAsyncDataOptions,
   UseFetchOptions,
+  DmsServerFetch,
   DmsErrorData,
   DmsPayload,
   DmsStateOptions,

package/templates/vue/frontend-runtime/module-registration.ts

@@ -1,5 +1,4 @@
 import { usePage } from "@inertiajs/vue3";
-import { ofetch } from "ofetch";
 import {
   type Component,
   type EffectScope,
@@ -19,6 +18,7 @@ import {
   type DmsPluginRegistrationOptions,
   type DmsPluginSetup,
   type DmsRoute,
+  type DmsServerFetch,
   type DmsSharedPagePayload,
   type RouteLocationRaw,
 } from "./types";
@@ -212,7 +212,7 @@ export interface DmsFrontendRuntime {
   /** Whether to warn about what a development render does wrong. */
   devWarnings?: boolean;
   runtimeHooks: Map<string, DmsRuntimeHook[]>;
-  serverFetch?: typeof ofetch;
+  serverFetch?: DmsServerFetch;
   currentError: Ref<Error | null>;
   route: DmsRoute;
   currentRoutePattern?: string;

package/templates/vue/frontend-runtime/state.ts

@@ -1,4 +1,3 @@
-import { ofetch } from "ofetch";
 import {
   type App,
   effectScope,
@@ -19,6 +18,7 @@ import {
 import {
   type DmsAppContext,
   type DmsRoute,
+  type DmsServerFetch,
   type DmsRuntimeConfig,
 } from "./types";
 
@@ -65,7 +65,7 @@ export function forgetBrowserRuntime(runtime: DmsFrontendRuntime): void {
 
 /** Creates mutable runtime state owned by one Vue application. */
 export function createDmsFrontendRuntime(
-  serverFetch?: typeof ofetch,
+  serverFetch?: DmsServerFetch,
   hydratedAsyncData?: Record<string, unknown>,
   isServer = false,
   requestCookies?: string,

package/templates/vue/frontend-runtime/types.ts

@@ -1,5 +1,5 @@
 import { type InertiaLinkProps } from "@inertiajs/vue3";
-import { type FetchOptions, ofetch } from "ofetch";
+import { type FetchOptions } from "ofetch";
 import {
   type App,
   type ComputedRef,
@@ -246,6 +246,12 @@ export interface UseAsyncDataOptions<T> {
    */
   refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
 }
+/** What the runtime calls to read the backend: `ofetch`, or a stand-in for it. */
+export type DmsServerFetch = (
+  request: string,
+  options?: FetchOptions,
+) => Promise<unknown>;
+
 /**
  * `useDmsFetch`'s options: ofetch's request options, of which the method, the
  * query, the params and the body may be refs or getters, and the async data
@@ -271,7 +277,7 @@ export interface UseFetchOptions<T>
     context: DmsFetchTransformContext,
   ) => T | Promise<T>;
   /** Replaces the fetch function; it receives the run's signal. */
-  $fetch?: typeof ofetch;
+  $fetch?: DmsServerFetch;
 }
 export interface DmsErrorData {
   statusCode?: number;

package/templates/vue/head-order.mjs

@@ -1,6 +1,10 @@
 const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
 const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
 
+/**
+ * @param {string} html
+ * @returns {string}
+ */
 function deprioritize(html) {
   return html.replace(SCRIPT, (tag) =>
     tag.includes("fetchpriority")
@@ -24,12 +28,16 @@ function deprioritize(html) {
  * HTTP/1.1 the generated server speaks. Kept beside vite.config.ts rather than
  * inside it so the transform can be exercised on its own, the way
  * client-manifest.mjs is.
+ *
+ * @param {string} html
+ * @returns {string}
  */
 export function orderHeadForFirstPaint(html) {
   const prioritized = deprioritize(html);
   const stylesheet = prioritized.match(STYLESHEET);
-  const script = prioritized.match(SCRIPT);
-  if (!stylesheet || !script || stylesheet.index < script.index)
+  const stylesheetAt = prioritized.search(STYLESHEET);
+  const scriptAt = prioritized.search(SCRIPT);
+  if (!stylesheet || scriptAt < 0 || stylesheetAt < scriptAt)
     return prioritized;
   return prioritized
     .replace(STYLESHEET, "")

package/templates/vue/icon-api.mjs

@@ -9,6 +9,8 @@ export const ICON_API_PATH = "/api/_dms/icons/";
 /**
  * The `@iconify/vue` API provider serving every icon the client bundle lacks
  * from `origin`, instead of `api.iconify.design` and its fallbacks.
+ *
+ * @param {string} origin
  */
 export function sameOriginIconProvider(origin) {
   return { resources: [origin], path: ICON_API_PATH };

package/templates/vue/icon-scan.mjs

@@ -19,6 +19,10 @@ const SOURCE_SCRIPT_GLOB = "app/**/*.ts";
  * fetched from the Iconify API at run time. Every frontend source root lives
  * under the workspace (`frontend-modules/`, enforced when the registry is
  * written), so a relative glob reaches it. Globs are POSIX on every platform.
+ *
+ * @param {string} viteRoot
+ * @param {readonly string[]} sourceRoots
+ * @returns {string[]}
  */
 export function iconScanGlobs(viteRoot, sourceRoots) {
   const sourceGlobs = sourceRoots.map((root) =>

package/templates/vue/server/auth/backend.mjs

@@ -1,4 +1,5 @@
 import { REDIRECT_STATUSES } from "../proxy-redirects.mjs";
+import { isObjectLike, isString } from "../type-guards.mjs";
 import { clientCountryHeader, clientIp, clientIpHeader } from "./client-ip.mjs";
 
 /**
@@ -14,6 +15,10 @@ export const CLIENT_HEADERS = [
 ];
 
 export class UpstreamError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} message
+   */
   constructor(status, message) {
     super(message);
     this.status = status;
@@ -27,9 +32,15 @@ const PUBLIC_AUTH_MESSAGE = /^error\.[a-z0-9_.-]{1,100}$/;
  */
 export const GENERIC_ERROR_MESSAGE = "error.500.description";
 
+/**
+ * @param {unknown} data A backend answer: any JSON value, or the text of one
+ *   that is not JSON
+ * @returns {string | undefined}
+ */
 export function publicBackendMessage(data) {
-  const message = typeof data === "string" ? data : data?.message;
-  return typeof message === "string" && PUBLIC_AUTH_MESSAGE.test(message)
+  /** @type {unknown} */
+  const message = isObjectLike(data) ? data.message : data;
+  return isString(message) && PUBLIC_AUTH_MESSAGE.test(message)
     ? message
     : undefined;
 }
@@ -37,8 +48,10 @@ export function publicBackendMessage(data) {
 /**
  * The headers of a client request the server relays to the backend.
  *
- * @param request The client request
- * @param names Lowercase names of the request headers to copy when present
+ * @param {import("./client-ip.mjs").ForwardedRequest} request The client
+ *   request
+ * @param {readonly string[]} names Lowercase names of the request headers to
+ *   copy when present
  * @returns The client country header, then the copied headers
  */
 export function relayedHeaders(request, names) {
@@ -46,7 +59,7 @@ export function relayedHeaders(request, names) {
     ...clientCountryHeader(request),
     ...Object.fromEntries(
       names.flatMap((name) =>
-        request.headers[name] ? [[name, request.headers[name]]] : [],
+        request.headers[name] ? [[name, String(request.headers[name])]] : [],
       ),
     ),
   };
@@ -58,8 +71,22 @@ export function relayedHeaders(request, names) {
  * `options.headers` adds request headers; the client's address and the
  * relayed client headers are set after them, so no caller replaces those.
  * A redirect is not followed: it is no JSON answer, so it fails with a 502.
+ *
+ * @param {string} path
+ * @param {import("./client-ip.mjs").ForwardedRequest} request The client
+ *   request
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   token?: string,
+ *   relay?: boolean,
+ *   headers?: Record<string, string>
+ * }} [options]
+ * @returns {Promise<unknown>} The answer's JSON, `{}` for a successful one that
+ *   is not JSON
  */
 export async function backend(path, request, options = {}) {
+  /** @type {Record<string, string>} */
   const headers = Object.fromEntries(
     Object.entries(options.headers ?? {}).map(([name, value]) => [
       name.toLowerCase(),
@@ -87,6 +114,7 @@ export async function backend(path, request, options = {}) {
     throw new UpstreamError(502, GENERIC_ERROR_MESSAGE);
   }
   const text = await response.text();
+  /** @type {unknown} */
   let data;
   try {
     data = JSON.parse(text);
@@ -105,12 +133,21 @@ export async function backend(path, request, options = {}) {
 }
 
 export class RequestBodyError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} message
+   */
   constructor(status, message) {
     super(message);
     this.status = status;
   }
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {unknown} value Anything `JSON.stringify` writes
+ */
 export function json(response, status, value) {
   response.writeHead(status, { "content-type": "application/json" });
   response.end(JSON.stringify(value));