@stacksjs/error-handling 0.70.88 → 0.70.91

package/dist/error-page.d.ts

@@ -0,0 +1,240 @@
+import { ERROR_PAGE_CSS } from './error-page-styles';
+export declare function isFrameworkFrame(file: string): boolean;
+/**
+ * Render a simple production error page.
+ *
+ * Checks for a userland override at `resources/views/errors/<status>.html`
+ * (or `error.html` as a generic fallback) first; renders the built-in
+ * template only when no custom page is provided. stacksjs/stacks#863.
+ */
+export declare function renderProductionErrorPage(status: number): string;
+/**
+ * Render the contextual hint block (common causes, suggestion, doc link)
+ * for a given HTTP status. Returns an empty string for statuses without
+ * enriched data so the dev page degrades gracefully.
+ */
+export declare function renderHttpErrorHints(status: number): string;
+/**
+ * Create an error handler instance
+ */
+export declare function createErrorHandler(config?: ErrorPageConfig): ErrorPageHandler;
+/**
+ * Render an error page (alias)
+ */
+export declare function renderErrorPage(error: Error, status?: number, config?: ErrorPageConfig): Promise<string>;
+/**
+ * Render error (alias)
+ */
+export declare function renderError(error: Error, status?: number): Promise<string>;
+/**
+ * Create an error response
+ */
+export declare function errorResponse(error: Error, status?: number, config?: ErrorPageConfig): Promise<Response>;
+/**
+ * HTTP error definitions. Each entry includes a doc link, likely causes,
+// and a concrete suggestion so the dev-mode error page reads like a hint
+// instead of just "something went wrong".
+ * @defaultValue
+ * ```ts
+ * {
+ *   400: {
+ *     status: 400,
+ *     title: 'Bad Request',
+ *     message: 'The request was malformed or invalid.',
+ *     commonCauses: [ 'JSON body is missing or has a syntax error', 'A required field is absent from the payload', 'Content-Type header does not match the body format', ],
+ *     suggestion: 'Inspect the request body and Content-Type — most 400s come from malformed JSON or a missing required field.'
+ *   },
+ *   401: {
+ *     status: 401,
+ *     title: 'Unauthorized',
+ *     message: 'Authentication is required to access this resource.',
+ *     commonCauses: [ 'No Authorization header was sent', 'The bearer token expired', 'The session cookie was cleared', ],
+ *     suggestion: 'Confirm a valid `Authorization: Bearer <token>` header is sent and the token has not expired.'
+ *   },
+ *   403: {
+ *     status: 403,
+ *     title: 'Forbidden',
+ *     message: 'You do not have permission to access this resource.',
+ *     commonCauses: [ 'The authenticated user lacks the required ability or role', 'A Gate or policy denied access (see app/Gates.ts)', 'The token was issued without the needed ability', ],
+ *     suggestion: 'Check Gates / policies and the abilities encoded in the access token.'
+ *   },
+ *   404: {
+ *     status: 404,
+ *     title: 'Not Found',
+ *     message: 'The requested resource could not be found.',
+ *     commonCauses: [ 'The route is not registered in app/Routes.ts', 'A typo in the URL path', 'A model lookup returned no row (ModelNotFoundError)', ],
+ *     suggestion: 'Run `buddy route:list` to see registered routes, or verify the model exists with the given id.'
+ *   },
+ *   405: {
+ *     status: 405,
+ *     title: 'Method Not Allowed',
+ *     message: 'The request method is not supported for this resource.',
+ *     commonCauses: [ 'The route is registered for a different HTTP method', 'A form posted GET when the route expects POST', ],
+ *     suggestion: 'Confirm the HTTP method in `app/Routes.ts` matches what the client sent.'
+ *   },
+ *   408: {
+ *     status: 408,
+ *     title: 'Request Timeout',
+ *     message: 'The request took too long to complete.',
+ *     commonCauses: [ 'A long-running query or external API call exceeded the timeout', 'The client uploaded a slow body that stalled', ],
+ *     suggestion: 'Move slow work into a queued job, or raise the route timeout if the work is genuinely long.'
+ *   },
+ *   409: {
+ *     status: 409,
+ *     title: 'Conflict',
+ *     message: 'The request conflicts with the current state of the resource.',
+ *     commonCauses: [ 'A unique-constraint violation (duplicate email, slug, etc.)', 'Optimistic locking detected a stale write', ],
+ *     suggestion: 'Re-fetch the resource and retry, or surface the conflict to the user.'
+ *   },
+ *   410: {
+ *     status: 410,
+ *     title: 'Gone',
+ *     message: 'The requested resource is no longer available.',
+ *     commonCauses: ['The resource was permanently deleted', 'A signed URL expired'],
+ *     suggestion: 'Issue a fresh signed URL or fall back to the canonical resource.'
+ *   },
+ *   422: {
+ *     status: 422,
+ *     title: 'Unprocessable Entity',
+ *     message: 'The request was well-formed but could not be processed.',
+ *     commonCauses: [ 'Validation rules from the action / model rejected the payload', 'A field value is outside the allowed range or shape', ],
+ *     suggestion: 'Inspect `errors` in the response body — each key maps to a failing field.'
+ *   },
+ *   429: {
+ *     status: 429,
+ *     title: 'Too Many Requests',
+ *     message: 'You have exceeded the rate limit.',
+ *     commonCauses: ['Rate-limit middleware tripped on this IP / token', 'A retry loop is hammering the endpoint'],
+ *     suggestion: 'Honor the `Retry-After` response header and back off before retrying.'
+ *   },
+ *   500: {
+ *     status: 500,
+ *     title: 'Internal Server Error',
+ *     message: 'An unexpected error occurred on the server.',
+ *     commonCauses: [ 'An unhandled exception in an action or middleware', 'A failing database connection or migration', 'A misconfigured environment variable', ],
+ *     suggestion: 'Check server logs for the original stack trace — the error page above shows the throw site in dev.'
+ *   },
+ *   502: {
+ *     status: 502,
+ *     title: 'Bad Gateway',
+ *     message: 'The server received an invalid response from an upstream server.',
+ *     commonCauses: ['An upstream HTTP API returned a malformed response', 'A reverse proxy could not reach the origin'],
+ *     suggestion: 'Verify the upstream service is healthy and returning the expected content type.'
+ *   },
+ *   503: {
+ *     status: 503,
+ *     title: 'Service Unavailable',
+ *     message: 'The service is temporarily unavailable.',
+ *     commonCauses: ['Maintenance mode is enabled', 'A health check is failing', 'A dependency (db, redis, queue) is down'],
+ *     suggestion: 'Run `buddy doctor` and check dependent services.'
+ *   },
+ *   504: {
+ *     status: 504,
+ *     title: 'Gateway Timeout',
+ *     message: 'The upstream server did not respond in time.',
+ *     commonCauses: ['An upstream HTTP call exceeded its deadline', 'A long-running database query timed out'],
+ *     suggestion: 'Move the work to a queued job or raise the upstream timeout if the latency is expected.'
+ *   }
+ * }
+ * ```
+ */
+export declare const HTTP_ERRORS: Record<HttpStatusCode, HttpError>;
+/**
+ * Error Page Rendering - Ignition-style error pages
+ *
+ * Provides beautiful development error pages with full stack traces,
+ * database queries, and request context.
+ */
+// Types
+export declare interface ErrorPageConfig {
+  appName?: string
+  theme?: 'light' | 'dark' | 'auto'
+  showEnvironment?: boolean
+  showQueries?: boolean
+  showRequest?: boolean
+  enableCopyMarkdown?: boolean
+  snippetLines?: number
+  basePaths?: string[]
+  showFrameworkFrames?: boolean
+}
+export declare interface RequestContext {
+  method: string
+  url: string
+  headers: Record<string, string>
+  queryParams?: Record<string, string>
+  body?: unknown
+}
+export declare interface RoutingContext {
+  controller?: string
+  routeName?: string
+  middleware?: string[]
+}
+export declare interface UserContext {
+  id?: string | number
+  email?: string
+  name?: string
+}
+export declare interface QueryInfo {
+  query: string
+  time?: number
+  connection?: string
+}
+export declare interface StackFrame {
+  file: string
+  line: number
+  column?: number
+  function?: string
+  code?: string
+}
+export declare interface CodeSnippet {
+  file: string
+  line: number
+  code: string[]
+  highlight: number
+}
+export declare interface EnvironmentContext {
+  nodeVersion?: string
+  platform?: string
+  arch?: string
+  env?: Record<string, string>
+}
+export declare interface JobContext {
+  name?: string
+  queue?: string
+  attempts?: number
+}
+export declare interface ErrorPageData {
+  error: Error
+  status: number
+  stack: StackFrame[]
+  request?: RequestContext
+  routing?: RoutingContext
+  user?: UserContext
+  queries?: QueryInfo[]
+  environment?: EnvironmentContext
+  job?: JobContext
+  framework?: { name: string, version?: string }
+}
+export declare interface HttpError {
+  status: HttpStatusCode
+  title: string
+  message: string
+  docLink?: string
+  commonCauses?: string[]
+  suggestion?: string
+}
+export type HttpStatusCode = 400 | 401 | 403 | 404 | 405 | 408 | 409 | 410 | 422 | 429 | 500 | 502 | 503 | 504;
+/**
+ * Error Page Handler class
+ */
+export declare class ErrorPageHandler {
+  constructor(config?: ErrorPageConfig);
+  setFramework(name: string, version?: string): this;
+  setRequest(request: Request | RequestContext): this;
+  setRouting(routing: RoutingContext): this;
+  setUser(user: UserContext): this;
+  addQuery(query: string, time?: number, connection?: string): this;
+  render(error: Error, status?: number): Promise<string>;
+  handleError(error: Error, status?: number): Promise<Response>;
+}
+export { ERROR_PAGE_CSS };

package/dist/error-page.js

@@ -0,0 +1,373 @@
+var {require}=import.meta;const DOCS_BASE = "https://stacksjs.org/docs/errors";
+export const HTTP_ERRORS = {
+  400: {
+    status: 400,
+    title: "Bad Request",
+    message: "The request was malformed or invalid.",
+    docLink: `${DOCS_BASE}/400`,
+    commonCauses: [
+      "JSON body is missing or has a syntax error",
+      "A required field is absent from the payload",
+      "Content-Type header does not match the body format"
+    ],
+    suggestion: "Inspect the request body and Content-Type \u2014 most 400s come from malformed JSON or a missing required field."
+  },
+  401: {
+    status: 401,
+    title: "Unauthorized",
+    message: "Authentication is required to access this resource.",
+    docLink: `${DOCS_BASE}/401`,
+    commonCauses: [
+      "No Authorization header was sent",
+      "The bearer token expired",
+      "The session cookie was cleared"
+    ],
+    suggestion: "Confirm a valid `Authorization: Bearer <token>` header is sent and the token has not expired."
+  },
+  403: {
+    status: 403,
+    title: "Forbidden",
+    message: "You do not have permission to access this resource.",
+    docLink: `${DOCS_BASE}/403`,
+    commonCauses: [
+      "The authenticated user lacks the required ability or role",
+      "A Gate or policy denied access (see app/Gates.ts)",
+      "The token was issued without the needed ability"
+    ],
+    suggestion: "Check Gates / policies and the abilities encoded in the access token."
+  },
+  404: {
+    status: 404,
+    title: "Not Found",
+    message: "The requested resource could not be found.",
+    docLink: `${DOCS_BASE}/404`,
+    commonCauses: [
+      "The route is not registered in app/Routes.ts",
+      "A typo in the URL path",
+      "A model lookup returned no row (ModelNotFoundError)"
+    ],
+    suggestion: "Run `buddy route:list` to see registered routes, or verify the model exists with the given id."
+  },
+  405: {
+    status: 405,
+    title: "Method Not Allowed",
+    message: "The request method is not supported for this resource.",
+    docLink: `${DOCS_BASE}/405`,
+    commonCauses: [
+      "The route is registered for a different HTTP method",
+      "A form posted GET when the route expects POST"
+    ],
+    suggestion: "Confirm the HTTP method in `app/Routes.ts` matches what the client sent."
+  },
+  408: {
+    status: 408,
+    title: "Request Timeout",
+    message: "The request took too long to complete.",
+    docLink: `${DOCS_BASE}/408`,
+    commonCauses: [
+      "A long-running query or external API call exceeded the timeout",
+      "The client uploaded a slow body that stalled"
+    ],
+    suggestion: "Move slow work into a queued job, or raise the route timeout if the work is genuinely long."
+  },
+  409: {
+    status: 409,
+    title: "Conflict",
+    message: "The request conflicts with the current state of the resource.",
+    docLink: `${DOCS_BASE}/409`,
+    commonCauses: [
+      "A unique-constraint violation (duplicate email, slug, etc.)",
+      "Optimistic locking detected a stale write"
+    ],
+    suggestion: "Re-fetch the resource and retry, or surface the conflict to the user."
+  },
+  410: {
+    status: 410,
+    title: "Gone",
+    message: "The requested resource is no longer available.",
+    docLink: `${DOCS_BASE}/410`,
+    commonCauses: ["The resource was permanently deleted", "A signed URL expired"],
+    suggestion: "Issue a fresh signed URL or fall back to the canonical resource."
+  },
+  422: {
+    status: 422,
+    title: "Unprocessable Entity",
+    message: "The request was well-formed but could not be processed.",
+    docLink: `${DOCS_BASE}/422`,
+    commonCauses: [
+      "Validation rules from the action / model rejected the payload",
+      "A field value is outside the allowed range or shape"
+    ],
+    suggestion: "Inspect `errors` in the response body \u2014 each key maps to a failing field."
+  },
+  429: {
+    status: 429,
+    title: "Too Many Requests",
+    message: "You have exceeded the rate limit.",
+    docLink: `${DOCS_BASE}/429`,
+    commonCauses: ["Rate-limit middleware tripped on this IP / token", "A retry loop is hammering the endpoint"],
+    suggestion: "Honor the `Retry-After` response header and back off before retrying."
+  },
+  500: {
+    status: 500,
+    title: "Internal Server Error",
+    message: "An unexpected error occurred on the server.",
+    docLink: `${DOCS_BASE}/500`,
+    commonCauses: [
+      "An unhandled exception in an action or middleware",
+      "A failing database connection or migration",
+      "A misconfigured environment variable"
+    ],
+    suggestion: "Check server logs for the original stack trace \u2014 the error page above shows the throw site in dev."
+  },
+  502: {
+    status: 502,
+    title: "Bad Gateway",
+    message: "The server received an invalid response from an upstream server.",
+    docLink: `${DOCS_BASE}/502`,
+    commonCauses: ["An upstream HTTP API returned a malformed response", "A reverse proxy could not reach the origin"],
+    suggestion: "Verify the upstream service is healthy and returning the expected content type."
+  },
+  503: {
+    status: 503,
+    title: "Service Unavailable",
+    message: "The service is temporarily unavailable.",
+    docLink: `${DOCS_BASE}/503`,
+    commonCauses: ["Maintenance mode is enabled", "A health check is failing", "A dependency (db, redis, queue) is down"],
+    suggestion: "Run `buddy doctor` and check dependent services."
+  },
+  504: {
+    status: 504,
+    title: "Gateway Timeout",
+    message: "The upstream server did not respond in time.",
+    docLink: `${DOCS_BASE}/504`,
+    commonCauses: ["An upstream HTTP call exceeded its deadline", "A long-running database query timed out"],
+    suggestion: "Move the work to a queued job or raise the upstream timeout if the latency is expected."
+  }
+};
+import {
+  buildErrorMarkdown,
+  escapeHtml,
+  renderExceptionTrace,
+  wrapErrorPage
+} from "./error-page-template";
+import { ERROR_PAGE_CSS } from "./error-page-styles";
+
+export { ERROR_PAGE_CSS };
+const FRAMEWORK_FRAME_FRAGMENTS = [
+  "/storage/framework/core/",
+  "/node_modules/@stacksjs/",
+  "node:internal/",
+  "bun:wrap"
+];
+export function isFrameworkFrame(file) {
+  if (!file)
+    return !1;
+  return FRAMEWORK_FRAME_FRAGMENTS.some((f) => file.includes(f));
+}
+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 loadCustomErrorPage(status, title, message) {
+  let resourcesPath;
+  try {
+    const mod = require("@stacksjs/path");
+    resourcesPath = mod.resourcesPath ?? mod.path?.resourcesPath;
+  } catch {}
+  if (!resourcesPath)
+    return null;
+  const fs = require("node:fs"), candidates = [
+    resourcesPath(`views/errors/${status}.html`),
+    resourcesPath("views/errors/error.html")
+  ];
+  for (const filePath of candidates)
+    try {
+      if (!fs.existsSync(filePath))
+        continue;
+      return fs.readFileSync(filePath, "utf-8").replace(/\{\{\s*status\s*\}\}/g, escapeHtml(String(status))).replace(/\{\{\s*title\s*\}\}/g, escapeHtml(title)).replace(/\{\{\s*message\s*\}\}/g, escapeHtml(message));
+    } catch {}
+  return null;
+}
+export function renderProductionErrorPage(status) {
+  const httpError = HTTP_ERRORS[status] || {
+    status,
+    title: "Error",
+    message: "An unexpected error occurred."
+  }, custom = loadCustomErrorPage(httpError.status, httpError.title, httpError.message);
+  if (custom !== null)
+    return custom;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${httpError.status} - ${httpError.title}</title>
+  <style>${ERROR_PAGE_CSS}</style>
+</head>
+<body>
+  <div class="production-page">
+    <div class="production-status">${httpError.status}</div>
+    <h1 class="production-title">${escapeHtml(httpError.title)}</h1>
+    <p class="production-message">${escapeHtml(httpError.message)}</p>
+    <a href="/" class="production-link">\u2190 Back to Home</a>
+  </div>
+</body>
+</html>`;
+}
+export function renderHttpErrorHints(status) {
+  const info = HTTP_ERRORS[status];
+  if (!info)
+    return "";
+  const hasCauses = Array.isArray(info.commonCauses) && info.commonCauses.length > 0, hasSuggestion = typeof info.suggestion === "string" && info.suggestion.length > 0, hasDoc = typeof info.docLink === "string" && info.docLink.length > 0;
+  if (!hasCauses && !hasSuggestion && !hasDoc)
+    return "";
+  const causes = hasCauses ? `<ul class="error-hint-causes">${info.commonCauses.map((c) => `<li>${escapeHtml(c)}</li>`).join("")}</ul>` : "", suggestion = hasSuggestion ? `<p class="error-hint-suggestion">${escapeHtml(info.suggestion)}</p>` : "", doc = hasDoc ? `<a class="text-blue-600 text-sm dark:text-blue-500 hover:underline" href="${escapeHtml(info.docLink)}" target="_blank" rel="noreferrer noopener">Read the docs \u2192</a>` : "";
+  return `<section class="p-4 bg-amber-200/30 dark:bg-amber-950/40 border border-amber-200 rounded-xl dark:border-amber-800 shadow-xs">
+  <div class="mb-2 font-semibold text-amber-900 text-sm dark:text-amber-300">Likely causes &amp; next steps</div>
+  <div class="text-neutral-700 text-sm dark:text-neutral-300">${causes}${suggestion}${doc}</div>
+</section>`;
+}
+
+export class ErrorPageHandler {
+  config;
+  framework;
+  request;
+  routing;
+  user;
+  queries = [];
+  constructor(config) {
+    this.config = {
+      appName: "App",
+      theme: "auto",
+      showEnvironment: !0,
+      showQueries: !0,
+      showRequest: !0,
+      enableCopyMarkdown: !0,
+      snippetLines: 8,
+      ...config
+    };
+  }
+  setFramework(name, version) {
+    this.framework = { name, version };
+    return this;
+  }
+  setRequest(request) {
+    if (request instanceof Request) {
+      const url = new URL(request.url);
+      this.request = {
+        method: request.method,
+        url: request.url,
+        headers: Object.fromEntries(request.headers.entries()),
+        queryParams: Object.fromEntries(url.searchParams.entries())
+      };
+    } else
+      this.request = request;
+    return this;
+  }
+  setRouting(routing) {
+    this.routing = routing;
+    return this;
+  }
+  setUser(user) {
+    this.user = user;
+    return this;
+  }
+  addQuery(query, time, connection) {
+    this.queries.push({ query, time, connection });
+    return this;
+  }
+  async render(error, status = 500) {
+    try {
+      const { renderDevErrorPage } = await import("./error-page-renderer");
+      return await renderDevErrorPage({
+        error,
+        status,
+        config: this.config,
+        framework: this.framework,
+        request: this.request,
+        routing: this.routing,
+        user: this.user,
+        queries: this.queries
+      });
+    } catch (renderError) {
+      console.error("[ErrorPageHandler] STX render failed, using fallback:", renderError);
+      return this.renderFallback(error, status);
+    }
+  }
+  renderFallback(error, status) {
+    const frames = parseStackTrace(error.stack, this.config.basePaths, {
+      includeFrameworkFrames: this.config.showFrameworkFrames === !0
+    }), statusTitle = HTTP_ERRORS[status]?.title ?? "Error", topFrame = frames[0], body = `
+    <header class="header"><div class="header-title"><span class="header-dot"></span><span>${escapeHtml(statusTitle)}</span></div></header>
+    <section class="summary">
+      <h1>${escapeHtml(error.name || "Error")}</h1>
+      ${topFrame ? `<div class="summary-file">${escapeHtml(topFrame.file)}:${topFrame.line}</div>` : ""}
+      <p class="summary-message">${escapeHtml(error.message)}</p>
+    </section>
+    ${renderHttpErrorHints(status)}
+    ${renderExceptionTrace(frames, this.config.snippetLines ?? 8)}
+    `, markdown = buildErrorMarkdown({
+      statusTitle,
+      errorName: error.name || "Error",
+      errorMessage: error.message,
+      status,
+      file: topFrame?.file,
+      line: topFrame?.line,
+      request: this.request,
+      framework: this.framework,
+      frames
+    });
+    return wrapErrorPage(body, markdown);
+  }
+  async handleError(error, status = 500) {
+    const html = await this.render(error, status);
+    return new Response(html, {
+      status,
+      headers: { "Content-Type": "text/html; charset=utf-8" }
+    });
+  }
+}
+export function createErrorHandler(config) {
+  return new ErrorPageHandler(config);
+}
+export async function renderErrorPage(error, status = 500, config) {
+  return createErrorHandler(config).render(error, status);
+}
+export async function renderError(error, status = 500) {
+  return renderErrorPage(error, status);
+}
+export async function errorResponse(error, status = 500, config) {
+  return createErrorHandler(config).handleError(error, status);
+}

package/dist/handler.d.ts

@@ -0,0 +1,30 @@
+import * as path from '@stacksjs/path';
+import type { LogErrorOptions } from '@stacksjs/logging';
+// Function to update the default log path when config is available
+export declare function setLogPath(path: string): void;
+export declare function writeToLogFile(message: string, options?: WriteOptions): Promise<void>;
+export declare function handleError(err: string | Error | object | unknown, options?: unknown): Error;
+/**
+ * Context information attached to errors for better debugging.
+ */
+export declare interface ErrorContext {
+  requestId?: string
+  url?: string
+  method?: string
+  userId?: string | number
+  ip?: string
+  userAgent?: string
+  [key: string]: unknown
+}
+declare interface WriteOptions {
+  logFile?: string
+}
+declare type ErrorMessage = string;
+export declare class ErrorHandler {
+  static isTestEnvironment: boolean;
+  static shouldExitProcess: boolean;
+  static handle(err: Error | ErrorMessage | unknown, options?: LogErrorOptions): Error;
+  static handleError(err: Error, options?: LogErrorOptions): Error;
+  static writeErrorToFile(err: Error | unknown, context?: ErrorContext): Promise<void>;
+  static writeErrorToConsole(err: string | Error | unknown): void;
+}