or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-pnpm--fetcher-base

Types for pnpm-compatible fetchers

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@pnpm/fetcher-base@1001.0.x

To install, run

npx @tessl/cli install tessl/npm-pnpm--fetcher-base@1001.0.0

@pnpm/fetcher-base

@pnpm/fetcher-base provides TypeScript type definitions and interfaces for creating pnpm-compatible package fetchers. It defines core types like FetchOptions, FetchResult, and specialized interfaces for different fetcher types (GitFetcher, BinaryFetcher, DirectoryFetcher) that enable the development of custom package retrieval mechanisms within the pnpm ecosystem.

Package Information

Package Name: @pnpm/fetcher-base
Package Type: npm
Language: TypeScript
Installation: pnpm add @pnpm/fetcher-base

Core Imports

import {
  type FetchOptions,
  type FetchResult,
  type FetchFunction,
  type GitFetcher,
  type BinaryFetcher,
  type DirectoryFetcher,
  type Fetchers,
  type CustomFetchers,
  type PkgNameVersion
} from "@pnpm/fetcher-base";

For CommonJS (types are not available at runtime, only used for TypeScript compilation):

// This package exports only TypeScript types, no runtime values
// Use with JSDoc for type annotations in JavaScript:
/**
 * @typedef {import('@pnpm/fetcher-base').FetchOptions} FetchOptions
 * @typedef {import('@pnpm/fetcher-base').FetchResult} FetchResult
 * @typedef {import('@pnpm/fetcher-base').FetchFunction} FetchFunction
 */

Basic Usage

import { type Resolution } from '@pnpm/resolver-base';
import { type Cafs } from '@pnpm/cafs-types';
import {
  type FetchOptions,
  type FetchResult,
  type FetchFunction
} from '@pnpm/fetcher-base';

// Example fetcher implementation using the base types
export const myFetcher: FetchFunction = async (
  cafs: Cafs,
  resolution: Resolution,
  opts: FetchOptions
): Promise<FetchResult> => {
  // Fetch logic here
  return {
    filesIndex: {}, // File hash mapping
    requiresBuild: false,
    manifest: undefined // Optional manifest
  };
};

Architecture

@pnpm/fetcher-base is built around several key components:

Core Types: Basic interfaces like PkgNameVersion, FetchOptions, and FetchResult that all fetchers use
Generic Function Type: FetchFunction<TResolution, TOptions, TResult> providing a flexible template for different fetcher implementations
Specialized Fetchers: Type-safe interfaces for specific package sources (Git, Directory, Binary)
Fetcher Collections: Fetchers and CustomFetchers interfaces for organizing multiple fetcher implementations
Factory Pattern: CustomFetcherFactory for creating configurable fetcher instances

Capabilities

Core Fetching Types

Basic types and interfaces used by all pnpm fetchers for package retrieval operations.

interface PkgNameVersion {
  /** Optional package name */
  name?: string;
  /** Optional package version */
  version?: string;
}

interface FetchOptions {
  /** Path to files index file */
  filesIndexFile: string;
  /** Path to lockfile directory */
  lockfileDir: string;
  /** Optional callback fired when fetch starts */
  onStart?: (totalSize: number | null, attempt: number) => void;
  /** Optional callback fired during download progress */
  onProgress?: (downloaded: number) => void;
  /** Whether to read package manifest */
  readManifest?: boolean;
  /** Package information */
  pkg: PkgNameVersion;
}

interface FetchResult {
  /** Whether package is stored locally */
  local?: boolean;
  /** Package manifest if requested */
  manifest?: DependencyManifest;
  /** Mapping of file paths to their hashes */
  filesIndex: Record<string, string>;
  /** Whether package requires build step */
  requiresBuild: boolean;
}

type FetchFunction<
  FetcherResolution = Resolution,
  Options = FetchOptions,
  Result = FetchResult
> = (
  cafs: Cafs,
  resolution: FetcherResolution,
  opts: Options
) => Promise<Result>;

Git Fetchers

Specialized types for fetching packages from Git repositories.

interface GitFetcherOptions {
  /** Whether to read package manifest */
  readManifest?: boolean;
  /** Path to files index file */
  filesIndexFile: string;
  /** Optional package information */
  pkg?: PkgNameVersion;
}

interface GitFetcherResult {
  /** Mapping of file paths to their hashes */
  filesIndex: Record<string, string>;
  /** Package manifest if requested */
  manifest?: DependencyManifest;
  /** Whether package requires build step */
  requiresBuild: boolean;
}

type GitFetcher = FetchFunction<GitResolution, GitFetcherOptions, GitFetcherResult>;

Directory Fetchers

Specialized types for fetching packages from local directories.

interface DirectoryFetcherOptions {
  /** Path to lockfile directory */
  lockfileDir: string;
  /** Whether to read package manifest */
  readManifest?: boolean;
}

interface DirectoryFetcherResult {
  /** Always true for directory fetcher */
  local: true;
  /** Mapping of file paths to their hashes */
  filesIndex: Record<string, string>;
  /** Always 'hardlink' for directories */
  packageImportMethod: 'hardlink';
  /** Package manifest if requested */
  manifest?: DependencyManifest;
  /** Whether package requires build step */
  requiresBuild: boolean;
}

type DirectoryFetcher = FetchFunction<DirectoryResolution, DirectoryFetcherOptions, DirectoryFetcherResult>;

Binary Fetchers

Specialized types for fetching binary packages.

type BinaryFetcher = FetchFunction<BinaryResolution>;

Fetcher Collections

Interfaces for organizing and managing multiple fetcher implementations.

interface Fetchers {
  /** Fetcher for local tarball files */
  localTarball: FetchFunction;
  /** Fetcher for remote tarball files */
  remoteTarball: FetchFunction;
  /** Fetcher for git-hosted tarball files */
  gitHostedTarball: FetchFunction;
  /** Fetcher for local directories */
  directory: DirectoryFetcher;
  /** Fetcher for git repositories */
  git: GitFetcher;
  /** Fetcher for binary packages */
  binary: BinaryFetcher;
}

interface CustomFetchers {
  /** Optional custom local tarball fetcher factory */
  localTarball?: CustomFetcherFactory<FetchFunction>;
  /** Optional custom remote tarball fetcher factory */
  remoteTarball?: CustomFetcherFactory<FetchFunction>;
  /** Optional custom git-hosted tarball fetcher factory */
  gitHostedTarball?: CustomFetcherFactory<FetchFunction>;
  /** Optional custom directory fetcher factory */
  directory?: CustomFetcherFactory<DirectoryFetcher>;
  /** Optional custom git fetcher factory */
  git?: CustomFetcherFactory<GitFetcher>;
}

Custom Fetcher Factories

Factory pattern for creating configurable fetcher instances.

type CustomFetcherFactory<Fetcher> = (opts: CustomFetcherFactoryOptions) => Fetcher;

interface CustomFetcherFactoryOptions {
  /** Default fetcher implementations to fall back to */
  defaultFetchers: Fetchers;
}

Types

External Dependencies

This package relies on types from external dependencies that should be imported separately:

// From @pnpm/resolver-base - import these when implementing fetchers
interface Resolution {
  // Union type for all resolution types (tarball, git, directory, etc.)
}

interface GitResolution {
  // Git repository resolution details
}

interface DirectoryResolution {
  // Local directory resolution details
}

interface BinaryResolution {
  // Binary package resolution details
}

// From @pnpm/cafs-types - import when implementing fetchers
interface Cafs {
  // Content-addressable file system interface
}

// From @pnpm/types - import when implementing fetchers
interface DependencyManifest {
  // Package manifest structure (package.json contents)
}

Note: These external types must be imported from their respective packages (@pnpm/resolver-base, @pnpm/cafs-types, @pnpm/types) when implementing fetchers. The fetcher-base package only provides the function signatures and interfaces that reference these types.