use global-state added to expression in constructor instead of the one passed as a parameter to evaluate function (#1267)

* prepare integration tests for `global-state` to define it as an object separate from expression parameters

* use `global-state` added to expression in constructor instead of the one passed as a parameter to the `evaluate` function

* changelog

Author: melitele

CHANGELOG.md

@@ -1,6 +1,8 @@
 ## main
 
 ### ✨ Features and improvements
+
+- Change passing `global-state` to expression from the `evaluate` function to the constructor ([#1267](https://github.com/maplibre/maplibre-style-spec/pull/1267))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes

src/expression/expression.test.ts

@@ -39,7 +39,7 @@ describe('createPropertyExpression', () => {
     });
 
     test('sets globalStateRefs', () => {
-        const {value} = createPropertyExpression(['case', ['>', ['global-state','stateKey'], 0], 100, ['global-state', 'anotherStateKey']], {
+        const {value} = createPropertyExpression(['case', ['>', ['global-state', 'stateKey'], 0], 100, ['global-state', 'anotherStateKey']], {
             type: 'number',
             'property-type': 'data-driven',
             expression: {
@@ -69,6 +69,38 @@ describe('evaluate expression', () => {
         expect(value.evaluate({globalState: {}, zoom: 10} as GlobalProperties)).toBe(42);
         expect(console.warn).not.toHaveBeenCalled();
     });
+
+    test('global state as expression property', () => {
+        const {value} = createPropertyExpression(['global-state', 'x'], {
+            type: null,
+            default: 42,
+            'property-type': 'data-driven',
+            transition: false
+        }, {x: 5}) as {value: StylePropertyExpression};
+
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+        expect(value.evaluate({globalState: {x: 15}, zoom: 10} as GlobalProperties)).toBe(5);
+        expect(console.warn).not.toHaveBeenCalled();
+    });
+
+    test('global state as expression property of zoom dependent expression', () => {
+        const {value} = createPropertyExpression(['interpolate', ['linear'], ['zoom'], 10, ['global-state', 'x'], 20, 50], {
+            type: 'number',
+            default: 42,
+            'property-type': 'data-driven',
+            expression: {
+                interpolated: true,
+                parameters: ['zoom']
+            }
+        } as StylePropertySpecification, {x: 5}) as {value: StylePropertyExpression};
+
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+        expect(value.evaluate({globalState: {x: 15}, zoom: 10} as GlobalProperties)).toBe(5);
+        expect(console.warn).not.toHaveBeenCalled();
+    });
+
     test('warns and falls back to default for invalid enum values', () => {
         const {value} = createPropertyExpression(['get', 'x'], {
             type: 'enum',
@@ -81,7 +113,7 @@ describe('evaluate expression', () => {
             }
         } as any as StylePropertySpecification) as {value: StylePropertyExpression};
 
-        vi.spyOn(console, 'warn').mockImplementation(() => { });
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
 
         expect(value.kind).toBe('source');
 

src/expression/index.ts

@@ -73,13 +73,15 @@ export class StyleExpression {
     _defaultValue: Value;
     _warningHistory: {[key: string]: boolean};
     _enumValues: {[_: string]: any};
+    readonly _globalState: Record<string, any>;
 
-    constructor(expression: Expression, propertySpec?: StylePropertySpecification | null) {
+    constructor(expression: Expression, propertySpec?: StylePropertySpecification | null, globalState?: Record<string, any>) {
         this.expression = expression;
         this._warningHistory = {};
         this._evaluator = new EvaluationContext();
         this._defaultValue = propertySpec ? getDefaultValue(propertySpec) : null;
         this._enumValues = propertySpec && propertySpec.type === 'enum' ? propertySpec.values : null;
+        this._globalState = globalState;
     }
 
     evaluateWithoutErrorHandling(
@@ -90,6 +92,9 @@ export class StyleExpression {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         this._evaluator.globals = globals;
         this._evaluator.feature = feature;
         this._evaluator.featureState = featureState;
@@ -108,6 +113,9 @@ export class StyleExpression {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         this._evaluator.globals = globals;
         this._evaluator.feature = feature || null;
         this._evaluator.featureState = featureState || null;
@@ -150,7 +158,7 @@ export function isExpression(expression: unknown) {
  *
  * @private
  */
-export function createExpression(expression: unknown, propertySpec?: StylePropertySpecification | null): Result<StyleExpression, Array<ExpressionParsingError>> {
+export function createExpression(expression: unknown, propertySpec?: StylePropertySpecification | null, globalState?: Record<string, any>): Result<StyleExpression, Array<ExpressionParsingError>> {
     const parser = new ParsingContext(expressions, isExpressionConstant, [], propertySpec ? getExpectedType(propertySpec) : undefined);
 
     // For string-valued properties, coerce to string at the top level rather than asserting.
@@ -161,20 +169,22 @@ export function createExpression(expression: unknown, propertySpec?: StyleProper
         return error(parser.errors);
     }
 
-    return success(new StyleExpression(parsed, propertySpec));
+    return success(new StyleExpression(parsed, propertySpec, globalState));
 }
 
 export class ZoomConstantExpression<Kind extends EvaluationKind> {
     kind: Kind;
     isStateDependent: boolean;
     globalStateRefs: Set<string>;
     _styleExpression: StyleExpression;
+    readonly _globalState: Record<string, any>;
 
-    constructor(kind: Kind, expression: StyleExpression) {
+    constructor(kind: Kind, expression: StyleExpression, globalState?: Record<string, any>) {
         this.kind = kind;
         this._styleExpression = expression;
         this.isStateDependent = kind !== ('constant' as EvaluationKind) && !isStateConstant(expression.expression);
         this.globalStateRefs = findGlobalStateRefs(expression.expression);
+        this._globalState = globalState;
     }
 
     evaluateWithoutErrorHandling(
@@ -185,6 +195,9 @@ export class ZoomConstantExpression<Kind extends EvaluationKind> {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         return this._styleExpression.evaluateWithoutErrorHandling(globals, feature, featureState, canonical, availableImages, formattedSection);
     }
 
@@ -196,6 +209,9 @@ export class ZoomConstantExpression<Kind extends EvaluationKind> {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         return this._styleExpression.evaluate(globals, feature, featureState, canonical, availableImages, formattedSection);
     }
 }
@@ -207,14 +223,16 @@ export class ZoomDependentExpression<Kind extends EvaluationKind> {
     globalStateRefs: Set<string>;
     _styleExpression: StyleExpression;
     interpolationType: InterpolationType;
+    readonly _globalState: Record<string, any>;
 
-    constructor(kind: Kind, expression: StyleExpression, zoomStops: Array<number>, interpolationType?: InterpolationType) {
+    constructor(kind: Kind, expression: StyleExpression, zoomStops: Array<number>, interpolationType?: InterpolationType, globalState?: Record<string, any>) {
         this.kind = kind;
         this.zoomStops = zoomStops;
         this._styleExpression = expression;
         this.isStateDependent = kind !== ('camera' as EvaluationKind) && !isStateConstant(expression.expression);
         this.globalStateRefs = findGlobalStateRefs(expression.expression);
         this.interpolationType = interpolationType;
+        this._globalState = globalState;
     }
 
     evaluateWithoutErrorHandling(
@@ -225,6 +243,9 @@ export class ZoomDependentExpression<Kind extends EvaluationKind> {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         return this._styleExpression.evaluateWithoutErrorHandling(globals, feature, featureState, canonical, availableImages, formattedSection);
     }
 
@@ -236,6 +257,9 @@ export class ZoomDependentExpression<Kind extends EvaluationKind> {
         availableImages?: Array<string>,
         formattedSection?: FormattedSection
     ): any {
+        if (this._globalState) {
+            globals = {...globals, globalState: this._globalState};
+        }
         return this._styleExpression.evaluate(globals, feature, featureState, canonical, availableImages, formattedSection);
     }
 
@@ -255,6 +279,7 @@ export function isZoomExpression(expression: any): expression is ZoomConstantExp
 export type ConstantExpression = {
     kind: 'constant';
     globalStateRefs: Set<string>;
+    readonly _globalState: Record<string, any>;
     readonly evaluate: (
         globals: GlobalProperties,
         feature?: Feature,
@@ -268,6 +293,7 @@ export type SourceExpression = {
     kind: 'source';
     isStateDependent: boolean;
     globalStateRefs: Set<string>;
+    readonly _globalState: Record<string, any>;
     readonly evaluate: (
         globals: GlobalProperties,
         feature?: Feature,
@@ -281,6 +307,7 @@ export type SourceExpression = {
 export type CameraExpression = {
     kind: 'camera';
     globalStateRefs: Set<string>;
+    readonly _globalState: Record<string, any>;
     readonly evaluate: (
         globals: GlobalProperties,
         feature?: Feature,
@@ -297,6 +324,7 @@ export type CompositeExpression = {
     kind: 'composite';
     isStateDependent: boolean;
     globalStateRefs: Set<string>;
+    readonly _globalState: Record<string, any>;
     readonly evaluate: (
         globals: GlobalProperties,
         feature?: Feature,
@@ -312,8 +340,8 @@ export type CompositeExpression = {
 
 export type StylePropertyExpression = ConstantExpression | SourceExpression | CameraExpression | CompositeExpression;
 
-export function createPropertyExpression(expressionInput: unknown, propertySpec: StylePropertySpecification): Result<StylePropertyExpression, Array<ExpressionParsingError>> {
-    const expression = createExpression(expressionInput, propertySpec);
+export function createPropertyExpression(expressionInput: unknown, propertySpec: StylePropertySpecification, globalState?: Record<string, any>): Result<StylePropertyExpression, Array<ExpressionParsingError>> {
+    const expression = createExpression(expressionInput, propertySpec, globalState);
     if (expression.result === 'error') {
         return expression;
     }
@@ -341,15 +369,15 @@ export function createPropertyExpression(expressionInput: unknown, propertySpec:
 
     if (!zoomCurve) {
         return success(isFeatureConstantResult ?
-            (new ZoomConstantExpression('constant', expression.value) as ConstantExpression) :
-            (new ZoomConstantExpression('source', expression.value) as SourceExpression));
+            (new ZoomConstantExpression('constant', expression.value, globalState) as ConstantExpression) :
+            (new ZoomConstantExpression('source', expression.value, globalState) as SourceExpression));
     }
 
     const interpolationType = zoomCurve instanceof Interpolate ? zoomCurve.interpolation : undefined;
 
     return success(isFeatureConstantResult ?
-        (new ZoomDependentExpression('camera', expression.value, zoomCurve.labels, interpolationType) as CameraExpression) :
-        (new ZoomDependentExpression('composite', expression.value, zoomCurve.labels, interpolationType) as CompositeExpression));
+        (new ZoomDependentExpression('camera', expression.value, zoomCurve.labels, interpolationType, globalState) as CameraExpression) :
+        (new ZoomDependentExpression('composite', expression.value, zoomCurve.labels, interpolationType, globalState) as CompositeExpression));
 }
 
 // serialization wrapper for old-style stop functions normalized to the
@@ -386,13 +414,14 @@ export class StylePropertyFunction<T> {
 
 export function normalizePropertyExpression<T>(
     value: PropertyValueSpecification<T>,
-    specification: StylePropertySpecification
+    specification: StylePropertySpecification,
+    globalState?: Record<string, any>
 ): StylePropertyExpression {
     if (isFunction(value)) {
         return new StylePropertyFunction(value, specification) as any;
 
     } else if (isExpression(value)) {
-        const expression = createPropertyExpression(value, specification);
+        const expression = createPropertyExpression(value, specification, globalState);
         if (expression.result === 'error') {
             // this should have been caught in validation
             throw new Error(expression.value.map(err => `${err.key}: ${err.message}`).join(', '));
@@ -416,6 +445,7 @@ export function normalizePropertyExpression<T>(
         }
         return {
             globalStateRefs: new Set<string>(),
+            _globalState: null,
             kind: 'constant',
             evaluate: () => constant
         };

test/integration/expression/expression.test.ts

@@ -30,6 +30,7 @@ type ExpressionFixture = {
     propertySpec?: Partial<StylePropertySpecification>;
     expression: any[];
     inputs?: FixtureInput[];
+    globalState?: Record<string, any>;
     expected?: FixtureResult;
 };
 
@@ -144,8 +145,8 @@ function getCompletePropertySpec(propertySpec: ExpressionFixture['propertySpec']
 
 function evaluateFixture(fixture: ExpressionFixture, spec: StylePropertySpecification): FixtureResult {
     const expression = isFunction(fixture.expression) ?
-        createPropertyExpression(convertFunction(fixture.expression, spec), spec) :
-        createPropertyExpression(fixture.expression, spec);
+        createPropertyExpression(convertFunction(fixture.expression, spec), spec, fixture.globalState) :
+        createPropertyExpression(fixture.expression, spec, fixture.globalState);
 
     if (expression.result === 'error') {
         return {

test/integration/expression/tests/global-state/basic/test.json

@@ -10,22 +10,11 @@
     [
       {},
       {}
-    ],
-    [
-      {
-        "globalState": {}
-      },
-      {}
-    ],
-    [
-      {
-        "globalState": {
-          "x": 1
-        }
-      },
-      {}
     ]
   ],
+  "globalState": {
+    "x": 1
+  },
   "expected": {
     "compiled": {
       "result": "success",
@@ -34,12 +23,6 @@
       "type": "number"
     },
     "outputs": [
-      {
-        "error": "Expected value to be of type number, but found null instead."
-      },
-      {
-        "error": "Expected value to be of type number, but found null instead."
-      },
       1
     ]
   }

test/integration/expression/tests/global-state/empty/test.json

@@ -0,0 +1,29 @@
+{
+  "expression": [
+    "number",
+    [
+      "global-state",
+      "x"
+    ]
+  ],
+  "inputs": [
+    [
+      {},
+      {}
+    ]
+  ],
+  "globalState": {},
+  "expected": {
+    "compiled": {
+      "result": "success",
+      "isFeatureConstant": true,
+      "isZoomConstant": true,
+      "type": "number"
+    },
+    "outputs": [
+      {
+        "error": "Expected value to be of type number, but found null instead."
+      }
+    ]
+  }
+}