0
# @pnpm/tarball-resolver
1

2
@pnpm/tarball-resolver is a resolver for tarball dependencies that handles HTTP/HTTPS URLs. It processes tarball URLs from npm registries and other sources, managing redirects for immutable cache responses and filtering out direct repository URLs.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/tarball-resolver
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/tarball-resolver`
10
- **Node.js Requirements**: >=18.12
11

12
## Core Imports
13

14
```typescript
15
import { resolveFromTarball, type TarballResolveResult } from "@pnpm/tarball-resolver";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { resolveFromTarball } = require("@pnpm/tarball-resolver");
22
```
23

24
Note: Some older examples show `require('@pnpm/tarball-resolver').default`, but the named import is preferred.
25

26
## Basic Usage
27

28
```typescript
29
import { resolveFromTarball } from "@pnpm/tarball-resolver";
30
import { createFetchFromRegistry } from "@pnpm/fetch";
31

32
// Create a fetch function for registry requests
33
const fetch = createFetchFromRegistry({});
34

35
// Resolve a tarball from npm registry
36
const result = await resolveFromTarball(fetch, {
37
  bareSpecifier: "https://registry.npmjs.org/is-array/-/is-array-1.0.1.tgz"
38
});
39

40
if (result) {
41
  console.log("Resolved tarball:");
42
  console.log("ID:", result.id);
43
  console.log("Tarball URL:", result.resolution.tarball);
44
  console.log("Resolved via:", result.resolvedVia);
45
}
46
```
47

48
## Capabilities
49

50
### Tarball Resolution
51

52
Resolves tarball dependencies from HTTP/HTTPS URLs, handling redirects for immutable responses and filtering out repository URLs.
53

54
```typescript { .api }
55
async function resolveFromTarball(
56
  fetchFromRegistry: FetchFromRegistry,
57
  wantedDependency: { bareSpecifier: string }
58
): Promise<TarballResolveResult | null>;
59
```
60

61
**Parameters:**
62
- `fetchFromRegistry`: Function that performs HTTP requests to package registries
63
- `wantedDependency`: Object containing the tarball URL to resolve
64

65
**Returns:**
66
- `Promise<TarballResolveResult | null>`: Resolution result or null if URL is not a valid tarball
67

68
**Behavior:**
69
- Only processes URLs starting with `http:` or `https:`
70
- Returns `null` for non-HTTP/HTTPS URLs
71
- Returns `null` for direct repository URLs (GitHub, GitLab, Bitbucket)
72
- Makes HEAD request to check for immutable cache-control headers
73
- Uses final redirected URL for immutable responses
74
- Uses original URL for mutable responses
75

76
**Usage Examples:**
77

78
Resolving an immutable tarball (npm registry):
79
```typescript
80
const result = await resolveFromTarball(fetch, {
81
  bareSpecifier: "http://registry.npmjs.org/is-array/-/is-array-1.0.1.tgz"
82
});
83
// Returns result with HTTPS redirected URL
84
```
85

86
Resolving a mutable tarball:
87
```typescript
88
const result = await resolveFromTarball(fetch, {
89
  bareSpecifier: "https://github.com/hegemonic/taffydb/tarball/master"
90
});
91
// Returns result with original URL
92
```
93

94
Non-tarball URLs (returns null):
95
```typescript
96
// Repository URLs are filtered out
97
const result1 = await resolveFromTarball(fetch, {
98
  bareSpecifier: "https://github.com/foo/bar"
99
});
100
// Returns null
101

102
// Non-HTTP URLs are filtered out
103
const result2 = await resolveFromTarball(fetch, {
104
  bareSpecifier: "file:///path/to/local.tgz"
105
});
106
// Returns null
107
```
108

109
## Types
110

111
```typescript { .api }
112
interface TarballResolveResult extends ResolveResult {
113
  normalizedBareSpecifier: string;
114
  resolution: TarballResolution;
115
  resolvedVia: 'url';
116
}
117
```
118

119
The result object returned by `resolveFromTarball` when successful.
120

121
**Properties:**
122
- `id`: Package resolution identifier (inherited from ResolveResult)
123
- `normalizedBareSpecifier`: The final tarball URL (after any redirects)
124
- `resolution`: Tarball resolution metadata containing the tarball URL
125
- `resolvedVia`: Always set to 'url' for tarball resolutions
126

127
```typescript { .api }
128
interface TarballResolution {
129
  type?: undefined;
130
  tarball: string;
131
  integrity?: string;
132
  path?: string;
133
}
134
```
135

136
Resolution metadata for tarball dependencies.
137

138
**Properties:**
139
- `tarball`: The URL of the tarball file
140
- `integrity`: Optional integrity hash for verification
141
- `path`: Optional path within the tarball
142
- `type`: Always undefined for tarball resolutions
143

144
```typescript { .api }
145
type FetchFromRegistry = (
146
  url: string,
147
  opts?: RequestInit & {
148
    authHeaderValue?: string;
149
    compress?: boolean;
150
    retry?: RetryTimeoutOptions;
151
    timeout?: number;
152
  }
153
) => Promise<Response>;
154
```
155

156
Function type for making HTTP requests to package registries.
157

158
**Parameters:**
159
- `url`: The URL to fetch
160
- `opts`: Optional request options including authentication, compression, retry, and timeout settings
161

162
**Returns:**
163
- `Promise<Response>`: Standard HTTP Response object
164

165
```typescript { .api }
166
type ResolveResult = {
167
  id: PkgResolutionId;
168
  latest?: string;
169
  publishedAt?: string;
170
  manifest?: DependencyManifest;
171
  resolution: Resolution;
172
  resolvedVia: string;
173
  normalizedBareSpecifier?: string;
174
  alias?: string;
175
};
176
```
177

178
Base interface for all resolution results (from @pnpm/resolver-base).
179

180
```typescript { .api }
181
type PkgResolutionId = string;
182
```
183

184
Unique identifier for a resolved package (from @pnpm/resolver-base).