appstage 0.2.1

package/src/controllers/dir.ts

@@ -0,0 +1,119 @@
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import type { Request, Response } from "express";
+import type { Controller } from "../types/Controller.ts";
+import type { TransformContent } from "../types/TransformContent.ts";
+import { emitLog } from "../utils/emitLog.ts";
+import {
+  type ResolveFilePathParams,
+  resolveFilePath,
+} from "../utils/resolveFilePath.ts";
+
+const defaultExt = ["html", "htm"];
+const defaultName = (req: Request) => req.path.split("/").at(-1);
+
+type ZeroTransform = false | null | undefined;
+
+export type DirParams = Partial<
+  Pick<ResolveFilePathParams, "supportedLocales" | "index">
+> & {
+  /** Directory path to serve files from. */
+  path: string;
+  /**
+   * File name.
+   * By default, the portion of `req.path` after the last slash.
+   */
+  name?:
+    | string
+    | undefined
+    | ((req: Request, res: Response) => string | undefined);
+  /**
+   * Allowed file extensions.
+   *
+   * @defaultValue `['html', 'htm']`
+   */
+  ext?: ResolveFilePathParams["ext"];
+  /**
+   * Custom transforms applied to the file content.
+   *
+   * Example: Use `injectNonce` from this package to inject the `nonce`
+   * value generated for the current request into the `{{nonce}}`
+   * placeholders in an HTML file.
+   */
+  transform?:
+    | TransformContent
+    | ZeroTransform
+    | (TransformContent | ZeroTransform)[];
+  supportedLocales?: string[];
+};
+
+/**
+ * Serves files from the specified directory path in a locale-aware
+ * fashion after applying optional transforms.
+ *
+ * A file ending with `.<lang>.<ext>` is picked first if the `<lang>`
+ * part matches `req.ctx.lang`. If the `supportedLocales` array is
+ * provided, the `*.<lang>.<ext>` file is picked only if the given
+ * array contains `req.ctx.lang`. Otherwise, a file without the locale
+ * in its path (`*.<ext>`) is picked.
+ */
+export const dir: Controller<DirParams> = ({
+  path,
+  name = defaultName,
+  ext = defaultExt,
+  transform,
+  supportedLocales,
+  index = true,
+}) => {
+  if (typeof path !== "string") throw new Error(`'path' is not a string`);
+
+  let transformSet = (
+    Array.isArray(transform) ? transform : [transform]
+  ).filter((item) => typeof item === "function");
+
+  return async (req, res) => {
+    let fileName = typeof name === "function" ? name(req, res) : name;
+
+    emitLog(req.app, `Name: ${JSON.stringify(fileName)}`, {
+      req,
+      res,
+    });
+
+    if (fileName === undefined) {
+      res.status(404).send(await req.app.renderStatus?.(req, res));
+
+      return;
+    }
+
+    let filePath = await resolveFilePath({
+      name: fileName,
+      dir: path,
+      ext,
+      supportedLocales,
+      lang: req.ctx?.lang,
+      index,
+    });
+
+    emitLog(req.app, `Path: ${JSON.stringify(filePath)}`, {
+      req,
+      res,
+    });
+
+    if (!filePath) {
+      res.status(404).send(await req.app.renderStatus?.(req, res));
+
+      return;
+    }
+
+    let content = (await readFile(filePath)).toString();
+
+    for (let transformItem of transformSet)
+      content = await transformItem(req, res, {
+        content,
+        path: filePath,
+        name: basename(filePath, extname(filePath)),
+      });
+
+    res.send(content);
+  };
+};

package/src/controllers/unhandledError.ts

@@ -0,0 +1,15 @@
+import type { ErrorController } from "../types/ErrorController.ts";
+import { emitLog } from "../utils/emitLog.ts";
+
+export const unhandledError: ErrorController = () => async (err, req, res) => {
+  emitLog(req.app, "Unhandled error", {
+    level: "error",
+    data: err,
+    req,
+    res,
+  });
+
+  res
+    .status(500)
+    .send(await req.app.renderStatus?.(req, res, "unhandled_error"));
+};

package/src/controllers/unhandledRoute.ts

@@ -0,0 +1,14 @@
+import type { Controller } from "../types/Controller.ts";
+import { emitLog } from "../utils/emitLog.ts";
+
+export const unhandledRoute: Controller = () => async (req, res) => {
+  emitLog(req.app, "Unhandled route", {
+    level: "debug",
+    req,
+    res,
+  });
+
+  res
+    .status(404)
+    .send(await req.app.renderStatus?.(req, res, "unhandled_route"));
+};

package/src/lib/lang/getEffectiveLocale.ts

@@ -0,0 +1,52 @@
+import { toLanguage } from "./toLanguage.ts";
+
+type Match = {
+  index?: number;
+  locale?: string | undefined;
+};
+
+export function getEffectiveLocale(
+  preferredLocales: string[] | undefined,
+  supportedLocales: string[] | undefined,
+): string | undefined {
+  if (!supportedLocales || supportedLocales.length === 0) return undefined;
+
+  if (!preferredLocales || preferredLocales.length === 0)
+    return supportedLocales[0];
+
+  let exactMatch: Match = {};
+
+  for (let i = 0; i < preferredLocales.length && !exactMatch.locale; i++) {
+    let k = supportedLocales.indexOf(preferredLocales[i]);
+
+    if (k !== -1) {
+      exactMatch.index = i;
+      exactMatch.locale = supportedLocales[k];
+    }
+  }
+
+  let languageMatch: Match = {};
+
+  let supportedLanguages = supportedLocales.map(toLanguage);
+  let preferredLanguages = preferredLocales.map(toLanguage);
+
+  for (let i = 0; i < preferredLanguages.length && !languageMatch.locale; i++) {
+    let k = supportedLanguages.indexOf(preferredLanguages[i]);
+
+    if (k !== -1) {
+      languageMatch.index = i;
+      languageMatch.locale = supportedLocales[k];
+    }
+  }
+
+  // if both an exact match and a language match are found, prefer
+  // the one with an index closer to the beginning of the preferred
+  // locale list
+  if (
+    exactMatch.locale &&
+    (!languageMatch.locale || exactMatch.index! < languageMatch.index!)
+  )
+    return exactMatch.locale;
+
+  return languageMatch.locale ?? supportedLocales[0];
+}

package/src/lib/lang/getLocales.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses a language range string (typically a value of the 'Accept-Language'
+ * HTTP request header) and returns a corresponding array of locales
+ * @example 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'
+ */
+export function getLocales(languageRange: string | undefined): string[] {
+  return (languageRange ?? "")
+    .split(/[,;]\s*/)
+    .filter((s) => !s.startsWith("q=") && s !== "*");
+}

package/src/lib/lang/toLanguage.ts

@@ -0,0 +1,3 @@
+export function toLanguage(locale: string): string {
+  return locale.split(/[-_]/)[0];
+}

package/src/lib/logger/LogOptions.ts

@@ -0,0 +1,8 @@
+import type { Request } from "express";
+
+export type LogOptions = {
+  timestamp?: number;
+  level?: "debug" | "info" | "warn" | "error";
+  data?: unknown;
+  req?: Request;
+};

package/src/lib/logger/ansiEscapeCodes.ts

@@ -0,0 +1,6 @@
+export const ansiEscapeCodes: Record<string, string> = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+};

package/src/lib/logger/levelColors.ts

@@ -0,0 +1,4 @@
+export const levelColors: Record<string, string> = {
+  error: "red",
+  warn: "yellow",
+};

package/src/lib/logger/log.ts

@@ -0,0 +1,82 @@
+import { formatDate, formatDuration } from "dateshape";
+import { ansiEscapeCodes } from "./ansiEscapeCodes.ts";
+import type { LogOptions } from "./LogOptions.ts";
+import { levelColors } from "./levelColors.ts";
+
+function isEmpty(x: unknown) {
+  if (x === null || x === undefined || x === "") return true;
+  if (Array.isArray(x) && x.length === 0) return true;
+  if (typeof x === "object" && Object.keys(x).length === 0) return true;
+
+  return false;
+}
+
+export function log(
+  message: string | Error | undefined = "",
+  { timestamp, level, data, req }: LogOptions = {},
+): void {
+  let currentTime = timestamp ?? Date.now();
+  let error: Error | null = null;
+
+  if (message instanceof Error) {
+    error = message;
+    message = error.message;
+
+    data = {
+      error,
+      data,
+    };
+
+    if (!level) level = "error";
+  }
+
+  if (data instanceof Error) {
+    error = data;
+
+    if (data.message)
+      message = `${message ? `${message} - ` : ""}${data.message}`;
+
+    if (!level) level = "error";
+  }
+
+  if (!level) level = "info";
+
+  let levelCode = ansiEscapeCodes[levelColors[level]] ?? "";
+  let requestTarget = req ? `${req.method} ${req.originalUrl}` : "";
+
+  let { startTime, id: sessionId } = req?.ctx ?? {};
+
+  console[level]();
+
+  console[level](
+    levelCode +
+      ansiEscapeCodes.dim +
+      formatDate(currentTime, "{isoDate} {isoTimeMs} {tz}") +
+      (sessionId ? ` <${sessionId}>` : "") +
+      (startTime === undefined
+        ? ""
+        : ` +${formatDuration(currentTime - startTime)}`) +
+      ansiEscapeCodes.reset,
+  );
+
+  console[level](
+    levelCode +
+      requestTarget +
+      (requestTarget && message && !message.startsWith("\n") ? " - " : "") +
+      message +
+      ansiEscapeCodes.reset,
+  );
+
+  if (!isEmpty(data))
+    console[level](
+      levelCode +
+        ansiEscapeCodes.dim +
+        (typeof data === "string" ? data : JSON.stringify(data, null, 2)) +
+        ansiEscapeCodes.reset,
+    );
+
+  if (error?.stack)
+    console[level](
+      levelCode + ansiEscapeCodes.dim + error.stack + ansiEscapeCodes.reset,
+    );
+}

package/src/middleware/init.ts

@@ -0,0 +1,22 @@
+import { randomBytes } from "node:crypto";
+import type { Middleware } from "../types/Middleware.ts";
+import { emitLog } from "../utils/emitLog.ts";
+
+/**
+ * Initializes the request context on `req.ctx`.
+ */
+export const init: Middleware = () => (req, res, next) => {
+  req.ctx = {
+    ...req.ctx,
+    id: randomBytes(16).toString("hex"),
+    nonce: randomBytes(8).toString("hex"),
+    startTime: Date.now(),
+  };
+
+  emitLog(req.app, "Inited", {
+    req,
+    res,
+  });
+
+  next();
+};

package/src/middleware/lang.ts

@@ -0,0 +1,83 @@
+import type { CookieOptions } from "express";
+import { getEffectiveLocale } from "../lib/lang/getEffectiveLocale.ts";
+import { getLocales } from "../lib/lang/getLocales.ts";
+import { toLanguage } from "../lib/lang/toLanguage.ts";
+import type { Middleware } from "../types/Middleware.ts";
+import { emitLog } from "../utils/emitLog.ts";
+
+const defaultLangCookieOptions: CookieOptions = {
+  maxAge: 90 * 86_400_000,
+};
+
+export type LangParams = {
+  supportedLocales?: string[];
+  shouldSetCookie?: boolean;
+  shouldRedirect?: boolean;
+  langCookieOptions?: CookieOptions;
+};
+
+export const lang: Middleware<LangParams | void> = ({
+  supportedLocales = [],
+  shouldSetCookie = true,
+  shouldRedirect = true,
+  langCookieOptions = defaultLangCookieOptions,
+} = {}) => {
+  let langSet = new Set(supportedLocales.map(toLanguage));
+  let localeSet = new Set(supportedLocales);
+
+  return (req, res, next) => {
+    let langParam = req.query.lang as string[] | string | undefined;
+    let lang = (Array.isArray(langParam) ? langParam[0] : langParam) ?? "";
+
+    if (localeSet.has(lang) || langSet.has(lang)) {
+      if (shouldSetCookie) {
+        emitLog(req.app, `Set lang cookie: ${JSON.stringify(lang)}`, {
+          req,
+          res,
+        });
+
+        res.cookie("lang", lang, langCookieOptions);
+      }
+
+      if (shouldRedirect) {
+        let { originalUrl } = req;
+        let nextUrl = originalUrl.replace(/[?&]lang=[^&]+/g, "");
+
+        if (nextUrl !== originalUrl) {
+          emitLog(req.app, "Strip lang param and redirect", {
+            req,
+            res,
+          });
+
+          res.redirect(nextUrl);
+          return;
+        }
+      }
+    }
+
+    let langCookie = shouldSetCookie
+      ? (req.cookies.lang as string | undefined)
+      : undefined;
+
+    let userAgentLocales = getLocales(req.get("accept-language"));
+    let preferredLocales = langCookie
+      ? [langCookie, ...userAgentLocales]
+      : userAgentLocales;
+
+    let effectiveLang = getEffectiveLocale(preferredLocales, supportedLocales);
+
+    if (req.ctx && effectiveLang) req.ctx.lang = effectiveLang;
+
+    emitLog(req.app, `Detected lang: ${JSON.stringify(effectiveLang)}`, {
+      req,
+      res,
+      data: {
+        userAgentLocales,
+        langCookie,
+        lang: effectiveLang,
+      },
+    });
+
+    next();
+  };
+};

package/src/middleware/requestEvents.ts

@@ -0,0 +1,29 @@
+import type { Middleware } from "../types/Middleware.ts";
+import { emitLog } from "../utils/emitLog.ts";
+import { getStatusMessage } from "../utils/getStatusMessage.ts";
+
+/**
+ * Adds event handlers, like logging, to essential request phases.
+ */
+export const requestEvents: Middleware = () => (req, res, next) => {
+  let finished = false;
+
+  res.on("finish", () => {
+    finished = true;
+
+    emitLog(req.app, getStatusMessage("Finished", res.statusCode), {
+      req,
+      res,
+    });
+  });
+
+  res.on("close", () => {
+    if (!finished)
+      emitLog(req.app, getStatusMessage("Closed", res.statusCode), {
+        req,
+        res,
+      });
+  });
+
+  next();
+};

package/src/scripts/bin/build.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { cli } from "../cli.ts";
+
+// Runs the build script with custom arguments.
+await cli(process.argv.slice(2));

package/src/scripts/bin/startDev.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { start } from "../start.ts";
+
+// Runs the build script with a development preset.
+await start("development", process.argv[2]);

package/src/scripts/bin/startProd.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { start } from "../start.ts";
+
+// Runs the build script with a production preset.
+await start("production", process.argv[2]);

package/src/scripts/build.ts

@@ -0,0 +1,45 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { formatDuration } from "dateshape";
+import type { BuildParams } from "./types/BuildParams.ts";
+import { buildClient } from "./utils/buildClient.ts";
+import { buildServer } from "./utils/buildServer.ts";
+import { buildServerCSS } from "./utils/buildServerCSS.ts";
+import { createPostbuildPlugins } from "./utils/createPostbuildPlugins.ts";
+
+export async function build(params: BuildParams) {
+  let startTime = Date.now();
+  let log = params.silent ? () => {} : console.log;
+
+  log("Build started");
+
+  let serverProcess: ChildProcess | null = null;
+  let inited = false;
+
+  function handleServerRebuild() {
+    if (serverProcess) {
+      serverProcess.kill();
+      serverProcess = null;
+    }
+
+    if (!inited) {
+      log(`Build completed +${formatDuration(Date.now() - startTime)}`);
+      inited = true;
+    }
+
+    if (params.start)
+      serverProcess = spawn("node", [`${params.targetDir}/server/index.js`], {
+        stdio: "inherit",
+      });
+  }
+
+  let { serverPlugins, serverCSSPlugins } = createPostbuildPlugins(
+    params,
+    handleServerRebuild,
+  );
+
+  await Promise.all([
+    buildServer(params, serverPlugins),
+    buildServerCSS(params, serverCSSPlugins),
+    buildClient(params),
+  ]);
+}

package/src/scripts/cli.ts

@@ -0,0 +1,46 @@
+import { rm } from "node:fs/promises";
+import { build } from "./build.ts";
+import type { BuildParams } from "./types/BuildParams.ts";
+
+const defaultTargetDir = "dist";
+
+async function clean({ targetDir, publicAssetsDir }: BuildParams) {
+  let dirs = [
+    `${targetDir}/server`,
+    `${targetDir}/server-css`,
+    `${publicAssetsDir}/-`,
+  ];
+
+  return Promise.all(
+    dirs.map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+}
+
+export async function cli(args: string[] = []) {
+  let publicAssetsDir = args[0];
+  let targetDir = args[1];
+
+  if (!publicAssetsDir || publicAssetsDir.startsWith("--"))
+    throw new Error("Public assets directory is undefined");
+
+  if (!targetDir || targetDir.startsWith("--")) targetDir = defaultTargetDir;
+
+  let params: BuildParams = {
+    targetDir,
+    publicAssetsDir,
+    silent: args.includes("--silent"),
+    watch: args.includes("--watch"),
+    watchServer: args.includes("--watch-server"),
+    watchClient: args.includes("--watch-client"),
+    start: args.includes("--start"),
+  };
+
+  if (args.includes("--clean-only")) {
+    await clean(params);
+    return;
+  }
+
+  if (args.includes("--clean")) await clean(params);
+
+  await build(params);
+}

package/src/scripts/const/commonBuildOptions.ts

@@ -0,0 +1,13 @@
+import type { BuildOptions } from "esbuild";
+
+export const commonBuildOptions: Partial<BuildOptions> = {
+  format: "cjs",
+  jsx: "automatic",
+  jsxDev: process.env.NODE_ENV === "development",
+  loader: {
+    ".png": "dataurl",
+    ".svg": "dataurl",
+    ".html": "text",
+    ".txt": "text",
+  },
+};

package/src/scripts/const/entryExtensions.ts

@@ -0,0 +1 @@
+export const entryExtensions = ["js", "jsx", "ts", "tsx"];

package/src/scripts/start.ts

@@ -0,0 +1,18 @@
+import { cli } from "./cli.ts";
+
+export async function start(nodeEnv = "development", host?: string) {
+  if (nodeEnv) process.env.NODE_ENV = nodeEnv;
+
+  if (host) {
+    let [hostname, port] = host.split(":");
+
+    if (hostname) process.env.APP_HOST = hostname;
+    if (port) process.env.APP_PORT = port;
+  }
+
+  await cli(
+    nodeEnv === "development"
+      ? ["src/public", "--clean", "--start", "--watch"]
+      : ["src/public", "--clean", "--start", "--silent"],
+  );
+}

package/src/scripts/types/BuildParams.ts

@@ -0,0 +1,9 @@
+export type BuildParams = {
+  targetDir: string;
+  publicAssetsDir: string;
+  silent?: boolean;
+  watch?: boolean;
+  watchClient?: boolean;
+  watchServer?: boolean;
+  start?: boolean;
+};

package/src/scripts/utils/buildClient.ts

@@ -0,0 +1,41 @@
+import esbuild, { type BuildOptions, type Plugin } from "esbuild";
+import { commonBuildOptions } from "../const/commonBuildOptions.ts";
+import type { BuildParams } from "../types/BuildParams.ts";
+import { getEntryPoints } from "./getEntryPoints.ts";
+
+/**
+ * Builds the client-side code from the 'src/entries/<entry_name>/ui'
+ * directories. The directories should preferrably be called 'ui' rather
+ * than client since their contents can also be used with the server-side
+ * rendering.
+ */
+export async function buildClient(
+  { publicAssetsDir, watch, watchClient }: BuildParams,
+  plugins?: Plugin[],
+) {
+  let clientEntries = await getEntryPoints(["ui/index"]);
+
+  let buildOptions: BuildOptions = {
+    ...commonBuildOptions,
+    entryPoints: clientEntries.map(({ path }) => path),
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    outdir: `${publicAssetsDir}/-`,
+    outbase: "src/entries",
+    minify: process.env.NODE_ENV !== "development",
+    plugins,
+  };
+
+  if (watch || watchClient) {
+    let ctx = await esbuild.context(buildOptions);
+
+    await ctx.watch();
+
+    return async () => {
+      await ctx.dispose();
+    };
+  }
+
+  await esbuild.build(buildOptions);
+}