0
# Query and Navigation
1

2
The Browser Compat Data package provides powerful utilities for querying and navigating the compatibility dataset using dotted path notation and iterator-based walking algorithms.
3

4
## Capabilities
5

6
### Query Function
7

8
Query specific parts of the compatibility data using dotted path notation.
9

10
```typescript { .api }
11
/**
12
 * Get a subtree of compatibility data using dotted path notation
13
 * @param path - Dotted path string (e.g., "css.properties.display")
14
 * @param data - Data object to query (defaults to main dataset)
15
 * @returns The matching data subtree
16
 * @throws {ReferenceError} For invalid identifiers that don't exist in the data
17
 */
18
function query(path: string, data?: DataType): DataType;
19

20
/**
21
 * Union type representing any valid data node in the compatibility dataset
22
 */
23
type DataType = CompatData | BrowserStatement | CompatStatement | Identifier;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import bcd, { query } from '@mdn/browser-compat-data';
30

31
// Query CSS flexbox display values
32
const flexbox = query('css.properties.display', bcd);
33
console.log(flexbox.__compat.support.chrome.version_added); // "29"
34

35
// Query Web API interface
36
const fetchAPI = query('api.fetch', bcd);
37
console.log(fetchAPI.__compat.description); // "Fetch API description"
38

39
// Query specific browser
40
const chrome = query('browsers.chrome', bcd);
41
console.log(chrome.name); // "Chrome"
42

43
// Query nested API method
44
const fetchJson = query('api.fetch.json', bcd);
45
console.log(fetchJson.__compat.support.firefox.version_added); // "39"
46

47
// Query throws ReferenceError for non-existent paths
48
try {
49
  const nonExistent = query('does.not.exist', bcd);
50
} catch (error) {
51
  console.log(error.message); // "does.not.exist is not a valid tree identifier (failed at 'does')"
52
}
53
```
54

55
### Walk Function
56

57
Walk through compatibility data to iterate over features with compatibility statements.
58

59
```typescript { .api }
60
/**
61
 * Walk through compatibility data for features with compat statements
62
 * @param entryPoints - Starting path(s) to walk from (defaults to all data)
63
 * @param data - Data to walk through (defaults to main dataset)
64
 * @returns Iterator yielding path, data, and compat for each feature
65
 */
66
function walk(
67
  entryPoints?: string | string[], 
68
  data?: CompatData | CompatStatement | Identifier
69
): IterableIterator<WalkOutput>;
70

71
/**
72
 * Output from walk() iterator containing feature information
73
 */
74
interface WalkOutput {
75
  /** Dotted path to the feature */
76
  path: string;
77
  /** The feature's data object */
78
  data: DataType;
79
  /** The feature's compatibility statement */
80
  compat: CompatStatement;
81
}
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import bcd, { walk } from '@mdn/browser-compat-data';
88

89
// Walk all features to find deprecated ones
90
for (const { path, compat } of walk(undefined, bcd)) {
91
  if (compat.status?.deprecated) {
92
    console.log(`Deprecated: ${path}`);
93
  }
94
}
95

96
// Walk only CSS properties
97
for (const { path, compat } of walk('css.properties', bcd)) {
98
  if (compat.support.chrome?.version_added === false) {
99
    console.log(`Not supported in Chrome: ${path}`);
100
  }
101
}
102

103
// Walk multiple entry points
104
for (const { path, compat } of walk(['api.fetch', 'css.properties.display'], bcd)) {
105
  console.log(`Feature: ${path}`);
106
  console.log(`Chrome support: ${compat.support.chrome?.version_added}`);
107
}
108

109
// Walk API interfaces only
110
for (const { path, data, compat } of walk('api', bcd)) {
111
  if (compat.status?.experimental) {
112
    console.log(`Experimental API: ${path}`);
113
  }
114
}
115
```
116

117
### Low-Level Walk Function
118

119
Walk through all data including non-compatibility statements at a specified depth.
120

121
```typescript { .api }
122
/**
123
 * Walk through all data including non-compat statements at specified depth
124
 * @param data - Data to walk through (defaults to main dataset)
125
 * @param path - Current path prefix
126
 * @param depth - Maximum depth to traverse (defaults to unlimited)
127
 * @returns Iterator yielding all data nodes at the specified depth
128
 */
129
function lowLevelWalk(
130
  data?: DataType, 
131
  path?: string, 
132
  depth?: number
133
): IterableIterator<LowLevelWalkOutput>;
134

135
/**
136
 * Output from lowLevelWalk() containing comprehensive node information
137
 */
138
interface LowLevelWalkOutput {
139
  /** Dotted path to the data node */
140
  path: string;
141
  /** The data node itself */
142
  data: DataType;
143
  /** Browser statement if this is a browser node */
144
  browser?: BrowserStatement;
145
  /** Compatibility statement if this node has one */
146
  compat?: CompatStatement;
147
}
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import bcd, { lowLevelWalk } from '@mdn/browser-compat-data';
154

155
// Walk all top-level categories
156
for (const { path, data } of lowLevelWalk(bcd, '', 1)) {
157
  console.log(`Category: ${path}`);
158
}
159

160
// Walk browser data specifically
161
for (const { path, browser } of lowLevelWalk(bcd.browsers)) {
162
  if (browser) {
163
    console.log(`Browser: ${path} - ${browser.name}`);
164
  }
165
}
166

167
// Walk CSS properties at depth 2
168
for (const { path, data, compat } of lowLevelWalk(bcd.css, 'css', 2)) {
169
  if (compat) {
170
    console.log(`CSS Feature: ${path}`);
171
  }
172
}
173
```
174

175
### Browser Release Walk Function
176

177
Walk through browser releases to get release information.
178

179
```typescript { .api }
180
/**
181
 * Walk through browser releases
182
 * @param data - Data containing browser information
183
 * @param path - Current path prefix
184
 * @returns Iterator yielding browser release information
185
 */
186
function browserReleaseWalk(
187
  data: DataType, 
188
  path?: string
189
): IterableIterator<BrowserReleaseWalkOutput>;
190

191
/**
192
 * Output from browserReleaseWalk() containing browser release details
193
 */
194
interface BrowserReleaseWalkOutput {
195
  /** Path to the browser release */
196
  path: string;
197
  /** The data object being walked */
198
  data: DataType;
199
  /** Browser statement containing the releases */
200
  browser: BrowserStatement;
201
  /** Release statement with metadata */
202
  browserRelease: ReleaseStatement;
203
}
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import bcd, { browserReleaseWalk } from '@mdn/browser-compat-data';
210

211
// Walk all browser releases
212
for (const { path, browser, browserRelease } of browserReleaseWalk(bcd)) {
213
  if (browserRelease.status === 'current') {
214
    const version = path.split('.').pop(); // Extract version from path
215
    console.log(`Current ${browser.name} version: ${version}`);
216
  }
217
}
218

219
// Walk Chrome releases specifically
220
for (const { path, browserRelease } of browserReleaseWalk(bcd.browsers.chrome)) {
221
  if (browserRelease.release_date && browserRelease.release_date > '2023-01-01') {
222
    const version = path.split('.').pop(); // Extract version from path
223
    console.log(`Chrome ${version} released: ${browserRelease.release_date}`);
224
  }
225
}
226
```
227

228
### Walking Utility Functions
229

230
Helper functions for working with the walking algorithms.
231

232
```typescript { .api }
233
/**
234
 * Join path components together with dots
235
 * @param args - Path components to join
236
 * @returns Joined dotted path string
237
 */
238
function joinPath(...args: (string | undefined)[]): string;
239

240
/**
241
 * Check if an object is a BCD feature (has __compat property)
242
 * @param obj - Object to check
243
 * @returns True if the object is an Identifier with compatibility data
244
 */
245
function isFeature(obj: any): obj is Identifier;
246

247
/**
248
 * Check if an object is a browser statement
249
 * @param obj - Object to check
250
 * @returns True if the object is a BrowserStatement
251
 */
252
function isBrowser(obj: any): obj is BrowserStatement;
253

254
/**
255
 * Get descendant keys of an object, excluding keys starting with two underscores
256
 * @param data - Object to get keys from
257
 * @returns Array of descendant key names
258
 */
259
function descendantKeys(data: any): string[];
260
```
261

262
**Usage Examples:**
263

264
```typescript
265
// Note: These utility functions are used internally by walk() and other functions
266
// They are not directly exported from the main package
267
import { walk, query } from '@mdn/browser-compat-data';
268

269
// These utility functions are used internally by the walking algorithms
270
// They are demonstrated here for understanding the internal architecture
271

272
// Join path components (used internally by walk functions)
273
// Example: combining path segments like "api" + "fetch" + "json" = "api.fetch.json"
274

275
// Check if an object is a feature (used internally by walking algorithms)
276
// Used to determine if a data node contains compatibility information
277

278
// Check if an object is a browser (used internally by browserReleaseWalk)
279
// Used to identify browser data nodes during traversal
280

281
// Get descendant keys (used internally by lowLevelWalk)
282
// Filters out internal properties like __compat, __meta when walking data structures
283

284
// To access these behaviors, use the public walking functions:
285
for (const { path, data, compat } of walk('api.fetch', bcd)) {
286
  console.log(`Found feature: ${path}`);
287
  console.log(`Has compatibility data: ${!!compat}`);
288
}
289
```
290

291
### Path Normalization
292

293
Utility for normalizing file paths in cross-platform environments.
294

295
```typescript { .api }
296
/**
297
 * Normalize a file path for cross-platform compatibility
298
 * @param p - Path string to normalize
299
 * @returns Normalized path string
300
 */
301
function normalizePath(p: string): string;
302
```
303

304
**Usage Example:**
305

306
```typescript
307
import { normalizePath } from '@mdn/browser-compat-data';
308

309
// Normalize Windows-style path
310
const winPath = 'api\\fetch\\json.json';
311
const normalized = normalizePath(winPath);
312
console.log(normalized); // "api/fetch/json.json"
313
```
314

315
## Navigation Patterns
316

317
### Hierarchical Access
318

319
The data structure follows consistent hierarchical patterns:
320

321
```typescript
322
// Direct property access
323
bcd.api.fetch.__compat.support.chrome.version_added
324
bcd.css.properties.display.__compat.status.experimental
325
bcd.html.elements.div.__compat.support.safari.version_added
326

327
// Query equivalent
328
query('api.fetch', bcd).__compat.support.chrome.version_added
329
query('css.properties.display', bcd).__compat.status.experimental
330
query('html.elements.div', bcd).__compat.support.safari.version_added
331
```
332

333
### Iterative Processing
334

335
Combining query and walk functions for targeted iteration:
336

337
```typescript
338
// Walk only experimental CSS features
339
const cssData = query('css', bcd);
340
for (const { path, compat } of walk(undefined, cssData)) {
341
  if (compat.status?.experimental) {
342
    console.log(`Experimental CSS: ${path}`);
343
  }
344
}
345

346
// Process features by category
347
const categories = ['api', 'css', 'html', 'javascript'];
348
for (const category of categories) {
349
  const categoryData = query(category, bcd);
350
  for (const { path, compat } of walk(undefined, categoryData)) {
351
    // Process features in this category
352
  }
353
}
354
```