tessl/npm-pnpm--error
Specialized error classes for the pnpm package manager with standardized error codes and authentication token security.
index.mddocs/
@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;
}