0
# @pnpm/lockfile.filtering
1

2
## Overview
3

4
@pnpm/lockfile.filtering is an internal pnpm utility package that provides functions for filtering pnpm lockfile dependencies and workspace packages. This package enables selective filtering of lockfile entries based on importers (workspace projects), dependency types, and engine compatibility, allowing for optimized installations and dependency management in pnpm workspaces.
5

6
This package is primarily designed for internal use within the pnpm ecosystem, including pnpm core, plugins, and extensions that need to manipulate lockfile data.
7

8
## Package Information
9

10
- **Name**: @pnpm/lockfile.filtering
11
- **Type**: npm package (internal pnpm workspace package)
12
- **Language**: TypeScript
13
- **Installation**: This is an internal pnpm package. Install via pnpm itself or use in pnpm plugins/extensions
14

15
## Core Imports
16

17
```typescript
18
// ESM
19
import { 
20
  filterLockfile, 
21
  filterLockfileByImporters, 
22
  filterLockfileByImportersAndEngine, 
23
  filterLockfileByEngine
24
} from "@pnpm/lockfile.filtering";
25

26
// Note: Type imports need to be imported from the specific module
27
import type { FilterLockfileResult, FilterLockfileOptions } from "@pnpm/lockfile.filtering/lib/filterLockfileByImportersAndEngine";
28

29
// CommonJS
30
const { 
31
  filterLockfile, 
32
  filterLockfileByImporters, 
33
  filterLockfileByImportersAndEngine, 
34
  filterLockfileByEngine 
35
} = require("@pnpm/lockfile.filtering");
36
```
37

38
## Basic Usage
39

40
```typescript
41
import { filterLockfile } from "@pnpm/lockfile.filtering";
42
import type { LockfileObject, DepPath } from "@pnpm/lockfile.types";
43
import type { DependenciesField } from "@pnpm/types";
44

45
// Filter lockfile to include only production dependencies
46
const filteredLockfile = filterLockfile(lockfile, {
47
  include: {
48
    dependencies: true,
49
    devDependencies: false,
50
    optionalDependencies: false
51
  },
52
  skipped: new Set<DepPath>()
53
});
54
```
55

56
## Architecture
57

58
The package provides a layered filtering approach:
59

60
- **Basic Filtering** (`filterLockfile`): Filters all importers with dependency type selection
61
- **Importer-Specific Filtering** (`filterLockfileByImporters`): Filters specific workspace projects with error handling options
62
- **Engine-Aware Filtering** (`filterLockfileByEngine`, `filterLockfileByImportersAndEngine`): Advanced filtering with Node.js version compatibility, platform architecture support, and package installability validation
63

64
The engine-aware functions utilize `@pnpm/package-is-installable` to validate packages against the current environment, ensuring only compatible packages are included in the filtered lockfile. All filtering functions use `@pnpm/lockfile.walker` internally to traverse the dependency graph efficiently.
65

66
## Capabilities
67

68
### Basic Lockfile Filtering
69

70
Filters a lockfile for all importers with specified dependency types.
71

72
```typescript { .api }
73
/**
74
 * Filters a lockfile for all importers with specified dependency types
75
 * @param lockfile - The lockfile object to filter
76
 * @param opts - Filtering options
77
 * @param opts.include - Specifies which dependency types to include
78
 * @param opts.skipped - Set of dependency paths to skip
79
 * @returns Filtered lockfile object
80
 */
81
function filterLockfile(
82
  lockfile: LockfileObject,
83
  opts: {
84
    include: { [dependenciesField in DependenciesField]: boolean }
85
    skipped: Set<DepPath>
86
  }
87
): LockfileObject;
88
```
89

90
### Importer-Specific Filtering
91

92
Filters a lockfile for specific importers (workspace projects) with dependency type filtering and optional error handling for missing dependencies.
93

94
```typescript { .api }
95
/**
96
 * Filters a lockfile for specific importers with dependency type filtering
97
 * @param lockfile - The lockfile object to filter
98
 * @param importerIds - Array of project IDs to include in filtering
99
 * @param opts - Filtering options
100
 * @param opts.include - Specifies which dependency types to include
101
 * @param opts.skipped - Set of dependency paths to skip
102
 * @param opts.failOnMissingDependencies - Whether to throw error for missing dependencies
103
 * @returns Filtered lockfile object
104
 */
105
function filterLockfileByImporters(
106
  lockfile: LockfileObject,
107
  importerIds: ProjectId[],
108
  opts: {
109
    include: { [dependenciesField in DependenciesField]: boolean }
110
    skipped: Set<DepPath>
111
    failOnMissingDependencies: boolean
112
  }
113
): LockfileObject;
114
```
115

116
### Engine-Compatible Filtering for All Importers
117

118
Filters a lockfile for all importers with engine compatibility checking, including Node.js version and platform architecture support.
119

120
```typescript { .api }
121
/**
122
 * Filters a lockfile for all importers with engine compatibility checking
123
 * @param lockfile - The lockfile object to filter
124
 * @param opts - Engine filtering options
125
 * @returns Object containing filtered lockfile and selected importer IDs
126
 */
127
function filterLockfileByEngine(
128
  lockfile: LockfileObject,
129
  opts: FilterLockfileOptions
130
): FilterLockfileResult;
131
```
132

133
### Engine-Compatible Filtering for Specific Importers
134

135
Filters a lockfile by specific importers with comprehensive engine compatibility checking, platform support, and package installability validation.
136

137
```typescript { .api }
138
/**
139
 * Filters a lockfile by importers with engine compatibility checking
140
 * @param lockfile - The lockfile object to filter
141
 * @param importerIds - Array of project IDs to include in filtering
142
 * @param opts - Engine filtering options
143
 * @returns Object containing filtered lockfile and selected importer IDs
144
 */
145
function filterLockfileByImportersAndEngine(
146
  lockfile: LockfileObject,
147
  importerIds: ProjectId[],
148
  opts: FilterLockfileOptions
149
): FilterLockfileResult;
150
```
151

152
## Types
153

154
### FilterLockfileResult
155

156
Result object returned by engine-aware filtering functions containing the filtered lockfile and metadata about selected importers.
157

158
```typescript { .api }
159
interface FilterLockfileResult {
160
  /** The filtered lockfile object */
161
  lockfile: LockfileObject;
162
  /** Array of project IDs that were selected during filtering */
163
  selectedImporterIds: ProjectId[];
164
}
165
```
166

167
### FilterLockfileOptions
168

169
Comprehensive options for engine-aware lockfile filtering, including Node.js compatibility, platform architecture support, and error handling preferences.
170

171
```typescript { .api }
172
interface FilterLockfileOptions {
173
  /** Current engine configuration */
174
  currentEngine: {
175
    /** Node.js version for compatibility checking */
176
    nodeVersion?: string;
177
    /** pnpm version for compatibility checking */
178
    pnpmVersion: string;
179
  };
180
  /** Whether to strictly enforce engine compatibility */
181
  engineStrict: boolean;
182
  /** Specifies which dependency types to include */
183
  include: { [dependenciesField in DependenciesField]: boolean };
184
  /** Whether to include packages that are incompatible with current platform */
185
  includeIncompatiblePackages?: boolean;
186
  /** Whether to throw error for missing dependencies */
187
  failOnMissingDependencies: boolean;
188
  /** Directory path of the lockfile for resolving relative paths */
189
  lockfileDir: string;
190
  /** Set of dependency paths to skip during filtering */
191
  skipped: Set<string>;
192
  /** Platform architecture configurations for compatibility checking */
193
  supportedArchitectures?: SupportedArchitectures;
194
}
195
```
196

197
### Core Type Dependencies
198

199
The following types are imported from `@pnpm/types` and `@pnpm/lockfile.types`:
200

201
```typescript { .api }
202
/** Union type for dependency field names */
203
type DependenciesField = 'optionalDependencies' | 'dependencies' | 'devDependencies';
204

205
/** Branded string type for dependency paths */
206
type DepPath = string & { __brand: 'DepPath' };
207

208
/** Branded string type for project identifiers */
209
type ProjectId = string & { __brand: 'ProjectId' };
210

211
/** Lockfile object structure containing importers and package snapshots */
212
interface LockfileObject {
213
  /** Project configurations indexed by project ID */
214
  importers: Record<ProjectId, ProjectSnapshot>;
215
  /** Package snapshots indexed by dependency path */
216
  packages?: PackageSnapshots;
217
  /** Additional lockfile metadata */
218
  [key: string]: any;
219
}
220

221
/** Project snapshot containing dependency specifications and metadata */
222
interface ProjectSnapshot {
223
  /** Package version specifiers (required) */
224
  specifiers: Record<string, string>;
225
  /** Production dependencies */
226
  dependencies?: Record<string, string>;
227
  /** Development dependencies */
228
  devDependencies?: Record<string, string>;
229
  /** Optional dependencies */
230
  optionalDependencies?: Record<string, string>;
231
  /** Dependencies metadata for installation behavior */
232
  dependenciesMeta?: DependenciesMeta;
233
  /** Publish directory override */
234
  publishDirectory?: string;
235
}
236

237
/** Collection of package snapshots */
238
type PackageSnapshots = Record<DepPath, PackageSnapshot>;
239

240
/** Individual package snapshot with metadata and resolution */
241
interface PackageSnapshot {
242
  /** Package ID identifier */
243
  id?: string;
244
  /** Package resolution information */
245
  resolution: LockfileResolution;
246
  /** Whether package is optional */
247
  optional?: true;
248
  /** Package dependencies */
249
  dependencies?: Record<string, string>;
250
  /** Package optional dependencies */
251
  optionalDependencies?: Record<string, string>;
252
  /** Transitive peer dependencies */
253
  transitivePeerDependencies?: string[];
254
  /** Peer dependencies specification */
255
  peerDependencies?: Record<string, string>;
256
  /** Node.js engines specification */
257
  engines?: Record<string, string> & { node: string };
258
  /** Supported operating systems */
259
  os?: string[];
260
  /** Supported CPU architectures */
261
  cpu?: string[];
262
  /** Supported libc implementations */
263
  libc?: string[];
264
  /** Whether package has binaries */
265
  hasBin?: true;
266
  /** Package deprecation message */
267
  deprecated?: string;
268
}
269

270
/** Platform architecture configurations */
271
interface SupportedArchitectures {
272
  /** Supported CPU architectures */
273
  cpu?: string[];
274
  /** Supported operating systems */
275
  os?: string[];
276
  /** Supported libc implementations */
277
  libc?: string[];
278
}
279

280
/** Lockfile resolution types for different package sources */
281
type LockfileResolution = {
282
  /** Package integrity hash */
283
  integrity: string;
284
} | {
285
  /** Tarball resolution */
286
  tarball: string;
287
  integrity?: string;
288
} | {
289
  /** Git repository resolution */
290
  type: 'git';
291
  repo: string;
292
  commit: string;
293
  path?: string;
294
} | {
295
  /** Directory resolution */
296
  type: 'directory';
297
  directory: string;
298
};
299

300
/** Dependencies metadata for controlling installation behavior */
301
interface DependenciesMeta {
302
  [dependencyName: string]: {
303
    /** Mark dependency as optional */
304
    optional?: boolean;
305
    /** Mark dependency as injected */
306
    injected?: boolean;
307
  };
308
}
309
```