0
# Style Operations
1

2
Tools for manipulating, formatting, and transforming Mapbox GL styles including migration, formatting, diffing, and composition operations.
3

4
## Capabilities
5

6
### Style Formatting
7

8
Formats style JSON with proper key ordering and indentation for readability and consistency.
9

10
```typescript { .api }
11
/**
12
 * Formats a style object with proper key ordering and indentation
13
 * @param style - Style object to format
14
 * @param space - Number of spaces for indentation (default: 2, use 0 for minified)
15
 * @returns Formatted JSON string
16
 */
17
function format(style: StyleSpecification, space?: number): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { format } from "@mapbox/mapbox-gl-style-spec";
24

25
const style = {
26
  version: 8,
27
  layers: [{ id: "bg", type: "background" }],
28
  sources: {}
29
};
30

31
// Pretty formatted with 2 spaces
32
const formatted = format(style, 2);
33

34
// Minified (single line)
35
const minified = format(style, 0);
36
```
37

38
### Style Migration
39

40
Migrates older style specifications to the latest version, updating deprecated syntax and properties.
41

42
```typescript { .api }
43
/**
44
 * Migrates a style from older versions to the current specification
45
 * Handles v7 to v8 migration and legacy function to expression conversion
46
 * @param style - Style object to migrate (any version)
47
 * @returns Migrated style conforming to current specification
48
 */
49
function migrate(style: any): StyleSpecification;
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { migrate } from "@mapbox/mapbox-gl-style-spec";
56

57
// Migrate a v7 style to v8
58
const v7Style = {
59
  version: 7,
60
  sources: { /* ... */ },
61
  layers: [
62
    {
63
      id: "roads",
64
      type: "line",
65
      paint: {
66
        "line-color": {
67
          "property": "class",
68
          "type": "categorical",
69
          "stops": [["primary", "red"], ["secondary", "blue"]]
70
        }
71
      }
72
    }
73
  ]
74
};
75

76
const v8Style = migrate(v7Style);
77
// Result has expressions instead of functions
78
```
79

80
### Style Diffing
81

82
Creates semantic diffs between two styles, generating command arrays for applying incremental changes.
83

84
```typescript { .api }
85
/**
86
 * Creates a semantic diff between two styles
87
 * @param before - Original style
88
 * @param after - Modified style
89
 * @returns Array of diff commands for applying changes
90
 */
91
function diff(before: StyleSpecification, after: StyleSpecification): DiffCommand[];
92

93
type DiffCommand = 
94
  | SetStyleCommand
95
  | AddLayerCommand
96
  | RemoveLayerCommand
97
  | SetPaintPropertyCommand
98
  | SetLayoutPropertyCommand
99
  | SetFilterCommand
100
  | AddSourceCommand
101
  | RemoveSourceCommand
102
  | SetGeoJSONSourceDataCommand
103
  | SetLayerZoomRangeCommand
104
  | SetLightCommand
105
  | SetTerrainCommand
106
  | SetFogCommand;
107

108
interface SetStyleCommand {
109
  command: 'setStyle';
110
  args: [StyleSpecification];
111
}
112

113
interface AddLayerCommand {
114
  command: 'addLayer';
115
  args: [LayerSpecification, string?];
116
}
117

118
interface RemoveLayerCommand {
119
  command: 'removeLayer';
120
  args: [string];
121
}
122

123
interface SetPaintPropertyCommand {
124
  command: 'setPaintProperty';
125
  args: [string, string, any];
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { diff } from "@mapbox/mapbox-gl-style-spec";
133

134
const oldStyle = {
135
  version: 8,
136
  sources: {},
137
  layers: [
138
    { id: "bg", type: "background", paint: { "background-color": "white" } }
139
  ]
140
};
141

142
const newStyle = {
143
  version: 8,
144
  sources: {},
145
  layers: [
146
    { id: "bg", type: "background", paint: { "background-color": "black" } }
147
  ]
148
};
149

150
const commands = diff(oldStyle, newStyle);
151
// Result: [{ command: 'setPaintProperty', args: ['bg', 'background-color', 'black'] }]
152

153
// Apply commands to a map
154
commands.forEach(command => {
155
  if (command.command === 'setPaintProperty') {
156
    map.setPaintProperty(...command.args);
157
  }
158
  // Handle other command types...
159
});
160
```
161

162
### Layer Dereferencing
163

164
Resolves layer `ref` properties by copying properties from referenced layers.
165

166
```typescript { .api }
167
/**
168
 * Dereferences layers by resolving `ref` properties
169
 * @param layers - Array of layer specifications that may contain ref properties
170
 * @returns Array of layers with ref properties resolved
171
 */
172
function derefLayers(layers: LayerSpecification[]): LayerSpecification[];
173
```
174

175
### Source Composition
176

177
Combines multiple Mapbox vector sources into a single composite source.
178

179
```typescript { .api }
180
/**
181
 * Composites multiple vector sources into a single source
182
 * @param style - Style containing sources to composite
183
 * @returns Style with composited sources
184
 */
185
function composite(style: StyleSpecification): StyleSpecification;
186
```
187

188
### Style Visiting
189

190
Utilities for iterating over style components with callback functions.
191

192
```typescript { .api }
193
/**
194
 * Iterates over all sources in a style
195
 * @param style - Style to iterate over
196
 * @param callback - Function called for each source
197
 */
198
function eachSource(
199
  style: StyleSpecification, 
200
  callback: (source: SourceSpecification) => void
201
): void;
202

203
/**
204
 * Iterates over all layers in a style
205
 * @param style - Style to iterate over
206
 * @param callback - Function called for each layer
207
 */
208
function eachLayer(
209
  style: StyleSpecification, 
210
  callback: (layer: LayerSpecification) => void
211
): void;
212

213
/**
214
 * Iterates over layer properties with filtering options
215
 * @param style - Style to iterate over
216
 * @param options - Options for property iteration
217
 * @param callback - Function called for each property
218
 */
219
function eachProperty(
220
  style: StyleSpecification,
221
  options: {
222
    paint?: boolean;
223
    layout?: boolean;
224
  },
225
  callback: (property: {
226
    path: string[];
227
    key: string;
228
    value: any;
229
    reference: any;
230
    set: (value: any) => void;
231
  }) => void
232
): void;
233
```
234

235
**Usage Examples:**
236

237
```typescript
238
import { eachSource, eachLayer, eachProperty } from "@mapbox/mapbox-gl-style-spec";
239

240
// Iterate over sources
241
eachSource(style, (source) => {
242
  console.log(`Source:`, source.type);
243
});
244

245
// Iterate over layers
246
eachLayer(style, (layer) => {
247
  console.log(`Layer ${layer.id}:`, layer.type);
248
});
249

250
// Iterate over paint properties
251
eachProperty(style, { paint: true }, (property) => {
252
  console.log(`Property ${property.key}:`, property.value);
253
});
254
```
255

256
## Types
257

258
```typescript { .api }
259
interface VisitOptions {
260
  paint?: boolean;
261
  layout?: boolean;
262
}
263

264
interface PropertyInfo {
265
  path: string[];
266
  key: string;
267
  value: any;
268
  reference: any;
269
  set: (value: any) => void;
270
}
271
```