@antelopejs/dms-frontend 0.9.3 → 0.10.0

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,