0
# Type System
1

2
The Browser Compat Data package provides complete TypeScript type definitions for all compatibility data structures, utility functions, and data organization patterns.
3

4
## Capabilities
5

6
### Core Data Types
7

8
Main type definitions for the compatibility data structure.
9

10
```typescript { .api }
11
/**
12
 * Main browser compatibility data interface containing all technology categories
13
 */
14
interface CompatData {
15
  /** Package metadata */
16
  __meta: {
17
    version: string;
18
    timestamp: string;
19
  };
20
  /** Web API interfaces, methods, properties, and events */
21
  api: { [key: string]: Identifier };
22
  /** Browser information, releases, and engine data */
23
  browsers: { [key: string]: BrowserStatement };
24
  /** CSS properties, selectors, at-rules, and functions */
25
  css: { [key: string]: Identifier };
26
  /** HTML elements, attributes, and global attributes */
27
  html: { [key: string]: Identifier };
28
  /** HTTP headers, status codes, methods, and features */
29
  http: { [key: string]: Identifier };
30
  /** JavaScript language features and built-in objects */
31
  javascript: { [key: string]: Identifier };
32
  /** Web App Manifest properties and PWA features */
33
  manifests: { [key: string]: Identifier };
34
  /** MathML elements and attributes */
35
  mathml: { [key: string]: Identifier };
36
  /** SVG elements, attributes, and features */
37
  svg: { [key: string]: Identifier };
38
  /** WebAssembly instructions, types, and features */
39
  webassembly: { [key: string]: Identifier };
40
  /** WebDriver automation commands and capabilities */
41
  webdriver: { [key: string]: Identifier };
42
  /** Browser extension APIs across different browsers */
43
  webextensions: { [key: string]: Identifier };
44
}
45

46
/**
47
 * Represents a feature tree node that may contain sub-features and compatibility data
48
 */
49
interface Identifier {
50
  /** Compatibility statement for this feature */
51
  __compat?: CompatStatement;
52
  /** Sub-features or related properties (index signature for nested features) */
53
  [key: string]: Identifier | CompatStatement | undefined;
54
}
55

56
/**
57
 * Union type representing any valid data node in the compatibility dataset
58
 */
59
type DataType = CompatData | BrowserStatement | CompatStatement | Identifier;
60
```
61

62
### Browser Types
63

64
Type definitions for browser information and releases.
65

66
```typescript { .api }
67
/**
68
 * Describes a browser including its releases, engine information, and capabilities
69
 */
70
interface BrowserStatement {
71
  /** Human-readable browser name */
72
  name: string;
73
  /** Browser type classification */
74
  type?: BrowserType;
75
  /** All browser releases with version information */
76
  releases: { [version: string]: ReleaseStatement };
77
  /** Whether browser accepts feature flags for enabling experimental features */
78
  accepts_flags?: boolean;
79
  /** Whether browser accepts webextensions */
80
  accepts_webextensions?: boolean;
81
  /** Preview browser name for development/beta versions */
82
  preview_name?: string;
83
  /** Upstream browser this one is based on (e.g., Chromium for Edge) */
84
  upstream?: string;
85
}
86

87
/**
88
 * Browser type classification
89
 */
90
type BrowserType = "desktop" | "mobile" | "xr" | "server";
91

92
/**
93
 * Information about a specific browser release
94
 */
95
interface ReleaseStatement {
96
  /** Release date in YYYY-MM-DD format */
97
  release_date?: string;
98
  /** URL to release notes for this version */
99
  release_notes?: string;
100
  /** Current status of this release */
101
  status: "retired" | "current" | "exclusive" | "beta" | "nightly" | "esr" | "planned";
102
  /** Rendering engine name (e.g., "Blink", "Gecko", "WebKit") */
103
  engine: string;
104
  /** Engine version for this browser release */
105
  engine_version: string;
106
}
107

108
/**
109
 * Union type of all supported browser names
110
 */
111
type BrowserName = 
112
  | "chrome" 
113
  | "chrome_android" 
114
  | "edge" 
115
  | "firefox" 
116
  | "firefox_android" 
117
  | "safari" 
118
  | "safari_ios" 
119
  | "opera" 
120
  | "opera_android" 
121
  | "webview_android" 
122
  | "samsunginternet_android" 
123
  | "oculus" 
124
  | "webview_ios";
125
```
126

127
### Compatibility Statement Types
128

129
Types for browser compatibility and support information.
130

131
```typescript { .api }
132
/**
133
 * Contains support data and metadata for a web platform feature
134
 */
135
interface CompatStatement {
136
  /** Human-readable description of the feature */
137
  description?: string;
138
  /** Specification URL(s) where this feature is defined */
139
  spec_url?: string | string[];
140
  /** Tags for categorization and web-features integration */
141
  tags?: string[];
142
  /** Browser support information */
143
  support: SupportBlock;
144
  /** Standardization and implementation status */
145
  status?: StatusStatement;
146
  /** Source file path in the repository where this data is defined */
147
  source_file?: string;
148
}
149

150
/**
151
 * Browser support information mapping browser names to support statements
152
 */
153
type SupportBlock = Partial<Record<BrowserName, SupportStatement>>;
154

155
/**
156
 * Support information for a specific browser (single statement or array for complex cases)
157
 */
158
type SupportStatement = SimpleSupportStatement | SimpleSupportStatement[];
159

160
/**
161
 * Detailed browser support information for a specific implementation
162
 */
163
interface SimpleSupportStatement {
164
  /** Version when support was added (string version, true for supported, false for not supported, null for unknown) */
165
  version_added: VersionValue;
166
  /** Version when support was removed (if applicable) */
167
  version_removed?: VersionValue;
168
  /** Required vendor prefix for the feature (e.g., "-webkit-", "-moz-") */
169
  prefix?: string;
170
  /** Alternative name the feature was known by in this browser */
171
  alternative_name?: string;
172
  /** Required flags to enable the feature */
173
  flags?: FlagStatement[];
174
  /** Implementation tracking URL (bug reports, implementation tickets) */
175
  impl_url?: string;
176
  /** Additional notes about the implementation, limitations, or caveats */
177
  notes?: string | string[];
178
  /** Whether support is only partial (missing some functionality from the spec) */
179
  partial_implementation?: boolean;
180
}
181

182
/**
183
 * Version value - string for specific versions, boolean for general support status
184
 */
185
type VersionValue = string | boolean | null;
186

187
/**
188
 * Standardization and implementation status information
189
 */
190
interface StatusStatement {
191
  /** Whether the feature is experimental and may change */
192
  experimental?: boolean;
193
  /** Whether the feature is on the W3C/WHATWG standards track */
194
  standard_track?: boolean;
195
  /** Whether the feature is deprecated and should be avoided */
196
  deprecated?: boolean;
197
}
198

199
/**
200
 * Information about feature flags required to enable functionality
201
 */
202
interface FlagStatement {
203
  /** Type of flag or preference */
204
  type: "preference" | "compile_flag" | "runtime_flag";
205
  /** Name of the flag or preference to set */
206
  name: string;
207
  /** Value to set for the flag (if applicable) */
208
  value_to_set?: string;
209
}
210
```
211

212
### Internal Types
213

214
Internal type definitions used by the package implementation.
215

216
```typescript { .api }
217
/**
218
 * Extended support statement that includes mirroring for internal processing
219
 */
220
type InternalSupportStatement = SupportStatement | 'mirror';
221

222
/**
223
 * Support block that can contain mirror statements for internal processing
224
 */
225
type InternalSupportBlock = Partial<Record<BrowserName, InternalSupportStatement>>;
226
```
227

228
### Walking and Query Types
229

230
Types for the navigation and walking utilities.
231

232
```typescript { .api }
233
/**
234
 * Output from walk() iterator containing feature information
235
 */
236
interface WalkOutput {
237
  /** Dotted path to the feature (e.g., "api.fetch.json") */
238
  path: string;
239
  /** The feature's data object */
240
  data: DataType;
241
  /** The feature's compatibility statement */
242
  compat: CompatStatement;
243
}
244

245
/**
246
 * Output from lowLevelWalk() containing comprehensive node information
247
 */
248
interface LowLevelWalkOutput {
249
  /** Dotted path to the data node */
250
  path: string;
251
  /** The data node itself */
252
  data: DataType;
253
  /** Browser statement if this is a browser node */
254
  browser?: BrowserStatement;
255
  /** Compatibility statement if this node has one */
256
  compat?: CompatStatement;
257
}
258

259
/**
260
 * Output from browserReleaseWalk() containing browser release details
261
 */
262
interface BrowserReleaseWalkOutput {
263
  /** Path to the browser release */
264
  path: string;
265
  /** The data object being walked */
266
  data: DataType;
267
  /** Browser statement containing the releases */
268
  browser: BrowserStatement;
269
  /** Release statement with metadata */
270
  browserRelease: ReleaseStatement;
271
}
272
```
273

274
### Utility Function Types
275

276
Type definitions for utility functions.
277

278
```typescript { .api }
279
/**
280
 * Query function type for getting data subtrees
281
 */
282
type QueryFunction = (path: string, data?: DataType) => DataType;
283

284
/**
285
 * Walk function type for iterating over features with compatibility data
286
 */
287
type WalkFunction = (
288
  entryPoints?: string | string[], 
289
  data?: CompatData | CompatStatement | Identifier
290
) => IterableIterator<WalkOutput>;
291

292
/**
293
 * Low-level walk function type for comprehensive data traversal
294
 */
295
type LowLevelWalkFunction = (
296
  data?: DataType, 
297
  path?: string, 
298
  depth?: number
299
) => IterableIterator<LowLevelWalkOutput>;
300

301
/**
302
 * Browser release walk function type
303
 */
304
type BrowserReleaseWalkFunction = (
305
  data: DataType, 
306
  path?: string
307
) => IterableIterator<BrowserReleaseWalkOutput>;
308

309
/**
310
 * Support iteration function type
311
 */
312
type IterSupportFunction = (
313
  compat: CompatStatement, 
314
  browser: BrowserName
315
) => SimpleSupportStatement[];
316

317
/**
318
 * Path normalization function type
319
 */
320
type NormalizePathFunction = (p: string) => string;
321

322
/**
323
 * Path joining function type
324
 */
325
type JoinPathFunction = (...args: (string | undefined)[]) => string;
326

327
/**
328
 * Feature detection function type
329
 */
330
type IsFeatureFunction = (obj: any) => obj is Identifier;
331

332
/**
333
 * Browser detection function type
334
 */
335
type IsBrowserFunction = (obj: any) => obj is BrowserStatement;
336

337
/**
338
 * Descendant keys function type
339
 */
340
type DescendantKeysFunction = (data: any) => string[];
341
```
342

343
### Process Utility Types
344

345
Types for process execution utilities.
346

347
```typescript { .api }
348
/**
349
 * Synchronous process spawn function type
350
 */
351
type SpawnFunction = (
352
  command: string, 
353
  args: readonly string[], 
354
  opts?: SpawnSyncOptionsWithStringEncoding
355
) => string;
356

357
/**
358
 * Asynchronous process spawn function type
359
 */
360
type SpawnAsyncFunction = (
361
  command: string, 
362
  args: readonly string[], 
363
  opts?: SpawnOptions
364
) => Promise<string>;
365
```
366

367
### Type Guards and Utilities
368

369
Helper types for working with the data structures.
370

371
```typescript { .api }
372
/**
373
 * Type predicate for checking if a value is a CompatData object
374
 */
375
function isCompatData(value: any): value is CompatData {
376
  return value && typeof value === 'object' && '__meta' in value;
377
}
378

379
/**
380
 * Type predicate for checking if a value is a BrowserStatement
381
 */
382
function isBrowserStatement(value: any): value is BrowserStatement {
383
  return value && typeof value === 'object' && 'name' in value && 'releases' in value;
384
}
385

386
/**
387
 * Type predicate for checking if a value is a CompatStatement
388
 */
389
function isCompatStatement(value: any): value is CompatStatement {
390
  return value && typeof value === 'object' && 'support' in value;
391
}
392

393
/**
394
 * Type predicate for checking if a value is an Identifier
395
 */
396
function isIdentifier(value: any): value is Identifier {
397
  return value && typeof value === 'object' && ('__compat' in value || 
398
    Object.keys(value).some(key => !key.startsWith('__')));
399
}
400
```
401

402
### Import Types
403

404
Type definitions for different import patterns.
405

406
```typescript { .api }
407
/**
408
 * Default export type (main data object)
409
 */
410
export default CompatData;
411

412
/**
413
 * Named export types for utilities
414
 */
415
export {
416
  query,
417
  walk,
418
  lowLevelWalk,
419
  browserReleaseWalk,
420
  iterSupport,
421
  normalizePath,
422
  joinPath,
423
  isFeature,
424
  isBrowser,
425
  descendantKeys,
426
  spawn,
427
  spawnAsync
428
};
429

430
/**
431
 * Type-only exports for TypeScript consumers
432
 */
433
export type {
434
  CompatData,
435
  Identifier,
436
  BrowserStatement,
437
  ReleaseStatement,
438
  CompatStatement,
439
  SupportStatement,
440
  SimpleSupportStatement,
441
  SupportBlock,
442
  StatusStatement,
443
  FlagStatement,
444
  BrowserName,
445
  BrowserType,
446
  VersionValue,
447
  DataType,
448
  WalkOutput,
449
  LowLevelWalkOutput,
450
  BrowserReleaseWalkOutput,
451
  InternalSupportStatement,
452
  InternalSupportBlock
453
};
454
```
455

456
## Usage Examples
457

458
### Type-Safe Data Access
459

460
```typescript
461
import type { CompatData, BrowserName, SimpleSupportStatement } from '@mdn/browser-compat-data/types';
462
import bcd, { iterSupport } from '@mdn/browser-compat-data';
463

464
// Type-safe browser support checking
465
function checkSupport(
466
  feature: string, 
467
  browser: BrowserName, 
468
  data: CompatData = bcd
469
): SimpleSupportStatement[] {
470
  const featureData = data.api[feature];
471
  if (featureData?.__compat) {
472
    return iterSupport(featureData.__compat, browser);
473
  }
474
  return [];
475
}
476

477
// Usage with full type safety
478
const fetchSupport = checkSupport('fetch', 'chrome');
479
console.log(fetchSupport[0].version_added); // TypeScript knows this is VersionValue
480
```
481

482
### Generic Type Usage
483

484
```typescript
485
import type { Identifier, CompatStatement } from '@mdn/browser-compat-data/types';
486

487
// Generic function for processing any feature category
488
function processCategory<T extends Record<string, Identifier>>(
489
  category: T,
490
  processor: (path: string, compat: CompatStatement) => void
491
): void {
492
  for (const [key, feature] of Object.entries(category)) {
493
    if (feature.__compat) {
494
      processor(key, feature.__compat);
495
    }
496
  }
497
}
498

499
// Type-safe usage
500
processCategory(bcd.css.properties, (path, compat) => {
501
  console.log(`CSS Property: ${path}`);
502
  console.log(`Experimental: ${compat.status?.experimental}`);
503
});
504
```
505

506
### Custom Type Extensions
507

508
```typescript
509
import type { CompatStatement, SimpleSupportStatement, BrowserName } from '@mdn/browser-compat-data/types';
510

511
// Extend types for custom analysis
512
interface ExtendedSupportInfo extends SimpleSupportStatement {
513
  browserName: BrowserName;
514
  isModern: boolean;
515
  category: string;
516
}
517

518
function createExtendedSupport(
519
  compat: CompatStatement,
520
  browser: BrowserName,
521
  category: string
522
): ExtendedSupportInfo[] {
523
  const support = iterSupport(compat, browser);
524
  
525
  return support.map(s => ({
526
    ...s,
527
    browserName: browser,
528
    isModern: typeof s.version_added === 'string' && 
529
              parseInt(s.version_added) >= 70,
530
    category
531
  }));
532
}
533
```