0
# mem-fs-editor
1

2
mem-fs-editor provides comprehensive file system editing utilities that work on top of the mem-fs in-memory file system. It offers a rich API for file operations including reading, writing, copying, moving, and templating files with EJS template support, designed for build tools, scaffolding systems, code generators, and development tools.
3

4
## Package Information
5

6
- **Package Name**: mem-fs-editor
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install mem-fs-editor`
10
- **Peer Dependency**: `mem-fs ^4.0.0`
11

12
## Core Imports
13

14
```typescript
15
import { create, MemFsEditor } from "mem-fs-editor";
16
import { create as createMemFs } from "mem-fs";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { create } = require("mem-fs-editor");
23
const { create: createMemFs } = require("mem-fs");
24
```
25

26
State management utilities:
27

28
```typescript
29
import { 
30
  setFileState, 
31
  isFileNew, 
32
  isFileStateModified,
33
  setModifiedFileState 
34
} from "mem-fs-editor/state";
35
```
36

37
Transform utilities:
38

39
```typescript
40
import { createCommitTransform } from "mem-fs-editor/transform";
41
```
42

43
## Basic Usage
44

45
```typescript
46
import { create as createMemFs } from "mem-fs";
47
import { create as createEditor } from "mem-fs-editor";
48

49
// Initialize the editor
50
const store = createMemFs();
51
const fs = createEditor(store);
52

53
// Write a file
54
fs.write("somefile.js", "var a = 1;");
55

56
// Read the file
57
const content = fs.read("somefile.js");
58

59
// Copy files with glob pattern
60
fs.copy("src/**/*.js", "dist/");
61

62
// Use templates with context
63
fs.copyTpl("templates/*.ejs", "output/", { name: "John" });
64

65
// Commit changes to disk
66
await fs.commit();
67
```
68

69
## Architecture
70

71
mem-fs-editor is built around several key components:
72

73
- **MemFsEditor Class**: Main interface providing all file operations as instance methods
74
- **Action Modules**: Individual file operations (read, write, copy, etc.) implemented as separate modules
75
- **State Management**: File state tracking system for managing pending changes and commit operations
76
- **Template Engine**: EJS-based templating system for dynamic file generation
77
- **Glob Support**: Pattern matching for bulk file operations using globby
78
- **Async Pipeline**: Stream-based commit system for batch file operations with transforms
79

80
## Capabilities
81

82
### File Reading Operations
83

84
Core file reading functionality for accessing file contents with support for various data formats.
85

86
```typescript { .api }
87
function read(filepath: string, options?: ReadOptions): string | null;
88
function readJSON(filepath: string, defaults?: any): any;
89
function exists(filepath: string): boolean;
90

91
interface ReadOptions {
92
  raw?: boolean;
93
  defaults?: string | Buffer | null;
94
}
95
```
96

97
[File Reading](./file-reading.md)
98

99
### File Writing Operations
100

101
File writing capabilities including basic write operations, JSON handling, and content appending.
102

103
```typescript { .api }
104
function write(filepath: string, contents: string | Buffer, stat?: FileStats): string;
105
function writeJSON(filepath: string, contents: any, replacer?: JSONReplacer, space?: string | number): string;
106
function append(filepath: string, contents: string | Buffer, options?: AppendOptions): void;
107

108
interface FileStats {
109
  mode?: number;
110
}
111

112
type JSONReplacer = ((key: string, value: any) => any) | (number | string)[] | null;
113

114
interface AppendOptions {
115
  create?: boolean;
116
  trimEnd?: boolean;
117
  separator?: string;
118
}
119
```
120

121
[File Writing](./file-writing.md)
122

123
### File Copy Operations
124

125
Comprehensive file copying with glob pattern support, processing functions, and template integration.
126

127
```typescript { .api }
128
function copy(
129
  from: string | string[],
130
  to: string,
131
  options?: CopyOptions,
132
  context?: Record<string, any>,
133
  tplSettings?: EJSOptions
134
): void;
135

136
function copyAsync(
137
  from: string | string[],
138
  to: string,
139
  options?: CopyAsyncOptions,
140
  context?: Record<string, any>,
141
  tplSettings?: EJSOptions
142
): Promise<void>;
143

144
interface CopyOptions {
145
  noGlob?: boolean;
146
  globOptions?: GlobOptions;
147
  ignoreNoMatch?: boolean;
148
  fromBasePath?: string;
149
  processDestinationPath?: (path: string) => string;
150
  append?: boolean;
151
  process?: (contents: string | Buffer, filepath: string, destination: string) => string | Buffer;
152
}
153
```
154

155
[File Copy Operations](./file-copy.md)
156

157
### Template Processing
158

159
EJS template processing for dynamic file generation with context variables and template options.
160

161
```typescript { .api }
162
function copyTpl(
163
  from: string | string[],
164
  to: string,
165
  context?: Record<string, any>,
166
  tplSettings?: EJSOptions,
167
  options?: CopySingleOptions
168
): void;
169

170
function copyTplAsync(
171
  from: string | string[],
172
  to: string,
173
  context?: Record<string, any>,
174
  tplSettings?: EJSOptions,
175
  options?: CopySingleOptions
176
): Promise<void>;
177

178
function appendTpl(
179
  filepath: string,
180
  contents: string,
181
  context: Record<string, any>,
182
  templateOptions?: EJSOptions,
183
  options?: AppendOptions
184
): void;
185

186
interface EJSOptions {
187
  filename?: string;
188
  cache?: boolean;
189
  [key: string]: any;
190
}
191
```
192

193
[Template Processing](./template-processing.md)
194

195
### File Management
196

197
File management operations including moving, deleting, and bulk operations with glob pattern support.
198

199
```typescript { .api }
200
function move(from: string, to: string, options?: CopyOptions): void;
201
function delete(paths: string | string[], options?: DeleteOptions): void;
202

203
interface DeleteOptions {
204
  globOptions?: GlobOptions;
205
}
206

207
interface GlobOptions {
208
  nodir?: boolean;
209
  [key: string]: any;
210
}
211
```
212

213
[File Management](./file-management.md)
214

215
### Commit and Pipeline Operations
216

217
Pipeline-based commit system for batch file operations with custom transforms and filtering.
218

219
```typescript { .api }
220
function commit<EditorFile extends MemFsEditorFile>(
221
  options?: PipelineOptions<EditorFile> | FileTransform<EditorFile>,
222
  ...transforms: FileTransform<EditorFile>[]
223
): Promise<void>;
224

225
function dump<EditorFile extends MemFsEditorFile>(
226
  cwd?: string,
227
  filter?: string | ((file: EditorFile, cwd: string) => boolean)
228
): Record<string, MemFsEditorFileDump>;
229

230
interface PipelineOptions<T> {
231
  filter?: (file: T) => boolean;
232
  [key: string]: any;
233
}
234

235
interface FileTransform<T> {
236
  (file: T): T | Promise<T>;
237
}
238

239
interface MemFsEditorFileDump {
240
  contents: string | null;
241
  state?: string;
242
  stateCleared?: string;
243
}
244
```
245

246
[Commit and Pipeline Operations](./commit-pipeline.md)
247

248
### State Management
249

250
File state management system for tracking file lifecycle states, commit status, and managing pending changes.
251

252
```typescript { .api }
253
function setFileState(file: MemFsEditorFile, state: 'modified' | 'deleted'): void;
254
function isFileNew(file: MemFsEditorFile): boolean;
255
function isFileStateModified(file: MemFsEditorFile): boolean;
256
function setModifiedFileState(file: MemFsEditorFile): void;
257
function isFilePending(file: MemFsEditorFile): boolean;
258
function resetFile(file: MemFsEditorFile): void;
259
```
260

261
[State Management](./state-management.md)
262

263
### Transform Operations
264

265
Stream-based transformation utilities for processing files during commit operations with async support.
266

267
```typescript { .api }
268
function createCommitTransform(): Transform;
269

270
interface Transform extends NodeJS.ReadWriteStream {
271
  objectMode: true;
272
  _transform(file: MemFsEditorFile, encoding: string, callback: TransformCallback): void;
273
}
274
```
275

276
[Transform Operations](./transform.md)
277

278
## Core Types
279

280
```typescript { .api }
281
class MemFsEditor<EditorFile extends MemFsEditorFile = VinylMemFsEditorFile> {
282
  store: Store<EditorFile>;
283
  constructor(store: Store<EditorFile>);
284
}
285

286
interface MemFsEditorFile {
287
  path: string;
288
  stat?: { mode?: number } | null;
289
  contents: Buffer | null;
290
  committed?: boolean;
291
  isNew?: boolean;
292
  state?: 'modified' | 'deleted';
293
  stateCleared?: 'modified' | 'deleted';
294
}
295

296
interface VinylMemFsEditorFile extends Omit<Vinyl, 'contents' | 'stat'>, MemFsEditorFile {}
297

298
function create<EditorFile extends MemFsEditorFile = VinylMemFsEditorFile>(
299
  store: Store<EditorFile>
300
): MemFsEditor<EditorFile>;
301
```