CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/npm-pnpm--error

Specialized error classes for the pnpm package manager with standardized error codes and authentication token security.

Overview
Eval results
Files

@pnpm/error

@pnpm/error provides specialized error classes for the pnpm package manager ecosystem, offering a structured approach to error handling with standardized error codes, helpful hints, and security-conscious authentication token hiding.

Package Information

  • Package Name: @pnpm/error
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @pnpm/error

Core Imports

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

For CommonJS:

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

Basic Usage

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

// Basic pnpm error with hint
const error = new PnpmError("CUSTOM_ERROR", "Something went wrong", {
  hint: "Try running the command with --verbose for more details"
});

// HTTP fetch error with automatic auth token masking
const fetchError = new FetchError(
  { url: "https://registry.npmjs.org/package", authHeaderValue: "Bearer token123456789012345678901234567890" },
  { status: 401, statusText: "Unauthorized" }
);

// Lockfile dependency error
const lockfileError = new LockfileMissingDependencyError("/some/dependency/path");

Capabilities

Base Error Class

Core error class for pnpm-specific errors with standardized error codes and optional troubleshooting hints.

/**
 * Base error class for pnpm-specific errors
 * Automatically prefixes error codes with ERR_PNPM_ if not already present
 */
class PnpmError extends Error {
  /** The error code with ERR_PNPM_ prefix */
  readonly code: string;
  /** Optional hint for troubleshooting */
  readonly hint?: string;
  /** Number of attempts made (for retry scenarios) */
  attempts?: number;
  /** Error prefix context */
  prefix?: string;
  /** Package stack trace for dependency resolution errors */
  pkgsStack?: Array<{ id: string, name: string, version: string }>;

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

Key Features:

  • Automatically prefixes error codes with ERR_PNPM_ if not already present
  • Supports optional hints for better user experience
  • Extends native Error class with additional pnpm-specific properties
  • Can track retry attempts and package dependency stacks

HTTP Fetch Errors

Specialized error class for HTTP request failures with automatic authentication token masking to prevent credential leakage in logs.

/**
 * Error class for HTTP request failures with automatic authentication token masking
 * Provides enhanced hints for authentication errors (401, 403, 404 responses)
 */
class FetchError extends PnpmError {
  /** The HTTP response information */
  readonly response: FetchErrorResponse;
  /** The HTTP request information (with masked authentication tokens) */
  readonly request: FetchErrorRequest;

  constructor(
    request: FetchErrorRequest,
    response: FetchErrorResponse,
    hint?: string
  );
}

interface FetchErrorRequest {
  /** Request URL */
  url: string;
  /** Optional authentication header value (will be masked in error output) */
  authHeaderValue?: string;
}

interface FetchErrorResponse {
  /** HTTP status code */
  status: number;
  /** HTTP status text */
  statusText: string;
}

Security Features:

  • Authentication tokens are automatically masked in error messages and request objects
  • Tokens ≥20 characters show first 4 characters: Bearer 1234[hidden]
  • Shorter tokens are completely hidden: Bearer [hidden]
  • Enhanced hints for 401, 403, and 404 errors include authentication status information

Lockfile Dependency Errors

Specialized error for handling broken lockfile scenarios with specific recovery instructions.

/**
 * Error for handling broken lockfile scenarios with dependency resolution issues
 * Automatically provides recovery instructions for lockfile corruption
 */
class LockfileMissingDependencyError extends PnpmError {
  constructor(depPath: string);
}

Features:

  • Automatically sets error code to ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY
  • Generates descriptive message referencing the missing dependency path and lockfile
  • Provides built-in recovery hint: pnpm install --no-frozen-lockfile
  • Common for merge conflict resolution scenarios

Error Handling Patterns

All error classes in this package follow consistent patterns:

try {
  // Some pnpm operation
} catch (error) {
  if (error instanceof FetchError) {
    console.error(`HTTP Error: ${error.message}`);
    console.error(`Status: ${error.response.status}`);
    if (error.hint) {
      console.error(`Hint: ${error.hint}`);
    }
  } else if (error instanceof LockfileMissingDependencyError) {
    console.error(`Lockfile Error: ${error.message}`);
    console.error(`Recovery: ${error.hint}`);
  } else if (error instanceof PnpmError) {
    console.error(`PNPM Error [${error.code}]: ${error.message}`);
    if (error.hint) {
      console.error(`Hint: ${error.hint}`);
    }
  }
}

Types

interface FetchErrorRequest {
  /** Request URL */
  url: string;
  /** Optional authentication header value (automatically masked in errors) */
  authHeaderValue?: string;
}

interface FetchErrorResponse {
  /** HTTP status code */
  status: number;
  /** HTTP status text */
  statusText: string;
}
tessl i tessl/npm-pnpm--error@900.0.0
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@pnpm/error@900.0.x