@math.gl/expressions 4.2.0-alpha.5

package/src/function-libraries.ts

@@ -0,0 +1,168 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
+
+import {
+  acos,
+  asin,
+  atan,
+  clamp,
+  cos,
+  degrees,
+  lerp,
+  normalizeAngle,
+  radians,
+  safeMod,
+  sin,
+  tan,
+  toDegrees,
+  toRadians
+} from '@math.gl/core';
+import {Ellipsoid, isWGS84} from '@math.gl/geospatial';
+import type {ExpressionFunctionRegistry} from './function-registry';
+
+/**
+ * A function that can be exposed to evaluated expressions.
+ *
+ * @param args - Arguments supplied by a call expression.
+ * @returns The value made available to the expression.
+ */
+export type ExpressionFunction = (...args: any[]) => any;
+
+/**
+ * A named collection of functions that can be supplied to an expression
+ * evaluator through {@link ExpressionEvaluationOptions}.
+ */
+export type ExpressionFunctionLibrary = Record<string, ExpressionFunction>;
+
+/**
+ * Options shared by the synchronous and asynchronous expression evaluators.
+ */
+export type ExpressionEvaluationOptions = {
+  /**
+   * Instance-scoped registry of named functions available to the expression.
+   */
+  registry?: ExpressionFunctionRegistry;
+
+  /**
+   * Function libraries to add to the evaluation context.
+   *
+   * Libraries are merged from left to right. Functions in later libraries
+   * replace functions with the same name in earlier libraries. Values in the
+   * expression context replace functions with the same name in any library.
+   */
+  libraries?: ExpressionFunctionLibrary[];
+};
+
+/**
+ * General-purpose mathematical functions for expression evaluation.
+ *
+ * Includes JavaScript `Math` functions and math.gl helpers such as `clamp`,
+ * `lerp`, `normalizeAngle`, `safeMod`, `toDegrees`, and `toRadians`.
+ *
+ * @example
+ * ```ts
+ * const evaluate = compile("clamp(sin(angle), 0, 1)", {
+ *   libraries: [BASIC_MATH_FUNCTION_LIBRARY]
+ * });
+ * evaluate({angle: Math.PI / 2});
+ * ```
+ */
+export const BASIC_MATH_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  abs: Math.abs,
+  acos,
+  asin,
+  atan,
+  ceil: Math.ceil,
+  clamp,
+  cos,
+  degrees,
+  exp: Math.exp,
+  floor: Math.floor,
+  lerp,
+  log: Math.log,
+  max: Math.max,
+  min: Math.min,
+  normalizeAngle,
+  pow: Math.pow,
+  radians,
+  round: Math.round,
+  safeMod,
+  sign: Math.sign,
+  sin,
+  sqrt: Math.sqrt,
+  tan,
+  toDegrees,
+  toRadians,
+  trunc: Math.trunc
+};
+
+/**
+ * WGS84 ellipsoid functions for expression evaluation.
+ *
+ * Includes cartographic and Cartesian coordinate conversion, surface
+ * projection, local east-north-up frame generation, and WGS84 inspection.
+ * Angular arguments use radians unless the selected function states otherwise.
+ *
+ * @example
+ * ```ts
+ * const evaluate = compile("cartographicToCartesian(position)", {
+ *   libraries: [GEOSPATIAL_FUNCTION_LIBRARY]
+ * });
+ * evaluate({position: [0, 0, 0]});
+ * ```
+ */
+export const GEOSPATIAL_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  cartesianToCartographic: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.cartesianToCartographic(cartesian, result),
+  cartographicToCartesian: (cartographic: number[], result?: number[]) =>
+    Ellipsoid.WGS84.cartographicToCartesian(cartographic, result),
+  eastNorthUpToFixedFrame: (origin: number[], result?: number[]) =>
+    Ellipsoid.WGS84.eastNorthUpToFixedFrame(origin, result),
+  geodeticSurfaceNormal: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.geodeticSurfaceNormal(cartesian, result),
+  geodeticSurfaceNormalCartographic: (cartographic: number[], result?: number[]) =>
+    Ellipsoid.WGS84.geodeticSurfaceNormalCartographic(cartographic, result),
+  isWGS84,
+  scaleToGeocentricSurface: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.scaleToGeocentricSurface(cartesian, result),
+  scaleToGeodeticSurface: (cartesian: number[], result?: number[]) =>
+    Ellipsoid.WGS84.scaleToGeodeticSurface(cartesian, result),
+  toDegrees,
+  toRadians,
+  transformPositionFromScaledSpace: (position: number[], result?: number[]) =>
+    Ellipsoid.WGS84.transformPositionFromScaledSpace(position, result),
+  transformPositionToScaledSpace: (position: number[], result?: number[]) =>
+    Ellipsoid.WGS84.transformPositionToScaledSpace(position, result)
+};
+
+/**
+ * Adds configured function libraries to an expression context.
+ *
+ * @param context - Values available to the expression.
+ * @param options - Function libraries to merge into the context.
+ * @returns The original context when no libraries are supplied, or a new
+ * context containing the libraries and context values.
+ *
+ * @remarks
+ * Libraries are merged from left to right, then overlaid with `context`.
+ * Registry functions have the lowest precedence. The input objects are not modified.
+ */
+export function mergeFunctionLibraries(
+  context: Record<string, unknown>,
+  options?: ExpressionEvaluationOptions
+): Record<string, unknown> {
+  if (!options?.libraries?.length) {
+    if (!options?.registry) {
+      return context;
+    }
+  }
+
+  return Object.assign(
+    {},
+    options.registry?.getFunctionTable(),
+    ...(options.libraries || []),
+    context
+  );
+}

package/src/function-registry.ts

@@ -0,0 +1,163 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ExpressionFunction, ExpressionFunctionLibrary} from './function-libraries';
+
+const FUNCTION_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const DISALLOWED_FUNCTION_NAMES = new Set(['__proto__', 'prototype', 'constructor']);
+
+/**
+ * Options for registering functions with an {@link ExpressionFunctionRegistry}.
+ */
+export type FunctionRegistrationOptions = {
+  /**
+   * Replace an existing function with the same name.
+   *
+   * @defaultValue false
+   */
+  replace?: boolean;
+};
+
+/**
+ * An isolated collection of named functions available to expression evaluators.
+ *
+ * @remarks
+ * Registries are instance scoped. Registering a function does not affect other
+ * registries or evaluators that do not receive the registry.
+ *
+ * Function names must be valid JavaScript-style identifiers so they can be
+ * called directly from JSEP expressions.
+ *
+ * @example
+ * ```ts
+ * const registry = new ExpressionFunctionRegistry()
+ *   .registerFunction('double', (value) => value * 2)
+ *   .registerFunctions(BASIC_MATH_FUNCTION_LIBRARY);
+ *
+ * const evaluate = compile('double(round(value))', {registry});
+ * evaluate({value: 2.4});
+ * ```
+ */
+export class ExpressionFunctionRegistry {
+  private readonly functions = Object.create(null) as ExpressionFunctionLibrary;
+
+  /**
+   * Creates a function registry.
+   *
+   * @param functionTables - Function tables to register in order.
+   * @throws If a table contains an invalid or duplicate function name.
+   */
+  constructor(functionTables: readonly ExpressionFunctionLibrary[] = []) {
+    for (const functionTable of functionTables) {
+      this.registerFunctions(functionTable);
+    }
+  }
+
+  /**
+   * Registers one named function.
+   *
+   * @param name - Identifier used to call the function from an expression.
+   * @param fn - JavaScript function invoked with evaluated expression arguments.
+   * @param options - Duplicate registration behavior.
+   * @returns This registry.
+   * @throws If the name is invalid, the value is not a function, or the name is
+   * already registered and replacement was not requested.
+   */
+  registerFunction(
+    name: string,
+    fn: ExpressionFunction,
+    options: FunctionRegistrationOptions = {}
+  ): this {
+    validateFunction(name, fn);
+    if (this.hasFunction(name) && !options.replace) {
+      throw new Error(`Expression function "${name}" is already registered.`);
+    }
+    this.functions[name] = fn;
+    return this;
+  }
+
+  /**
+   * Registers all entries in a function table.
+   *
+   * @param functionTable - Map from expression identifiers to JavaScript functions.
+   * @param options - Duplicate registration behavior.
+   * @returns This registry.
+   * @throws If any entry is invalid or conflicts with an existing registration.
+   *
+   * @remarks
+   * Validation is atomic: no entries are registered when any entry is invalid.
+   */
+  registerFunctions(
+    functionTable: ExpressionFunctionLibrary,
+    options: FunctionRegistrationOptions = {}
+  ): this {
+    const entries = Object.entries(functionTable);
+    const names = new Set<string>();
+
+    for (const [name, fn] of entries) {
+      validateFunction(name, fn);
+      if (names.has(name) || (this.hasFunction(name) && !options.replace)) {
+        throw new Error(`Expression function "${name}" is already registered.`);
+      }
+      names.add(name);
+    }
+
+    for (const [name, fn] of entries) {
+      this.functions[name] = fn;
+    }
+    return this;
+  }
+
+  /**
+   * Removes a registered function.
+   *
+   * @param name - Function name to remove.
+   * @returns `true` when a function was removed.
+   */
+  unregisterFunction(name: string): boolean {
+    if (!this.hasFunction(name)) {
+      return false;
+    }
+    return delete this.functions[name];
+  }
+
+  /**
+   * Tests whether a function is registered.
+   *
+   * @param name - Function name to inspect.
+   * @returns `true` when the registry contains the name.
+   */
+  hasFunction(name: string): boolean {
+    return Object.prototype.hasOwnProperty.call(this.functions, name);
+  }
+
+  /**
+   * Returns a registered function.
+   *
+   * @param name - Function name to retrieve.
+   * @returns The registered function, or `undefined`.
+   */
+  getFunction(name: string): ExpressionFunction | undefined {
+    return this.functions[name];
+  }
+
+  /**
+   * Returns an immutable snapshot of all registered functions.
+   *
+   * @returns A frozen function table.
+   */
+  getFunctionTable(): Readonly<ExpressionFunctionLibrary> {
+    return Object.freeze({...this.functions});
+  }
+}
+
+/** Validates one registry entry. */
+function validateFunction(name: string, fn: ExpressionFunction): void {
+  if (!FUNCTION_NAME_PATTERN.test(name) || DISALLOWED_FUNCTION_NAMES.has(name)) {
+    throw new Error(`Invalid expression function name "${name}".`);
+  }
+  if (typeof fn !== 'function') {
+    throw new TypeError(`Expression function "${name}" must be a function.`);
+  }
+}

package/src/get.ts

@@ -0,0 +1,37 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Access properties of nested containers using dot-path notation.
+ *
+ * @param container - Object from which to read a value.
+ * @param compositeKey - Dot-separated property path.
+ * @returns The nested value, or `undefined` when the path cannot be resolved.
+ */
+export function get(container: Record<string, unknown>, compositeKey: string): unknown {
+  let value: unknown = container;
+
+  for (const key of getKeys(compositeKey)) {
+    value = isObject(value) ? value[key] : undefined;
+  }
+
+  return value;
+}
+
+/** Tests whether a value can be used for property access. */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object';
+}
+
+const keyMap: Record<string, string[]> = {};
+
+/** Returns a cached list of property names for a dot-separated path. */
+function getKeys(compositeKey: string): string[] {
+  let keyList = keyMap[compositeKey];
+  if (!keyList) {
+    keyList = compositeKey.split('.');
+    keyMap[compositeKey] = keyList;
+  }
+  return keyList;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type {
+  ExpressionEvaluationOptions,
+  ExpressionFunction,
+  ExpressionFunctionLibrary
+} from './function-libraries';
+export {ExpressionFunctionRegistry, type FunctionRegistrationOptions} from './function-registry';
+export type {BinaryOperator, Expression, ExpressionContext, UnaryOperator} from './expression-eval';
+export {
+  addBinaryOp,
+  addUnaryOp,
+  compile,
+  compileAsync,
+  eval,
+  evalAsync,
+  parse
+} from './expression-eval';
+export {
+  BASIC_MATH_FUNCTION_LIBRARY,
+  GEOSPATIAL_FUNCTION_LIBRARY,
+  mergeFunctionLibraries
+} from './function-libraries';
+export {parseExpressionString, type AccessorFunction} from './parse-expression-string';

package/src/parse-expression-string.ts

@@ -0,0 +1,80 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type jsep from 'jsep';
+import {eval as evaluate, parse} from './expression-eval';
+import {get} from './get';
+
+/**
+ * An accessor compiled from a JSON-style expression string.
+ *
+ * @param row - Data object against which the expression is evaluated.
+ * @returns The value produced by the expression.
+ */
+export type AccessorFunction = (row: Record<string, unknown>) => unknown;
+
+const cachedExpressionMap: Record<string, AccessorFunction> = {
+  '-': object => object
+};
+
+/**
+ * Compiles a JSON-style expression string into an accessor function.
+ *
+ * @param propValue - Accessor expression to compile.
+ * @returns A cached accessor function.
+ * @throws If the expression is invalid or contains a function call.
+ *
+ * @remarks
+ * `-` maps to the identity accessor and `a.b.c` maps to nested property
+ * access. Function calls are rejected so accessors cannot execute functions
+ * supplied by input data.
+ */
+export function parseExpressionString(propValue: string): AccessorFunction {
+  if (propValue in cachedExpressionMap) {
+    return cachedExpressionMap[propValue];
+  }
+
+  const ast = parse(propValue);
+  const func =
+    ast.type === 'Identifier'
+      ? (row: Record<string, unknown>) => get(row, propValue)
+      : compileAst(ast);
+
+  cachedExpressionMap[propValue] = func;
+  return func;
+}
+
+/** Validates and compiles a parsed accessor expression. */
+function compileAst(ast: jsep.Expression): AccessorFunction {
+  traverse(ast, node => {
+    if (node.type === 'CallExpression') {
+      throw new Error('Function calls not allowed in expression accessors');
+    }
+  });
+
+  return (row: Record<string, unknown>) => evaluate(ast, row);
+}
+
+/** Visits each AST-like object in a parsed expression. */
+// eslint-disable-next-line complexity
+function traverse(node: unknown, visitor: (node: {type: string}) => void): void {
+  if (Array.isArray(node)) {
+    node.forEach(element => traverse(element, visitor));
+    return;
+  }
+
+  if (node && typeof node === 'object') {
+    if (isNodeLike(node)) {
+      visitor(node);
+    }
+    for (const key in node) {
+      traverse((node as Record<string, unknown>)[key], visitor);
+    }
+  }
+}
+
+/** Tests whether an object resembles a JSEP AST node. */
+function isNodeLike(node: object): node is {type: string} {
+  return 'type' in node && typeof (node as {type?: unknown}).type === 'string';
+}