0
# File Reading (src)
1

2
Stream-based file reading functionality that creates a readable stream of Vinyl File objects from glob patterns. Supports advanced features like encoding transformation, sourcemap handling, and symbolic link resolution.
3

4
## Capabilities
5

6
### src Function
7

8
Creates a readable stream of Vinyl File objects from glob patterns with comprehensive options for file processing.
9

10
```javascript { .api }
11
/**
12
 * Creates a readable stream of Vinyl File objects from glob patterns
13
 * @param {string|string[]} globs - Glob pattern(s) to match files
14
 * @param {Object} [options] - Configuration options
15
 * @returns {Transform} Transform stream that produces Vinyl File objects
16
 * @throws {Error} When glob argument is invalid
17
 */
18
function src(globs, options);
19

20
interface SrcOptions {
21
  /** Buffer file contents into memory (default: true) */
22
  buffer?: boolean;
23
  /** Whether to read file contents (default: true) */
24
  read?: boolean;
25
  /** Only stream files modified since timestamp */
26
  since?: Date | number;
27
  /** Remove UTF-8 BOM from files (default: true) */
28
  removeBOM?: boolean;
29
  /** File encoding for transcoding (default: 'utf8') */
30
  encoding?: string | boolean;
31
  /** Enable sourcemap support (default: false) */
32
  sourcemaps?: boolean;
33
  /** Resolve symlinks to targets (default: true) */
34
  resolveSymlinks?: boolean;
35
  /** Match dot files in globs (default: false) */
36
  dot?: boolean;
37
  /** Working directory for relative globs */
38
  cwd?: string;
39
  /** Base directory for relative paths */
40
  base?: string;
41
}
42
```
43

44
### Glob Patterns
45

46
Glob patterns are executed in order, so negations should follow positive globs.
47

48
```javascript
49
// Correct: excludes files starting with 'b'
50
vfs.src(['*', '!b*']);
51

52
// Incorrect: does not exclude files starting with 'b'
53
vfs.src(['!b*', '*']);
54
```
55

56
### Option Details
57

58
#### buffer
59
Controls whether file contents are loaded into memory or streamed.
60

61
```javascript
62
// Buffer contents into memory (default)
63
vfs.src('*.js', { buffer: true });
64

65
// Stream contents (file.contents will be a readable stream)
66
vfs.src('*.js', { buffer: false });
67
```
68

69
#### read
70
Controls whether file contents are read at all.
71

72
```javascript
73
// Read file contents (default)
74
vfs.src('*.js', { read: true });
75

76
// Skip reading contents (file.contents will be null)
77
vfs.src('*.js', { read: false });
78
```
79

80
#### since
81
Only processes files modified after the specified time.
82

83
```javascript
84
// Only files modified in the last hour
85
const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
86
vfs.src('*.js', { since: oneHourAgo });
87

88
// Using timestamp
89
vfs.src('*.js', { since: 1609459200000 });
90
```
91

92
#### encoding
93
Controls character encoding for file contents.
94

95
```javascript
96
// Default UTF-8 encoding
97
vfs.src('*.txt', { encoding: 'utf8' });
98

99
// Latin-1 encoding
100
vfs.src('*.txt', { encoding: 'latin1' });
101

102
// No encoding (raw binary)
103
vfs.src('*.bin', { encoding: false });
104
```
105

106
#### sourcemaps
107
Enables sourcemap processing for files.
108

109
```javascript
110
// Load and process sourcemaps
111
vfs.src('*.js', { sourcemaps: true });
112
```
113

114
#### resolveSymlinks
115
Controls symbolic link handling.
116

117
```javascript
118
// Resolve symlinks to their targets (default)
119
vfs.src('**/*', { resolveSymlinks: true });
120

121
// Preserve symlinks (file.symlink will contain target path)
122
vfs.src('**/*', { resolveSymlinks: false });
123
```
124

125
### Error Handling
126

127
The src function throws errors for invalid inputs:
128

129
```javascript
130
// Throws: "Invalid glob argument: null"
131
try {
132
  vfs.src(null);
133
} catch (error) {
134
  console.error(error.message);
135
}
136
```
137

138
### Usage Examples
139

140
**Basic file reading:**
141

142
```javascript
143
const vfs = require('vinyl-fs');
144

145
vfs.src('src/**/*.js')
146
  .on('data', (file) => {
147
    console.log('Processing:', file.path);
148
  })
149
  .on('end', () => {
150
    console.log('All files processed');
151
  });
152
```
153

154
**Advanced configuration:**
155

156
```javascript
157
vfs.src(['src/**/*.js', '!src/vendor/**'], {
158
  buffer: false,        // Stream large files
159
  since: new Date('2023-01-01'),  // Only recent files
160
  sourcemaps: true,     // Process sourcemaps
161
  encoding: 'utf8'      // Ensure UTF-8 encoding
162
});
163
```
164

165
**Function-based options:**
166

167
```javascript
168
vfs.src('**/*', {
169
  // Dynamic encoding based on file extension
170
  encoding: (file) => {
171
    return file.extname === '.bin' ? false : 'utf8';
172
  },
173
  // Conditional reading
174
  read: (file) => {
175
    return file.extname !== '.tmp';
176
  }
177
});
178
```