Style Manipulation

/**
 * Calculate the differences between two styles
 * @param before - The original style specification
 * @param after - The target style specification
 * @returns Array of commands representing the differences
 */
function diff(before: StyleSpecification, after: StyleSpecification): Command[];

interface Command {
  command: string;
  args: unknown[];
}

import { diff } from "@mapbox/mapbox-gl-style-spec";

const beforeStyle = {
  version: 8,
  sources: {},
  layers: [{ id: "background", type: "background" }]
};

const afterStyle = {
  version: 8,
  sources: {},
  layers: [
    { id: "background", type: "background" },
    { id: "water", type: "fill", source: "water-source" }
  ]
};

const commands = diff(beforeStyle, afterStyle);
// Returns commands like [{ command: 'addLayer', args: [...] }]

/**
 * Composite multiple sources into a single source
 * @param style - Style specification with multiple sources to composite
 * @returns Style with composited sources
 */
function composite(style: StyleSpecification): StyleSpecification;

import { composite } from "@mapbox/mapbox-gl-style-spec";

const style = {
  version: 8,
  sources: {
    "source1": { type: "vector", url: "mapbox://mapbox.mapbox-streets-v8" },
    "source2": { type: "vector", url: "mapbox://mapbox.mapbox-terrain-v2" }
  },
  layers: []
};

const compositedStyle = composite(style);
// Combines sources into a single composite source

/**
 * Dereference layers that use the ref property
 * @param layers - Array of layer specifications, some potentially with ref properties
 * @returns Array of layers with ref properties resolved
 */
function derefLayers(layers: LayerSpecification[]): LayerSpecification[];

import { derefLayers } from "@mapbox/mapbox-gl-style-spec";

const layersWithRefs = [
  { id: "base", type: "fill", source: "data" },
  { id: "variant", ref: "base", paint: { "fill-color": "red" } }
];

const dereferencedLayers = derefLayers(layersWithRefs);
// Returns layers with ref properties resolved to explicit properties

interface VisitAPI {
  /**
   * Iterate over all sources in a style
   * @param style - Style specification
   * @param callback - Function called for each source
   */
  eachSource(style: StyleSpecification, callback: (source: SourceSpecification) => void): void;
  
  /**
   * Iterate over all layers in a style
   * @param style - Style specification  
   * @param callback - Function called for each layer
   */
  eachLayer(style: StyleSpecification, callback: (layer: LayerSpecification) => void): void;
  
  /**
   * Iterate over all paint and layout properties in a style
   * @param style - Style specification
   * @param options - Configure which property types to visit
   * @param callback - Function called for each property
   */
  eachProperty(
    style: StyleSpecification,
    options: { paint?: boolean; layout?: boolean },
    callback: PropertyCallback
  ): void;
}

const visit: VisitAPI;

type PropertyCallback = (arg: {
  path: [string, 'paint' | 'layout', string]; // [layerId, propertyType, propertyKey]
  key: string;
  value: PropertyValueSpecification<unknown>;
  reference: StylePropertySpecification;
  set: (value: PropertyValueSpecification<unknown>) => void;
}) => void;

import { visit } from "@mapbox/mapbox-gl-style-spec";

// Iterate over all sources
visit.eachSource(style, (source) => {
  if (source.type === 'vector') {
    console.log('Found vector source:', source.url);
  }
});

// Iterate over all layers
visit.eachLayer(style, (layer) => {
  console.log('Layer:', layer.id, layer.type);
});

// Iterate over paint properties
visit.eachProperty(style, { paint: true }, ({ path, key, value, set }) => {
  if (key === 'fill-color' && value === 'red') {
    set('blue'); // Change red fills to blue
  }
});

interface StyleFunctionAPI {
  /**
   * Create a function from legacy function specification
   * @param parameters - Function parameters
   * @param propertySpec - Property specification
   * @returns Compiled function
   */
  createFunction(parameters: any, propertySpec: StylePropertySpecification): any;
  
  /**
   * Check if a value is a legacy function
   * @param value - Value to check
   * @returns True if value is a legacy function
   */
  isFunction(value: any): boolean;
  
  /**
   * Convert legacy function to expression format
   * @param parameters - Function parameters
   * @param propertySpec - Property specification  
   * @returns Converted expression
   */
  convertFunction(parameters: any, propertySpec: StylePropertySpecification): any;
}

const function: StyleFunctionAPI;

/**
 * Convert legacy filter format to current filter specification
 * @param filter - Legacy filter
 * @returns Converted filter specification
 */
function convertFilter(filter: any): FilterSpecification;

/**
 * Validate that a style only uses Mapbox API features that are supported
 * @param style - Style specification to validate
 * @param sourceAccessToken - Optional access token for source validation
 * @returns Array of validation errors for unsupported features
 */
function validateMapboxApiSupported(
  style: StyleSpecification,
  sourceAccessToken?: string
): ValidationError[];

interface Command {
  command: 'setStyle' | 'addLayer' | 'removeLayer' | 'setPaintProperty' | 'setLayoutProperty' | 'addSource' | 'removeSource' | 'setGeoJSONSourceData' | 'setLayerZoomRange' | 'setCenter' | 'setZoom' | 'setBearing' | 'setPitch';
  args: unknown[];
}

type PropertyValueSpecification<T> = T | StyleExpression | any;