Improve expression types (#1128)

* improve array-related expression types

* improve lookup expression types

* improve interpolate expression types

* improve types expression types

* improve feature data expression types

* improve decision expression types

* improve math expression types

* add tests for updated types

* improve expression typings in docs

* fix malformed "within" expression tests

* use explicit typecheck tests in expression.test.ts

* replace compileTimeCheck with Vitest typecheck

* fix lint errors

* unroll loops in expression unit tests

* use `as` assertions for type narrowing

---------

Co-authored-by: Harel M <[email protected]>

Author: sruenwg

build/generate-style-spec.ts

@@ -157,18 +157,18 @@ export type CollatorExpressionSpecification =
 
 export type InterpolationSpecification =
     | ['linear']
-    | ['exponential', number | ExpressionSpecification]
-    | ['cubic-bezier', number | ExpressionSpecification, number | ExpressionSpecification, number | ExpressionSpecification, number | ExpressionSpecification]
+    | ['exponential', number]
+    | ['cubic-bezier', number, number, number, number]
 
 export type ExpressionSpecification =
     // types
-    | ['array', unknown | ExpressionSpecification] // array
-    | ['array', ExpressionInputType | ExpressionSpecification, unknown | ExpressionSpecification] // array
-    | ['array', ExpressionInputType | ExpressionSpecification, number | ExpressionSpecification, unknown | ExpressionSpecification] // array
-    | ['boolean', ...(unknown | ExpressionSpecification)[], unknown | ExpressionSpecification] // boolean
+    | ['array', ExpressionSpecification] // array
+    | ['array', 'string' | 'number' | 'boolean', ExpressionSpecification] // array
+    | ['array', 'string' | 'number' | 'boolean', number, ExpressionSpecification] // array
+    | ['boolean', unknown | ExpressionSpecification, ...(unknown | ExpressionSpecification)[]] // boolean
     | CollatorExpressionSpecification
-    | ['format', ...(string | ['image', ExpressionSpecification] | ExpressionSpecification | {'font-scale'?: number | ExpressionSpecification, 'text-font'?: string[] | ExpressionSpecification, 'text-color'?: ColorSpecification | ExpressionSpecification})[]] // string
-    | ['image', unknown | ExpressionSpecification] // image
+    | ['format', ...(string | ['image', ExpressionSpecification] | ExpressionSpecification | {'font-scale'?: number | ExpressionSpecification, 'text-font'?: ExpressionSpecification, 'text-color'?: ColorSpecification | ExpressionSpecification, 'vertical-align'?: 'bottom' | 'center' | 'top'})[]] // string
+    | ['image', string | ExpressionSpecification] // image
     | ['literal', unknown]
     | ['number', unknown | ExpressionSpecification, ...(unknown | ExpressionSpecification)[]] // number
     | ['number-format', number | ExpressionSpecification, {'locale'?: string | ExpressionSpecification, 'currency'?: string | ExpressionSpecification, 'min-fraction-digits'?: number | ExpressionSpecification, 'max-fraction-digits'?: number | ExpressionSpecification}] // string
@@ -178,47 +178,48 @@ export type ExpressionSpecification =
     | ['to-color', unknown | ExpressionSpecification, ...(unknown | ExpressionSpecification)[]] // color
     | ['to-number', unknown | ExpressionSpecification, ...(unknown | ExpressionSpecification)[]] // number
     | ['to-string', unknown | ExpressionSpecification] // string
+    | ['typeof', unknown | ExpressionSpecification] // string
     // feature data
     | ['accumulated']
-    | ['feature-state', string]
+    | ['feature-state', string | ExpressionSpecification]
     | ['geometry-type'] // string
     | ['id']
     | ['line-progress'] // number
     | ['properties'] // object
     // lookup
     | ['at', number | ExpressionSpecification, ExpressionSpecification]
-    | ['get', string | ExpressionSpecification, (Record<string, unknown> | ExpressionSpecification)?]
-    | ['has', string | ExpressionSpecification, (Record<string, unknown> | ExpressionSpecification)?]
-    | ['in', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification]
-    | ['index-of', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification] // number
+    | ['get', string | ExpressionSpecification, ExpressionSpecification?]
+    | ['global-state', string]
+    | ['has', string | ExpressionSpecification, ExpressionSpecification?]
+    | ['in', null | ExpressionInputType | ExpressionSpecification, string | ExpressionSpecification]
+    | ['index-of', null | ExpressionInputType | ExpressionSpecification, string | ExpressionSpecification, (number | ExpressionSpecification)?] // number
     | ['length', string | ExpressionSpecification]
     | ['slice', string | ExpressionSpecification, number | ExpressionSpecification, (number | ExpressionSpecification)?]
     // Decision
     | ['!', boolean | ExpressionSpecification] // boolean
-    | ['!=', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
-    | ['<', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
-    | ['<=', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
-    | ['==', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
-    | ['>', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
-    | ['>=', ExpressionInputType | ExpressionSpecification, ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['!=', null | ExpressionInputType | ExpressionSpecification, null | ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['<', string | number | ExpressionSpecification, string | number | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['<=', string | number | ExpressionSpecification, string | number | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['==', null | ExpressionInputType | ExpressionSpecification, null | ExpressionInputType | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['>', string | number | ExpressionSpecification, string | number | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
+    | ['>=', string | number | ExpressionSpecification, string | number | ExpressionSpecification, CollatorExpressionSpecification?] // boolean
     | ['all', ...(boolean | ExpressionSpecification)[]] // boolean
     | ['any', ...(boolean | ExpressionSpecification)[]] // boolean
-    | ['case', boolean | ExpressionSpecification, ExpressionInputType | ExpressionSpecification,
-        ...(boolean | ExpressionInputType | ExpressionSpecification)[], ExpressionInputType | ExpressionSpecification]
+    | ['case', boolean | ExpressionSpecification, null | ExpressionInputType | ExpressionSpecification,
+        ...(boolean | null | ExpressionInputType | ExpressionSpecification)[], null | ExpressionInputType | ExpressionSpecification]
     | ['coalesce', ...(ExpressionInputType | ExpressionSpecification)[]] // at least two inputs required
-    | ['match', ExpressionInputType | ExpressionSpecification,
-        ExpressionInputType | ExpressionInputType[], ExpressionInputType | ExpressionSpecification,
-        ...(ExpressionInputType | ExpressionInputType[] | ExpressionSpecification)[], // repeated as above
-        ExpressionInputType | ExpressionSpecification]
-    | ['within', unknown | ExpressionSpecification]
-    | ['distance', unknown | ExpressionSpecification]
+    | ['match', string | number | ExpressionSpecification,
+        string | number | string[] | number[], null | ExpressionInputType | ExpressionSpecification,
+        ...(string | number | string[] | number[] | null | ExpressionInputType | ExpressionSpecification)[], // repeated as above
+        null | ExpressionInputType | ExpressionSpecification]
+    | ['within', GeoJSON.GeoJSON]
     // Ramps, scales, curves
     | ['interpolate', InterpolationSpecification, number | ExpressionSpecification,
-        ...(number | number[] | ColorSpecification | ExpressionSpecification | ProjectionDefinitionSpecification )[]] // alternating number and number | number[] | ColorSpecification
+        ...(number | ColorSpecification | ExpressionSpecification | ProjectionDefinitionSpecification)[]] // alternating number and number | ColorSpecification | ExpressionSpecification | ProjectionDefinitionSpecification
     | ['interpolate-hcl', InterpolationSpecification, number | ExpressionSpecification,
-        ...(number | ColorSpecification)[]] // alternating number and ColorSpecificaton
+        ...(number | ColorSpecification | ExpressionSpecification)[]] // alternating number and ColorSpecificaton | ExpressionSpecification
     | ['interpolate-lab', InterpolationSpecification, number | ExpressionSpecification,
-        ...(number | ColorSpecification)[]] // alternating number and ColorSpecification
+        ...(number | ColorSpecification | ExpressionSpecification)[]] // alternating number and ColorSpecification | ExpressionSpecification
     | ['step', number | ExpressionSpecification, ExpressionInputType | ExpressionSpecification,
         ...(number | ExpressionInputType | ExpressionSpecification)[]] // alternating number and ExpressionInputType | ExpressionSpecification
     // Variable binding
@@ -247,8 +248,8 @@ export type ExpressionSpecification =
     | ['atan', number | ExpressionSpecification] // number
     | ['ceil', number | ExpressionSpecification] // number
     | ['cos', number | ExpressionSpecification] // number
-    | ['distance', Record<string, unknown> | ExpressionSpecification] // number
-    | ['ExpressionSpecification'] // number
+    | ['distance', GeoJSON.GeoJSON] // number
+    | ['e'] // number
     | ['floor', number | ExpressionSpecification] // number
     | ['ln', number | ExpressionSpecification] // number
     | ['ln2'] // number