0
# webpack-sources
1

2
webpack-sources provides a comprehensive set of classes for handling source code in webpack and other build tools. It offers different representations of source code with optional source map support, enabling sophisticated source manipulation while preserving debugging information.
3

4
## Package Information
5

6
- **Package Name**: webpack-sources
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install webpack-sources`
10

11
## Core Imports
12

13
```javascript
14
const { Source, RawSource, OriginalSource, SourceMapSource, util } = require("webpack-sources");
15
```
16

17
For ESM:
18

19
```typescript
20
import { Source, RawSource, OriginalSource, SourceMapSource, util } from "webpack-sources";
21
```
22

23
For utility functions:
24

25
```javascript
26
const { util: { stringBufferUtils } } = require("webpack-sources");
27
// Access optimization utilities:
28
// stringBufferUtils.enableDualStringBufferCaching()
29
// stringBufferUtils.internString(str)
30
```
31

32
## Basic Usage
33

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

37
// Create a simple source
38
const source = new RawSource("console.log('Hello World!');");
39

40
// Get source content
41
const code = source.source(); // "console.log('Hello World!');"
42
const size = source.size(); // 27
43

44
// Combine sources
45
const combined = new ConcatSource(
46
  new RawSource("const greeting = "),
47
  new RawSource("'Hello World';"),
48
  new RawSource("\nconsole.log(greeting);")
49
);
50
```
51

52
## Architecture
53

54
webpack-sources is built around several key components:
55

56
- **Base Source Class**: Abstract foundation providing the core source interface
57
- **Source Implementations**: Concrete classes representing different source types and capabilities
58
- **Source Manipulation**: Classes for combining, modifying, and transforming sources
59
- **Caching Layer**: Performance optimization through memoization of expensive operations
60
- **Source Map Support**: Full integration with source maps for debugging support
61
- **Memory Optimization**: String interning and buffer caching for reduced memory usage
62

63
## Capabilities
64

65
### Base Source Interface
66

67
Core interface that all source representations implement, providing methods for accessing source code, size, and source maps.
68

69
```typescript { .api }
70
abstract class Source {
71
  /** Returns the source code as string or Buffer */
72
  source(): string | Buffer;
73
  /** Returns the source code as Buffer */
74
  buffer(): Buffer;
75
  /** Returns size in bytes */
76
  size(): number;
77
  /** Returns source map or null */
78
  map(options?: MapOptions): RawSourceMap | null;
79
  /** Returns both source and map together */
80
  sourceAndMap(options?: MapOptions): SourceAndMap;
81
  /** Updates hash with source content */
82
  updateHash(hash: HashLike): void;
83
}
84

85
interface MapOptions {
86
  /** Include column mappings (default: true) */
87
  columns?: boolean;
88
  /** Treat as module */
89
  module?: boolean;
90
}
91

92
interface SourceAndMap {
93
  source: string | Buffer;
94
  map: RawSourceMap | null;
95
}
96

97
interface HashLike {
98
  update(data: string | Buffer, encoding?: string): HashLike;
99
  digest(encoding?: string): string | Buffer;
100
}
101
```
102

103
[Base Source](./base-source.md)
104

105
### Source Implementations
106

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

109
```typescript { .api }
110
class RawSource extends Source {
111
  constructor(value: string | Buffer, convertToString?: boolean);
112
  isBuffer(): boolean;
113
}
114

115
class OriginalSource extends Source {
116
  constructor(value: string | Buffer, name: string);
117
  getName(): string;
118
}
119

120
class SourceMapSource extends Source {
121
  constructor(
122
    value: string | Buffer,
123
    name: string,
124
    sourceMap?: string | RawSourceMap | Buffer,
125
    originalSource?: string | Buffer,
126
    innerSourceMap?: string | RawSourceMap | Buffer,
127
    removeOriginalSource?: boolean
128
  );
129
  getArgsAsBuffers(): [Buffer, string, Buffer, Buffer?, Buffer?, boolean?];
130
}
131
```
132

133
[Source Implementations](./source-implementations.md)
134

135
### Source Manipulation
136

137
Classes for combining, modifying, and transforming sources while preserving source map information.
138

139
```typescript { .api }
140
class ConcatSource extends Source {
141
  constructor(...items: ConcatSourceChild[]);
142
  add(item: ConcatSourceChild): void;
143
  getChildren(): Source[];
144
}
145

146
class ReplaceSource extends Source {
147
  constructor(source: Source, name?: string);
148
  replace(start: number, end: number, newValue: string, name?: string): void;
149
  insert(pos: number, newValue: string, name?: string): void;
150
  original(): Source;
151
}
152

153
class PrefixSource extends Source {
154
  constructor(prefix: string, source: string | Source | Buffer);
155
  getPrefix(): string;
156
  original(): Source;
157
}
158

159
type ConcatSourceChild = string | Source | SourceLike;
160
```
161

162
[Source Manipulation](./source-manipulation.md)
163

164
### Caching and Performance
165

166
Performance optimization through caching and memory management utilities.
167

168
```typescript { .api }
169
class CachedSource extends Source {
170
  constructor(source: Source | (() => Source), cachedData?: CachedData);
171
  getCachedData(): CachedData;
172
  original(): Source;
173
  originalLazy(): Source | (() => Source);
174
}
175

176
interface CachedData {
177
  source?: boolean;
178
  buffer: Buffer;
179
  size?: number;
180
  maps: Map<string, BufferEntry>;
181
  hash?: (string | Buffer)[];
182
}
183
```
184

185
[Caching and Performance](./caching-performance.md)
186

187
### Utility Classes
188

189
Additional utilities for source compatibility and specialized use cases.
190

191
```typescript { .api }
192
class CompatSource extends Source {
193
  constructor(sourceLike: SourceLike);
194
  static from(sourceLike: SourceLike): Source;
195
}
196

197
class SizeOnlySource extends Source {
198
  constructor(size: number);
199
}
200

201
interface SourceLike {
202
  source(): string | Buffer;
203
  buffer?(): Buffer;
204
  size?(): number;
205
  map?(options?: MapOptions): RawSourceMap | null;
206
  sourceAndMap?(options?: MapOptions): SourceAndMap;
207
  updateHash?(hash: HashLike): void;
208
}
209
```
210

211
[Utility Classes](./utility-classes.md)
212

213
## Types
214

215
```typescript { .api }
216
interface RawSourceMap {
217
  version: number;
218
  sources: string[];
219
  names: string[];
220
  sourceRoot?: string;
221
  sourcesContent?: string[];
222
  mappings: string;
223
  file: string;
224
  debugId?: string;
225
  ignoreList?: number[];
226
}
227

228
interface BufferEntry {
229
  map?: RawSourceMap | null;
230
  bufferedMap?: BufferedMap | null;
231
}
232

233
interface BufferedMap {
234
  version: number;
235
  sources: string[];
236
  names: string[];
237
  sourceRoot?: string;
238
  sourcesContent?: ("" | Buffer)[];
239
  mappings?: Buffer;
240
  file: string;
241
}
242

243
interface GeneratedSourceInfo {
244
  generatedLine?: number;
245
  generatedColumn?: number;
246
  source?: string;
247
}
248

249
interface StreamChunksOptions {
250
  source?: boolean;
251
  finalSource?: boolean;
252
  columns?: boolean;
253
}
254

255
type OnChunk = (
256
  chunk: string | undefined,
257
  generatedLine: number,
258
  generatedColumn: number,
259
  sourceIndex: number,
260
  originalLine: number,
261
  originalColumn: number,
262
  nameIndex: number
263
) => void;
264

265
type OnSource = (
266
  sourceIndex: number,
267
  source: string | null,
268
  sourceContent?: string
269
) => void;
270

271
type OnName = (nameIndex: number, name: string) => void;
272
```