@math.gl/core 5.0.0-alpha.18 → 5.0.0-alpha.19

package/src/expressions/function-registry.ts

@@ -0,0 +1,163 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 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/expressions/get.ts

@@ -0,0 +1,37 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 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/expressions/index.ts

@@ -0,0 +1,22 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 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, mergeFunctionLibraries} from './function-libraries';
+export {parseExpressionString, type AccessorFunction} from './parse-expression-string';

package/src/expressions/parse-expression-string.ts

@@ -0,0 +1,80 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {Jsep as jsep} from './vendor/jsep/types';
+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';
+}

package/src/expressions/vendor/jsep/LICENSE.txt

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: Copyright (c) 2013 Stephen Oney
+
+Copyright (c) 2013 Stephen Oney, https://ericsmekens.github.io/jsep/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/src/expressions/vendor/jsep/README.md

@@ -0,0 +1,22 @@
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+-->
+
+# Vendored jsep
+
+- Upstream: https://github.com/EricSmekens/jsep
+- npm release: jsep 1.4.0 (MIT).
+- Source: published dist/jsep.js and typings/tsd.d.ts.
+- runtime.ts is the ESM runtime bundled without minification; its private default export is typed as any at the boundary. types.ts preserves the upstream declarations, replacing the ambient npm module wrapper with a local Jsep export. No parser algorithms are changed.
+- LICENSE.txt retains the complete upstream license and copyright notice. It is distributed in the package's src directory.
+
+## Refreshing
+
+From the repository root after yarn install, run:
+
+```sh
+node scripts/vendor-expression-timezone-deps.mjs
+```
+
+The script pins upstream releases and SHA-512 tarball integrity values, verifies downloads, and never runs upstream package scripts. The repository lockfile pins the esbuild tool used for generation. Review upstream changes and licenses before changing pins. Keep the SPDX headers and license files when refreshing. Run the repository's build and existing expression/timezone and package boundary checks after a refresh. Vendored files are excluded from automatic formatting to preserve reproducible output.