0
# Google Ignore List Processing
1

2
Processing of Google's ignore list extension for source maps, used to mark generated or third-party code that should be ignored during debugging.
3

4
## Capabilities
5

6
### GoogleIgnoreListConsumer Class
7

8
Processes `x_google_ignoreList` metadata from source maps to identify sources that should be ignored during debugging and error reporting.
9

10
```javascript { .api }
11
/**
12
 * Consumes Google ignore list metadata from source maps
13
 * @param map - Source map object (BasicSourceMap or IndexMap)
14
 * @param normalizeSourceFn - Optional function to normalize source names
15
 */
16
class GoogleIgnoreListConsumer {
17
  constructor(map: MixedSourceMap, normalizeSourceFn?: SourceNameNormalizer);
18
  
19
  /**
20
   * Checks if a source is in the ignore list
21
   * @param {source} - Object containing source file name to check (can be null)
22
   * @returns true if source should be ignored, false otherwise
23
   */
24
  isIgnored({source}: {source: ?string}): boolean;
25
  
26
  /**
27
   * Returns this map's ignore list as a new array with indices based on sources
28
   * @param sources - Array of source names
29
   * @returns Array of indices representing ignored sources
30
   */
31
  toArray(sources: Array<?string>): Array<number>;
32
}
33
```
34

35
**Usage Examples:**
36

37
```javascript
38
const GoogleIgnoreListConsumer = require('metro-symbolicate/private/GoogleIgnoreListConsumer');
39
const fs = require('fs');
40

41
// Load source map with ignore list
42
const sourceMap = JSON.parse(fs.readFileSync('bundle.js.map', 'utf8'));
43
const ignoreListConsumer = new GoogleIgnoreListConsumer(sourceMap);
44

45
// Check if sources should be ignored
46
const shouldIgnore = ignoreListConsumer.isIgnored({source: 'node_modules/react/index.js'});
47
if (shouldIgnore) {
48
  console.log('Source is in ignore list - skip in stack traces');
49
}
50

51
// Filter stack traces to exclude ignored sources
52
const filterStackTrace = (trace, ignoreConsumer) => {
53
  return trace
54
    .split('\n')
55
    .filter(line => {
56
      const match = line.match(/at .* \((.*?):\d+:\d+\)/);
57
      if (match) {
58
        const source = match[1];
59
        return !ignoreConsumer.isIgnored({source});
60
      }
61
      return true;
62
    })
63
    .join('\n');
64
};
65
```
66

67
### Ignore List Integration
68

69
Seamlessly integrates with debugging tools and stack trace processing to hide generated or third-party code.
70

71
**Common Use Cases:**
72

73
1. **Library Code Filtering**: Hide third-party dependencies from stack traces
74
2. **Generated Code Filtering**: Exclude bundler-generated code and polyfills  
75
3. **Debug Experience**: Focus on application code during debugging
76

77
```javascript
78
// Example: Enhanced stack trace symbolication with ignore list filtering
79
const Symbolication = require('metro-symbolicate/private/Symbolication');
80
const GoogleIgnoreListConsumer = require('metro-symbolicate/private/GoogleIgnoreListConsumer');
81
const { SourceMapConsumer } = require('source-map');
82

83
const processStackTraceWithFiltering = (sourceMapContent, stackTrace) => {
84
  // Create symbolication context
85
  const context = Symbolication.createContext(SourceMapConsumer, sourceMapContent);
86
  
87
  // Create ignore list consumer
88
  const sourceMap = JSON.parse(sourceMapContent);
89
  const ignoreList = new GoogleIgnoreListConsumer(sourceMap);
90
  
91
  // Symbolicate the stack trace
92
  const symbolicatedTrace = context.symbolicate(stackTrace);
93
  
94
  // Filter out ignored sources
95
  const filteredTrace = symbolicatedTrace
96
    .split('\n')
97
    .filter(line => {
98
      const match = line.match(/at .* \((.*?):\d+:\d+\)/);
99
      if (match) {
100
        const source = match[1];
101
        return !ignoreList.isIgnored({source});
102
      }
103
      return true; // Keep non-source lines (error messages, etc.)
104
    })
105
    .join('\n');
106
  
107
  return filteredTrace;
108
};
109
```
110

111
### Source Name Normalization
112

113
Handles source name normalization to ensure consistent matching between source maps and ignore lists.
114

115
**Default Normalization:**
116

117
Uses the same normalization logic as the `source-map@0.5.6` package to ensure consistency:
118

119
```javascript
120
const GoogleIgnoreListConsumer = require('metro-symbolicate/private/GoogleIgnoreListConsumer');
121

122
// Default normalization (same as source-map library)
123
const consumer = new GoogleIgnoreListConsumer(sourceMap);
124

125
// Custom normalization for specific bundler configurations
126
const customConsumer = new GoogleIgnoreListConsumer(sourceMap, (source, options) => {
127
  // Remove webpack-specific prefixes
128
  if (source.startsWith('webpack:///')) {
129
    source = source.slice('webpack:///'.length);
130
  }
131
  
132
  // Handle source root
133
  if (options.sourceRoot && !source.startsWith('/')) {
134
    source = options.sourceRoot.replace(/\/$/, '') + '/' + source;
135
  }
136
  
137
  return source;
138
});
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
// Working with different bundler outputs
145
const createIgnoreListConsumer = (sourceMap, bundlerType) => {
146
  let normalizer;
147
  
148
  switch (bundlerType) {
149
    case 'webpack':
150
      normalizer = (source) => source.replace(/^webpack:\/\/\//, '');
151
      break;
152
    case 'metro':
153
      normalizer = (source) => source; // Metro uses standard normalization
154
      break;
155
    default:
156
      normalizer = undefined; // Use default normalization
157
  }
158
  
159
  return new GoogleIgnoreListConsumer(sourceMap, normalizer);
160
};
161
```
162

163
### Ignore List Format
164

165
Understands the standard Google ignore list format used in source maps.
166

167
**Source Map Ignore List Structure:**
168

169
```javascript
170
// Example source map with ignore list
171
{
172
  "version": 3,
173
  "sources": [
174
    "src/app.js",           // index 0 - application code
175
    "src/utils.js",         // index 1 - application code  
176
    "node_modules/react/index.js",  // index 2 - library code
177
    "webpack/bootstrap"     // index 3 - generated code
178
  ],
179
  "x_google_ignoreList": [2, 3], // Ignore sources at indices 2 and 3
180
  // ... other source map fields
181
}
182
```
183

184
**Ignore List Processing:**
185

186
```javascript
187
const consumer = new GoogleIgnoreListConsumer(sourceMap);
188

189
// Check specific sources
190
console.log(consumer.isIgnored({source: 'src/app.js'}));           // false
191
console.log(consumer.isIgnored({source: 'src/utils.js'}));         // false  
192
console.log(consumer.isIgnored({source: 'node_modules/react/index.js'})); // true
193
console.log(consumer.isIgnored({source: 'webpack/bootstrap'}));    // true
194

195
// Handle null/undefined sources gracefully
196
console.log(consumer.isIgnored({source: null}));      // false
197
console.log(consumer.isIgnored({source: undefined})); // false
198
```
199

200
### Performance Optimization
201

202
Efficiently processes ignore lists using internal caching for repeated queries.
203

204
```javascript
205
// Internal ignore set is built lazily and cached
206
const consumer = new GoogleIgnoreListConsumer(largeSourceMap);
207

208
// First call builds the ignore set
209
const isIgnored1 = consumer.isIgnored({source: 'some/source.js'});
210

211
// Subsequent calls use cached set for fast lookups
212
const isIgnored2 = consumer.isIgnored({source: 'another/source.js'});
213
const isIgnored3 = consumer.isIgnored({source: 'third/source.js'});
214
```
215

216
### Error Handling
217

218
Gracefully handles missing or malformed ignore list data.
219

220
```javascript
221
// Missing ignore list - no sources are ignored
222
const sourceMapWithoutIgnoreList = {
223
  version: 3,
224
  sources: ['src/app.js'],
225
  mappings: '...'
226
  // No x_google_ignoreList field
227
};
228

229
const consumer = new GoogleIgnoreListConsumer(sourceMapWithoutIgnoreList);
230
console.log(consumer.isIgnored({source: 'src/app.js'})); // false
231

232
// Invalid ignore list indices are handled gracefully
233
const sourceMapWithInvalidIgnoreList = {
234
  version: 3,
235
  sources: ['src/app.js'],
236
  mappings: '...',
237
  x_google_ignoreList: [999] // Index out of bounds
238
};
239

240
const invalidConsumer = new GoogleIgnoreListConsumer(sourceMapWithInvalidIgnoreList);
241
console.log(invalidConsumer.isIgnored({source: 'src/app.js'})); // false
242
```
243

244
## Types
245

246
```javascript { .api }
247
type MixedSourceMap = BasicSourceMap | IndexMap;
248

249
type BasicSourceMap = {
250
  version: number;
251
  sources: Array<string>;
252
  names: Array<string>;
253
  mappings: string;
254
  file?: string;
255
  sourceRoot?: string;
256
  sourcesContent?: Array<?string>;
257
  x_google_ignoreList?: Array<number>; // Array of source indices to ignore
258
};
259

260
type IndexMap = {
261
  version: number;
262
  file?: string;
263
  sections: Array<IndexMapSection>;
264
  x_google_ignoreList?: Array<number>; // Array of source indices to ignore
265
};
266

267
type SourceNameNormalizer = (
268
  source: string,
269
  options: { sourceRoot?: ?string }
270
) => string;
271
```