appstage 0.2.1

package/src/scripts/utils/buildServer.ts

@@ -0,0 +1,35 @@
+import esbuild, { type BuildOptions, type Plugin } from "esbuild";
+import { commonBuildOptions } from "../const/commonBuildOptions.ts";
+import type { BuildParams } from "../types/BuildParams.ts";
+import { populateEntries } from "./populateEntries.ts";
+
+export async function buildServer(
+  { targetDir, watch, watchServer }: BuildParams,
+  plugins?: Plugin[],
+) {
+  await populateEntries();
+
+  let buildOptions: BuildOptions = {
+    ...commonBuildOptions,
+    entryPoints: ["src/server/index.ts"],
+    bundle: true,
+    splitting: true,
+    outdir: `${targetDir}/server`,
+    platform: "node",
+    format: "esm",
+    packages: "external",
+    plugins,
+  };
+
+  if (watch || watchServer) {
+    let ctx = await esbuild.context(buildOptions);
+
+    await ctx.watch();
+
+    return async () => {
+      await ctx.dispose();
+    };
+  }
+
+  await esbuild.build(buildOptions);
+}

package/src/scripts/utils/buildServerCSS.ts

@@ -0,0 +1,38 @@
+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";
+
+export async function buildServerCSS(
+  { targetDir, watch, watchServer }: BuildParams,
+  plugins?: Plugin[],
+) {
+  let serverEntries = await getEntryPoints(["server", "server/index"]);
+
+  let buildOptions: BuildOptions = {
+    ...commonBuildOptions,
+    entryPoints: serverEntries.map(({ name, path }) => ({
+      in: path,
+      out: name,
+    })),
+    bundle: true,
+    splitting: false,
+    outdir: `${targetDir}/server-css`,
+    platform: "node",
+    format: "esm",
+    packages: "external",
+    plugins,
+  };
+
+  if (watch || watchServer) {
+    let ctx = await esbuild.context(buildOptions);
+
+    await ctx.watch();
+
+    return async () => {
+      await ctx.dispose();
+    };
+  }
+
+  await esbuild.build(buildOptions);
+}

package/src/scripts/utils/createPostbuildPlugins.ts

@@ -0,0 +1,66 @@
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import type { Plugin } from "esbuild";
+import type { BuildParams } from "../types/BuildParams.ts";
+
+export function createPostbuildPlugins(
+  { targetDir, publicAssetsDir }: BuildParams,
+  onServerRebuild: () => void,
+) {
+  let serverPlugins: Plugin[] = [
+    {
+      name: "skip-css",
+      setup(build) {
+        /** @see https://github.com/evanw/esbuild/issues/599#issuecomment-745118158 */
+        build.onLoad({ filter: /\.css$/ }, () => ({ contents: "" }));
+      },
+    },
+    {
+      name: "postbuild-server",
+      setup(build) {
+        build.onEnd(() => {
+          onServerRebuild();
+        });
+      },
+    },
+  ];
+
+  let serverCSSPlugins: Plugin[] = [
+    {
+      name: "postbuild-server-css",
+      setup(build) {
+        build.onEnd(async () => {
+          let dir = `${targetDir}/server-css`;
+
+          try {
+            let files = (await readdir(dir)).filter((name) =>
+              name.endsWith(".css"),
+            );
+
+            if (files.length === 0) return;
+
+            await mkdir(`${publicAssetsDir}/-`, { recursive: true });
+
+            await Promise.all(
+              files.map(async (name) => {
+                let dir = `${publicAssetsDir}/-/${name.slice(0, -4)}`;
+
+                await mkdir(dir, { recursive: true });
+                await rename(
+                  `${targetDir}/server-css/${name}`,
+                  `${dir}/index.css`,
+                );
+              }),
+            );
+
+            await rm(dir, { recursive: true, force: true });
+          } catch {}
+        });
+      },
+    },
+  ];
+
+  return {
+    serverPlugins,
+    serverCSSPlugins,
+  };
+}

package/src/scripts/utils/getEntries.ts

@@ -0,0 +1,22 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function getEntries() {
+  let cwd = process.cwd();
+
+  try {
+    let list = await readdir(join(cwd, "src/entries"));
+
+    let dirs = await Promise.all(
+      list.map(async (name) => {
+        let itemStat = await lstat(join(cwd, "src/entries", name));
+
+        return itemStat.isDirectory() ? name : undefined;
+      }),
+    );
+
+    return dirs.filter((dir) => dir !== undefined);
+  } catch {
+    return [];
+  }
+}

package/src/scripts/utils/getEntryPoints.ts

@@ -0,0 +1,25 @@
+import { getEntries } from "./getEntries.ts";
+import { getFirstAvailable } from "./getFirstAvailable.ts";
+
+type EntryPoint = {
+  name: string;
+  path: string;
+};
+
+export async function getEntryPoints(
+  path: string | string[],
+): Promise<EntryPoint[]> {
+  let entries = await getEntries();
+
+  return (
+    await Promise.all(
+      entries.map(async (name) => {
+        let resolvedPath = await getFirstAvailable(`src/entries/${name}`, path);
+
+        return resolvedPath === undefined
+          ? undefined
+          : { name, path: resolvedPath };
+      }),
+    )
+  ).filter((item) => item !== undefined);
+}

package/src/scripts/utils/getFirstAvailable.ts

@@ -0,0 +1,22 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { entryExtensions } from "../const/entryExtensions.ts";
+
+export async function getFirstAvailable(
+  dirPath: string,
+  path: string | string[],
+) {
+  let paths = Array.isArray(path) ? path : [path];
+
+  for (let filePath of paths) {
+    for (let ext of entryExtensions) {
+      let path = join(process.cwd(), dirPath, `${filePath}.${ext}`);
+
+      try {
+        await access(path);
+
+        return path;
+      } catch {}
+    }
+  }
+}

package/src/scripts/utils/populateEntries.ts

@@ -0,0 +1,28 @@
+import { writeFile } from "node:fs/promises";
+import { getEntryPoints } from "./getEntryPoints.ts";
+import { toImportPath } from "./toImportPath.ts";
+
+export async function populateEntries() {
+  let serverEntries = await getEntryPoints(["server", "server/index"]);
+  let content = "";
+
+  if (serverEntries.length === 0) content = "export const entries = [];";
+  else {
+    content = "export const entries = (\n  await Promise.all([";
+
+    for (let i = 0; i < serverEntries.length; i++) {
+      content += `\n    // ${serverEntries[i].name}
+    import("${toImportPath(serverEntries[i].path, "src/server")}"),`;
+    }
+
+    content += "\n  ])\n).map(({ server }) => server);";
+  }
+
+  await writeFile(
+    "src/server/entries.ts",
+    `// Populated automatically during the build phase by picking
+// all server exports from 'src/entries/<entry_name>/server(/index)?.(js|ts)'
+${content}
+`,
+  );
+}

package/src/scripts/utils/toImportPath.ts

@@ -0,0 +1,12 @@
+import { join, posix, relative, sep } from "node:path";
+
+export function toImportPath(relativePath: string, referencePath = ".") {
+  let cwd = process.cwd();
+  let importPath = posix.join(
+    ...relative(join(cwd, referencePath), relativePath).split(sep),
+  );
+
+  if (importPath && !/^\.+\//.test(importPath)) importPath = `./${importPath}`;
+
+  return importPath;
+}

package/src/types/Controller.ts

@@ -0,0 +1,4 @@
+import type { RequestHandler } from "express";
+
+/** Defines a final request handler sending a response */
+export type Controller<T = void> = (params: T) => RequestHandler;

package/src/types/ErrorController.ts

@@ -0,0 +1,3 @@
+import type { ErrorRequestHandler } from "express";
+
+export type ErrorController<T = void> = (params: T) => ErrorRequestHandler;

package/src/types/LogEventPayload.ts

@@ -0,0 +1,12 @@
+import type { Request, Response } from "express";
+import type { LogLevel } from "./LogLevel.ts";
+
+export type LogEventPayload = {
+  timestamp?: number;
+  level?: LogLevel;
+  message?: string | Error;
+  status?: number;
+  req?: Request;
+  res?: Response;
+  data?: unknown;
+};

package/src/types/LogLevel.ts

@@ -0,0 +1 @@
+export type LogLevel = "error" | "debug" | "info" | "warn";

package/src/types/Middleware.ts

@@ -0,0 +1,7 @@
+import type { RequestHandler } from "express";
+
+/**
+ * Defines an intermediate request handler performing manipulations
+ * with request data without sending a response
+ */
+export type Middleware<T = void> = (params: T) => RequestHandler;

package/src/types/MiddlewareSet.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from "express";
+
+export type MiddlewareSet<T = void> = (params: T) => RequestHandler[];

package/src/types/RenderStatus.ts

@@ -0,0 +1,9 @@
+import type { Request, Response } from "express";
+
+type SendParam = Parameters<Response["send"]>[0];
+
+export type RenderStatus = (
+  req: Request,
+  res: Response,
+  payload?: unknown,
+) => Promise<SendParam>;

package/src/types/ReqCtx.ts

@@ -0,0 +1,11 @@
+/** Session request data collected on the server via `req.ctx` */
+export type ReqCtx = {
+  /** Request ID */
+  id?: string;
+  /** CSP nonce */
+  nonce?: string;
+  /** When the request started to be handled */
+  startTime?: number;
+  /** User locale */
+  lang?: string;
+};

package/src/types/TransformContent.ts

@@ -0,0 +1,11 @@
+import type { Request, Response } from "express";
+
+export type TransformContent = (
+  req: Request,
+  res: Response,
+  params: {
+    content: string;
+    path?: string;
+    name?: string;
+  },
+) => string | Promise<string>;

package/src/types/express.d.ts

@@ -0,0 +1,15 @@
+import EventEmitter from "node:events";
+import type { RenderStatus } from "../types/RenderStatus.ts";
+import type { ReqCtx } from "./ReqCtx.ts";
+
+declare global {
+  namespace Express {
+    interface Request {
+      ctx: ReqCtx;
+    }
+    interface Application {
+      events?: EventEmitter;
+      renderStatus?: RenderStatus;
+    }
+  }
+}

package/src/types/global.d.ts

@@ -0,0 +1,17 @@
+declare module "*.svg" {
+  let content: string;
+
+  export default content;
+}
+
+declare module "*.txt" {
+  let content: string;
+
+  export default content;
+}
+
+declare module "*.html" {
+  let content: string;
+
+  export default content;
+}

package/src/utils/createApp.ts

@@ -0,0 +1,44 @@
+import EventEmitter from "node:events";
+import express from "express";
+import { log } from "../lib/logger/log.ts";
+import { init } from "../middleware/init.ts";
+import { requestEvents } from "../middleware/requestEvents.ts";
+import type { LogEventPayload } from "../types/LogEventPayload.ts";
+import { emitLog } from "./emitLog.ts";
+import { renderStatus } from "./renderStatus.ts";
+
+export function createApp(callback?: () => void | Promise<void>) {
+  let app = express();
+
+  if (!app.events) app.events = new EventEmitter();
+
+  let host = process.env.APP_HOST || "localhost";
+  let port = Number(process.env.APP_PORT) || 80;
+
+  let listen = () => {
+    app.listen(port, host, () => {
+      let location = `http://${host}:${port}/`;
+      let env = `NODE_ENV=${process.env.NODE_ENV}`;
+
+      emitLog(app, `Server running at ${location} (${env})`);
+    });
+  };
+
+  if (process.env.NODE_ENV === "development")
+    app.events?.on("log", ({ message, ...payload }: LogEventPayload) => {
+      log(message, payload);
+    });
+
+  if (!app.renderStatus) app.renderStatus = renderStatus;
+
+  app.disable("x-powered-by");
+  app.use(init());
+  app.use(requestEvents());
+
+  let callbackResult = typeof callback === "function" ? callback() : null;
+
+  if (callbackResult instanceof Promise) callbackResult.then(listen);
+  else listen();
+
+  return app;
+}

package/src/utils/cspNonce.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage } from "node:http";
+import type { Request } from "express";
+
+export const cspNonce = (req: IncomingMessage) => {
+  return `'nonce-${(req as Request).ctx?.nonce}'`;
+};

package/src/utils/emitLog.ts

@@ -0,0 +1,18 @@
+import type { Application } from "express";
+import type { LogEventPayload } from "../types/LogEventPayload.ts";
+
+export function emitLog(
+  app: Application,
+  message?: LogEventPayload["message"] | LogEventPayload,
+  payload?: LogEventPayload,
+) {
+  let normalizedPayload: LogEventPayload = {
+    timestamp: Date.now(),
+    ...payload,
+    ...(typeof message === "string" || message instanceof Error
+      ? { message }
+      : message),
+  };
+
+  return app.events?.emit("log", normalizedPayload);
+}

package/src/utils/getEntries.ts

@@ -0,0 +1,22 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function getEntries() {
+  let cwd = process.cwd();
+
+  try {
+    let list = await readdir(join(cwd, "src/entries"));
+
+    let dirs = await Promise.all(
+      list.map(async (name) => {
+        let itemStat = await lstat(join(cwd, "src/entries", name));
+
+        return itemStat.isDirectory() ? name : undefined;
+      }),
+    );
+
+    return dirs.filter((dir) => dir !== undefined);
+  } catch {
+    return [];
+  }
+}

package/src/utils/getStatusMessage.ts

@@ -0,0 +1,5 @@
+import { STATUS_CODES } from "node:http";
+
+export function getStatusMessage(prefix: string, statusCode: number) {
+  return `${prefix} - [${statusCode}] ${STATUS_CODES[statusCode]}`;
+}

package/src/utils/injectNonce.ts

@@ -0,0 +1,7 @@
+import type { TransformContent } from "../types/TransformContent.ts";
+
+export const injectNonce: TransformContent = (req, _res, { content }) => {
+  let { nonce } = req.ctx;
+
+  return nonce ? content.replace(/\{\{nonce\}\}/g, nonce) : content;
+};

package/src/utils/renderStatus.ts

@@ -0,0 +1,20 @@
+import { STATUS_CODES } from "node:http";
+import type { RenderStatus } from "../types/RenderStatus.ts";
+
+export const renderStatus: RenderStatus = async (req, res) => {
+  let { id, nonce } = req.ctx;
+  let statusText = `${res.statusCode} ${STATUS_CODES[res.statusCode]}`;
+  let date = `${new Date().toISOString().replace(/T/, " ").replace(/Z$/, "")} UTC`;
+
+  return (
+    "<!DOCTYPE html>" +
+    '<html><head><meta charset="utf-8"/>' +
+    '<meta name="viewport" content="width=device-width"/>' +
+    `<title>${statusText}</title>` +
+    `<style${nonce ? ` nonce="${nonce}"` : ""}>` +
+    "body{text-align:center;}</style></head>" +
+    `<body><h1>${statusText}</h1><hr/><p>` +
+    (id ? `<code>ID: ${id}</code><br/>` : "") +
+    `<code>${date}</code></p></body></html>`
+  );
+};

package/src/utils/resolveFilePath.ts

@@ -0,0 +1,78 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { toLanguage } from "../lib/lang/toLanguage.ts";
+
+export type ResolveFilePathParams = {
+  name: string;
+  dir?: string;
+  lang?: string;
+  supportedLocales?: string[];
+  /** Allowed file extensions. */
+  ext?: string | string[];
+  /**
+   * Whether an index file should be checked if the resolved file name
+   * doesn't correspond to an existing file.
+   *
+   * @defaultValue `true`
+   */
+  index?: boolean;
+};
+
+export async function resolveFilePath({
+  name,
+  dir = ".",
+  lang,
+  supportedLocales = [],
+  ext,
+  index,
+}: ResolveFilePathParams) {
+  let cwd = process.cwd();
+
+  let localeSet = new Set(supportedLocales);
+  let langSet = new Set(supportedLocales.map(toLanguage));
+
+  let availableNames = [
+    name,
+    ...[...localeSet, ...langSet].map((item) => `${name}.${item}`),
+  ];
+
+  let preferredLangNames: string[] | undefined;
+
+  if (
+    lang &&
+    (!supportedLocales.length || localeSet.has(lang) || langSet.has(lang))
+  )
+    preferredLangNames = [`${name}.${lang}`, `${name}.${toLanguage(lang)}`];
+
+  let names = new Set(
+    preferredLangNames
+      ? [...preferredLangNames, ...availableNames]
+      : availableNames,
+  );
+
+  let exts = Array.isArray(ext) ? ext : [ext];
+
+  for (let item of names) {
+    for (let itemExt of exts) {
+      let path = join(cwd, dir, `${item}${itemExt ? `.${itemExt}` : ""}`);
+
+      try {
+        await access(path);
+        return path;
+      } catch {}
+    }
+  }
+
+  if (index) {
+    for (let item of names) {
+      for (let itemExt of exts) {
+        let path = join(cwd, dir, item, `index${itemExt ? `.${itemExt}` : ""}`);
+
+        try {
+          await access(path);
+          return path;
+        } catch {}
+      }
+    }
+  }
+}

package/src/utils/serializeState.ts

@@ -0,0 +1,3 @@
+export function serializeState(state: unknown) {
+  return JSON.stringify(state).replace(/</g, "\\x3c");
+}

package/src/utils/servePipeableStream.ts

@@ -0,0 +1,32 @@
+import type { Request, Response } from "express";
+import { emitLog } from "./emitLog.ts";
+import { getStatusMessage } from "./getStatusMessage.ts";
+
+type PipeableStream = {
+  pipe: <Writable extends NodeJS.WritableStream>(
+    destination: Writable,
+  ) => Writable;
+};
+
+export function servePipeableStream(req: Request, res: Response) {
+  return async ({ pipe }: PipeableStream, error?: unknown) => {
+    let statusCode = error ? 500 : 200;
+
+    emitLog(req.app, getStatusMessage("Stream", statusCode), {
+      level: error ? "error" : undefined,
+      req,
+      res,
+      data: error,
+    });
+
+    res.status(statusCode);
+
+    if (statusCode >= 400) {
+      res.send(await req.app.renderStatus?.(req, res));
+      return;
+    }
+
+    res.set("Content-Type", "text/html");
+    pipe(res);
+  };
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "include": ["./index.ts", "./src"],
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}