0
# Source Implementations
1

2
Different types of source representations for various use cases, from simple raw text to complex source-mapped content.
3

4
## Capabilities
5

6
### RawSource
7

8
Represents source code without source map information. The simplest source implementation.
9

10
```typescript { .api }
11
/**
12
 * Source code without source map
13
 * @param value - The source code as string or Buffer
14
 * @param convertToString - If true, forces Buffer to be converted to string
15
 */
16
class RawSource extends Source {
17
  constructor(value: string | Buffer, convertToString?: boolean);
18
  
19
  /** Returns true if the source represents binary data */
20
  isBuffer(): boolean;
21
  
22
  /** Streams source chunks for processing */
23
  streamChunks(
24
    options: StreamChunksOptions,
25
    onChunk: OnChunk,
26
    onSource: OnSource,
27
    onName: OnName
28
  ): GeneratedSourceInfo;
29
}
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
const { RawSource } = require("webpack-sources");
36

37
// Text source
38
const textSource = new RawSource("console.log('Hello World');");
39
console.log(textSource.source()); // "console.log('Hello World');"
40
console.log(textSource.size()); // 27
41
console.log(textSource.isBuffer()); // false
42

43
// Buffer source  
44
const bufferSource = new RawSource(Buffer.from("binary data", "utf8"));
45
console.log(bufferSource.isBuffer()); // true
46
console.log(bufferSource.buffer()); // <Buffer 62 69 6e 61 72 79 20 64 61 74 61>
47

48
// Force buffer to string conversion
49
const convertedSource = new RawSource(Buffer.from("test"), true);
50
console.log(convertedSource.isBuffer()); // false
51
```
52

53
### OriginalSource
54

55
Represents source code that is a copy of the original file. Automatically creates column mappings when requested.
56

57
```typescript { .api }
58
/**
59
 * Source code copy of original file with automatic column mapping
60
 * @param value - The source code as string or Buffer
61
 * @param name - The filename of the original source code
62
 */
63
class OriginalSource extends Source {
64
  constructor(value: string | Buffer, name: string);
65
  
66
  /** Returns the filename of the original source */
67
  getName(): string;
68
  
69
  /** Streams source chunks with column mappings */
70
  streamChunks(
71
    options: StreamChunksOptions,
72
    onChunk: OnChunk,
73
    onSource: OnSource,
74
    onName: OnName
75
  ): GeneratedSourceInfo;
76
}
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
const { OriginalSource } = require("webpack-sources");
83

84
const source = new OriginalSource(
85
  "function hello() {\n  console.log('Hello');\n}",
86
  "hello.js"
87
);
88

89
console.log(source.getName()); // "hello.js"
90
console.log(source.source()); // "function hello() {\n  console.log('Hello');\n}"
91

92
// Generate source map with column mappings
93
const map = source.map({ columns: true });
94
console.log(map.sources); // ["hello.js"]
95
console.log(map.file); // "hello.js"
96
```
97

98
### SourceMapSource
99

100
Represents source code with an existing source map, optionally with additional source map for the original source.
101

102
```typescript { .api }
103
/**
104
 * Source code with existing source map support
105
 * @param value - The source code as string or Buffer
106
 * @param name - The filename of the original source code  
107
 * @param sourceMap - The source map for the source code
108
 * @param originalSource - Optional original source code
109
 * @param innerSourceMap - Optional source map for the original source
110
 * @param removeOriginalSource - Remove original source from final map
111
 */
112
class SourceMapSource extends Source {
113
  constructor(
114
    value: string | Buffer,
115
    name: string,
116
    sourceMap?: string | RawSourceMap | Buffer,
117
    originalSource?: string | Buffer,
118
    innerSourceMap?: string | RawSourceMap | Buffer,
119
    removeOriginalSource?: boolean
120
  );
121
  
122
  /** Returns constructor arguments as buffers for serialization */
123
  getArgsAsBuffers(): [
124
    Buffer,
125
    string,
126
    Buffer,
127
    Buffer | undefined,
128
    Buffer | undefined,
129
    boolean | undefined
130
  ];
131
  
132
  /** Streams source chunks with source map support */
133
  streamChunks(
134
    options: StreamChunksOptions,
135
    onChunk: OnChunk,
136
    onSource: OnSource,
137
    onName: OnName
138
  ): GeneratedSourceInfo;
139
}
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
const { SourceMapSource } = require("webpack-sources");
146

147
// Simple source with source map
148
const sourceMapSource = new SourceMapSource(
149
  "console.log('compiled');",
150
  "output.js",
151
  {
152
    version: 3,
153
    sources: ["input.js"],
154
    names: [],
155
    mappings: "AAAA",
156
    file: "output.js"
157
  }
158
);
159

160
console.log(sourceMapSource.source()); // "console.log('compiled');"
161
const map = sourceMapSource.map();
162
console.log(map.sources); // ["input.js"]
163

164
// Complex source with inner source map
165
const complexSource = new SourceMapSource(
166
  "var a=1;console.log(a);", // minified code
167
  "bundle.js",
168
  bundleSourceMap, // source map from bundler
169
  "const a = 1;\nconsole.log(a);", // original unminified code  
170
  originalSourceMap // source map from TypeScript compiler
171
);
172

173
// Get serializable arguments
174
const args = complexSource.getArgsAsBuffers();
175
// Can be used to recreate: new SourceMapSource(...args)
176
```
177

178
### Source Type Definition
179

180
Type alias for source value that can be either string or Buffer.
181

182
```typescript { .api }
183
/** Source content can be either string or Buffer */
184
type SourceValue = string | Buffer;
185
```
186

187
### Streaming Support
188

189
All source implementations support streaming for efficient processing of large sources.
190

191
```typescript { .api }
192
interface StreamChunksOptions {
193
  /** Include source content in chunks */
194
  source?: boolean;
195
  /** Mark as final source */
196
  finalSource?: boolean;
197
  /** Include column information */
198
  columns?: boolean;
199
}
200

201
interface GeneratedSourceInfo {
202
  /** Final generated line number */
203
  generatedLine?: number;
204
  /** Final generated column number */
205
  generatedColumn?: number;
206
  /** Source file name */
207
  source?: string;
208
}
209

210
type OnChunk = (
211
  chunk: string | undefined,
212
  generatedLine: number,
213
  generatedColumn: number,
214
  sourceIndex: number,
215
  originalLine: number,
216
  originalColumn: number,
217
  nameIndex: number
218
) => void;
219

220
type OnSource = (
221
  sourceIndex: number,
222
  source: string | null,
223
  sourceContent?: string
224
) => void;
225

226
type OnName = (nameIndex: number, name: string) => void;
227
```
228

229
**Usage Example:**
230

231
```javascript
232
const { OriginalSource } = require("webpack-sources");
233

234
const source = new OriginalSource("line1\nline2\nline3", "test.js");
235

236
source.streamChunks(
237
  { columns: true },
238
  (chunk, genLine, genCol, srcIdx, origLine, origCol, nameIdx) => {
239
    console.log(`Chunk: "${chunk}" at ${genLine}:${genCol}`);
240
  },
241
  (srcIdx, src, content) => {
242
    console.log(`Source ${srcIdx}: ${src}`);
243
  },
244
  (nameIdx, name) => {
245
    console.log(`Name ${nameIdx}: ${name}`);
246
  }
247
);
248
```