@math.gl/expressions 4.2.0-alpha.5

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { ExpressionEvaluationOptions, ExpressionFunction, ExpressionFunctionLibrary } from "./function-libraries.js";
+export { ExpressionFunctionRegistry, type FunctionRegistrationOptions } from "./function-registry.js";
+export type { BinaryOperator, Expression, ExpressionContext, UnaryOperator } from "./expression-eval.js";
+export { addBinaryOp, addUnaryOp, compile, compileAsync, eval, evalAsync, parse } from "./expression-eval.js";
+export { BASIC_MATH_FUNCTION_LIBRARY, GEOSPATIAL_FUNCTION_LIBRARY, mergeFunctionLibraries } from "./function-libraries.js";
+export { parseExpressionString, type AccessorFunction } from "./parse-expression-string.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,2BAA2B,EAC3B,kBAAkB,EAClB,yBAAyB,EAC1B,gCAA6B;AAC9B,OAAO,EAAC,0BAA0B,EAAE,KAAK,2BAA2B,EAAC,+BAA4B;AACjG,YAAY,EAAC,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAC,6BAA0B;AACpG,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,KAAK,EACN,6BAA0B;AAC3B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACvB,gCAA6B;AAC9B,OAAO,EAAC,qBAAqB,EAAE,KAAK,gBAAgB,EAAC,qCAAkC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+export { ExpressionFunctionRegistry } from "./function-registry.js";
+export { addBinaryOp, addUnaryOp, compile, compileAsync, eval, evalAsync, parse } from "./expression-eval.js";
+export { BASIC_MATH_FUNCTION_LIBRARY, GEOSPATIAL_FUNCTION_LIBRARY, mergeFunctionLibraries } from "./function-libraries.js";
+export { parseExpressionString } from "./parse-expression-string.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,+BAA+B;AAC/B,oCAAoC;AAOpC,OAAO,EAAC,0BAA0B,EAAmC,+BAA4B;AAEjG,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,KAAK,EACN,6BAA0B;AAC3B,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACvB,gCAA6B;AAC9B,OAAO,EAAC,qBAAqB,EAAwB,qCAAkC"}

package/dist/parse-expression-string.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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;
+/**
+ * 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 declare function parseExpressionString(propValue: string): AccessorFunction;
+//# sourceMappingURL=parse-expression-string.d.ts.map

package/dist/parse-expression-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-expression-string.d.ts","sourceRoot":"","sources":["../src/parse-expression-string.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAMzE;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAazE"}

package/dist/parse-expression-string.js

@@ -0,0 +1,61 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { eval as evaluate, parse } from "./expression-eval.js";
+import { get } from "./get.js";
+const cachedExpressionMap = {
+    '-': 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) {
+    if (propValue in cachedExpressionMap) {
+        return cachedExpressionMap[propValue];
+    }
+    const ast = parse(propValue);
+    const func = ast.type === 'Identifier'
+        ? (row) => get(row, propValue)
+        : compileAst(ast);
+    cachedExpressionMap[propValue] = func;
+    return func;
+}
+/** Validates and compiles a parsed accessor expression. */
+function compileAst(ast) {
+    traverse(ast, node => {
+        if (node.type === 'CallExpression') {
+            throw new Error('Function calls not allowed in expression accessors');
+        }
+    });
+    return (row) => evaluate(ast, row);
+}
+/** Visits each AST-like object in a parsed expression. */
+// eslint-disable-next-line complexity
+function traverse(node, visitor) {
+    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[key], visitor);
+        }
+    }
+}
+/** Tests whether an object resembles a JSEP AST node. */
+function isNodeLike(node) {
+    return 'type' in node && typeof node.type === 'string';
+}
+//# sourceMappingURL=parse-expression-string.js.map

package/dist/parse-expression-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-expression-string.js","sourceRoot":"","sources":["../src/parse-expression-string.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,+BAA+B;AAC/B,oCAAoC;AAGpC,OAAO,EAAC,IAAI,IAAI,QAAQ,EAAE,KAAK,EAAC,6BAA0B;AAC1D,OAAO,EAAC,GAAG,EAAC,iBAAc;AAU1B,MAAM,mBAAmB,GAAqC;IAC5D,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM;CACtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,IAAI,SAAS,IAAI,mBAAmB,EAAE,CAAC;QACrC,OAAO,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,IAAI,GACR,GAAG,CAAC,IAAI,KAAK,YAAY;QACvB,CAAC,CAAC,CAAC,GAA4B,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC;QACvD,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAEtB,mBAAmB,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2DAA2D;AAC3D,SAAS,UAAU,CAAC,GAAoB;IACtC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE;QACnB,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,GAA4B,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,0DAA0D;AAC1D,sCAAsC;AACtC,SAAS,QAAQ,CAAC,IAAa,EAAE,OAAuC;IACtE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACpD,OAAO;IACT,CAAC;IAED,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,QAAQ,CAAE,IAAgC,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,MAAM,IAAI,IAAI,IAAI,OAAQ,IAAyB,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC/E,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@math.gl/expressions",
+  "description": "Experimental expression parsing and evaluation utilities",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "4.2.0-alpha.5",
+  "keywords": [
+    "javascript",
+    "math",
+    "expressions",
+    "parser",
+    "evaluator",
+    "jsep"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visgl/math.gl.git"
+  },
+  "types": "dist/index.d.ts",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./dggs": {
+      "types": "./dist/dggs.d.ts",
+      "import": "./dist/dggs.js",
+      "require": "./dist/dggs.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@math.gl/core": "4.2.0-alpha.5",
+    "@math.gl/dggs-geohash": "4.2.0-alpha.5",
+    "@math.gl/dggs-quadkey": "4.2.0-alpha.5",
+    "@math.gl/dggs-s2": "4.2.0-alpha.5",
+    "@math.gl/geospatial": "4.2.0-alpha.5",
+    "jsep": "^1.4.0"
+  },
+  "gitHead": "9c13785761867748e2edb167b5f2749dce803039"
+}

package/src/dggs.ts

@@ -0,0 +1,62 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  getGeohashBoundary,
+  getGeohashBoundaryFlat,
+  getGeohashBounds,
+  getGeohashLngLat
+} from '@math.gl/dggs-geohash';
+import {
+  getQuadkeyBoundary,
+  getQuadkeyBoundaryFlat,
+  getQuadkeyLngLat,
+  quadkeyToWorldBounds
+} from '@math.gl/dggs-quadkey';
+import {
+  getS2BoundaryFlat,
+  getS2ChildIndex,
+  getS2IndexFromToken,
+  getS2TokenFromIndex
+} from '@math.gl/dggs-s2';
+import type {ExpressionFunctionLibrary} from './function-libraries';
+
+/**
+ * GeoHash functions ready to register with an expression evaluator.
+ */
+export const GEOHASH_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getGeohashBoundary,
+  getGeohashBoundaryFlat,
+  getGeohashBounds,
+  getGeohashLngLat
+};
+
+/**
+ * Quadkey functions ready to register with an expression evaluator.
+ */
+export const QUADKEY_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getQuadkeyBoundary,
+  getQuadkeyBoundaryFlat,
+  getQuadkeyLngLat,
+  quadkeyToWorldBounds
+};
+
+/**
+ * S2 functions ready to register with an expression evaluator.
+ */
+export const S2_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  getS2BoundaryFlat,
+  getS2ChildIndex,
+  getS2IndexFromToken,
+  getS2TokenFromIndex
+};
+
+/**
+ * Combined GeoHash, Quadkey, and S2 function table.
+ */
+export const DGGS_FUNCTION_LIBRARY: ExpressionFunctionLibrary = {
+  ...GEOHASH_FUNCTION_LIBRARY,
+  ...QUADKEY_FUNCTION_LIBRARY,
+  ...S2_FUNCTION_LIBRARY
+};

package/src/expression-eval.ts

@@ -0,0 +1,426 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Sources:
+ * - Copyright (c) 2013 Stephen Oney, http://jsep.from.so/, MIT License
+ * - Copyright (c) 2023 Don McCurdy, https://github.com/donmccurdy/expression-eval, MIT License
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/restrict-plus-operands */
+
+import jsep from 'jsep';
+import {mergeFunctionLibraries, type ExpressionEvaluationOptions} from './function-libraries';
+
+/**
+ * Named values and functions available while evaluating an expression.
+ */
+export type ExpressionContext = Record<string, unknown>;
+
+/**
+ * A JSEP abstract syntax tree node supported by the evaluator.
+ */
+export type Expression =
+  | jsep.ArrayExpression
+  | jsep.BinaryExpression
+  | jsep.CallExpression
+  | jsep.ConditionalExpression
+  | jsep.Identifier
+  | jsep.Literal
+  | jsep.MemberExpression
+  | jsep.ThisExpression
+  | jsep.UnaryExpression;
+
+/**
+ * Evaluator implementation for a custom unary operator.
+ *
+ * @param operand - Value produced by the operator's operand expression.
+ * @returns The operator result.
+ */
+export type UnaryOperator = (operand: any) => any;
+
+/**
+ * Evaluator implementation for a custom binary operator.
+ *
+ * @param left - Value produced by the left operand expression.
+ * @param right - Value produced by the right operand expression.
+ * @returns The operator result.
+ */
+export type BinaryOperator = (left: any, right: any) => any;
+
+type Callable = (...args: any[]) => any;
+
+const DEFAULT_PRECEDENCE: Record<string, number> = {
+  '||': 1,
+  '&&': 2,
+  '|': 3,
+  '^': 4,
+  '&': 5,
+  '==': 6,
+  '!=': 6,
+  '===': 6,
+  '!==': 6,
+  '<': 7,
+  '>': 7,
+  '<=': 7,
+  '>=': 7,
+  '<<': 8,
+  '>>': 8,
+  '>>>': 8,
+  '+': 9,
+  '-': 9,
+  '*': 10,
+  '/': 10,
+  '%': 10
+};
+
+const binops: Record<string, (...args: any[]) => any> = {
+  '||': (a: unknown, b: unknown) => a || b,
+  '&&': (a: unknown, b: unknown) => a && b,
+  '|': (a: number, b: number) => a | b,
+  '^': (a: number, b: number) => a ^ b,
+  '&': (a: number, b: number) => a & b,
+  '==': (a: unknown, b: unknown) => {
+    // biome-ignore lint/suspicious/noDoubleEquals: this operator implements JavaScript loose equality.
+    return a == b;
+  },
+  '!=': (a: unknown, b: unknown) => {
+    // biome-ignore lint/suspicious/noDoubleEquals: this operator implements JavaScript loose inequality.
+    return a != b;
+  },
+  '===': (a: unknown, b: unknown) => a === b,
+  '!==': (a: unknown, b: unknown) => a !== b,
+  '<': (a: number | string, b: number | string) => a < b,
+  '>': (a: number | string, b: number | string) => a > b,
+  '<=': (a: number | string, b: number | string) => a <= b,
+  '>=': (a: number | string, b: number | string) => a >= b,
+  '<<': (a: number, b: number) => a << b,
+  '>>': (a: number, b: number) => a >> b,
+  '>>>': (a: number, b: number) => a >>> b,
+  '+': (a: unknown, b: unknown) => {
+    // @ts-expect-error Addition intentionally supports JS coercion semantics.
+    return a + b;
+  },
+  '-': (a: number, b: number) => a - b,
+  '*': (a: number, b: number) => a * b,
+  '/': (a: number, b: number) => a / b,
+  '%': (a: number, b: number) => a % b
+};
+
+const unops: Record<string, (...args: any[]) => any> = {
+  '-': (a: number) => -a,
+  '+': (a: unknown) => {
+    // eslint-disable-next-line no-implicit-coercion
+    return +a;
+  },
+  '~': (a: number) => ~a,
+  '!': (a: unknown) => !a
+};
+
+function evaluateArray(list: jsep.Expression[], context: ExpressionContext): unknown[] {
+  return list.map(value => evaluate(value, context));
+}
+
+/** Evaluates each expression in an array concurrently. */
+async function evaluateArrayAsync(
+  list: jsep.Expression[],
+  context: ExpressionContext
+): Promise<unknown[]> {
+  return await Promise.all(list.map(value => evalAsync(value, context)));
+}
+
+/** Resolves a member expression and preserves its receiver for method calls. */
+function evaluateMember(
+  node: jsep.MemberExpression,
+  context: ExpressionContext
+): [Record<string, unknown>, unknown] {
+  const object = evaluate(node.object, context) as Record<string, unknown>;
+  const key = node.computed
+    ? (evaluate(node.property, context) as string)
+    : (node.property as jsep.Identifier).name;
+
+  if (/^__proto__|prototype|constructor$/.test(key)) {
+    throw new Error(`Access to member "${key}" disallowed.`);
+  }
+
+  return [object, object?.[key]];
+}
+
+/** Asynchronously resolves a member expression and its receiver. */
+async function evaluateMemberAsync(
+  node: jsep.MemberExpression,
+  context: ExpressionContext
+): Promise<[Record<string, unknown>, unknown]> {
+  const object = (await evalAsync(node.object, context)) as Record<string, unknown>;
+  const key = node.computed
+    ? ((await evalAsync(node.property, context)) as string)
+    : (node.property as jsep.Identifier).name;
+
+  if (/^__proto__|prototype|constructor$/.test(key)) {
+    throw new Error(`Access to member "${key}" disallowed.`);
+  }
+
+  return [object, object?.[key]];
+}
+
+/** Evaluates one expression node synchronously. */
+// eslint-disable-next-line complexity
+function evaluateExpression(
+  node: jsep.Expression,
+  context: ExpressionContext,
+  options?: ExpressionEvaluationOptions
+): unknown {
+  const expression = node as Expression;
+  const mergedContext = mergeFunctionLibraries(context, options);
+
+  switch (expression.type) {
+    case 'ArrayExpression':
+      return evaluateArray(expression.elements, mergedContext);
+
+    case 'BinaryExpression':
+      if (expression.operator === '||') {
+        return (
+          evaluate(expression.left, mergedContext) || evaluate(expression.right, mergedContext)
+        );
+      }
+      if (expression.operator === '&&') {
+        return (
+          evaluate(expression.left, mergedContext) && evaluate(expression.right, mergedContext)
+        );
+      }
+      return binops[expression.operator](
+        evaluate(expression.left, mergedContext),
+        evaluate(expression.right, mergedContext)
+      );
+
+    case 'CallExpression': {
+      let caller: Record<string, unknown> | undefined;
+      let fn: Callable | undefined;
+
+      if (expression.callee.type === 'MemberExpression') {
+        const member = evaluateMember(expression.callee as jsep.MemberExpression, mergedContext);
+        caller = member[0];
+        fn = member[1] as Callable | undefined;
+      } else {
+        fn = evaluate(expression.callee, mergedContext) as Callable | undefined;
+      }
+
+      if (typeof fn !== 'function') {
+        return undefined;
+      }
+
+      return fn.apply(caller, evaluateArray(expression.arguments, mergedContext));
+    }
+
+    case 'ConditionalExpression':
+      return evaluate(expression.test, mergedContext)
+        ? evaluate(expression.consequent, mergedContext)
+        : evaluate(expression.alternate, mergedContext);
+
+    case 'Identifier':
+      return mergedContext[expression.name];
+
+    case 'Literal':
+      return expression.value;
+
+    case 'MemberExpression':
+      return evaluateMember(expression, mergedContext)[1];
+
+    case 'ThisExpression':
+      return mergedContext;
+
+    case 'UnaryExpression':
+      return unops[expression.operator](evaluate(expression.argument, mergedContext));
+
+    default:
+      return undefined;
+  }
+}
+
+/** Evaluates a nested expression using an already-merged context. */
+function evaluate(node: jsep.Expression, context: ExpressionContext): unknown {
+  return evaluateExpression(node, context);
+}
+
+/**
+ * Evaluates a parsed expression asynchronously.
+ *
+ * @param node - Expression AST to evaluate.
+ * @param context - Named values and functions available to the expression.
+ * @param options - Function libraries to add to the context.
+ * @returns The resolved expression value.
+ *
+ * @remarks
+ * Function calls are awaited, including calls nested inside arrays, member
+ * expressions, conditionals, unary expressions, and binary expressions.
+ */
+// eslint-disable-next-line complexity
+export async function evalAsync(
+  node: jsep.Expression,
+  context: ExpressionContext,
+  options?: ExpressionEvaluationOptions
+): Promise<unknown> {
+  const expression = node as Expression;
+  const mergedContext = mergeFunctionLibraries(context, options);
+
+  switch (expression.type) {
+    case 'ArrayExpression':
+      return await evaluateArrayAsync(expression.elements, mergedContext);
+
+    case 'BinaryExpression':
+      if (expression.operator === '||') {
+        return (
+          (await evalAsync(expression.left, mergedContext)) ||
+          (await evalAsync(expression.right, mergedContext))
+        );
+      }
+      if (expression.operator === '&&') {
+        return (
+          (await evalAsync(expression.left, mergedContext)) &&
+          (await evalAsync(expression.right, mergedContext))
+        );
+      }
+      return binops[expression.operator](
+        await evalAsync(expression.left, mergedContext),
+        await evalAsync(expression.right, mergedContext)
+      );
+
+    case 'CallExpression': {
+      let caller: Record<string, unknown> | undefined;
+      let fn: Callable | undefined;
+
+      if (expression.callee.type === 'MemberExpression') {
+        const member = await evaluateMemberAsync(
+          expression.callee as jsep.MemberExpression,
+          mergedContext
+        );
+        caller = member[0];
+        fn = member[1] as Callable | undefined;
+      } else {
+        fn = (await evalAsync(expression.callee, mergedContext)) as Callable | undefined;
+      }
+
+      if (typeof fn !== 'function') {
+        return undefined;
+      }
+
+      return await fn.apply(caller, await evaluateArrayAsync(expression.arguments, mergedContext));
+    }
+
+    case 'ConditionalExpression':
+      return (await evalAsync(expression.test, mergedContext))
+        ? await evalAsync(expression.consequent, mergedContext)
+        : await evalAsync(expression.alternate, mergedContext);
+
+    case 'Identifier':
+      return mergedContext[expression.name];
+
+    case 'Literal':
+      return expression.value;
+
+    case 'MemberExpression':
+      return (await evaluateMemberAsync(expression, mergedContext))[1];
+
+    case 'ThisExpression':
+      return mergedContext;
+
+    case 'UnaryExpression':
+      return unops[expression.operator](await evalAsync(expression.argument, mergedContext));
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Compiles an expression into a reusable synchronous evaluator.
+ *
+ * @param expression - Expression source or a previously parsed AST.
+ * @param options - Function libraries to add to each evaluation context.
+ * @returns A function that evaluates the expression against a context.
+ */
+export function compile(
+  expression: string | jsep.Expression,
+  options?: ExpressionEvaluationOptions
+): (context: ExpressionContext) => unknown {
+  const ast = parse(expression);
+  return (context: ExpressionContext) => evaluateExpression(ast, context, options);
+}
+
+/**
+ * Compiles an expression into a reusable asynchronous evaluator.
+ *
+ * @param expression - Expression source or a previously parsed AST.
+ * @param options - Function libraries to add to each evaluation context.
+ * @returns A function that asynchronously evaluates the expression.
+ */
+export function compileAsync(
+  expression: string | jsep.Expression,
+  options?: ExpressionEvaluationOptions
+): (context: ExpressionContext) => Promise<unknown> {
+  const ast = parse(expression);
+  return (context: ExpressionContext) => evalAsync(ast, context, options);
+}
+
+/**
+ * Registers a custom unary operator with the parser and evaluator.
+ *
+ * @param operator - Operator token to register.
+ * @param fn - Evaluator implementation for the operator.
+ *
+ * @remarks
+ * Registration changes module-global parser state and affects subsequent
+ * calls to {@link parse}.
+ */
+export function addUnaryOp(operator: string, fn: UnaryOperator): void {
+  jsep.addUnaryOp(operator);
+  unops[operator] = fn;
+}
+
+/**
+ * Registers a custom binary operator with the parser and evaluator.
+ *
+ * @param operator - Operator token to register.
+ * @param precedenceOrFn - Parser precedence, or the evaluator implementation
+ * when using the default precedence for a built-in operator.
+ * @param fn - Evaluator implementation when an explicit precedence is given.
+ *
+ * @remarks
+ * Registration changes module-global parser state and affects subsequent
+ * calls to {@link parse}. New operators should provide explicit precedence.
+ */
+export function addBinaryOp(
+  operator: string,
+  precedenceOrFn: number | BinaryOperator,
+  fn?: BinaryOperator
+): void {
+  if (fn) {
+    jsep.addBinaryOp(operator, precedenceOrFn as number);
+    binops[operator] = fn;
+    return;
+  }
+
+  jsep.addBinaryOp(operator, DEFAULT_PRECEDENCE[operator] || 1);
+  binops[operator] = precedenceOrFn as BinaryOperator;
+}
+
+/**
+ * Parses expression source into a JSEP abstract syntax tree.
+ *
+ * @param expression - Expression source or an existing AST.
+ * @returns A parsed AST, or the supplied AST unchanged.
+ * @throws If the expression string is not valid JSEP syntax.
+ */
+export function parse(expression: string | jsep.Expression): jsep.Expression {
+  return typeof expression === 'string' ? jsep(expression) : expression;
+}
+
+/**
+ * Evaluates a parsed expression synchronously.
+ *
+ * @param node - Expression AST to evaluate.
+ * @param context - Named values and functions available to the expression.
+ * @param options - Function libraries to add to the context.
+ * @returns The expression value.
+ */
+export {evaluateExpression as eval};