Type System

/**
 * Main browser compatibility data interface containing all technology categories
 */
interface CompatData {
  /** Package metadata */
  __meta: {
    version: string;
    timestamp: string;
  };
  /** Web API interfaces, methods, properties, and events */
  api: { [key: string]: Identifier };
  /** Browser information, releases, and engine data */
  browsers: { [key: string]: BrowserStatement };
  /** CSS properties, selectors, at-rules, and functions */
  css: { [key: string]: Identifier };
  /** HTML elements, attributes, and global attributes */
  html: { [key: string]: Identifier };
  /** HTTP headers, status codes, methods, and features */
  http: { [key: string]: Identifier };
  /** JavaScript language features and built-in objects */
  javascript: { [key: string]: Identifier };
  /** Web App Manifest properties and PWA features */
  manifests: { [key: string]: Identifier };
  /** MathML elements and attributes */
  mathml: { [key: string]: Identifier };
  /** SVG elements, attributes, and features */
  svg: { [key: string]: Identifier };
  /** WebAssembly instructions, types, and features */
  webassembly: { [key: string]: Identifier };
  /** WebDriver automation commands and capabilities */
  webdriver: { [key: string]: Identifier };
  /** Browser extension APIs across different browsers */
  webextensions: { [key: string]: Identifier };
}

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

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

/**
 * Describes a browser including its releases, engine information, and capabilities
 */
interface BrowserStatement {
  /** Human-readable browser name */
  name: string;
  /** Browser type classification */
  type?: BrowserType;
  /** All browser releases with version information */
  releases: { [version: string]: ReleaseStatement };
  /** Whether browser accepts feature flags for enabling experimental features */
  accepts_flags?: boolean;
  /** Whether browser accepts webextensions */
  accepts_webextensions?: boolean;
  /** Preview browser name for development/beta versions */
  preview_name?: string;
  /** Upstream browser this one is based on (e.g., Chromium for Edge) */
  upstream?: string;
}

/**
 * Browser type classification
 */
type BrowserType = "desktop" | "mobile" | "xr" | "server";

/**
 * Information about a specific browser release
 */
interface ReleaseStatement {
  /** Release date in YYYY-MM-DD format */
  release_date?: string;
  /** URL to release notes for this version */
  release_notes?: string;
  /** Current status of this release */
  status: "retired" | "current" | "exclusive" | "beta" | "nightly" | "esr" | "planned";
  /** Rendering engine name (e.g., "Blink", "Gecko", "WebKit") */
  engine: string;
  /** Engine version for this browser release */
  engine_version: string;
}

/**
 * Union type of all supported browser names
 */
type BrowserName = 
  | "chrome" 
  | "chrome_android" 
  | "edge" 
  | "firefox" 
  | "firefox_android" 
  | "safari" 
  | "safari_ios" 
  | "opera" 
  | "opera_android" 
  | "webview_android" 
  | "samsunginternet_android" 
  | "oculus" 
  | "webview_ios";

/**
 * Contains support data and metadata for a web platform feature
 */
interface CompatStatement {
  /** Human-readable description of the feature */
  description?: string;
  /** Specification URL(s) where this feature is defined */
  spec_url?: string | string[];
  /** Tags for categorization and web-features integration */
  tags?: string[];
  /** Browser support information */
  support: SupportBlock;
  /** Standardization and implementation status */
  status?: StatusStatement;
  /** Source file path in the repository where this data is defined */
  source_file?: string;
}

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

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

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

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

/**
 * Standardization and implementation status information
 */
interface StatusStatement {
  /** Whether the feature is experimental and may change */
  experimental?: boolean;
  /** Whether the feature is on the W3C/WHATWG standards track */
  standard_track?: boolean;
  /** Whether the feature is deprecated and should be avoided */
  deprecated?: boolean;
}

/**
 * Information about feature flags required to enable functionality
 */
interface FlagStatement {
  /** Type of flag or preference */
  type: "preference" | "compile_flag" | "runtime_flag";
  /** Name of the flag or preference to set */
  name: string;
  /** Value to set for the flag (if applicable) */
  value_to_set?: string;
}

/**
 * Extended support statement that includes mirroring for internal processing
 */
type InternalSupportStatement = SupportStatement | 'mirror';

/**
 * Support block that can contain mirror statements for internal processing
 */
type InternalSupportBlock = Partial<Record<BrowserName, InternalSupportStatement>>;

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

/**
 * 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;
}

/**
 * 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;
}

/**
 * Query function type for getting data subtrees
 */
type QueryFunction = (path: string, data?: DataType) => DataType;

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

/**
 * Low-level walk function type for comprehensive data traversal
 */
type LowLevelWalkFunction = (
  data?: DataType, 
  path?: string, 
  depth?: number
) => IterableIterator<LowLevelWalkOutput>;

/**
 * Browser release walk function type
 */
type BrowserReleaseWalkFunction = (
  data: DataType, 
  path?: string
) => IterableIterator<BrowserReleaseWalkOutput>;

/**
 * Support iteration function type
 */
type IterSupportFunction = (
  compat: CompatStatement, 
  browser: BrowserName
) => SimpleSupportStatement[];

/**
 * Path normalization function type
 */
type NormalizePathFunction = (p: string) => string;

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

/**
 * Feature detection function type
 */
type IsFeatureFunction = (obj: any) => obj is Identifier;

/**
 * Browser detection function type
 */
type IsBrowserFunction = (obj: any) => obj is BrowserStatement;

/**
 * Descendant keys function type
 */
type DescendantKeysFunction = (data: any) => string[];

/**
 * Synchronous process spawn function type
 */
type SpawnFunction = (
  command: string, 
  args: readonly string[], 
  opts?: SpawnSyncOptionsWithStringEncoding
) => string;

/**
 * Asynchronous process spawn function type
 */
type SpawnAsyncFunction = (
  command: string, 
  args: readonly string[], 
  opts?: SpawnOptions
) => Promise<string>;

/**
 * Type predicate for checking if a value is a CompatData object
 */
function isCompatData(value: any): value is CompatData {
  return value && typeof value === 'object' && '__meta' in value;
}

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

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

/**
 * Type predicate for checking if a value is an Identifier
 */
function isIdentifier(value: any): value is Identifier {
  return value && typeof value === 'object' && ('__compat' in value || 
    Object.keys(value).some(key => !key.startsWith('__')));
}

/**
 * Default export type (main data object)
 */
export default CompatData;

/**
 * Named export types for utilities
 */
export {
  query,
  walk,
  lowLevelWalk,
  browserReleaseWalk,
  iterSupport,
  normalizePath,
  joinPath,
  isFeature,
  isBrowser,
  descendantKeys,
  spawn,
  spawnAsync
};

/**
 * Type-only exports for TypeScript consumers
 */
export type {
  CompatData,
  Identifier,
  BrowserStatement,
  ReleaseStatement,
  CompatStatement,
  SupportStatement,
  SimpleSupportStatement,
  SupportBlock,
  StatusStatement,
  FlagStatement,
  BrowserName,
  BrowserType,
  VersionValue,
  DataType,
  WalkOutput,
  LowLevelWalkOutput,
  BrowserReleaseWalkOutput,
  InternalSupportStatement,
  InternalSupportBlock
};

import type { CompatData, BrowserName, SimpleSupportStatement } from '@mdn/browser-compat-data/types';
import bcd, { iterSupport } from '@mdn/browser-compat-data';

// Type-safe browser support checking
function checkSupport(
  feature: string, 
  browser: BrowserName, 
  data: CompatData = bcd
): SimpleSupportStatement[] {
  const featureData = data.api[feature];
  if (featureData?.__compat) {
    return iterSupport(featureData.__compat, browser);
  }
  return [];
}

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

import type { Identifier, CompatStatement } from '@mdn/browser-compat-data/types';

// Generic function for processing any feature category
function processCategory<T extends Record<string, Identifier>>(
  category: T,
  processor: (path: string, compat: CompatStatement) => void
): void {
  for (const [key, feature] of Object.entries(category)) {
    if (feature.__compat) {
      processor(key, feature.__compat);
    }
  }
}

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

import type { CompatStatement, SimpleSupportStatement, BrowserName } from '@mdn/browser-compat-data/types';

// Extend types for custom analysis
interface ExtendedSupportInfo extends SimpleSupportStatement {
  browserName: BrowserName;
  isModern: boolean;
  category: string;
}

function createExtendedSupport(
  compat: CompatStatement,
  browser: BrowserName,
  category: string
): ExtendedSupportInfo[] {
  const support = iterSupport(compat, browser);
  
  return support.map(s => ({
    ...s,
    browserName: browser,
    isModern: typeof s.version_added === 'string' && 
              parseInt(s.version_added) >= 70,
    category
  }));
}