0
# @pnpm/npm-resolver
1

2
@pnpm/npm-resolver is a TypeScript library that provides comprehensive package resolution for npm-hosted packages. It handles package metadata fetching, caching, version selection, offline support, and registry authentication as part of the pnpm ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/npm-resolver
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/npm-resolver`
10
- **Peer Dependencies**: `@pnpm/logger@^1.0.0 || ^2.0.0`
11

12
## Core Imports
13

14
ES6/TypeScript:
15
```typescript
16
import createResolveFromNpm, { PackageMeta, PackageMetaCache } from '@pnpm/npm-resolver';
17
import type { ResolveResult, LocalPackages } from '@pnpm/resolver-base';
18
import type { PackageJson } from '@pnpm/types';
19
```
20

21
CommonJS:
22
```javascript
23
const createResolveFromNpm = require('@pnpm/npm-resolver').default;
24
const { PackageMeta, PackageMetaCache } = require('@pnpm/npm-resolver');
25
```
26

27
## Basic Usage
28

29
```typescript
30
import createResolveFromNpm from '@pnpm/npm-resolver';
31

32
// Create resolver with configuration
33
const resolve = createResolveFromNpm({
34
  metaCache: new Map(),
35
  store: '.store',
36
  offline: false,
37
  rawNpmConfig: {
38
    registry: 'https://registry.npmjs.org/',
39
  },
40
});
41

42
// Resolve a package
43
const result = await resolve(
44
  { alias: 'is-positive', pref: '1.0.0' },
45
  { 
46
    registry: 'https://registry.npmjs.org/',
47
    prefix: process.cwd()
48
  }
49
);
50

51
console.log(result.id);           // 'registry.npmjs.org/is-positive/1.0.0'
52
console.log(result.latest);       // '3.1.0'
53
console.log(result.resolvedVia);  // 'npm-registry'
54
```
55

56
## Architecture
57

58
The resolver follows a factory pattern where `createResolveFromNpm` creates a configured resolver function. Key components include:
59

60
- **Registry Fetcher**: Handles HTTP requests to npm registries with authentication
61
- **Metadata Cache**: Caches package metadata to reduce registry requests
62
- **Version Picker**: Selects appropriate package versions based on preferences
63
- **Local Package Fallback**: Falls back to local packages when registry resolution fails
64
- **Offline Support**: Works with cached metadata when offline
65

66
## Capabilities
67

68
### Package Resolution
69

70
Creates a resolver function that can resolve npm packages by name and version preference.
71

72
```typescript { .api }
73
function createResolveFromNpm(opts: ResolverOptions): ResolveFunction;
74

75
interface ResolverOptions {
76
  cert?: string;
77
  fullMetadata?: boolean;
78
  key?: string;
79
  ca?: string;
80
  strictSsl?: boolean;
81
  rawNpmConfig: object;
82
  metaCache: PackageMetaCache;
83
  store: string;
84
  proxy?: string;
85
  httpsProxy?: string;
86
  localAddress?: string;
87
  userAgent?: string;
88
  offline?: boolean;
89
  preferOffline?: boolean;
90
  fetchRetries?: number;
91
  fetchRetryFactor?: number;
92
  fetchRetryMintimeout?: number;
93
  fetchRetryMaxtimeout?: number;
94
}
95

96
type ResolveFunction = (
97
  wantedDependency: WantedDependency,
98
  opts: ResolveOptions
99
) => Promise<ResolveResult | null>;
100
```
101

102
[Package Resolution](./package-resolution.md)
103

104
### Metadata Management
105

106
Package metadata caching and retrieval from npm registries.
107

108
```typescript { .api }
109
interface PackageMetaCache {
110
  get(key: string): PackageMeta | undefined;
111
  set(key: string, meta: PackageMeta): void;
112
  has(key: string): boolean;
113
}
114

115
interface PackageMeta {
116
  'dist-tags': { [name: string]: string };
117
  versions: { [name: string]: PackageInRegistry };
118
  cachedAt?: number;
119
}
120
```
121

122
[Metadata Management](./metadata-management.md)
123

124
### Version Selection
125

126
Intelligent package version selection based on preferences and constraints.
127

128
```typescript { .api }
129
interface WantedDependency {
130
  alias?: string;
131
  pref?: string;
132
}
133

134
interface ResolveOptions {
135
  defaultTag?: string;
136
  dryRun?: boolean;
137
  registry: string;
138
  preferredVersions?: {
139
    [packageName: string]: {
140
      selector: string;
141
      type: 'version' | 'range' | 'tag';
142
    };
143
  };
144
  prefix: string;
145
  localPackages?: LocalPackages;
146
}
147
```
148

149
[Version Selection](./version-selection.md)
150

151

152
## Core Types
153

154
**Note**: `ResolveResult` and `LocalPackages` are imported from `@pnpm/resolver-base`, `PackageJson` from `@pnpm/types`, and `PackageManifest` from `@pnpm/types`.
155

156
```typescript { .api }
157
interface ResolveResult {
158
  id: string;
159
  latest: string;
160
  normalizedPref?: string;
161
  package: PackageInRegistry;
162
  resolution: {
163
    integrity: string;
164
    registry: string;
165
    tarball: string;
166
  } | {
167
    directory: string;
168
    type: 'directory';
169
  };
170
  resolvedVia: 'npm-registry' | 'local-filesystem';
171
}
172

173
interface RegistryPackageSpec {
174
  type: 'tag' | 'version' | 'range';
175
  name: string;
176
  fetchSpec: string;
177
  normalizedPref?: string;
178
}
179

180
type PackageInRegistry = PackageManifest & {
181
  dist: {
182
    integrity?: string;
183
    shasum: string;
184
    tarball: string;
185
  };
186
};
187

188
interface LocalPackages {
189
  [packageName: string]: {
190
    [version: string]: {
191
      directory: string;
192
      package: PackageJson;
193
    };
194
  };
195
}
196
```