appstage 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstage",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -15,10 +15,6 @@
     "shape": "npx codeshape",
     "typecheck": "npx codeshape typecheck"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/axtk/appstage.git"
-  },
   "author": "axtk",
   "license": "MIT",
   "peerDependencies": {
@@ -26,7 +22,7 @@
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
-    "@types/node": "^25.4.0"
+    "@types/node": "^25.9.2"
   },
   "dependencies": {
     "args-json": "^1.4.3",

package/src/controllers/files.ts

@@ -1,250 +0,0 @@
-import { lstat, readFile } from "node:fs/promises";
-import { basename, extname, join, resolve as resolveAbsPath } from "node:path";
-import type { Request } from "express";
-import type { Controller } from "../types/Controller.ts";
-import type { TransformContent } from "../types/TransformContent.ts";
-import { emitLog } from "../utils/emitLog.ts";
-
-type StringMatcher =
-  | string
-  | RegExp
-  | (string | RegExp)[]
-  | ((x: string) => boolean)
-  | null;
-
-const maxLanguages = 3;
-
-async function resolve(...parts: string[]) {
-  let fullPath = join(...parts);
-  try {
-    if ((await lstat(fullPath)).isFile()) return resolveAbsPath(fullPath);
-  } catch {}
-  return null;
-}
-
-// ["en-US", "ru"] > ["en-US", "en", "ru"]
-function getLanguageList(req: Request) {
-  let langParam = req.query.lang;
-
-  if (langParam) return [String(langParam)];
-
-  let acceptedLanguages = req.acceptsLanguages();
-  let langs = new Set<string>();
-
-  for (let i = 0; i < acceptedLanguages.length && i < maxLanguages; i++) {
-    let s = acceptedLanguages[i];
-    let [lang] = s.split(/[-_]/);
-
-    if (s === lang) langs.add(s);
-    else {
-      langs.add(s);
-      langs.add(lang);
-    }
-  }
-
-  return Array.from(langs);
-}
-
-function matches(x: string, matcher: StringMatcher | undefined) {
-  if (matcher === null || matcher === undefined) return true;
-
-  if (typeof matcher === "function") return matcher(x);
-
-  let patterns = Array.isArray(matcher) ? matcher : [matcher];
-
-  for (let pattern of patterns) {
-    if (pattern instanceof RegExp) {
-      if (pattern.test(x)) return true;
-    } else if (pattern === x) return true;
-  }
-
-  return false;
-}
-
-export type FilesParams = {
-  base: string | string[];
-  path?: string | ((req: Request) => string);
-  /** Specifies which paths should be accepted. */
-  matches?: StringMatcher;
-  /**
-   * @default ["html", "htm"]
-   */
-  extensions?: string[];
-  languages?: (req: Request) => string[];
-  /**
-   * Assumed file language if unspecified in the file name.
-   *
-   * @default "en"
-   */
-  defaultLanguage?: string | ((req: Request) => string);
-  transform?: TransformContent[];
-  fallthrough?: boolean;
-};
-
-const defaultExtensions = ["html", "htm"];
-const defaultPath = (req: Request) => decodeURIComponent(req.path);
-
-/**
- * Serves files from the specified directory path or paths in a locale-aware
- * fashion after applying optional transforms.
- */
-export const files: Controller<string | FilesParams> = (params) => {
-  let p: FilesParams = typeof params === "string" ? { base: params } : params;
-
-  let bases = Array.isArray(p.base) ? p.base : [p.base];
-  let exts = p.extensions ?? defaultExtensions;
-  let fallthrough = p.fallthrough ?? true;
-
-  return async (req, res, next) => {
-    let urlPath =
-      typeof p.path === "string" ? p.path : (p.path ?? defaultPath)(req);
-
-    let defaultLanguage =
-      typeof p.defaultLanguage === "function"
-        ? p.defaultLanguage(req)
-        : (p.defaultLanguage ?? "en");
-
-    if (!matches(urlPath, p.matches)) {
-      if (fallthrough) next();
-      else {
-        emitLog(req.app, "Unmatched path", {
-          data: { urlPath },
-          req,
-          res,
-        });
-
-        res.status(404).send(
-          await req.app.renderStatus?.(req, res, {
-            code: "unmatched_path",
-            urlPath,
-          }),
-        );
-      }
-
-      return;
-    }
-
-    if (urlPath.includes("../")) {
-      if (fallthrough) next();
-      else {
-        emitLog(req.app, "Invalid path (potential traversal attempt)", {
-          data: { urlPath },
-          req,
-          res,
-        });
-
-        res.status(400).send(
-          await req.app.renderStatus?.(req, res, {
-            code: "invalid_path",
-            urlPath,
-          }),
-        );
-      }
-
-      return;
-    }
-
-    let filePath: string | null = null;
-    let urlExt = extname(urlPath);
-
-    let langs = (p.languages ?? getLanguageList)(req);
-    let defaultLanguageIndex = langs.indexOf(defaultLanguage);
-
-    let suffixes = langs.map((s) => `.${s}`);
-
-    // Check the suffixless path right after the default language suffix.
-    if (defaultLanguageIndex === -1) suffixes.push("");
-    else suffixes.splice(defaultLanguageIndex + 1, 0, "");
-
-    // Example:
-    // path = /x, langs = [en, ru], default lang: en, exts = [html, htm]
-    for (let k = 0; k < bases.length && filePath === null; k++) {
-      let base = bases[k];
-
-      if (!urlPath.endsWith("/")) {
-        if (filePath === null && urlExt) {
-          let urlPathBase = urlPath.slice(0, -urlExt.length);
-
-          // /x.en.ext /x.ext /x.ru.ext
-          for (let i = 0; i < suffixes.length && filePath === null; i++)
-            filePath = await resolve(
-              base,
-              `${urlPathBase}${suffixes[i]}${urlExt}`,
-            );
-        }
-
-        // /x.en /x /x.ru
-        for (let i = 0; i < suffixes.length && filePath === null; i++)
-          filePath = await resolve(base, `${urlPath}${suffixes[i]}`);
-
-        // /x.en.html /x.en.htm /x.html /x.htm /x.ru.html /x.ru.htm
-        for (let i = 0; i < suffixes.length && filePath === null; i++) {
-          for (let j = 0; j < exts.length && filePath === null; j++)
-            filePath = await resolve(
-              base,
-              `${urlPath}${suffixes[i]}.${exts[j]}`,
-            );
-        }
-      }
-
-      // /x/index.en.html /x/index.en.htm /x/index.html /x/index.htm /x/index.ru.html /x/index.ru.htm
-      for (let i = 0; i < suffixes.length && filePath === null; i++) {
-        for (let j = 0; j < exts.length && filePath === null; j++)
-          filePath = await resolve(
-            base,
-            urlPath,
-            `index${suffixes[i]}.${exts[j]}`,
-          );
-      }
-    }
-
-    if (filePath === null) {
-      if (fallthrough) next();
-      else {
-        emitLog(req.app, "Unknown path", {
-          data: { urlPath },
-          req,
-          res,
-        });
-
-        res.status(404).send(
-          await req.app.renderStatus?.(req, res, {
-            code: "unknown_path",
-            urlPath,
-          }),
-        );
-      }
-
-      return;
-    }
-
-    emitLog(req.app, "File path resolved", {
-      data: {
-        filePath,
-      },
-      req,
-      res,
-    });
-
-    if (!p.transform?.length) {
-      res.sendFile(filePath);
-      return;
-    }
-
-    let content = (await readFile(filePath)).toString();
-    let fileExt = extname(filePath);
-    let fileName = basename(filePath, fileExt);
-
-    for (let transform of p.transform) {
-      let result = transform(req, res, {
-        content,
-        path: filePath,
-        name: fileName,
-      });
-
-      content = result instanceof Promise ? await result : result;
-    }
-
-    res.type(fileExt.slice(1)).send(content);
-  };
-};

package/src/controllers/redirect.ts

@@ -1,29 +0,0 @@
-import type { Controller } from "../types/Controller.ts";
-import { emitLog } from "../utils/emitLog.ts";
-
-export type RedirectParams = {
-  url: string;
-  status?: number;
-};
-
-export const redirect: Controller<string | RedirectParams> = (params) => {
-  let { url, status = 302 } =
-    typeof params === "string" ? { url: params } : params;
-
-  return (req, res) => {
-    let search = req.originalUrl.split("?")[1] ?? "";
-
-    if (search) search = `${url.includes("?") ? "&" : "?"}${search}`;
-
-    emitLog(req.app, "Redirecting", {
-      data: {
-        from: req.originalUrl,
-        to: `${url}${search}`,
-      },
-      req,
-      res,
-    });
-
-    res.redirect(status, `${url}${search}`);
-  };
-};

package/src/controllers/unhandledError.ts

@@ -1,15 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,10 +0,0 @@
-/**
- * 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

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

package/src/lib/logger/LogOptions.ts

@@ -1,8 +0,0 @@
-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

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

package/src/lib/logger/levelColors.ts

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

package/src/lib/logger/log.ts

@@ -1,82 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,83 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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.ts

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-import { hasKey, isKey } from "args-json";
-import { cli } from "./cli.ts";
-
-const availableScriptNames = new Set(["build", "dev", "prod"]);
-
-const nodeEnvMap: Record<string, string> = {
-  dev: "development",
-  prod: "production",
-};
-
-async function run() {
-  let [scriptName, ...args] = process.argv.slice(2);
-
-  if (!availableScriptNames.has(scriptName)) {
-    console.error("Provide a script name: 'build', 'dev', or 'prod'");
-    return;
-  }
-
-  if (scriptName === "build") return await cli(args);
-
-  let nodeEnv = nodeEnvMap[scriptName];
-
-  if (nodeEnv !== undefined) process.env.NODE_ENV = nodeEnv;
-
-  if (args.length !== 0 && args[0] && !isKey(args[0])) {
-    process.env.SERVER_URL = args[0];
-    args.shift();
-  }
-
-  if (!hasKey("--client-dir")) args.push("--client-dir", "src/public/-");
-
-  await cli(
-    nodeEnv === "development"
-      ? ["--clean", "--start", "--watch", ...args]
-      : ["--clean", "--start", "--silent", ...args],
-  );
-}
-
-await run();