0
# Transform Operations
1

2
Stream-based transformation utilities for processing files during commit operations, enabling custom file processing pipelines with async support.
3

4
## Capabilities
5

6
### Commit Transform Stream
7

8
Create a Node.js Transform stream that processes files during commit operations with async file writing support.
9

10
```typescript { .api }
11
/**
12
 * Create a Transform stream for committing files asynchronously
13
 * @returns Transform stream that processes MemFsEditorFile objects
14
 */
15
function createCommitTransform(): Transform;
16

17
interface Transform extends NodeJS.ReadWriteStream {
18
  /** Transform stream in object mode for processing file objects */
19
  objectMode: true;
20
  /** Process each file through commitFileAsync and pass to next stream */
21
  _transform(file: MemFsEditorFile, encoding: string, callback: TransformCallback): void;
22
}
23

24
interface TransformCallback {
25
  /** Callback function to signal completion or error */
26
  (error?: Error | null, data?: MemFsEditorFile): void;
27
}
28
```
29

30
## Usage Examples
31

32
```typescript
33
import { createCommitTransform } from "mem-fs-editor/transform";
34
import { create as createMemFs } from "mem-fs";
35
import { create as createEditor } from "mem-fs-editor";
36
import { pipeline } from "stream";
37
import { promisify } from "util";
38

39
const pipelineAsync = promisify(pipeline);
40
const store = createMemFs();
41
const fs = createEditor(store);
42

43
// Basic usage with commit transform
44
const commitTransform = createCommitTransform();
45

46
// Create some files
47
fs.write("file1.txt", "Content 1");
48
fs.write("file2.txt", "Content 2");
49

50
// Use in a stream pipeline for custom file processing
51
await pipelineAsync(
52
  store.stream(), // Source stream of files
53
  createCommitTransform(), // Transform files and commit to disk
54
  // Additional transforms can be added here
55
);
56

57
// Advanced usage with custom transform chain
58
import { Transform } from "stream";
59

60
// Create a custom transform to modify files before commit
61
const customTransform = new Transform({
62
  objectMode: true,
63
  transform(file, encoding, callback) {
64
    // Add header to all text files
65
    if (file.path.endsWith('.txt') && file.contents) {
66
      const header = Buffer.from('// Auto-generated header\n');
67
      file.contents = Buffer.concat([header, file.contents]);
68
    }
69
    callback(null, file);
70
  }
71
});
72

73
// Chain transforms: custom processing -> commit to disk
74
await pipelineAsync(
75
  store.stream(),
76
  customTransform,
77
  createCommitTransform()
78
);
79
```
80

81
## Integration with Commit Pipeline
82

83
The transform module integrates seamlessly with the commit system to provide streaming file processing:
84

85
```typescript
86
import { createCommitTransform } from "mem-fs-editor/transform";
87
import { create as createMemFs } from "mem-fs";
88
import { create as createEditor } from "mem-fs-editor";
89

90
const store = createMemFs();
91
const fs = createEditor(store);
92

93
// Write multiple files
94
fs.write("src/index.js", "console.log('Hello');");
95
fs.write("src/utils.js", "export const helper = () => {};");
96
fs.write("README.md", "# My Project");
97

98
// Use transform in commit process
99
const commitTransform = createCommitTransform();
100

101
// Process files in streaming fashion
102
const fileStream = store.stream();
103
fileStream.pipe(commitTransform);
104

105
// Handle completion and errors
106
commitTransform.on('finish', () => {
107
  console.log('All files committed successfully');
108
});
109

110
commitTransform.on('error', (error) => {
111
  console.error('Error during commit:', error);
112
});
113
```
114

115
## Transform Stream Behavior
116

117
The `createCommitTransform` function creates a Transform stream with these characteristics:
118

119
- **Object Mode**: Processes MemFsEditorFile objects, not raw data
120
- **Async Processing**: Each file is processed through `commitFileAsync` for proper async disk operations
121
- **Error Handling**: Errors during file commit are propagated through the stream error mechanism
122
- **File Preservation**: Original file objects are passed through unchanged after commit
123
- **Directory Creation**: Automatically creates parent directories as needed during commit
124
- **Permission Handling**: Preserves file permissions (stat.mode) when writing to disk
125

126
This enables building complex file processing pipelines where files can be transformed, validated, and committed in a streaming fashion with full async support and proper error handling.