0
# State Management
1

2
File state management system for tracking file lifecycle states, commit status, and managing pending changes in the mem-fs-editor store.
3

4
## Capabilities
5

6
### File State Management
7

8
Set, check, and manage file states for tracking modifications and deletions.
9

10
```typescript { .api }
11
/**
12
 * Set the state of a file
13
 * @param file - The file object to modify
14
 * @param state - The state value to set ('modified' | 'deleted')
15
 */
16
function setFileState(file: MemFsEditorFile, state: 'modified' | 'deleted'): void;
17

18
/**
19
 * Check if a file is new (doesn't exist on disk)
20
 * @param file - The file object to check
21
 * @returns True if file is new, false if it exists on disk
22
 */
23
function isFileNew(file: MemFsEditorFile): boolean;
24

25
/**
26
 * Check if a file's state is marked as modified
27
 * @param file - The file object to check
28
 * @returns True if file state is 'modified'
29
 */
30
function isFileStateModified(file: MemFsEditorFile): boolean;
31

32
/**
33
 * Set a file's state to modified
34
 * @param file - The file object to modify
35
 */
36
function setModifiedFileState(file: MemFsEditorFile): void;
37

38
/**
39
 * Check if a file's state is marked as deleted
40
 * @param file - The file object to check
41
 * @returns True if file state is 'deleted'
42
 */
43
function isFileStateDeleted(file: MemFsEditorFile): boolean;
44

45
/**
46
 * Set a file's state to deleted
47
 * @param file - The file object to modify
48
 */
49
function setDeletedFileState(file: MemFsEditorFile): void;
50

51
/**
52
 * Check if a file has pending changes (modified or deleted but not new)
53
 * @param file - The file object to check
54
 * @returns True if file has pending changes
55
 */
56
function isFilePending(file: MemFsEditorFile): boolean;
57
```
58

59
### Commit State Management
60

61
Manage file commit status and track which files have been committed to disk.
62

63
```typescript { .api }
64
/**
65
 * Mark a file as committed to disk
66
 * @param file - The file object to mark as committed
67
 */
68
function setCommittedFile(file: MemFsEditorFile): void;
69

70
/**
71
 * Check if a file has been committed to disk
72
 * @param file - The file object to check
73
 * @returns True if file is committed
74
 */
75
function isFileCommitted(file: MemFsEditorFile): boolean;
76
```
77

78
### State Reset and Cleanup
79

80
Reset file states and clean up internal state tracking properties.
81

82
```typescript { .api }
83
/**
84
 * Reset the file state (remove state property)
85
 * @param file - The file object to reset
86
 */
87
function resetFileState(file: MemFsEditorFile): void;
88

89
/**
90
 * Delete commit-related states (stateCleared and committed properties)
91
 * @param file - The file object to clean up
92
 */
93
function resetFileCommitStates(file: MemFsEditorFile): void;
94

95
/**
96
 * Delete all mem-fs-editor related states (complete cleanup)
97
 * @param file - The file object to reset completely
98
 */
99
function resetFile(file: MemFsEditorFile): void;
100

101
/**
102
 * Clear file state by moving current state to stateCleared
103
 * @param file - The file object to clear state for
104
 */
105
function clearFileState(file: MemFsEditorFile): void;
106
```
107

108
### State Query Functions
109

110
Check for the presence of state properties on file objects.
111

112
```typescript { .api }
113
/**
114
 * Check if a file has any state property set
115
 * @param file - The file object to check
116
 * @returns True if file has a state property
117
 */
118
function hasState(file: MemFsEditorFile): boolean;
119

120
/**
121
 * Check if a file has a cleared state property
122
 * @param file - The file object to check
123
 * @returns True if file has a stateCleared property
124
 */
125
function hasClearedState(file: MemFsEditorFile): boolean;
126
```
127

128
## Usage Examples
129

130
```typescript
131
import { 
132
  setFileState, 
133
  isFileNew, 
134
  isFileStateModified,
135
  setModifiedFileState,
136
  isFilePending,
137
  resetFile
138
} from "mem-fs-editor/state";
139
import { create as createMemFs } from "mem-fs";
140
import { create as createEditor } from "mem-fs-editor";
141

142
const store = createMemFs();
143
const fs = createEditor(store);
144

145
// Write a file and check its state
146
fs.write("example.txt", "Hello World");
147
const file = store.get("example.txt");
148

149
// Check if file is new
150
console.log(isFileNew(file)); // true (doesn't exist on disk yet)
151

152
// File is automatically marked as modified when written
153
console.log(isFileStateModified(file)); // true
154

155
// Check if file has pending changes
156
console.log(isFilePending(file)); // true
157

158
// After committing, the file state changes
159
await fs.commit();
160
console.log(isFilePending(file)); // false
161

162
// Manually manage file states
163
const anotherFile = store.get("another.txt");
164
setModifiedFileState(anotherFile);
165

166
// Clean up all states when done
167
resetFile(file);
168
```
169

170
## State Lifecycle
171

172
Files in mem-fs-editor follow this state lifecycle:
173

174
1. **New File**: `isNew: true` when file doesn't exist on disk
175
2. **Modified**: `state: 'modified'` when file contents change
176
3. **Deleted**: `state: 'deleted'` when file is marked for deletion
177
4. **Committed**: `committed: true` after successful commit to disk
178
5. **Cleared**: `stateCleared: 'modified'|'deleted'` when state is cleared but preserved
179

180
The state management functions allow you to query and manipulate files at any point in this lifecycle, providing fine-grained control over file operations and commit behavior.