0
# @pnpm/store-controller-types
1

2
TypeScript type definitions for pnpm's store controller functionality, providing comprehensive interfaces for package resolution, fetching, and storage operations. This package serves as the central interface contract between pnpm's package management system and its storage layer.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/store-controller-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/store-controller-types`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  StoreController,
16
  RequestPackageFunction,
17
  FetchPackageToStoreFunction,
18
  PackageResponse,
19
  BundledManifest
20
} from "@pnpm/store-controller-types";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const {
27
  StoreController,
28
  RequestPackageFunction,
29
  FetchPackageToStoreFunction,
30
  PackageResponse,
31
  BundledManifest
32
} = require("@pnpm/store-controller-types");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import {
39
  StoreController,
40
  RequestPackageFunction,
41
  FetchPackageToStoreFunction,
42
  RequestPackageOptions,
43
  FetchPackageToStoreOptions
44
} from "@pnpm/store-controller-types";
45

46
// Implementing a store controller
47
class MyStoreController implements StoreController {
48
  async requestPackage: RequestPackageFunction = async (wantedDependency, options) => {
49
    // Implementation for requesting packages
50
    return {
51
      body: {
52
        isLocal: false,
53
        resolution: { type: 'version', version: '1.0.0' },
54
        id: 'registry.npmjs.org/my-package/1.0.0',
55
        updated: false
56
      }
57
    };
58
  };
59

60
  fetchPackage: FetchPackageToStoreFunction = (opts) => {
61
    // Implementation for fetching packages
62
    return {
63
      filesIndexFile: '/path/to/files-index',
64
      fetching: async () => ({
65
        files: { fromStore: false, filenames: [], sideEffects: {} }
66
      })
67
    };
68
  };
69

70
  // Other required methods...
71
  async close() {}
72
  async prune() {}
73
  // etc.
74
}
75
```
76

77
## Architecture
78

79
The @pnpm/store-controller-types package defines the core architecture for pnpm's package storage system:
80

81
- **Store Controller Interface**: Central hub coordinating all package storage operations
82
- **Package Resolution Types**: Types for resolving package identifiers to concrete packages  
83
- **Fetch Operations**: Interfaces for downloading and caching packages
84
- **Import Operations**: Types for importing packages from store to node_modules
85
- **Bundled Manifest Types**: Subset of package manifest fields for bundled dependencies
86
- **Error Handling**: Type-safe error handling patterns
87

88
## Capabilities
89

90
### Store Controller Interface
91

92
Core interface that orchestrates all package storage operations including requesting, fetching, importing, and managing packages.
93

94
```typescript { .api }
95
interface StoreController {
96
  /** Request and resolve a package, returning metadata and optional fetch function */
97
  requestPackage: RequestPackageFunction;
98
  /** Fetch a package to the store, returning files index and fetch promise */
99
  fetchPackage: FetchPackageToStoreFunction | FetchPackageToStoreFunctionAsync;
100
  /** Get the files index file path for a package */
101
  getFilesIndexFilePath: GetFilesIndexFilePath;
102
  /** Import a package from store to destination directory */
103
  importPackage: ImportPackageFunctionAsync;
104
  /** Close the store controller and cleanup resources */
105
  close: () => Promise<void>;
106
  /** Prune unused packages from the store */
107
  prune: (removeAlienFiles?: boolean) => Promise<void>;
108
  /** Upload a built package to the store */
109
  upload: UploadPkgToStore;
110
  /** Clear the resolution cache */
111
  clearResolutionCache: () => void;
112
}
113
```
114

115
### Package Request Operations
116

117
Functions and types for requesting packages with dependency resolution.
118

119
```typescript { .api }
120
type RequestPackageFunction = (
121
  wantedDependency: WantedDependency & { optional?: boolean },
122
  options: RequestPackageOptions
123
) => Promise<PackageResponse>;
124

125
interface RequestPackageOptions {
126
  /** Always try workspace packages first when resolving */
127
  alwaysTryWorkspacePackages?: boolean;
128
  /** Information about the current package being processed */
129
  currentPkg?: {
130
    id?: PkgResolutionId;
131
    name?: string;
132
    resolution?: Resolution;
133
    version?: string;
134
  };
135
  /** Expected package name and version from lockfile */
136
  expectedPkg?: PkgNameVersion;
137
  /** Default tag to use when no version is specified */
138
  defaultTag?: string;
139
  /** Prefer the lowest satisfying version instead of highest */
140
  pickLowestVersion?: boolean;
141
  /** Date when package was published (for filtering) */
142
  publishedBy?: Date;
143
  /** Priority for downloading this package */
144
  downloadPriority: number;
145
  /** Skip running scripts during installation */
146
  ignoreScripts?: boolean;
147
  /** Directory of the current project */
148
  projectDir: string;
149
  /** Directory containing the lockfile */
150
  lockfileDir: string;
151
  /** Version preferences for resolution */
152
  preferredVersions: PreferredVersions;
153
  /** Prefer workspace packages over external packages */
154
  preferWorkspacePackages?: boolean;
155
  /** Enable side effects caching */
156
  sideEffectsCache?: boolean;
157
  /** Skip fetching the package (resolve only) */
158
  skipFetch?: boolean;
159
  /** Update strategy: false (no updates), 'compatible', or 'latest' */
160
  update?: false | 'compatible' | 'latest';
161
  /** Workspace packages mapping */
162
  workspacePackages?: WorkspacePackages;
163
  /** Force resolution even if cached */
164
  forceResolve?: boolean;
165
  /** Supported architectures for native packages */
166
  supportedArchitectures?: SupportedArchitectures;
167
  /** Error handler for fetch operations */
168
  onFetchError?: OnFetchError;
169
  /** Inject workspace packages into resolution */
170
  injectWorkspacePackages?: boolean;
171
  /** Calculate the normalized specifier */
172
  calcSpecifier?: boolean;
173
  /** Pinned version information */
174
  pinnedVersion?: PinnedVersion;
175
}
176

177
interface PackageResponse {
178
  /** Optional function to fetch package files */
179
  fetching?: () => Promise<PkgRequestFetchResult>;
180
  /** Path to the files index file */
181
  filesIndexFile?: string;
182
  /** Package resolution and metadata */
183
  body: {
184
    /** Whether package is local (workspace) */
185
    isLocal: boolean;
186
    /** Whether package can be installed */
187
    isInstallable?: boolean;
188
    /** Package resolution information */
189
    resolution: Resolution;
190
    /** Package manifest/metadata */
191
    manifest?: PackageManifest;
192
    /** Unique package identifier */
193
    id: PkgResolutionId;
194
    /** Normalized bare specifier */
195
    normalizedBareSpecifier?: string;
196
    /** Whether package was updated */
197
    updated: boolean;
198
    /** Package publication timestamp */
199
    publishedAt?: string;
200
    /** How package was resolved */
201
    resolvedVia?: string;
202
    /** Latest available version */
203
    latest?: string;
204
    /** Package alias */
205
    alias?: string;
206
  } & (
207
    {
208
      isLocal: true;
209
      resolution: DirectoryResolution;
210
    } | {
211
      isLocal: false;
212
    }
213
  );
214
}
215
```
216

217
### Package Fetch Operations
218

219
Types for fetching packages from registries and storing them locally.
220

221
```typescript { .api }
222
type FetchPackageToStoreFunction = (opts: FetchPackageToStoreOptions) => FetchResponse;
223
type FetchPackageToStoreFunctionAsync = (opts: FetchPackageToStoreOptions) => Promise<FetchResponse>;
224

225
interface FetchPackageToStoreOptions {
226
  /** Fetch the raw package manifest */
227
  fetchRawManifest?: boolean;
228
  /** Force refetch even if package exists */
229
  force: boolean;
230
  /** Skip running package scripts */
231
  ignoreScripts?: boolean;
232
  /** Directory containing the lockfile */
233
  lockfileDir: string;
234
  /** Package information to fetch */
235
  pkg: PkgNameVersion & {
236
    id: string;
237
    resolution: Resolution;
238
  };
239
  /** Error handler for fetch failures */
240
  onFetchError?: OnFetchError;
241
  /** Supported architectures for platform-specific packages */
242
  supportedArchitectures?: SupportedArchitectures;
243
}
244

245
interface FetchResponse {
246
  /** Path to the files index file */
247
  filesIndexFile: string;
248
  /** Function to execute the actual fetch operation */
249
  fetching: () => Promise<PkgRequestFetchResult>;
250
}
251

252
interface PkgRequestFetchResult {
253
  /** Bundled manifest for the package */
254
  bundledManifest?: BundledManifest;
255
  /** Package files information */
256
  files: PackageFilesResponse;
257
}
258

259
type GetFilesIndexFilePath = (opts: Pick<FetchPackageToStoreOptions, 'pkg' | 'ignoreScripts'>) => {
260
  filesIndexFile: string;
261
  target: string;
262
};
263
```
264

265
### Package Import Operations
266

267
Types for importing packages from the store to node_modules directories.
268

269
```typescript { .api }
270
type ImportIndexedPackage = (to: string, opts: ImportOptions) => string | undefined;
271
type ImportIndexedPackageAsync = (to: string, opts: ImportOptions) => Promise<string | undefined>;
272

273
interface ImportOptions {
274
  /** Disable relinking of local directory dependencies */
275
  disableRelinkLocalDirDeps?: boolean;
276
  /** Mapping of file paths to their content hashes */
277
  filesMap: FilesMap;
278
  /** Force import even if target exists */
279
  force: boolean;
280
  /** Source location of the resolved package */
281
  resolvedFrom: ResolvedFrom;
282
  /** Keep existing modules directory during import */
283
  keepModulesDir?: boolean;
284
}
285

286
type FilesMap = Record<string, string>;
287
```
288

289
### Re-exported Import Functions
290

291
Import package functions re-exported from `@pnpm/cafs-types`.
292

293
```typescript { .api }
294
type ImportPackageFunction = (
295
  to: string,
296
  opts: ImportPackageOpts
297
) => { isBuilt: boolean, importMethod: undefined | string };
298

299
type ImportPackageFunctionAsync = (
300
  to: string,  
301
  opts: ImportPackageOpts
302
) => Promise<{ isBuilt: boolean, importMethod: undefined | string }>;
303

304
interface ImportPackageOpts {
305
  /** Disable relinking of local directory dependencies */
306
  disableRelinkLocalDirDeps?: boolean;
307
  /** Whether the package requires building */
308
  requiresBuild?: boolean;
309
  /** Cache key for side effects */
310
  sideEffectsCacheKey?: string;
311
  /** Package files response information */
312
  filesResponse: PackageFilesResponse;
313
  /** Force import even if target exists */
314
  force: boolean;
315
  /** Keep existing modules directory during import */
316
  keepModulesDir?: boolean;
317
}
318
```
319

320
### Package Upload Operations
321

322
Types for uploading built packages back to the store.
323

324
```typescript { .api }
325
type UploadPkgToStore = (builtPkgLocation: string, opts: UploadPkgToStoreOpts) => Promise<void>;
326

327
interface UploadPkgToStoreOpts {
328
  /** Path to the files index file */
329
  filesIndexFile: string;
330
  /** Cache key for side effects */
331
  sideEffectsCacheKey: string;
332
}
333
```
334

335
### Error Handling
336

337
Type for handling fetch errors with custom processing.
338

339
```typescript { .api }
340
type OnFetchError = (error: Error) => Error;
341
```
342

343
### Utility Types
344

345
Common utility types used throughout the package management system.
346

347
```typescript { .api }
348
interface PkgNameVersion {
349
  /** Package name */
350
  name?: string;
351
  /** Package version */
352
  version?: string;
353
}
354

355
type BundledManifestFunction = () => Promise<BundledManifest | undefined>;
356
```
357

358
## Types
359

360
### Core Package Types
361

362
```typescript { .api }
363
type BundledManifest = Pick<
364
  DependencyManifest,
365
  | 'bin'
366
  | 'bundledDependencies'
367
  | 'bundleDependencies'
368
  | 'cpu'
369
  | 'dependencies'
370
  | 'directories'
371
  | 'engines'
372
  | 'name'
373
  | 'optionalDependencies'
374
  | 'os'
375
  | 'peerDependencies'
376
  | 'peerDependenciesMeta'
377
  | 'scripts'
378
  | 'version'
379
>;
380
```
381

382
### Re-exported Types
383

384
The package re-exports all types from `@pnpm/resolver-base` and selectively re-exports key types from `@pnpm/cafs-types`:
385

386
```typescript { .api }
387
// From @pnpm/resolver-base (all exports)
388
export * from '@pnpm/resolver-base';
389

390
// From @pnpm/cafs-types (selective exports)
391
export type {
392
  PackageFileInfo,
393
  PackageFilesResponse,
394
  ImportPackageFunction,
395
  ImportPackageFunctionAsync
396
};
397
```
398

399
### Key Re-exported Type Definitions
400

401
Types re-exported from `@pnpm/resolver-base`:
402

403
```typescript { .api }
404
type PkgResolutionId = string & { __brand: 'PkgResolutionId' };
405

406
interface DirectoryResolution {
407
  type: 'directory';
408
  directory: string;
409
}
410

411
interface PreferredVersions {
412
  [packageName: string]: VersionSelectors;
413
}
414

415
interface VersionSelectors {
416
  [selector: string]: VersionSelectorWithWeight | VersionSelectorType;
417
}
418

419
interface VersionSelectorWithWeight {
420
  selectorType: VersionSelectorType;
421
  weight: number;
422
}
423

424
type VersionSelectorType = 'version' | 'range' | 'tag';
425

426
type Resolution = AtomicResolution | VariationsResolution;
427

428
type AtomicResolution =
429
  | TarballResolution
430
  | DirectoryResolution
431
  | GitResolution
432
  | BinaryResolution;
433

434
interface TarballResolution {
435
  type?: undefined;
436
  tarball: string;
437
  integrity?: string;
438
  path?: string;
439
}
440

441
interface GitResolution {
442
  commit: string;
443
  repo: string;
444
  path?: string;
445
  type: 'git';
446
}
447

448
interface BinaryResolution {
449
  type: 'binary';
450
  archive: 'tarball' | 'zip';
451
  url: string;
452
  integrity: string;
453
  bin: string;
454
  prefix?: string;
455
}
456

457
interface VariationsResolution {
458
  type: 'variations';
459
  variants: PlatformAssetResolution[];
460
}
461

462
interface PlatformAssetResolution {
463
  resolution: AtomicResolution;
464
  targets: PlatformAssetTarget[];
465
}
466

467
interface PlatformAssetTarget {
468
  os: string;
469
  cpu: string;
470
  libc?: 'musl';
471
}
472

473
type WantedDependency = {
474
  injected?: boolean;
475
  prevSpecifier?: string;
476
} & ({
477
  alias?: string;
478
  bareSpecifier: string;
479
} | {
480
  alias: string;
481
  bareSpecifier?: string;
482
});
483

484
type WorkspacePackages = Map<string, WorkspacePackagesByVersion>;
485

486
type WorkspacePackagesByVersion = Map<string, WorkspacePackage>;
487

488
interface WorkspacePackage {
489
  rootDir: ProjectRootDir;
490
  manifest: DependencyManifest;
491
}
492
```
493

494
Types re-exported from `@pnpm/cafs-types`:
495

496
```typescript { .api }
497
interface PackageFileInfo {
498
  checkedAt?: number;
499
  integrity: string;
500
  mode: number;
501
  size: number;
502
}
503

504
type ResolvedFrom = 'store' | 'local-dir' | 'remote';
505

506
type PackageFilesResponse = {
507
  resolvedFrom: ResolvedFrom;
508
  packageImportMethod?: 'auto' | 'hardlink' | 'copy' | 'clone' | 'clone-or-copy';
509
  sideEffects?: SideEffects;
510
  requiresBuild: boolean;
511
} & ({
512
  unprocessed?: false;
513
  filesIndex: Record<string, string>;
514
} | {
515
  unprocessed: true;
516
  filesIndex: PackageFiles;
517
});
518

519
type PackageFiles = Record<string, PackageFileInfo>;
520

521
type SideEffects = Record<string, SideEffectsDiff>;
522

523
interface SideEffectsDiff {
524
  deleted?: string[];
525
  added?: PackageFiles;
526
}
527
```
528

529
Types from `@pnpm/types`:
530

531
```typescript { .api }
532
interface SupportedArchitectures {
533
  os?: string[];
534
  cpu?: string[];
535
  libc?: string[];
536
}
537

538
interface DependencyManifest {
539
  name: string;
540
  version: string;
541
  bin?: PackageBin;
542
  description?: string;
543
  dependencies?: Dependencies;
544
  optionalDependencies?: Dependencies;
545
  peerDependencies?: Dependencies;
546
  peerDependenciesMeta?: PeerDependenciesMeta;
547
  scripts?: PackageScripts;
548
  engines?: object;
549
  cpu?: string[];
550
  os?: string[];
551
  // ... and many other package.json fields
552
}
553

554
interface PackageManifest extends DependencyManifest {
555
  deprecated?: string;
556
}
557

558
type PinnedVersion = 'none' | 'patch' | 'minor' | 'major';
559

560
type ProjectRootDir = string & { __brand: 'ProjectRootDir' };
561

562
type Dependencies = Record<string, string>;
563

564
type PackageBin = string | { [commandName: string]: string };
565

566
type PackageScripts = Record<string, string>;
567

568
interface PeerDependenciesMeta {
569
  [dependencyName: string]: {
570
    optional?: boolean;
571
  };
572
}
573
```