0
# Expression System
1

2
Powerful expression evaluation engine for data-driven styling with support for zoom-dependent and feature-dependent expressions. Enables dynamic styling based on data properties, zoom level, and geometric features.
3

4
## Capabilities
5

6
### Expression Creation
7

8
Creates and compiles expressions from specification objects into evaluatable StyleExpression instances.
9

10
```typescript { .api }
11
/**
12
 * Creates a StyleExpression from an expression specification
13
 * @param expression - Expression specification array or literal value
14
 * @param propertySpec - Optional property specification for context
15
 * @returns Compilation result with expression or errors
16
 */
17
function createExpression(
18
  expression: ExpressionSpecification, 
19
  propertySpec?: StylePropertySpecification
20
): {
21
  result: 'success' | 'error';
22
  value?: StyleExpression;
23
  errors?: ParsingError[];
24
};
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { createExpression } from "@mapbox/mapbox-gl-style-spec";
31

32
// Simple property access
33
const result1 = createExpression(['get', 'population'], {
34
  type: 'number',
35
  'property-type': 'data-driven'
36
});
37

38
if (result1.result === 'success') {
39
  const value = result1.value.evaluate({ zoom: 10 }, { 
40
    properties: { population: 50000 } 
41
  });
42
  console.log(value); // 50000
43
}
44

45
// Conditional expression
46
const result2 = createExpression([
47
  'case',
48
  ['>', ['get', 'population'], 100000], 'red',
49
  ['>', ['get', 'population'], 50000], 'orange',
50
  'yellow'
51
]);
52

53
// Interpolation expression
54
const result3 = createExpression([
55
  'interpolate',
56
  ['linear'],
57
  ['zoom'],
58
  10, 2,
59
  20, 10
60
]);
61
```
62

63
### Property Expression Creation
64

65
Creates property-specific expressions with additional validation and type checking.
66

67
```typescript { .api }
68
/**
69
 * Creates a property-specific StyleExpression with enhanced validation
70
 * @param expression - Expression specification or literal value
71
 * @param propertySpec - Property specification defining constraints
72
 * @returns Compilation result with property expression
73
 */
74
function createPropertyExpression(
75
  expression: PropertyValueSpecification<any>, 
76
  propertySpec: StylePropertySpecification
77
): {
78
  result: 'success' | 'error';
79
  value?: StylePropertyExpression;
80
  errors?: ParsingError[];
81
};
82
```
83

84
### Expression Normalization
85

86
Normalizes property values to consistent expression format.
87

88
```typescript { .api }
89
/**
90
 * Normalizes a property value to expression format
91
 * @param expression - Raw property value or expression
92
 * @param propertySpec - Property specification for context
93
 * @returns Normalized expression specification
94
 */
95
function normalizePropertyExpression(
96
  expression: PropertyValueSpecification<any>, 
97
  propertySpec: StylePropertySpecification
98
): ExpressionSpecification;
99
```
100

101
### Expression Type Checking
102

103
Utilities for identifying and working with different expression types.
104

105
```typescript { .api }
106
/**
107
 * Tests whether a value is an expression array
108
 * @param value - Value to test
109
 * @returns True if value uses expression syntax
110
 */
111
function isExpression(value: any): boolean;
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { isExpression, normalizePropertyExpression } from "@mapbox/mapbox-gl-style-spec";
118

119
// Check if value is an expression
120
const expr1 = ['get', 'name'];
121
const expr2 = 'static-value';
122

123
console.log(isExpression(expr1)); // true
124
console.log(isExpression(expr2)); // false
125

126
// Normalize property values
127
const normalized = normalizePropertyExpression(
128
  { stops: [[0, 'red'], [10, 'blue']] },
129
  { type: 'color', 'property-type': 'data-driven' }
130
);
131
```
132

133
## Expression Classes
134

135
### StyleExpression
136

137
Main expression evaluation class that handles all expression types with error handling.
138

139
```typescript { .api }
140
abstract class StyleExpression {
141
  /**
142
   * Evaluates the expression with error handling
143
   * @param globals - Evaluation context (zoom, etc.)
144
   * @param feature - Optional feature for feature-dependent expressions
145
   * @param featureState - Optional feature state for dynamic styling
146
   * @param canonical - Optional canonical tile ID for geo-dependent expressions
147
   * @param availableImages - Optional array of available image IDs
148
   * @param formattedSection - Optional formatted text section
149
   * @param featureTileCoord - Optional feature tile coordinates
150
   * @param featureDistanceData - Optional distance calculation data
151
   * @returns Evaluation result or error
152
   */
153
  evaluate(
154
    globals: EvaluationContext, 
155
    feature?: any,
156
    featureState?: any,
157
    canonical?: any,
158
    availableImages?: string[],
159
    formattedSection?: any,
160
    featureTileCoord?: any,
161
    featureDistanceData?: any
162
  ): any;
163

164
  /**
165
   * Evaluates the expression without automatic error handling
166
   * @param globals - Evaluation context
167
   * @param feature - Optional feature for evaluation
168
   * @returns Raw evaluation result
169
   */
170
  evaluateWithoutErrorHandling(globals: EvaluationContext, feature?: any): any;
171
}
172
```
173

174
### Expression Type Classes
175

176
Specialized expression classes for different evaluation patterns.
177

178
```typescript { .api }
179
/**
180
 * Expressions that return constant values regardless of zoom or feature
181
 */
182
class ZoomConstantExpression<Kind> extends StyleExpression {
183
  readonly kind: Kind;
184
  evaluate(globals: EvaluationContext, feature?: any): any;
185
}
186

187
/**
188
 * Expressions that vary based on zoom level
189
 */
190
class ZoomDependentExpression<Kind> extends StyleExpression {
191
  readonly kind: Kind;
192
  readonly zoomStops: number[];
193
  evaluate(globals: EvaluationContext, feature?: any): any;
194
}
195

196
/**
197
 * Legacy function wrapper for backward compatibility
198
 */
199
class StylePropertyFunction<T> extends StyleExpression {
200
  evaluate(globals: EvaluationContext, feature?: any): T;
201
}
202
```
203

204
### Property Expression Types
205

206
Union types for different expression evaluation patterns.
207

208
```typescript { .api }
209
type StylePropertyExpression = 
210
  | ConstantExpression
211
  | SourceExpression  
212
  | CameraExpression
213
  | CompositeExpression;
214

215
/**
216
 * Constant value expressions
217
 */
218
interface ConstantExpression {
219
  kind: 'constant';
220
  evaluate(): any;
221
}
222

223
/**
224
 * Feature-dependent expressions
225
 */
226
interface SourceExpression {
227
  kind: 'source';
228
  evaluate(globals: EvaluationContext, feature: any): any;
229
}
230

231
/**
232
 * Zoom-dependent expressions
233
 */
234
interface CameraExpression {
235
  kind: 'camera';
236
  evaluate(globals: EvaluationContext): any;
237
}
238

239
/**
240
 * Zoom and feature-dependent expressions
241
 */
242
interface CompositeExpression {
243
  kind: 'composite';
244
  evaluate(globals: EvaluationContext, feature: any): any;
245
}
246
```
247

248
## Types
249

250
```typescript { .api }
251
interface EvaluationContext {
252
  zoom: number;
253
  pitch?: number;
254
  heatmapDensity?: number;
255
  lineProgress?: number;
256
  rasterValue?: number;
257
  rasterParticleSpeed?: number;
258
  skyRadialProgress?: number;
259
  readonly isSupportedScript?: (script: string) => boolean;
260
  accumulated?: any;
261
  brightness?: number;
262
  worldview?: string;
263
}
264

265
type ExpressionSpecification = 
266
  | boolean 
267
  | number 
268
  | string 
269
  | Array<any>;
270

271
interface ExpressionMeta {
272
  interpolated: boolean;
273
  parameters?: Array<'zoom' | 'feature' | 'feature-state' | 'heatmap-density' | 'line-progress' | 'raster-value' | 'sky-radial-progress' | 'pitch' | 'distance-from-center' | 'measure-light' | 'raster-particle-speed'>;
274
  relaxZoomRestriction?: boolean;
275
}
276

277
type PropertyValueSpecification<T> = 
278
  | T 
279
  | ExpressionSpecification
280
  | CameraFunctionSpecification<T>
281
  | SourceFunctionSpecification<T>
282
  | CompositeFunctionSpecification<T>;
283

284
type DataDrivenPropertyValueSpecification<T> = 
285
  | T 
286
  | ExpressionSpecification
287
  | SourceFunctionSpecification<T>
288
  | CompositeFunctionSpecification<T>;
289
```