feat: Add CelProgram.evaluate static function which compiles and evaluates in one step

Author: kevinmichaelchen

__tests__/cel.test.ts

@@ -82,3 +82,44 @@ describe("CelProgram", () => {
     });
   });
 });
+
+describe("CelProgram.evaluate", () => {
+  it("should evaluate a simple expression in one step", async () => {
+    const result = await CelProgram.evaluate("size(message) > 5", {
+      message: "Hello World",
+    });
+    expect(result).toBe(true);
+  });
+
+  it("should handle errors gracefully", async () => {
+    await expect(
+      CelProgram.evaluate("invalid expression", {}),
+    ).rejects.toThrow();
+  });
+
+  it("should handle complex expressions and data structures", async () => {
+    const result = await CelProgram.evaluate(
+      '{"name": "test", "items": [1, 2, 3].map(i, {"id": i})}',
+      {},
+    );
+    expect(result).toEqual({
+      name: "test",
+      items: [{ id: 1 }, { id: 2 }, { id: 3 }],
+    });
+  });
+
+  it("should handle cart validation in one step", async () => {
+    const expr =
+      'has(cart.items) && cart.items.exists(item, item.productId == "prod_123" && item.quantity >= 1)';
+    const result = await CelProgram.evaluate(expr, {
+      cart: {
+        items: [
+          { productId: "prod_456", quantity: 1 },
+          { productId: "prod_123", quantity: 1 },
+          { productId: "prod_789", quantity: 3 },
+        ],
+      },
+    });
+    expect(result).toBe(true);
+  });
+});

src/index.ts

@@ -10,6 +10,26 @@ export class CelProgram {
     this.native = native;
   }
 
+  /**
+   * Compiles a CEL expression into a reusable program.
+   *
+   * Performance advantages:
+   * - Parsing and compilation are done only once: The CEL expression is parsed into an Abstract
+   *   Syntax Tree (AST) and compiled into an optimized internal representation in Rust
+   * - Type checking and validation happen during compilation: Any syntax errors or type
+   *   mismatches are caught early, before execution
+   * - The compiled program is cached in memory: The native Rust program object is retained
+   *   and can be reused without re-parsing or re-validating the expression
+   * - Execution is optimized: When executing the compiled program, it only needs to convert
+   *   the input context to CEL values and evaluate the pre-compiled expression tree
+   *
+   * This is particularly beneficial when you need to evaluate the same expression multiple
+   * times with different contexts, as you avoid the overhead of parsing, validation, and
+   * compilation for each evaluation.
+   *
+   * @param source The CEL expression to compile
+   * @returns A compiled CelProgram instance ready for execution
+   */
   static async compile(source: string): Promise<CelProgram> {
     if (!CelProgram.nativeModule) {
       // Use the NAPI-RS generated loader which handles platform detection
@@ -24,6 +44,16 @@ export class CelProgram {
   async execute(context: CelContext): Promise<any> {
     return this.native.execute(context);
   }
+
+  /**
+   * Convenience method to compile and execute a CEL expression in one step.
+   * Note: If you plan to evaluate the same expression multiple times with different contexts,
+   * it's more efficient to use compile() once and then call execute() multiple times.
+   */
+  static async evaluate(source: string, context: CelContext): Promise<any> {
+    const program = await CelProgram.compile(source);
+    return program.execute(context);
+  }
 }
 
 export default CelProgram;