Expression System

/**
 * Creates a StyleExpression from an expression specification
 * @param expression - Expression specification array or literal value
 * @param propertySpec - Optional property specification for context
 * @returns Compilation result with expression or errors
 */
function createExpression(
  expression: ExpressionSpecification, 
  propertySpec?: StylePropertySpecification
): {
  result: 'success' | 'error';
  value?: StyleExpression;
  errors?: ParsingError[];
};

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

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

if (result1.result === 'success') {
  const value = result1.value.evaluate({ zoom: 10 }, { 
    properties: { population: 50000 } 
  });
  console.log(value); // 50000
}

// Conditional expression
const result2 = createExpression([
  'case',
  ['>', ['get', 'population'], 100000], 'red',
  ['>', ['get', 'population'], 50000], 'orange',
  'yellow'
]);

// Interpolation expression
const result3 = createExpression([
  'interpolate',
  ['linear'],
  ['zoom'],
  10, 2,
  20, 10
]);

/**
 * Creates a property-specific StyleExpression with enhanced validation
 * @param expression - Expression specification or literal value
 * @param propertySpec - Property specification defining constraints
 * @returns Compilation result with property expression
 */
function createPropertyExpression(
  expression: PropertyValueSpecification<any>, 
  propertySpec: StylePropertySpecification
): {
  result: 'success' | 'error';
  value?: StylePropertyExpression;
  errors?: ParsingError[];
};

/**
 * Normalizes a property value to expression format
 * @param expression - Raw property value or expression
 * @param propertySpec - Property specification for context
 * @returns Normalized expression specification
 */
function normalizePropertyExpression(
  expression: PropertyValueSpecification<any>, 
  propertySpec: StylePropertySpecification
): ExpressionSpecification;

/**
 * Tests whether a value is an expression array
 * @param value - Value to test
 * @returns True if value uses expression syntax
 */
function isExpression(value: any): boolean;

import { isExpression, normalizePropertyExpression } from "@mapbox/mapbox-gl-style-spec";

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

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

// Normalize property values
const normalized = normalizePropertyExpression(
  { stops: [[0, 'red'], [10, 'blue']] },
  { type: 'color', 'property-type': 'data-driven' }
);

abstract class StyleExpression {
  /**
   * Evaluates the expression with error handling
   * @param globals - Evaluation context (zoom, etc.)
   * @param feature - Optional feature for feature-dependent expressions
   * @param featureState - Optional feature state for dynamic styling
   * @param canonical - Optional canonical tile ID for geo-dependent expressions
   * @param availableImages - Optional array of available image IDs
   * @param formattedSection - Optional formatted text section
   * @param featureTileCoord - Optional feature tile coordinates
   * @param featureDistanceData - Optional distance calculation data
   * @returns Evaluation result or error
   */
  evaluate(
    globals: EvaluationContext, 
    feature?: any,
    featureState?: any,
    canonical?: any,
    availableImages?: string[],
    formattedSection?: any,
    featureTileCoord?: any,
    featureDistanceData?: any
  ): any;

  /**
   * Evaluates the expression without automatic error handling
   * @param globals - Evaluation context
   * @param feature - Optional feature for evaluation
   * @returns Raw evaluation result
   */
  evaluateWithoutErrorHandling(globals: EvaluationContext, feature?: any): any;
}

/**
 * Expressions that return constant values regardless of zoom or feature
 */
class ZoomConstantExpression<Kind> extends StyleExpression {
  readonly kind: Kind;
  evaluate(globals: EvaluationContext, feature?: any): any;
}

/**
 * Expressions that vary based on zoom level
 */
class ZoomDependentExpression<Kind> extends StyleExpression {
  readonly kind: Kind;
  readonly zoomStops: number[];
  evaluate(globals: EvaluationContext, feature?: any): any;
}

/**
 * Legacy function wrapper for backward compatibility
 */
class StylePropertyFunction<T> extends StyleExpression {
  evaluate(globals: EvaluationContext, feature?: any): T;
}

type StylePropertyExpression = 
  | ConstantExpression
  | SourceExpression  
  | CameraExpression
  | CompositeExpression;

/**
 * Constant value expressions
 */
interface ConstantExpression {
  kind: 'constant';
  evaluate(): any;
}

/**
 * Feature-dependent expressions
 */
interface SourceExpression {
  kind: 'source';
  evaluate(globals: EvaluationContext, feature: any): any;
}

/**
 * Zoom-dependent expressions
 */
interface CameraExpression {
  kind: 'camera';
  evaluate(globals: EvaluationContext): any;
}

/**
 * Zoom and feature-dependent expressions
 */
interface CompositeExpression {
  kind: 'composite';
  evaluate(globals: EvaluationContext, feature: any): any;
}

interface EvaluationContext {
  zoom: number;
  pitch?: number;
  heatmapDensity?: number;
  lineProgress?: number;
  rasterValue?: number;
  rasterParticleSpeed?: number;
  skyRadialProgress?: number;
  readonly isSupportedScript?: (script: string) => boolean;
  accumulated?: any;
  brightness?: number;
  worldview?: string;
}

type ExpressionSpecification = 
  | boolean 
  | number 
  | string 
  | Array<any>;

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

type PropertyValueSpecification<T> = 
  | T 
  | ExpressionSpecification
  | CameraFunctionSpecification<T>
  | SourceFunctionSpecification<T>
  | CompositeFunctionSpecification<T>;

type DataDrivenPropertyValueSpecification<T> = 
  | T 
  | ExpressionSpecification
  | SourceFunctionSpecification<T>
  | CompositeFunctionSpecification<T>;