Guarantee that run() never throws an error (#283)

Author: davidflanagan

packages/cel/src/parse.ts

@@ -20,7 +20,8 @@ import { parse as internalParse } from "./parser.js";
 import { create } from "@bufbuild/protobuf";
 
 /**
- * Parses a CEL expression string into an abstract syntax tree (AST).
+ * Parses a CEL expression string into an abstract syntax tree (AST) or
+ * throws an Error if parsing fails.
  *
  * This is the first stage of CEL evaluation. The resulting ParsedExpr
  * can be passed to plan() for execution planning.

packages/cel/src/run.ts

@@ -13,12 +13,15 @@
 // limitations under the License.
 
 import { celEnv, type CelEnvOptions } from "./env.js";
+import { celError, type CelError } from "./error.js";
 import { parse } from "./parse.js";
 import { plan } from "./plan.js";
-import type { CelInput } from "./type.js";
+import type { CelInput, CelValue } from "./type.js";
 
 /**
  * Convenience function that parses, plans, and executes a CEL expression in one call.
+ * run() always returns a CelValue or a CelError and never throws exceptions. Use
+ * isCelError() to distinguish the two cases.
  *
  * This is the simplest way to evaluate a CEL expression, but for better performance
  * and reusability, consider using parse(), plan(), and execution separately.
@@ -27,6 +30,10 @@ export function run(
   expr: string,
   bindings?: Record<string, CelInput>,
   envOptions?: CelEnvOptions,
-) {
-  return plan(celEnv(envOptions), parse(expr))(bindings);
+): CelValue | CelError {
+  try {
+    return plan(celEnv(envOptions), parse(expr))(bindings);
+  } catch (e: unknown) {
+    return celError(e);
+  }
 }