0
# Directory Operations
1

2
Add files from local directories to the CAFS store and manage directory-based package operations for local development and file system integration.
3

4
## Capabilities
5

6
### Add Files From Directory
7

8
Adds files from a local directory to the CAFS store. This is useful for processing local packages or directories that aren't packaged as tarballs.
9

10
```typescript { .api }
11
/**
12
 * Adds files from a directory to the CAFS store
13
 * @param opts - Configuration options for directory processing
14
 * @returns Promise resolving to processing results with file mappings and metadata
15
 */
16
function addFilesFromDir(opts: AddFilesFromDirOptions): Promise<AddFilesResult>;
17

18
type AddFilesFromDirOptions = Pick<AddDirToStoreMessage, 'storeDir' | 'dir' | 'filesIndexFile' | 'sideEffectsCacheKey' | 'readManifest' | 'pkg' | 'files'>;
19

20
interface AddDirToStoreMessage {
21
  type: 'add-dir';
22
  /** Store directory path where files will be stored */
23
  storeDir: string;
24
  /** Source directory path to process */
25
  dir: string;
26
  /** Path to the files index file for metadata storage */
27
  filesIndexFile: string;
28
  /** Optional cache key for side effects tracking */
29
  sideEffectsCacheKey?: string;
30
  /** Whether to read and parse the package manifest */
31
  readManifest?: boolean;
32
  /** Package name and version information */
33
  pkg?: PkgNameVersion;
34
  /** Specific files to include (if not provided, includes all files) */
35
  files?: string[];
36
}
37

38
interface AddFilesResult {
39
  /** Mapping of file paths to their CAFS store locations */
40
  filesIndex: Record<string, string>;
41
  /** Parsed package manifest (package.json) if available */
42
  manifest: DependencyManifest;
43
  /** Whether the package requires a build step */
44
  requiresBuild: boolean;
45
}
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { addFilesFromDir } from "@pnpm/worker";
52

53
// Process entire directory
54
const result = await addFilesFromDir({
55
  storeDir: "/path/to/pnpm/store",
56
  dir: "/path/to/local/package",
57
  filesIndexFile: "/path/to/index.json",
58
  readManifest: true
59
});
60

61
console.log("Processed files:", Object.keys(result.filesIndex));
62
console.log("Package name:", result.manifest?.name);
63

64
// Process specific files with side effects caching
65
const specificFilesResult = await addFilesFromDir({
66
  storeDir: "/path/to/pnpm/store",
67
  dir: "/path/to/package",
68
  filesIndexFile: "/path/to/index.json",
69
  sideEffectsCacheKey: "build-artifacts",
70
  files: ["lib/index.js", "lib/utils.js", "package.json"],
71
  pkg: { name: "my-package", version: "1.0.0" }
72
});
73
```
74

75
### Hard Link Directory
76

77
Creates hard links from a source directory to multiple destination directories. This is an efficient way to duplicate directory structures without copying file contents.
78

79
```typescript { .api }
80
/**
81
 * Creates hard links from source directory to multiple destination directories
82
 * @param src - Source directory path to link from
83
 * @param destDirs - Array of destination directory paths
84
 * @returns Promise that resolves when all hard links are created
85
 */
86
function hardLinkDir(src: string, destDirs: string[]): Promise<void>;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { hardLinkDir } from "@pnpm/worker";
93

94
// Link one directory to multiple locations
95
await hardLinkDir(
96
  "/path/to/source/package",
97
  [
98
    "/path/to/project1/node_modules/package",
99
    "/path/to/project2/node_modules/package",
100
    "/path/to/project3/node_modules/package"
101
  ]
102
);
103

104
console.log("Hard links created successfully");
105

106
// Single destination
107
await hardLinkDir(
108
  "/pnpm/store/files/abc123",
109
  ["/project/node_modules/lodash"]
110
);
111
```
112

113
### Initialize Store Directory
114

115
Initializes the store directory structure for CAFS. This creates the necessary subdirectory structure used by pnpm's content-addressable file system.
116

117
```typescript { .api }
118
/**
119
 * Initializes the store directory structure for CAFS
120
 * @param storeDir - Store directory path to initialize
121
 * @returns Promise that resolves when store structure is created
122
 */
123
function initStoreDir(storeDir: string): Promise<void>;
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { initStoreDir } from "@pnpm/worker";
130

131
// Initialize a new pnpm store
132
await initStoreDir("/path/to/new/pnpm/store");
133
console.log("Store directory initialized");
134

135
// Initialize before other operations
136
const storeDir = "/path/to/pnpm/store";
137
await initStoreDir(storeDir);
138

139
// Now ready for other operations
140
const result = await addFilesFromDir({
141
  storeDir,
142
  dir: "/path/to/package",
143
  filesIndexFile: "/path/to/index.json"
144
});
145
```
146

147
## Side Effects Caching
148

149
The `sideEffectsCacheKey` parameter in `addFilesFromDir` enables tracking of build artifacts and other side effects:
150

151
### How Side Effects Work
152

153
1. **Base Files**: Initial files added to the store
154
2. **Side Effects**: Files created or modified after processing (e.g., build outputs)
155
3. **Diff Calculation**: Compares base files with side effects to track changes
156
4. **Cache Storage**: Stores differences in the files index for future reference
157

158
### Side Effects Cache Key Usage
159

160
```typescript
161
// Initial package processing
162
await addFilesFromDir({
163
  storeDir: "/store",
164
  dir: "/package",
165
  filesIndexFile: "/index.json",
166
  readManifest: true
167
});
168

169
// After build step - cache the build artifacts
170
await addFilesFromDir({
171
  storeDir: "/store", 
172
  dir: "/package",
173
  filesIndexFile: "/index.json",
174
  sideEffectsCacheKey: "post-build",
175
  readManifest: false
176
});
177
```
178

179
The side effects cache tracks:
180
- **Added files**: New files created during processing
181
- **Modified files**: Existing files with changed content or permissions
182
- **Deleted files**: Files removed during processing
183

184
## Store Directory Structure
185

186
The `initStoreDir` function creates the following structure:
187

188
```
189
store/
190
├── files/
191
│   ├── 00/
192
│   ├── 01/
193
│   ├── ...
194
│   └── ff/
195
└── index/
196
    ├── 00/
197
    ├── 01/
198
    ├── ...
199
    └── ff/
200
```
201

202
- **files/**: Contains actual file content, organized by content hash prefixes
203
- **index/**: Contains metadata and index files for fast lookups
204
- **Subdirectories**: 256 subdirectories (00-ff) for efficient file system performance