@stacksjs/error-handling 0.70.88 → 0.70.91

package/dist/error-page-template.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Escape HTML special characters
+ */
+export declare function escapeHtml(str: string): string;
+/**
+ * Read source lines around a stack frame for the code snippet panel.
+ */
+export declare function readCodeSnippet(filePath: string, line: number, radius?: number): CodeSnippetResult | null;
+export declare function renderCodeSnippet(snippet: CodeSnippetResult): string;
+export declare function renderTraceFrame(frame: ParsedFrame, index: number, snippetLines: number): string;
+export declare function renderVendorGroup(frames: ParsedFrame[], snippetLines: number): string;
+export declare function groupTraceFrames(frames: ParsedFrame[]): Array<ParsedFrame | ParsedFrame[]>;
+export declare function renderExceptionTrace(frames: ParsedFrame[], snippetLines: number): string;
+export declare function renderContextTabs(opts: {
+  request?: RequestContext
+  routing?: RoutingContext
+  user?: UserContext
+  queries?: QueryInfo[]
+  showEnvironment?: boolean
+}): string;
+export declare function buildErrorMarkdown(opts: {
+  statusTitle: string
+  errorName: string
+  errorMessage: string
+  status: number
+  file?: string
+  line?: number
+  request?: RequestContext
+  framework?: { name: string, version?: string }
+  frames: ParsedFrame[]
+}): string;
+export declare function wrapErrorPage(body: string, markdown: string): string;
+export declare const ERROR_PAGE_SCRIPT: string;
+export declare interface ParsedFrame {
+  file: string
+  line: number
+  column?: number
+  function?: string
+  absoluteFile: string
+  isFramework: boolean
+}
+declare interface QueryInfo {
+  query: string
+  time?: number
+  connection?: string
+}
+declare interface RequestContext {
+  method: string
+  url: string
+  headers: Record<string, string>
+  queryParams?: Record<string, string>
+  body?: unknown
+}
+declare interface RoutingContext {
+  controller?: string
+  routeName?: string
+  middleware?: string[]
+}
+declare interface UserContext {
+  id?: string | number
+  email?: string
+  name?: string
+}
+export declare interface CodeSnippetResult {
+  lines: Array<{ number: number, content: string, highlight: boolean }>
+}

package/dist/error-page-template.js

@@ -0,0 +1,224 @@
+var {require}=import.meta;import { ERROR_PAGE_CSS } from "./error-page-styles";
+export function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+export function readCodeSnippet(filePath, line, radius = 6) {
+  try {
+    const fs = require("node:fs");
+    if (!filePath || !fs.existsSync(filePath))
+      return null;
+    const allLines = fs.readFileSync(filePath, "utf-8").split(`
+`), start = Math.max(0, line - radius - 1), end = Math.min(allLines.length, line + radius);
+    return {
+      lines: allLines.slice(start, end).map((code, i) => ({
+        number: start + i + 1,
+        content: code,
+        highlight: start + i + 1 === line
+      }))
+    };
+  } catch {
+    return null;
+  }
+}
+export function renderCodeSnippet(snippet) {
+  return `<div class="code-block">${snippet.lines.map((l) => `
+    <div class="code-line${l.highlight ? " highlight" : ""}">
+      <span class="code-ln">${l.number}</span>
+      <span class="code-txt">${escapeHtml(l.content || " ")}</span>
+    </div>`).join("")}
+  </div>`;
+}
+export function renderTraceFrame(frame, index, snippetLines) {
+  const snippet = readCodeSnippet(frame.absoluteFile, frame.line, snippetLines), snippetHtml = snippet ? renderCodeSnippet(snippet) : "";
+  return `<div class="trace-frame${index === 0 ? " expanded" : ""}" data-frame>
+    <div class="trace-frame-header" onclick="this.parentElement.classList.toggle('expanded')">
+      <span class="trace-frame-fn">${escapeHtml(frame.function || "<anonymous>")}</span>
+      <span class="trace-frame-file">${escapeHtml(frame.file)}:${frame.line}</span>
+    </div>
+    ${snippetHtml ? `<div class="trace-frame-body">${snippetHtml}</div>` : ""}
+  </div>`;
+}
+export function renderVendorGroup(frames, snippetLines) {
+  const count = frames.length, label = count === 1 ? "1 framework frame" : `${count} framework frames`, inner = frames.map((f, i) => renderTraceFrame(f, i + 1, snippetLines)).join("");
+  return `<div class="trace-vendor" data-vendor-group>
+    <div class="trace-vendor-toggle" onclick="this.parentElement.classList.toggle('expanded')">
+      <span>${escapeHtml(label)}</span>
+    </div>
+    <div class="trace-vendor-frames">${inner}</div>
+  </div>`;
+}
+export function groupTraceFrames(frames) {
+  const groups = [];
+  let vendorBatch = [];
+  const flushVendor = () => {
+    if (vendorBatch.length > 0) {
+      groups.push(vendorBatch.length === 1 ? vendorBatch[0] : [...vendorBatch]);
+      vendorBatch = [];
+    }
+  };
+  for (const frame of frames)
+    if (frame.isFramework)
+      vendorBatch.push(frame);
+    else {
+      flushVendor();
+      groups.push(frame);
+    }
+  flushVendor();
+  return groups;
+}
+export function renderExceptionTrace(frames, snippetLines) {
+  if (frames.length === 0)
+    return "";
+  return `<section class="trace">
+    <h2 class="trace-title">Exception trace</h2>
+    ${groupTraceFrames(frames).map((group, i) => {
+    if (Array.isArray(group))
+      return renderVendorGroup(group, snippetLines);
+    return renderTraceFrame(group, i, snippetLines);
+  }).join("")}
+  </section>`;
+}
+export function renderContextTabs(opts) {
+  const tabs = [];
+  if (opts.request) {
+    const headerRows = Object.entries(opts.request.headers).map(([k, v]) => `<tr><td>${escapeHtml(k)}</td><td>${escapeHtml(v)}</td></tr>`).join("");
+    tabs.push({
+      id: "headers",
+      label: "Headers",
+      html: headerRows ? `<table class="kv-table">${headerRows}</table>` : '<p style="color:var(--neutral-500);font-size:0.875rem">No headers</p>'
+    });
+    const bodyContent = opts.request.body ? `<div class="json-block">${escapeHtml(JSON.stringify(opts.request.body, null, 2))}</div>` : '<p style="color:var(--neutral-500);font-size:0.875rem">// No request body</p>';
+    tabs.push({
+      id: "body",
+      label: "Body",
+      html: bodyContent
+    });
+  }
+  if (opts.routing) {
+    const rows = [
+      opts.routing.controller ? `<tr><td>controller</td><td>${escapeHtml(opts.routing.controller)}</td></tr>` : "",
+      opts.routing.routeName ? `<tr><td>route name</td><td>${escapeHtml(opts.routing.routeName)}</td></tr>` : "",
+      opts.routing.middleware?.length ? `<tr><td>middleware</td><td>${escapeHtml(opts.routing.middleware.join(", "))}</td></tr>` : ""
+    ].filter(Boolean).join("");
+    if (rows)
+      tabs.push({
+        id: "routing",
+        label: "Routing",
+        html: `<table class="kv-table">${rows}</table>`
+      });
+  }
+  if (opts.user) {
+    const rows = [
+      opts.user.id !== void 0 ? `<tr><td>id</td><td>${escapeHtml(String(opts.user.id))}</td></tr>` : "",
+      opts.user.email ? `<tr><td>email</td><td>${escapeHtml(opts.user.email)}</td></tr>` : "",
+      opts.user.name ? `<tr><td>name</td><td>${escapeHtml(opts.user.name)}</td></tr>` : ""
+    ].filter(Boolean).join("");
+    if (rows)
+      tabs.push({
+        id: "user",
+        label: "User",
+        html: `<table class="kv-table">${rows}</table>`
+      });
+  }
+  if (opts.queries && opts.queries.length > 0)
+    tabs.push({
+      id: "queries",
+      label: `Queries (${opts.queries.length})`,
+      html: opts.queries.map((q) => `
+        <div class="query-item">
+          ${escapeHtml(q.query)}
+          ${q.time !== void 0 ? `<div class="query-time">${q.time.toFixed(2)}ms${q.connection ? ` \u2022 ${escapeHtml(q.connection)}` : ""}</div>` : ""}
+        </div>`).join("")
+    });
+  if (opts.showEnvironment)
+    tabs.push({
+      id: "environment",
+      label: "Environment",
+      html: `<table class="kv-table">
+        <tr><td>runtime</td><td>${typeof process < "u" ? escapeHtml(process.version) : "N/A"}</td></tr>
+        <tr><td>platform</td><td>${typeof process < "u" ? escapeHtml(process.platform) : "N/A"}</td></tr>
+        <tr><td>arch</td><td>${typeof process < "u" ? escapeHtml(process.arch) : "N/A"}</td></tr>
+      </table>`
+    });
+  if (tabs.length === 0)
+    return "";
+  const tabButtons = tabs.map((t, i) => `<button class="context-tab${i === 0 ? " active" : ""}" data-tab="${t.id}" type="button">${escapeHtml(t.label)}</button>`).join(""), panels = tabs.map((t, i) => `<div class="context-panel${i === 0 ? " active" : ""}" data-panel="${t.id}">${t.html}</div>`).join("");
+  return `<section class="context">
+    <div class="context-tabs">${tabButtons}</div>
+    ${panels}
+  </section>`;
+}
+export function buildErrorMarkdown(opts) {
+  const lines = [
+    `# ${opts.statusTitle}`,
+    "",
+    `## ${opts.errorName}`,
+    "",
+    opts.errorMessage,
+    ""
+  ];
+  if (opts.file)
+    lines.push(`**${opts.file}${opts.line ? `:${opts.line}` : ""}**`, "");
+  if (opts.framework)
+    lines.push(`**${opts.framework.name.toUpperCase()}** ${opts.framework.version ?? ""}`.trim(), "");
+  lines.push(`**${opts.status}**`, "");
+  if (opts.request)
+    lines.push(`\`${opts.request.method}\` ${opts.request.url}`, "");
+  if (opts.frames.length > 0) {
+    lines.push("## Exception trace", "");
+    for (const frame of opts.frames.slice(0, 20))
+      lines.push(`\`${frame.function || "<anonymous>"}\` \u2014 ${frame.file}:${frame.line}`);
+  }
+  return lines.join(`
+`);
+}
+export const ERROR_PAGE_SCRIPT = `
+function initErrorPage() {
+  const copyBtn = document.getElementById('copy-markdown');
+  const markdown = document.getElementById('error-markdown');
+  if (copyBtn && markdown) {
+    copyBtn.addEventListener('click', async () => {
+      try {
+        await navigator.clipboard.writeText(markdown.textContent || '');
+        copyBtn.textContent = 'Copied!';
+        copyBtn.classList.add('copied');
+        setTimeout(() => {
+          copyBtn.textContent = 'Copy as Markdown';
+          copyBtn.classList.remove('copied');
+        }, 2000);
+      } catch {
+        copyBtn.textContent = 'Copy failed';
+      }
+    });
+  }
+
+  document.querySelectorAll('.context-tab').forEach(tab => {
+    tab.addEventListener('click', () => {
+      const id = tab.getAttribute('data-tab');
+      document.querySelectorAll('.context-tab').forEach(t => t.classList.remove('active'));
+      document.querySelectorAll('.context-panel').forEach(p => p.classList.remove('active'));
+      tab.classList.add('active');
+      const panel = document.querySelector('[data-panel="' + id + '"]');
+      if (panel) panel.classList.add('active');
+    });
+  });
+}
+document.addEventListener('DOMContentLoaded', initErrorPage);
+`;
+export function wrapErrorPage(body, markdown) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>${ERROR_PAGE_CSS}</style>
+</head>
+<body>
+  <div class="page">
+    ${body}
+  </div>
+  <script id="error-markdown" type="text/plain">${escapeHtml(markdown)}</script>
+  <script>${ERROR_PAGE_SCRIPT}</script>
+</body>
+</html>`;
+}

package/dist/error-page-view-model.d.ts

@@ -0,0 +1,70 @@
+import { languageForFile } from './error-page-highlighter';
+import type { ErrorPageConfig, QueryInfo, RequestContext, RoutingContext, UserContext } from './error-page';
+declare function parseStackTrace(stack: string | undefined, basePaths?: string[], options?: { includeFrameworkFrames?: boolean }): ParsedFrame[];
+declare function groupFrames(frames: ParsedFrame[]): Array<ParsedFrame | ParsedFrame[]>;
+export declare function buildErrorPageViewModel(opts: {
+  error: Error
+  status: number
+  config: ErrorPageConfig
+  framework?: { name: string, version?: string }
+  request?: RequestContext
+  routing?: RoutingContext
+  user?: UserContext
+  queries?: QueryInfo[]
+}): Promise<ErrorPageViewModel>;
+export declare interface FrameViewModel {
+  function: string
+  file: string
+  line: number
+  expanded: boolean
+  hasCode: boolean
+  codeHtml: string
+  isVendor: boolean
+}
+export declare interface TraceGroupViewModel {
+  type: 'frame' | 'vendor'
+  frames: FrameViewModel[]
+  vendorCount: number
+}
+export declare interface KeyValueRow {
+  key: string
+  value: string
+}
+export declare interface ErrorPageViewModel {
+  pageTitle: string
+  statusTitle: string
+  markdownJson: string
+  exceptionClass: string
+  message: string
+  fileLine: string
+  statusCode: number
+  errorCode: string
+  frameworkLabel: string
+  frameworkVersion: string
+  runtimeLabel: string
+  runtimeVersion: string
+  requestMethod: string
+  requestUrl: string
+  hasRequest: boolean
+  hintsHtml: string
+  traceGroups: TraceGroupViewModel[]
+  queries: Array<{ connection: string, sql: string, sqlHtml: string, time: string }>
+  queryCount: number
+  headers: KeyValueRow[]
+  bodyContent: string
+  routing: KeyValueRow[]
+  routeParamsJson: string
+  userRows: KeyValueRow[]
+  environmentRows: KeyValueRow[]
+  hasUser: boolean
+  hasEnvironment: boolean
+  hasQueries: boolean
+  hasHeaders: boolean
+  hasBody: boolean
+  hasRouting: boolean
+  hasRouteParams: boolean
+  highlightCss: string
+  enableCopyMarkdown: boolean
+}
+// Re-export for tests
+export { parseStackTrace, groupFrames, languageForFile };

package/dist/error-page-view-model.js

@@ -0,0 +1,166 @@
+import { HTTP_ERRORS as HTTP_ERROR_MAP, isFrameworkFrame, renderHttpErrorHints } from "./error-page";
+import { highlightSnippet, languageForFile } from "./error-page-highlighter";
+import { buildErrorMarkdown, escapeHtml, readCodeSnippet } from "./error-page-template";
+function parseStackTrace(stack, basePaths, options = {}) {
+  if (!stack)
+    return [];
+  const lines = stack.split(`
+`).slice(1), frames = [], includeAll = options.includeFrameworkFrames === !0;
+  for (const line of lines) {
+    const match = line.match(/^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/);
+    if (match) {
+      let file = match[2];
+      if (file === void 0)
+        continue;
+      const original = file, isFramework = isFrameworkFrame(original);
+      if (basePaths) {
+        for (const basePath of basePaths)
+          if (file.startsWith(basePath)) {
+            file = file.slice(basePath.length + 1);
+            break;
+          }
+      }
+      if (!includeAll && isFramework)
+        continue;
+      frames.push({
+        function: match[1] || "<anonymous>",
+        file,
+        absoluteFile: original,
+        isFramework,
+        line: parseInt(match[3] ?? "0", 10),
+        column: parseInt(match[4] ?? "0", 10)
+      });
+    }
+  }
+  if (!includeAll && frames.length === 0)
+    return parseStackTrace(stack, basePaths, { includeFrameworkFrames: !0 });
+  return frames;
+}
+function groupFrames(frames) {
+  const groups = [];
+  let vendorBatch = [];
+  const flushVendor = () => {
+    if (vendorBatch.length > 0) {
+      groups.push(vendorBatch.length === 1 ? vendorBatch[0] : [...vendorBatch]);
+      vendorBatch = [];
+    }
+  };
+  for (const frame of frames)
+    if (frame.isFramework)
+      vendorBatch.push(frame);
+    else {
+      flushVendor();
+      groups.push(frame);
+    }
+  flushVendor();
+  return groups;
+}
+async function buildFrameView(frame, index, snippetLines) {
+  const snippet = readCodeSnippet(frame.absoluteFile, frame.line, snippetLines);
+  let codeHtml = "";
+  if (snippet) {
+    const code = snippet.lines.map((l) => l.content).join(`
+`), startingLine = snippet.lines[0]?.number ?? frame.line;
+    codeHtml = (await highlightSnippet(code, frame.file, frame.line, startingLine)).html;
+  }
+  return {
+    function: frame.function || "<anonymous>",
+    file: frame.file,
+    line: frame.line,
+    expanded: index === 0,
+    hasCode: codeHtml.length > 0,
+    codeHtml,
+    isVendor: frame.isFramework
+  };
+}
+export async function buildErrorPageViewModel(opts) {
+  const { error, status, config } = opts, statusTitle = HTTP_ERROR_MAP[status]?.title ?? "Error", frames = parseStackTrace(error.stack, config.basePaths, {
+    includeFrameworkFrames: config.showFrameworkFrames === !0
+  }), topFrame = frames[0], runtimeVersion = typeof process < "u" ? process.version.replace(/^v/, "") : "", runtimeLabel = typeof process < "u" && process.versions.bun ? "BUN" : "NODE", errorCode = error.code, traceGroups = [];
+  let frameIndex = 0;
+  for (const group of groupFrames(frames))
+    if (Array.isArray(group)) {
+      const vendorFrames = await Promise.all(group.map((f, i) => buildFrameView(f, frameIndex + i, config.snippetLines ?? 8)));
+      traceGroups.push({ type: "vendor", frames: vendorFrames, vendorCount: vendorFrames.length });
+      frameIndex += vendorFrames.length;
+    } else {
+      traceGroups.push({
+        type: "frame",
+        frames: [await buildFrameView(group, frameIndex, config.snippetLines ?? 8)],
+        vendorCount: 0
+      });
+      frameIndex += 1;
+    }
+  const headers = opts.request ? Object.entries(opts.request.headers).map(([key, value]) => ({ key, value })) : [], routing = [];
+  if (opts.routing?.controller)
+    routing.push({ key: "controller", value: opts.routing.controller });
+  if (opts.routing?.routeName)
+    routing.push({ key: "route name", value: opts.routing.routeName });
+  if (opts.routing?.middleware?.length)
+    routing.push({ key: "middleware", value: opts.routing.middleware.join(", ") });
+  const userRows = [];
+  if (opts.user?.id !== void 0)
+    userRows.push({ key: "id", value: String(opts.user.id) });
+  if (opts.user?.email)
+    userRows.push({ key: "email", value: opts.user.email });
+  if (opts.user?.name)
+    userRows.push({ key: "name", value: opts.user.name });
+  const environmentRows = config.showEnvironment && typeof process < "u" ? [
+    { key: "runtime", value: process.version },
+    { key: "platform", value: process.platform },
+    { key: "arch", value: process.arch }
+  ] : [], queries = (opts.queries ?? []).slice(0, 100).map((q) => ({
+    connection: q.connection ?? "default",
+    sql: q.query,
+    sqlHtml: escapeHtml(q.query),
+    time: q.time !== void 0 ? q.time.toFixed(2) : "0.00"
+  })), bodyContent = opts.request?.body ? JSON.stringify(opts.request.body, null, 2) : "// No request body", routeParamsJson = opts.request?.queryParams && Object.keys(opts.request.queryParams).length > 0 ? JSON.stringify(opts.request.queryParams, null, 2) : "", markdown = buildErrorMarkdown({
+    statusTitle,
+    errorName: error.name || "Error",
+    errorMessage: error.message,
+    status,
+    file: topFrame?.file,
+    line: topFrame?.line,
+    request: opts.request,
+    framework: opts.framework,
+    frames
+  }), { getSharedHighlighterCss } = await import("./error-page-highlighter");
+  return {
+    pageTitle: statusTitle,
+    statusTitle,
+    markdownJson: JSON.stringify(markdown),
+    exceptionClass: error.name || "Error",
+    message: error.message,
+    fileLine: topFrame ? `${topFrame.file}:${topFrame.line}` : "",
+    statusCode: status,
+    errorCode: errorCode !== void 0 ? String(errorCode) : "0",
+    frameworkLabel: opts.framework?.name?.toUpperCase() ?? "STACKS",
+    frameworkVersion: opts.framework?.version ?? "",
+    runtimeLabel,
+    runtimeVersion,
+    requestMethod: opts.request?.method ?? "GET",
+    requestUrl: opts.request?.url ?? "",
+    hasRequest: !!opts.request,
+    hintsHtml: renderHttpErrorHints(status),
+    traceGroups,
+    queries,
+    queryCount: queries.length,
+    headers,
+    bodyContent,
+    routing,
+    routeParamsJson,
+    userRows,
+    environmentRows,
+    hasUser: userRows.length > 0,
+    hasEnvironment: environmentRows.length > 0,
+    hasQueries: queries.length > 0 && config.showQueries !== !1,
+    hasHeaders: headers.length > 0 && config.showRequest !== !1,
+    hasBody: config.showRequest !== !1,
+    hasRouting: routing.length > 0,
+    hasRouteParams: routeParamsJson.length > 0,
+    highlightCss: getSharedHighlighterCss(),
+    enableCopyMarkdown: config.enableCopyMarkdown !== !1
+  };
+}
+
+export { parseStackTrace, groupFrames, languageForFile };