0
# File Reading
1

2
Core file reading functionality for accessing file contents with support for various data formats including text, binary, and JSON files.
3

4
## Capabilities
5

6
### Read File Contents
7

8
Reads file contents as string or buffer with support for default values and raw binary data.
9

10
```typescript { .api }
11
/**
12
 * Read file contents as string with optional defaults
13
 * @param filepath - Path to the file to read
14
 * @param options - Reading options with string/null defaults
15
 * @returns File contents as string or null
16
 * @throws Error if file doesn't exist and no defaults provided
17
 */
18
function read(filepath: string, options?: ReadOptionsString): string | null;
19

20
/**
21
 * Read file contents as buffer with optional defaults
22
 * @param filepath - Path to the file to read  
23
 * @param options - Reading options with raw mode enabled and Buffer/null defaults
24
 * @returns File contents as Buffer, string, or null
25
 */
26
function read(filepath: string, options: ReadOptionsBuffer): Buffer | string | null;
27

28
interface ReadOptionsString {
29
  /** Return raw Buffer instead of string */
30
  raw?: boolean;
31
  /** Default value to return if file doesn't exist */
32
  defaults?: string | null;
33
}
34

35
interface ReadOptionsBuffer {
36
  /** Return raw Buffer instead of string */
37
  raw?: true;
38
  /** Default value to return if file doesn't exist */
39
  defaults?: Buffer | null;
40
}
41
```
42

43
**Usage Examples:**
44

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

49
const store = createMemFs();
50
const fs = createEditor(store);
51

52
// Read as string (default)
53
const content = fs.read("package.json");
54

55
// Read as raw Buffer
56
const binaryData = fs.read("image.png", { raw: true });
57

58
// Read with default value
59
const config = fs.read("config.json", { defaults: "{}" });
60

61
// Read with null default
62
const optional = fs.read("optional.txt", { defaults: null });
63
```
64

65
### Read JSON Files
66

67
Reads and parses JSON files with automatic error handling and default value support.
68

69
```typescript { .api }
70
/**
71
 * Read and parse JSON file contents
72
 * @param filepath - Path to the JSON file
73
 * @param defaults - Default value to return if file doesn't exist
74
 * @returns Parsed JSON object or defaults value
75
 * @throws Error if JSON parsing fails
76
 */
77
function readJSON(filepath: string, defaults?: any): any;
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
// Read package.json
84
const packageData = fs.readJSON("package.json");
85

86
// Read with object default
87
const config = fs.readJSON("config.json", { port: 3000, host: "localhost" });
88

89
// Read with array default  
90
const items = fs.readJSON("data.json", []);
91

92
// Read with null default
93
const optional = fs.readJSON("optional.json", null);
94
```
95

96
### Check File Existence
97

98
Checks if a file exists in the memory store.
99

100
```typescript { .api }
101
/**
102
 * Check if file exists in memory store
103
 * @param filepath - Path to check for existence
104
 * @returns True if file exists and has contents, false otherwise
105
 */
106
function exists(filepath: string): boolean;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
// Check if file exists
113
if (fs.exists("package.json")) {
114
  const data = fs.readJSON("package.json");
115
}
116

117
// Conditional file operations
118
if (!fs.exists("dist/index.js")) {
119
  fs.copy("src/index.js", "dist/index.js");
120
}
121

122
// Guard against missing files
123
const hasConfig = fs.exists("config.json");
124
const config = hasConfig ? fs.readJSON("config.json") : { port: 3000 };
125
```
126

127
## Error Handling
128

129
The `read` method throws an error when a file doesn't exist unless a `defaults` option is provided:
130

131
```typescript
132
try {
133
  const content = fs.read("missing-file.txt");
134
} catch (error) {
135
  console.log("File doesn't exist");
136
}
137

138
// Better approach with defaults
139
const content = fs.read("missing-file.txt", { defaults: "" });
140
```
141

142
The `readJSON` method throws an error if JSON parsing fails, but returns defaults for missing files:
143

144
```typescript
145
try {
146
  const data = fs.readJSON("invalid.json");
147
} catch (error) {
148
  console.log("Invalid JSON format");
149
}
150

151
// Safe approach with defaults
152
const data = fs.readJSON("config.json", {});
153
```