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
```