0
# Vinyl Source Stream
1

2
Vinyl Source Stream is a utility that enables the use of conventional text streams at the start of gulp or vinyl pipelines. It creates a bridge between standard Node.js streams and vinyl file objects, making it easier to integrate existing stream-based tools with gulp workflows without needing specialized wrapper plugins.
3

4
## Package Information
5

6
- **Package Name**: vinyl-source-stream
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install vinyl-source-stream`
10

11
## Core Imports
12

13
```javascript
14
const source = require('vinyl-source-stream');
15
```
16

17
ES Modules:
18

19
```javascript
20
import source from 'vinyl-source-stream';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const source = require('vinyl-source-stream');
27
const gulp = require('gulp');
28
const fs = require('fs');
29

30
// Basic usage with a readable stream
31
fs.createReadStream('input.txt')
32
  .pipe(source('output.txt'))
33
  .pipe(gulp.dest('./dist'));
34

35
// Common usage with browserify
36
const browserify = require('browserify');
37

38
const bundleStream = browserify('./index.js').bundle();
39
bundleStream
40
  .pipe(source('bundle.js'))
41
  .pipe(gulp.dest('./dist'));
42
```
43

44
## Capabilities
45

46
### Stream to Vinyl Conversion
47

48
Converts conventional text streams into vinyl file objects for use in gulp pipelines.
49

50
```javascript { .api }
51
/**
52
 * Creates a through stream that converts text input to vinyl file instances
53
 * @param filename - Optional filename for the output vinyl file
54
 * @param baseDir - Optional base directory for path resolution
55
 * @returns Transform stream that emits vinyl file objects
56
 */
57
function vinylSourceStream(filename, baseDir)
58
```
59

60
**Parameters:**
61

62
- `filename` (string, optional): A "pretend" filename to use for the vinyl file. This affects how downstream processes handle the file (e.g., for determining output filename, content type detection). If not provided, the vinyl file will have no path property.
63

64
- `baseDir` (string, optional): Base directory for resolving the file path. When combined with `filename`, creates the full file path using `path.resolve(baseDir || process.cwd(), filename)`. Also sets the vinyl file's `base` property when provided. If not provided but `filename` is given, path resolution defaults to `process.cwd()` but no `base` property is set.
65

66
**Returns:**
67

68
Transform stream (through2 in object mode) that:
69
- Accepts text/buffer chunks as input
70
- Emits a single vinyl file object containing the input stream as its contents
71
- The vinyl file's `contents` property is a readable stream containing all input data
72

73
**Stream Behavior:**
74

75
1. The first chunk of input triggers emission of the vinyl file object
76
2. All input chunks are forwarded to the vinyl file's internal contents stream
77
3. When input ends, both the internal stream and output stream are properly closed
78
4. The stream operates in object mode to handle vinyl file objects
79

80
**Usage Examples:**
81

82
```javascript
83
const source = require('vinyl-source-stream');
84
const fs = require('fs');
85
const gulp = require('gulp');
86

87
// Basic file conversion
88
fs.createReadStream('data.txt')
89
  .pipe(source('processed-data.txt'))
90
  .pipe(gulp.dest('./output'));
91

92
// With custom base directory
93
someReadableStream
94
  .pipe(source('result.json', './build'))
95
  .pipe(gulp.dest('./'));
96

97
// Filename only (base defaults to process.cwd())
98
dataStream
99
  .pipe(source('output.csv'))
100
  .pipe(someGulpPlugin())
101
  .pipe(gulp.dest('./dist'));
102

103
// Without filename (downstream plugins determine naming)
104
apiResponseStream
105
  .pipe(source())
106
  .pipe(someTransformPlugin())
107
  .pipe(gulp.dest('./cache'));
108
```
109

110
## Types
111

112
Since this is a JavaScript package, the following TypeScript-style definitions describe the expected types:
113

114
```typescript { .api }
115
interface VinylFile {
116
  contents: NodeJS.ReadableStream;
117
  path?: string;
118
  base?: string;
119
}
120

121
interface TransformStream extends NodeJS.ReadWriteStream {
122
  // Standard Node.js Transform stream interface
123
  // Accepts text/buffer chunks via write()
124
  // Emits vinyl file objects via 'data' events
125
}
126
```
127

128
## Integration Patterns
129

130
### With Browserify
131

132
```javascript
133
const browserify = require('browserify');
134
const source = require('vinyl-source-stream');
135
const gulp = require('gulp');
136

137
gulp.task('bundle', function() {
138
  return browserify('./src/app.js')
139
    .bundle()
140
    .pipe(source('app.bundle.js'))
141
    .pipe(gulp.dest('./dist/js'));
142
});
143
```
144

145
### With Other Stream-Based Tools
146

147
```javascript
148
const someStreamingTool = require('some-streaming-tool');
149
const source = require('vinyl-source-stream');
150

151
someStreamingTool.createStream()
152
  .pipe(source('tool-output.txt'))
153
  .pipe(gulp.dest('./output'));
154
```
155

156
## Error Handling
157

158
The stream follows standard Node.js stream error handling patterns. Errors from the input stream will be forwarded to the output stream:
159

160
```javascript
161
inputStream
162
  .pipe(source('output.txt'))
163
  .on('error', function(err) {
164
    console.error('Stream error:', err);
165
  })
166
  .pipe(gulp.dest('./dist'));
167
```