0
# @pnpm/fetcher-base
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/fetcher-base
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `pnpm add @pnpm/fetcher-base`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  type FetchOptions,
16
  type FetchResult,
17
  type FetchFunction,
18
  type GitFetcher,
19
  type BinaryFetcher,
20
  type DirectoryFetcher,
21
  type Fetchers,
22
  type CustomFetchers,
23
  type PkgNameVersion
24
} from "@pnpm/fetcher-base";
25
```
26

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

29
```javascript
30
// This package exports only TypeScript types, no runtime values
31
// Use with JSDoc for type annotations in JavaScript:
32
/**
33
 * @typedef {import('@pnpm/fetcher-base').FetchOptions} FetchOptions
34
 * @typedef {import('@pnpm/fetcher-base').FetchResult} FetchResult
35
 * @typedef {import('@pnpm/fetcher-base').FetchFunction} FetchFunction
36
 */
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { type Resolution } from '@pnpm/resolver-base';
43
import { type Cafs } from '@pnpm/cafs-types';
44
import {
45
  type FetchOptions,
46
  type FetchResult,
47
  type FetchFunction
48
} from '@pnpm/fetcher-base';
49

50
// Example fetcher implementation using the base types
51
export const myFetcher: FetchFunction = async (
52
  cafs: Cafs,
53
  resolution: Resolution,
54
  opts: FetchOptions
55
): Promise<FetchResult> => {
56
  // Fetch logic here
57
  return {
58
    filesIndex: {}, // File hash mapping
59
    requiresBuild: false,
60
    manifest: undefined // Optional manifest
61
  };
62
};
63
```
64

65
## Architecture
66

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

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

75
## Capabilities
76

77
### Core Fetching Types
78

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

81
```typescript { .api }
82
interface PkgNameVersion {
83
  /** Optional package name */
84
  name?: string;
85
  /** Optional package version */
86
  version?: string;
87
}
88

89
interface FetchOptions {
90
  /** Path to files index file */
91
  filesIndexFile: string;
92
  /** Path to lockfile directory */
93
  lockfileDir: string;
94
  /** Optional callback fired when fetch starts */
95
  onStart?: (totalSize: number | null, attempt: number) => void;
96
  /** Optional callback fired during download progress */
97
  onProgress?: (downloaded: number) => void;
98
  /** Whether to read package manifest */
99
  readManifest?: boolean;
100
  /** Package information */
101
  pkg: PkgNameVersion;
102
}
103

104
interface FetchResult {
105
  /** Whether package is stored locally */
106
  local?: boolean;
107
  /** Package manifest if requested */
108
  manifest?: DependencyManifest;
109
  /** Mapping of file paths to their hashes */
110
  filesIndex: Record<string, string>;
111
  /** Whether package requires build step */
112
  requiresBuild: boolean;
113
}
114

115
type FetchFunction<
116
  FetcherResolution = Resolution,
117
  Options = FetchOptions,
118
  Result = FetchResult
119
> = (
120
  cafs: Cafs,
121
  resolution: FetcherResolution,
122
  opts: Options
123
) => Promise<Result>;
124
```
125

126
### Git Fetchers
127

128
Specialized types for fetching packages from Git repositories.
129

130
```typescript { .api }
131
interface GitFetcherOptions {
132
  /** Whether to read package manifest */
133
  readManifest?: boolean;
134
  /** Path to files index file */
135
  filesIndexFile: string;
136
  /** Optional package information */
137
  pkg?: PkgNameVersion;
138
}
139

140
interface GitFetcherResult {
141
  /** Mapping of file paths to their hashes */
142
  filesIndex: Record<string, string>;
143
  /** Package manifest if requested */
144
  manifest?: DependencyManifest;
145
  /** Whether package requires build step */
146
  requiresBuild: boolean;
147
}
148

149
type GitFetcher = FetchFunction<GitResolution, GitFetcherOptions, GitFetcherResult>;
150
```
151

152
### Directory Fetchers
153

154
Specialized types for fetching packages from local directories.
155

156
```typescript { .api }
157
interface DirectoryFetcherOptions {
158
  /** Path to lockfile directory */
159
  lockfileDir: string;
160
  /** Whether to read package manifest */
161
  readManifest?: boolean;
162
}
163

164
interface DirectoryFetcherResult {
165
  /** Always true for directory fetcher */
166
  local: true;
167
  /** Mapping of file paths to their hashes */
168
  filesIndex: Record<string, string>;
169
  /** Always 'hardlink' for directories */
170
  packageImportMethod: 'hardlink';
171
  /** Package manifest if requested */
172
  manifest?: DependencyManifest;
173
  /** Whether package requires build step */
174
  requiresBuild: boolean;
175
}
176

177
type DirectoryFetcher = FetchFunction<DirectoryResolution, DirectoryFetcherOptions, DirectoryFetcherResult>;
178
```
179

180
### Binary Fetchers
181

182
Specialized types for fetching binary packages.
183

184
```typescript { .api }
185
type BinaryFetcher = FetchFunction<BinaryResolution>;
186
```
187

188
### Fetcher Collections
189

190
Interfaces for organizing and managing multiple fetcher implementations.
191

192
```typescript { .api }
193
interface Fetchers {
194
  /** Fetcher for local tarball files */
195
  localTarball: FetchFunction;
196
  /** Fetcher for remote tarball files */
197
  remoteTarball: FetchFunction;
198
  /** Fetcher for git-hosted tarball files */
199
  gitHostedTarball: FetchFunction;
200
  /** Fetcher for local directories */
201
  directory: DirectoryFetcher;
202
  /** Fetcher for git repositories */
203
  git: GitFetcher;
204
  /** Fetcher for binary packages */
205
  binary: BinaryFetcher;
206
}
207

208
interface CustomFetchers {
209
  /** Optional custom local tarball fetcher factory */
210
  localTarball?: CustomFetcherFactory<FetchFunction>;
211
  /** Optional custom remote tarball fetcher factory */
212
  remoteTarball?: CustomFetcherFactory<FetchFunction>;
213
  /** Optional custom git-hosted tarball fetcher factory */
214
  gitHostedTarball?: CustomFetcherFactory<FetchFunction>;
215
  /** Optional custom directory fetcher factory */
216
  directory?: CustomFetcherFactory<DirectoryFetcher>;
217
  /** Optional custom git fetcher factory */
218
  git?: CustomFetcherFactory<GitFetcher>;
219
}
220
```
221

222
### Custom Fetcher Factories
223

224
Factory pattern for creating configurable fetcher instances.
225

226
```typescript { .api }
227
type CustomFetcherFactory<Fetcher> = (opts: CustomFetcherFactoryOptions) => Fetcher;
228

229
interface CustomFetcherFactoryOptions {
230
  /** Default fetcher implementations to fall back to */
231
  defaultFetchers: Fetchers;
232
}
233
```
234

235
## Types
236

237
### External Dependencies
238

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

241
```typescript { .api }
242
// From @pnpm/resolver-base - import these when implementing fetchers
243
interface Resolution {
244
  // Union type for all resolution types (tarball, git, directory, etc.)
245
}
246

247
interface GitResolution {
248
  // Git repository resolution details
249
}
250

251
interface DirectoryResolution {
252
  // Local directory resolution details
253
}
254

255
interface BinaryResolution {
256
  // Binary package resolution details
257
}
258

259
// From @pnpm/cafs-types - import when implementing fetchers
260
interface Cafs {
261
  // Content-addressable file system interface
262
}
263

264
// From @pnpm/types - import when implementing fetchers
265
interface DependencyManifest {
266
  // Package manifest structure (package.json contents)
267
}
268
```
269

270
**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.