0
# Style Manipulation
1

2
Advanced utilities for style diffing, composition, layer dereferencing, and traversal operations. These functions provide low-level access to style transformation and analysis capabilities.
3

4
## Capabilities
5

6
### Style Diffing
7

8
Calculates the differences between two style specifications and returns a list of commands that can be used to transform one style into another.
9

10
```typescript { .api }
11
/**
12
 * Calculate the differences between two styles
13
 * @param before - The original style specification
14
 * @param after - The target style specification
15
 * @returns Array of commands representing the differences
16
 */
17
function diff(before: StyleSpecification, after: StyleSpecification): Command[];
18

19
interface Command {
20
  command: string;
21
  args: unknown[];
22
}
23
```
24

25
**Usage Example:**
26

27
```typescript
28
import { diff } from "@mapbox/mapbox-gl-style-spec";
29

30
const beforeStyle = {
31
  version: 8,
32
  sources: {},
33
  layers: [{ id: "background", type: "background" }]
34
};
35

36
const afterStyle = {
37
  version: 8,
38
  sources: {},
39
  layers: [
40
    { id: "background", type: "background" },
41
    { id: "water", type: "fill", source: "water-source" }
42
  ]
43
};
44

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

49
### Style Composition
50

51
Composites multiple vector tile sources that reference Mapbox-hosted datasets into a single composite source.
52

53
```typescript { .api }
54
/**
55
 * Composite multiple sources into a single source
56
 * @param style - Style specification with multiple sources to composite
57
 * @returns Style with composited sources
58
 */
59
function composite(style: StyleSpecification): StyleSpecification;
60
```
61

62
**Usage Example:**
63

64
```typescript
65
import { composite } from "@mapbox/mapbox-gl-style-spec";
66

67
const style = {
68
  version: 8,
69
  sources: {
70
    "source1": { type: "vector", url: "mapbox://mapbox.mapbox-streets-v8" },
71
    "source2": { type: "vector", url: "mapbox://mapbox.mapbox-terrain-v2" }
72
  },
73
  layers: []
74
};
75

76
const compositedStyle = composite(style);
77
// Combines sources into a single composite source
78
```
79

80
### Layer Dereferencing
81

82
Resolves layer references in styles that use the deprecated `ref` property, returning layers with all properties explicitly defined.
83

84
```typescript { .api }
85
/**
86
 * Dereference layers that use the ref property
87
 * @param layers - Array of layer specifications, some potentially with ref properties
88
 * @returns Array of layers with ref properties resolved
89
 */
90
function derefLayers(layers: LayerSpecification[]): LayerSpecification[];
91
```
92

93
**Usage Example:**
94

95
```typescript
96
import { derefLayers } from "@mapbox/mapbox-gl-style-spec";
97

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

103
const dereferencedLayers = derefLayers(layersWithRefs);
104
// Returns layers with ref properties resolved to explicit properties
105
```
106

107
### Style Traversal
108

109
Utilities for traversing and manipulating style components programmatically.
110

111
```typescript { .api }
112
interface VisitAPI {
113
  /**
114
   * Iterate over all sources in a style
115
   * @param style - Style specification
116
   * @param callback - Function called for each source
117
   */
118
  eachSource(style: StyleSpecification, callback: (source: SourceSpecification) => void): void;
119
  
120
  /**
121
   * Iterate over all layers in a style
122
   * @param style - Style specification  
123
   * @param callback - Function called for each layer
124
   */
125
  eachLayer(style: StyleSpecification, callback: (layer: LayerSpecification) => void): void;
126
  
127
  /**
128
   * Iterate over all paint and layout properties in a style
129
   * @param style - Style specification
130
   * @param options - Configure which property types to visit
131
   * @param callback - Function called for each property
132
   */
133
  eachProperty(
134
    style: StyleSpecification,
135
    options: { paint?: boolean; layout?: boolean },
136
    callback: PropertyCallback
137
  ): void;
138
}
139

140
const visit: VisitAPI;
141

142
type PropertyCallback = (arg: {
143
  path: [string, 'paint' | 'layout', string]; // [layerId, propertyType, propertyKey]
144
  key: string;
145
  value: PropertyValueSpecification<unknown>;
146
  reference: StylePropertySpecification;
147
  set: (value: PropertyValueSpecification<unknown>) => void;
148
}) => void;
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { visit } from "@mapbox/mapbox-gl-style-spec";
155

156
// Iterate over all sources
157
visit.eachSource(style, (source) => {
158
  if (source.type === 'vector') {
159
    console.log('Found vector source:', source.url);
160
  }
161
});
162

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

168
// Iterate over paint properties
169
visit.eachProperty(style, { paint: true }, ({ path, key, value, set }) => {
170
  if (key === 'fill-color' && value === 'red') {
171
    set('blue'); // Change red fills to blue
172
  }
173
});
174
```
175

176
### Legacy Function Support
177

178
Support for working with pre-expression function specifications and legacy filter formats.
179

180
```typescript { .api }
181
interface StyleFunctionAPI {
182
  /**
183
   * Create a function from legacy function specification
184
   * @param parameters - Function parameters
185
   * @param propertySpec - Property specification
186
   * @returns Compiled function
187
   */
188
  createFunction(parameters: any, propertySpec: StylePropertySpecification): any;
189
  
190
  /**
191
   * Check if a value is a legacy function
192
   * @param value - Value to check
193
   * @returns True if value is a legacy function
194
   */
195
  isFunction(value: any): boolean;
196
  
197
  /**
198
   * Convert legacy function to expression format
199
   * @param parameters - Function parameters
200
   * @param propertySpec - Property specification  
201
   * @returns Converted expression
202
   */
203
  convertFunction(parameters: any, propertySpec: StylePropertySpecification): any;
204
}
205

206
const function: StyleFunctionAPI;
207

208
/**
209
 * Convert legacy filter format to current filter specification
210
 * @param filter - Legacy filter
211
 * @returns Converted filter specification
212
 */
213
function convertFilter(filter: any): FilterSpecification;
214

215
/**
216
 * Validate that a style only uses Mapbox API features that are supported
217
 * @param style - Style specification to validate
218
 * @param sourceAccessToken - Optional access token for source validation
219
 * @returns Array of validation errors for unsupported features
220
 */
221
function validateMapboxApiSupported(
222
  style: StyleSpecification,
223
  sourceAccessToken?: string
224
): ValidationError[];
225
```
226

227
## Types
228

229
Core types used by style manipulation functions:
230

231
```typescript { .api }
232
interface Command {
233
  command: 'setStyle' | 'addLayer' | 'removeLayer' | 'setPaintProperty' | 'setLayoutProperty' | 'addSource' | 'removeSource' | 'setGeoJSONSourceData' | 'setLayerZoomRange' | 'setCenter' | 'setZoom' | 'setBearing' | 'setPitch';
234
  args: unknown[];
235
}
236

237
type PropertyValueSpecification<T> = T | StyleExpression | any;
238
```