tessl/npm-pacote

JavaScript package downloader and fetcher that serves as the core package handling library for npm

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Pacote

Name: tessl/npm-pacote
Author: tessl

Pacote is a comprehensive JavaScript package downloader and fetcher that serves as the core package handling library for npm. It provides a unified API for fetching package manifests, tarballs, and metadata from various sources including the npm registry, GitHub repositories, local directories, and tarball URLs.

Package Information

Package Name: pacote
Package Type: npm
Language: JavaScript
Installation: npm install pacote

Core Imports

const pacote = require('pacote');

For ESM:

import * as pacote from 'pacote';
// or
import { resolve, extract, manifest, packument, tarball } from 'pacote';

Basic Usage

const pacote = require('pacote');

// Get a package manifest
const manifest = await pacote.manifest('lodash@latest');
console.log('Package version:', manifest.version);

// Extract a package to a directory
const result = await pacote.extract('react@18.0.0', './packages/react');
console.log('Extracted from:', result.from);

// Download package tarball
const tarballData = await pacote.tarball('express@4.18.0');
console.log('Tarball size:', tarballData.length, 'bytes');

// Resolve package specifier to URL
const resolved = await pacote.resolve('github:npm/cli');
console.log('Resolved URL:', resolved);

Architecture

Pacote is built around several key components:

Core API Functions: High-level functions (resolve, extract, manifest, packument, tarball) for common package operations
Fetcher Classes: Specialized classes for different package sources (registry, git, file, directory, remote)
Unified Interface: Any package specifier that npm can install works with pacote
Caching System: Built-in caching for performance and offline support
Security Features: Integrity verification, signature validation, and attestation support

Capabilities

Core Package Operations

Essential functions for fetching, extracting, and resolving packages from any source that npm supports.

/**
 * Resolve a package specifier to a tarball URL, file path, or git repository
 */
function resolve(spec, opts);

/**
 * Extract a package's tarball into a destination folder
 */
function extract(spec, dest, opts);

/**
 * Fetch a package's manifest (package.json plus metadata)
 */
function manifest(spec, opts);

/**
 * Fetch a package's packument (full package document)
 */
function packument(spec, opts);

/**
 * Get package tarball data as a buffer
 */
function tarball(spec, opts);

/**
 * Stream tarball through a handler function
 */
function tarball.stream(spec, handler, opts);

/**
 * Save tarball to a file
 */
function tarball.file(spec, dest, opts);

Core API Functions

Advanced Fetcher Classes

Specialized fetcher classes for different package sources and advanced usage patterns.

/**
 * Fetcher classes for specific package types
 */
class GitFetcher extends FetcherBase;
class RegistryFetcher extends FetcherBase;
class FileFetcher extends FetcherBase;
class DirFetcher extends FetcherBase;
class RemoteFetcher extends FetcherBase;

/**
 * Base fetcher class with common functionality
 */
class FetcherBase {
  constructor(spec, opts);
  resolve();
  manifest();
  packument();
  extract(dest);
  tarball();
  tarballStream(handler);
  tarballFile(dest);
}

Fetcher Classes

Command Line Interface

Command line tool for package operations without requiring programmatic usage.

# Resolve package specifier
pacote resolve <spec> [--long]

# Fetch manifest
pacote manifest <spec>

# Fetch packument
pacote packument <spec>

# Download tarball
pacote tarball <spec> [filename]

# Extract package
pacote extract <spec> <folder>

CLI Interface

Configuration Options

Comprehensive configuration system supporting npm registry options, caching, security, and file system settings.

interface PacoteOptions {
  cache?: string;
  registry?: string;
  integrity?: string;
  resolved?: string;
  preferOnline?: boolean;
  preferOffline?: boolean;
  offline?: boolean;
  verifySignatures?: boolean;
  verifyAttestations?: boolean;
  packumentCache?: Map<string, any>;
  tufCache?: string;
  fullMetadata?: boolean;
  fullReadJson?: boolean;
  before?: string;
  defaultTag?: string;
  fmode?: number;
  dmode?: number;
  umask?: number;
  replaceRegistryHost?: string;
  // ... and many more options
}

Configuration Options

Utility Functions

Standalone utility functions for specialized package operations and processing.

/**
 * Utility functions for package processing
 */
function addGitSha(spec, sha);
function cacheDir(fakePlatform);
function isPackageBin(pkg, path);
function tarCreateOptions(manifest);
function removeTrailingSlashes(input);
function npm(npmBin, npmCommand, cwd, env, extra);

Utility Functions

Types

/**
 * Package specifier - any format that npm can install
 */
type PackageSpec = string;

/**
 * Extraction result with metadata
 */
interface ExtractionResult {
  from: string;
  resolved: string;
  integrity: string;
}

/**
 * Package manifest with metadata
 */
interface PackageManifest {
  name: string;
  version: string;
  _resolved: string;
  _from: string;
  _integrity: string;
  _id: string;
  // ... plus all standard package.json fields
}

/**
 * Full packument document
 */
interface Packument {
  name: string;
  versions: { [version: string]: PackageManifest };
  'dist-tags': { [tag: string]: string };
  time?: { [version: string]: string };
  _contentLength: number;
}

/**
 * Tarball data with metadata
 */
interface TarballResult extends Buffer {
  from: string;
  resolved: string;
  integrity: string;
}

Install with Tessl CLI