node_modules/webpack-sources/README.md

   1 # webpack-sources
   2
   3 Contains multiple classes which represent a `Source`. A `Source` can be asked for source code, size, source map and hash.
   4
   5 ## `Source`
   6
   7 Base class for all sources.
   8
   9 ### Public methods
  10
  11 All methods should be considered as expensive as they may need to do computations.
  12
  13 #### `source`
  14
  15 ```typescript
  16 Source.prototype.source() -> String | Buffer
  17 ```
  18
  19 Returns the represented source code as string or Buffer (for binary Sources).
  20
  21 #### `buffer`
  22
  23 ```typescript
  24 Source.prototype.buffer() -> Buffer
  25 ```
  26
  27 Returns the represented source code as Buffer. Strings are converted to utf-8.
  28
  29 #### `size`
  30
  31 ```typescript
  32 Source.prototype.size() -> Number
  33 ```
  34
  35 Returns the size in bytes of the represented source code.
  36
  37 #### `map`
  38
  39 ```typescript
  40 Source.prototype.map(options?: Object) -> Object | null
  41 ```
  42
  43 Returns the SourceMap of the represented source code as JSON. May return `null` if no SourceMap is available.
  44
  45 The `options` object can contain the following keys:
  46
  47 - `columns: Boolean` (default `true`): If set to false the implementation may omit mappings for columns.
  48
  49 #### `sourceAndMap`
  50
  51 ```typescript
  52 Source.prototype.sourceAndMap(options?: Object) -> {
  53         source: String | Buffer,
  54         map: Object | null
  55 }
  56 ```
  57
  58 Returns both, source code (like `Source.prototype.source()` and SourceMap (like `Source.prototype.map()`). This method could have better performance than calling `source()` and `map()` separately.
  59
  60 See `map()` for `options`.
  61
  62 #### `updateHash`
  63
  64 ```typescript
  65 Source.prototype.updateHash(hash: Hash) -> void
  66 ```
  67
  68 Updates the provided `Hash` object with the content of the represented source code. (`Hash` is an object with an `update` method, which is called with string values)
  69
  70 ## `RawSource`
  71
  72 Represents source code without SourceMap.
  73
  74 ```typescript
  75 new RawSource(sourceCode: String | Buffer)
  76 ```
  77
  78 ## `OriginalSource`
  79
  80 Represents source code, which is a copy of the original file.
  81
  82 ```typescript
  83 new OriginalSource(
  84         sourceCode: String | Buffer,
  85         name: String
  86 )
  87 ```
  88
  89 - `sourceCode`: The source code.
  90 - `name`: The filename of the original source code.
  91
  92 OriginalSource tries to create column mappings if requested, by splitting the source code at typical statement borders (`;`, `{`, `}`).
  93
  94 ## `SourceMapSource`
  95
  96 Represents source code with SourceMap, optionally having an additional SourceMap for the original source.
  97
  98 ```typescript
  99 new SourceMapSource(
 100         sourceCode: String | Buffer,
 101         name: String,
 102         sourceMap: Object | String | Buffer,
 103         originalSource?: String | Buffer,
 104         innerSourceMap?: Object | String | Buffer,
 105         removeOriginalSource?: boolean
 106 )
 107 ```
 108
 109 - `sourceCode`: The source code.
 110 - `name`: The filename of the original source code.
 111 - `sourceMap`: The SourceMap for the source code.
 112 - `originalSource`: The source code of the original file. Can be omitted if the `sourceMap` already contains the original source code.
 113 - `innerSourceMap`: The SourceMap for the `originalSource`/`name`.
 114 - `removeOriginalSource`: Removes the source code for `name` from the final map, keeping only the deeper mappings for that file.
 115
 116 The `SourceMapSource` supports "identity" mappings for the `innerSourceMap`.
 117 When original source matches generated source for a mapping it's assumed to be mapped char by char allowing to keep finer mappings from `sourceMap`.
 118
 119 ## `CachedSource`
 120
 121 Decorates a `Source` and caches returned results of `map`, `source`, `buffer`, `size` and `sourceAndMap` in memory. `updateHash` is not cached.
 122 It tries to reused cached results from other methods to avoid calculations, i. e. when `source` is already cached, calling `size` will get the size from the cached source, calling `sourceAndMap` will only call `map` on the wrapped Source.
 123
 124 ```typescript
 125 new CachedSource(source: Source)
 126 new CachedSource(source: Source | () => Source, cachedData?: CachedData)
 127 ```
 128
 129 Instead of passing a `Source` object directly one can pass an function that returns a `Source` object. The function is only called when needed and once.
 130
 131 ### Public methods
 132
 133 #### `getCachedData()`
 134
 135 Returns the cached data for passing to the constructor. All cached entries are converted to Buffers and strings are avoided.
 136
 137 #### `original()`
 138
 139 Returns the original `Source` object.
 140
 141 #### `originalLazy()`
 142
 143 Returns the original `Source` object or a function returning these.
 144
 145 ## `PrefixSource`
 146
 147 Prefix every line of the decorated `Source` with a provided string.
 148
 149 ```typescript
 150 new PrefixSource(
 151         prefix: String,
 152         source: Source | String | Buffer
 153 )
 154 ```
 155
 156 ## `ConcatSource`
 157
 158 Concatenate multiple `Source`s or strings to a single source.
 159
 160 ```typescript
 161 new ConcatSource(
 162         ...items?: Source | String
 163 )
 164 ```
 165
 166 ### Public methods
 167
 168 #### `add`
 169
 170 ```typescript
 171 ConcatSource.prototype.add(item: Source | String)
 172 ```
 173
 174 Adds an item to the source.
 175
 176 ## `ReplaceSource`
 177
 178 Decorates a `Source` with replacements and insertions of source code.
 179
 180 The `ReplaceSource` supports "identity" mappings for child source.
 181 When original source matches generated source for a mapping it's assumed to be mapped char by char allowing to split mappings at replacements/insertions.
 182
 183 ### Public methods
 184
 185 #### `replace`
 186
 187 ```typescript
 188 ReplaceSource.prototype.replace(
 189         start: Number,
 190         end: Number,
 191         replacement: String
 192 )
 193 ```
 194
 195 Replaces chars from `start` (0-indexed, inclusive) to `end` (0-indexed, inclusive) with `replacement`.
 196
 197 Locations represents locations in the original source and are not influenced by other replacements or insertions.
 198
 199 #### `insert`
 200
 201 ```typescript
 202 ReplaceSource.prototype.insert(
 203         pos: Number,
 204         insertion: String
 205 )
 206 ```
 207
 208 Inserts the `insertion` before char `pos` (0-indexed).
 209
 210 Location represents location in the original source and is not influenced by other replacements or insertions.
 211
 212 #### `original`
 213
 214 Get decorated `Source`.
 215
 216 ## `CompatSource`
 217
 218 Converts a Source-like object into a real Source object.
 219
 220 ### Public methods
 221
 222 #### static `from`
 223
 224 ```typescript
 225 CompatSource.from(sourceLike: any | Source)
 226 ```
 227
 228 If `sourceLike` is a real Source it returns it unmodified. Otherwise it returns it wrapped in a CompatSource.