0
# Fetcher Classes
1
2
Specialized fetcher classes for different package sources and advanced usage patterns. Each fetcher handles a specific type of package specifier and provides the same unified interface through the base FetcherBase class.
3
4
## Capabilities
5
6
### Base Fetcher Class
7
8
All fetcher classes extend FetcherBase, which provides the common interface and functionality.
9
10
```javascript { .api }
11
/**
12
* Base class for all fetchers
13
*/
14
class FetcherBase {
15
/**
16
* Create a fetcher instance
17
* @param {string} spec - Package specifier
18
* @param {Object} opts - Configuration options
19
*/
20
constructor(spec, opts);
21
22
/**
23
* Resolve package to concrete location
24
* @returns {Promise<string>} Resolved URL or path
25
*/
26
resolve();
27
28
/**
29
* Get package manifest
30
* @returns {Promise<PackageManifest>} Package manifest
31
*/
32
manifest();
33
34
/**
35
* Get package packument
36
* @returns {Promise<Packument>} Package document
37
*/
38
packument();
39
40
/**
41
* Extract package to directory
42
* @param {string} dest - Destination directory
43
* @returns {Promise<ExtractionResult>} Extraction result
44
*/
45
extract(dest);
46
47
/**
48
* Get tarball as buffer
49
* @returns {Promise<TarballResult>} Tarball data
50
*/
51
tarball();
52
53
/**
54
* Stream tarball through handler
55
* @param {Function} handler - Stream handler function
56
* @returns {Promise<void>} Handler completion promise
57
*/
58
tarballStream(handler);
59
60
/**
61
* Save tarball to file
62
* @param {string} dest - Destination file path
63
* @returns {Promise<TarballResult>} Tarball metadata
64
*/
65
tarballFile(dest);
66
67
/**
68
* Clean up cached content
69
* @returns {Promise<void>} Cleanup completion promise
70
*/
71
cleanupCached();
72
73
/**
74
* Pick best integrity algorithm from available options
75
* @returns {string} Best available integrity algorithm
76
*/
77
pickIntegrityAlgorithm();
78
79
/**
80
* Check if error indicates data corruption
81
* @param {Error} er - Error to check
82
* @returns {boolean} True if error indicates corruption
83
*/
84
isDataCorruptionError(er);
85
86
/**
87
* Check if error is retriable
88
* @param {Error} er - Error to check
89
* @returns {boolean} True if error can be retried
90
*/
91
isRetriableError(er);
92
93
// Instance properties
94
/** @type {Object} Parsed package specification */
95
spec;
96
/** @type {string} Original package specifier */
97
from;
98
/** @type {string} Resolved package URL/path */
99
resolved;
100
/** @type {string} Package integrity hash */
101
integrity;
102
/** @type {string} Fetcher class name */
103
type;
104
/** @type {string} Cache directory path */
105
cache;
106
/** @type {string} TUF cache directory path */
107
tufCache;
108
/** @type {string} Registry URL */
109
registry;
110
/** @type {Object} Cached manifest object */
111
package;
112
/** @type {Object} Configuration options */
113
opts;
114
}
115
116
/**
117
* Factory method to get appropriate fetcher for spec
118
* @param {string} spec - Package specifier
119
* @param {Object} opts - Configuration options
120
* @returns {FetcherBase} Appropriate fetcher instance
121
*/
122
FetcherBase.get(spec, opts);
123
```
124
125
### Registry Fetcher
126
127
Handles npm registry packages with support for signature verification and attestation validation.
128
129
```javascript { .api }
130
/**
131
* Fetcher for npm registry packages
132
* Supports spec types: ['tag', 'version', 'range']
133
*/
134
class RegistryFetcher extends FetcherBase {
135
constructor(spec, opts);
136
137
// Additional properties
138
/** @type {Map} Packument caching system */
139
packumentCache;
140
/** @type {string} Registry packument URL */
141
packumentUrl;
142
/** @type {Array} Registry signing keys */
143
registryKeys;
144
}
145
```
146
147
**Usage Examples:**
148
149
```javascript
150
const { RegistryFetcher } = require('pacote');
151
152
// Create registry fetcher directly
153
const fetcher = new RegistryFetcher('express@4.18.0', {
154
registry: 'https://registry.npmjs.org',
155
verifySignatures: true
156
});
157
158
const manifest = await fetcher.manifest();
159
console.log('Package:', manifest.name, manifest.version);
160
161
// Fetcher includes registry-specific features
162
const packument = await fetcher.packument(); // Supports corgi format
163
const resolved = await fetcher.resolve(); // Returns registry tarball URL
164
```
165
166
**Registry-Specific Features:**
167
- Supports both compressed (corgi) and full metadata formats
168
- Registry signature verification when enabled
169
- Package attestation verification via Sigstore
170
- Packument caching to reduce duplicate requests
171
- Integrity merging and validation
172
173
### Git Fetcher
174
175
Handles git repository dependencies with support for various hosting services and commit resolution.
176
177
```javascript { .api }
178
/**
179
* Fetcher for git repository packages
180
* Supports spec types: ['git']
181
*/
182
class GitFetcher extends FetcherBase {
183
constructor(spec, opts);
184
185
/**
186
* Construct repository URL from hosted git info
187
* @param {Object} hosted - Hosted git information
188
* @param {Object} opts - Configuration options
189
* @returns {string} Repository URL
190
*/
191
static repoUrl(hosted, opts);
192
193
// Additional properties
194
/** @type {Object} Git reference object */
195
resolvedRef;
196
/** @type {string} Resolved commit SHA */
197
resolvedSha;
198
/** @type {Function} Arborist constructor option */
199
Arborist;
200
}
201
```
202
203
**Usage Examples:**
204
205
```javascript
206
const { GitFetcher } = require('pacote');
207
208
// GitHub repository
209
const gitFetcher = new GitFetcher('github:facebook/react#v18.0.0', {
210
cache: './git-cache'
211
});
212
213
const manifest = await gitFetcher.manifest();
214
console.log('Git package:', manifest.name);
215
216
// GitLab repository
217
const gitlabFetcher = new GitFetcher('gitlab:user/project#main');
218
const resolved = await gitlabFetcher.resolve();
219
220
// Direct git URL
221
const directGit = new GitFetcher('git+https://github.com/npm/cli.git#latest');
222
await directGit.extract('./npm-cli');
223
```
224
225
**Git-Specific Features:**
226
- Supports hosted git services (GitHub, GitLab, Bitbucket)
227
- Automatic HTTPS to SSH fallback for private repositories
228
- Git reference and committish resolution
229
- Prepare script execution for git dependencies
230
- Clone-based extraction when tarball unavailable
231
232
### File Fetcher
233
234
Handles local tarball files with manifest extraction and proper permission handling.
235
236
```javascript { .api }
237
/**
238
* Fetcher for local tarball files
239
* Supports spec types: ['file']
240
*/
241
class FileFetcher extends FetcherBase {
242
constructor(spec, opts);
243
244
/**
245
* Make package bin scripts executable
246
* @param {Object} pkg - Package manifest
247
* @param {string} dest - Destination directory
248
* @returns {Promise<void>} Completion promise
249
*/
250
async exeBins(pkg, dest);
251
}
252
```
253
254
**Usage Examples:**
255
256
```javascript
257
const { FileFetcher } = require('pacote');
258
259
// Local tarball file
260
const fileFetcher = new FileFetcher('file:./packages/my-package.tgz');
261
262
const manifest = await fileFetcher.manifest();
263
console.log('Local package:', manifest.name);
264
265
// Extract local tarball
266
await fileFetcher.extract('./extracted-package');
267
268
// Relative file path
269
const relativeFetcher = new FileFetcher('file:../dist/package.tgz', {
270
where: '/current/working/directory'
271
});
272
```
273
274
**File-Specific Features:**
275
- Direct file system access to local tarballs
276
- Automatic executable permissions for package bin scripts
277
- Manifest extraction via temporary directory
278
- Support for relative file paths
279
280
### Directory Fetcher
281
282
Handles local directories with packaging and prepare script execution.
283
284
```javascript { .api }
285
/**
286
* Fetcher for local directories
287
* Supports spec types: ['directory']
288
*/
289
class DirFetcher extends FetcherBase {
290
constructor(spec, opts);
291
292
/**
293
* Get tar creation options for directory packaging
294
* @param {Object} manifest - Package manifest
295
* @returns {Object} Tar creation options
296
*/
297
static tarCreateOptions(manifest);
298
299
// Additional properties
300
/** @type {Object} Arborist tree object */
301
tree;
302
/** @type {Function} Arborist constructor */
303
Arborist;
304
}
305
```
306
307
**Usage Examples:**
308
309
```javascript
310
const { DirFetcher } = require('pacote');
311
312
// Local directory
313
const dirFetcher = new DirFetcher('file:./my-package', {
314
Arborist: require('@npmcli/arborist')
315
});
316
317
const manifest = await dirFetcher.manifest();
318
console.log('Directory package:', manifest.name);
319
320
// Create tarball from directory
321
const tarball = await dirFetcher.tarball();
322
console.log('Directory tarball size:', tarball.length);
323
324
// Package directory with prepare scripts
325
await dirFetcher.extract('./packaged-dir');
326
```
327
328
**Directory-Specific Features:**
329
- Executes prepare scripts before packaging
330
- Uses npm-packlist to determine included files
331
- Creates reproducible tarballs with consistent timestamps
332
- Requires Arborist constructor for dependency operations
333
334
### Remote Fetcher
335
336
Handles remote tarball URLs with streaming downloads and integrity verification.
337
338
```javascript { .api }
339
/**
340
* Fetcher for remote tarball URLs
341
* Supports spec types: ['remote']
342
*/
343
class RemoteFetcher extends FetcherBase {
344
constructor(spec, opts);
345
346
// Additional properties
347
/** @type {string} Package identifier for headers */
348
pkgid;
349
}
350
```
351
352
**Usage Examples:**
353
354
```javascript
355
const { RemoteFetcher } = require('pacote');
356
357
// Remote tarball URL
358
const remoteFetcher = new RemoteFetcher('https://example.com/package.tgz');
359
360
const manifest = await remoteFetcher.manifest();
361
console.log('Remote package:', manifest.name);
362
363
// Download and extract remote tarball
364
await remoteFetcher.extract('./remote-package');
365
366
// Remote tarball with integrity verification
367
const verifiedFetcher = new RemoteFetcher('https://cdn.example.com/pkg.tgz', {
368
integrity: 'sha512-...'
369
});
370
```
371
372
**Remote-Specific Features:**
373
- Registry host replacement support
374
- Streaming downloads with integrity verification
375
- Uses npm-registry-fetch for HTTP operations
376
- Relies on make-fetch-happen for caching
377
378
## Advanced Usage Patterns
379
380
### Direct Fetcher Instantiation
381
382
```javascript
383
const { RegistryFetcher, GitFetcher } = require('pacote');
384
385
// Create fetchers directly for advanced control
386
const registryFetcher = new RegistryFetcher('lodash@4.17.21', {
387
packumentCache: new Map(),
388
verifySignatures: true
389
});
390
391
const gitFetcher = new GitFetcher('github:npm/cli#latest', {
392
allowGitIgnore: true
393
});
394
395
// Use fetchers independently
396
const [registryManifest, gitManifest] = await Promise.all([
397
registryFetcher.manifest(),
398
gitFetcher.manifest()
399
]);
400
```
401
402
### Fetcher Factory Method
403
404
```javascript
405
const { FetcherBase } = require('pacote');
406
407
// Automatic fetcher selection
408
const fetcher1 = FetcherBase.get('express@latest'); // RegistryFetcher
409
const fetcher2 = FetcherBase.get('github:user/repo'); // GitFetcher
410
const fetcher3 = FetcherBase.get('file:./package.tgz'); // FileFetcher
411
const fetcher4 = FetcherBase.get('https://example.com/pkg.tgz'); // RemoteFetcher
412
const fetcher5 = FetcherBase.get('file:./src'); // DirFetcher
413
414
// All fetchers have the same interface
415
const manifests = await Promise.all([
416
fetcher1.manifest(),
417
fetcher2.manifest(),
418
fetcher3.manifest(),
419
fetcher4.manifest(),
420
fetcher5.manifest()
421
]);
422
```
423
424
### Fetcher Properties
425
426
All fetcher instances expose useful properties:
427
428
```javascript
429
const fetcher = new RegistryFetcher('express@4.18.0');
430
431
console.log('Spec:', fetcher.spec); // Parsed package spec
432
console.log('From:', fetcher.from); // Original specifier
433
console.log('Type:', fetcher.type); // 'RegistryFetcher'
434
console.log('Registry:', fetcher.registry); // Registry URL
435
console.log('Cache:', fetcher.cache); // Cache directory
436
console.log('Resolved:', fetcher.resolved); // Pre-resolved URL (if any)
437
```