@pnpm/error

import { PnpmError, FetchError, LockfileMissingDependencyError } from "@pnpm/error";
import type { FetchErrorResponse, FetchErrorRequest } from "@pnpm/error";

const { PnpmError, FetchError, LockfileMissingDependencyError } = require("@pnpm/error");

import { PnpmError, FetchError, LockfileMissingDependencyError } from "@pnpm/error";

// General pnpm error
try {
  throw new PnpmError("THE_ERROR_CODE", "Something went wrong", {
    hint: "Try running with --verbose for more details"
  });
} catch (err) {
  console.log(err.code); // "ERR_PNPM_THE_ERROR_CODE"
  console.log(err.message); // "Something went wrong"
  console.log(err.hint); // "Try running with --verbose for more details"
}

// HTTP fetch error
const fetchError = new FetchError(
  { url: "https://registry.npmjs.org/some-package" },
  { status: 404, statusText: "Not Found" }
);

// Lockfile dependency error
const lockfileError = new LockfileMissingDependencyError("some-dep@1.0.0");

class PnpmError extends Error {
  /** Error code, automatically prefixed with 'ERR_PNPM_' if not already present */
  readonly code: string;
  /** Optional hint for resolving the error */
  readonly hint?: string;
  /** Number of attempts made before the error occurred */
  attempts?: number;
  /** Prefix associated with the error context */
  prefix?: string;
  /** Stack of packages associated with the error */
  pkgsStack?: Array<{ id: string, name: string, version: string }>;

  constructor(
    code: string,
    message: string,
    opts?: {
      attempts?: number;
      hint?: string;
    }
  );
}

class FetchError extends PnpmError {
  /** Response information from the failed HTTP request */
  readonly response: FetchErrorResponse;
  /** Request information with authentication details masked for security */
  readonly request: FetchErrorRequest;

  /**
   * Creates a fetch error with automatic authentication token masking
   * @param request - Request details including URL and optional auth header
   * @param response - Response details with status code and message
   * @param hint - Optional additional hint for error resolution
   * @remarks The constructor automatically masks auth tokens in the request object for security
   */
  constructor(
    request: FetchErrorRequest,
    response: FetchErrorResponse,
    hint?: string
  );
}

class LockfileMissingDependencyError extends PnpmError {
  /**
   * Creates an error for missing lockfile dependencies with automatic hint
   * @param depPath - The dependency path that is missing from the lockfile
   * @remarks Uses WANTED_LOCKFILE constant from @pnpm/constants to reference the lockfile name
   */
  constructor(depPath: string);
}

interface FetchErrorResponse {
  /** HTTP status code from the failed request */
  status: number;
  /** HTTP status text from the failed request */
  statusText: string;
}

interface FetchErrorRequest {
  /** The URL that was being requested */
  url: string;
  /** Optional authorization header value (will be masked in error output) */
  authHeaderValue?: string;
}