Query and Navigation

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

/**
 * Union type representing any valid data node in the compatibility dataset
 */
type DataType = CompatData | BrowserStatement | CompatStatement | Identifier;

import bcd, { query } from '@mdn/browser-compat-data';

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

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

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

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

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

/**
 * Walk through compatibility data for features with compat statements
 * @param entryPoints - Starting path(s) to walk from (defaults to all data)
 * @param data - Data to walk through (defaults to main dataset)
 * @returns Iterator yielding path, data, and compat for each feature
 */
function walk(
  entryPoints?: string | string[], 
  data?: CompatData | CompatStatement | Identifier
): IterableIterator<WalkOutput>;

/**
 * Output from walk() iterator containing feature information
 */
interface WalkOutput {
  /** Dotted path to the feature */
  path: string;
  /** The feature's data object */
  data: DataType;
  /** The feature's compatibility statement */
  compat: CompatStatement;
}

import bcd, { walk } from '@mdn/browser-compat-data';

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

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

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

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

/**
 * Walk through all data including non-compat statements at specified depth
 * @param data - Data to walk through (defaults to main dataset)
 * @param path - Current path prefix
 * @param depth - Maximum depth to traverse (defaults to unlimited)
 * @returns Iterator yielding all data nodes at the specified depth
 */
function lowLevelWalk(
  data?: DataType, 
  path?: string, 
  depth?: number
): IterableIterator<LowLevelWalkOutput>;

/**
 * Output from lowLevelWalk() containing comprehensive node information
 */
interface LowLevelWalkOutput {
  /** Dotted path to the data node */
  path: string;
  /** The data node itself */
  data: DataType;
  /** Browser statement if this is a browser node */
  browser?: BrowserStatement;
  /** Compatibility statement if this node has one */
  compat?: CompatStatement;
}

import bcd, { lowLevelWalk } from '@mdn/browser-compat-data';

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

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

// Walk CSS properties at depth 2
for (const { path, data, compat } of lowLevelWalk(bcd.css, 'css', 2)) {
  if (compat) {
    console.log(`CSS Feature: ${path}`);
  }
}

/**
 * Walk through browser releases
 * @param data - Data containing browser information
 * @param path - Current path prefix
 * @returns Iterator yielding browser release information
 */
function browserReleaseWalk(
  data: DataType, 
  path?: string
): IterableIterator<BrowserReleaseWalkOutput>;

/**
 * Output from browserReleaseWalk() containing browser release details
 */
interface BrowserReleaseWalkOutput {
  /** Path to the browser release */
  path: string;
  /** The data object being walked */
  data: DataType;
  /** Browser statement containing the releases */
  browser: BrowserStatement;
  /** Release statement with metadata */
  browserRelease: ReleaseStatement;
}

import bcd, { browserReleaseWalk } from '@mdn/browser-compat-data';

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

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

/**
 * Join path components together with dots
 * @param args - Path components to join
 * @returns Joined dotted path string
 */
function joinPath(...args: (string | undefined)[]): string;

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

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

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

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

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

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

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

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

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

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

/**
 * Normalize a file path for cross-platform compatibility
 * @param p - Path string to normalize
 * @returns Normalized path string
 */
function normalizePath(p: string): string;

import { normalizePath } from '@mdn/browser-compat-data';

// Normalize Windows-style path
const winPath = 'api\\fetch\\json.json';
const normalized = normalizePath(winPath);
console.log(normalized); // "api/fetch/json.json"

// Direct property access
bcd.api.fetch.__compat.support.chrome.version_added
bcd.css.properties.display.__compat.status.experimental
bcd.html.elements.div.__compat.support.safari.version_added

// Query equivalent
query('api.fetch', bcd).__compat.support.chrome.version_added
query('css.properties.display', bcd).__compat.status.experimental
query('html.elements.div', bcd).__compat.support.safari.version_added

// Walk only experimental CSS features
const cssData = query('css', bcd);
for (const { path, compat } of walk(undefined, cssData)) {
  if (compat.status?.experimental) {
    console.log(`Experimental CSS: ${path}`);
  }
}

// Process features by category
const categories = ['api', 'css', 'html', 'javascript'];
for (const category of categories) {
  const categoryData = query(category, bcd);
  for (const { path, compat } of walk(undefined, categoryData)) {
    // Process features in this category
  }
}