chromegg/cel-js

cel-js is a Common Expression Language (CEL) evaluator for JavaScript

cel-js

cel-js is a powerful and efficient parser and evaluator for Google's Common Expression Language (CEL), built on the robust foundation of the Chevrotain parsing library. This library aims to provide a seamless and easy-to-use interface for working with CEL in JavaScript environments.

Live Demo 🚀

Try out cel-js in your browser with the live demo.

Features ✨

• 🚀 Fast and Efficient Parsing: Leverages Chevrotain for high-performance parsing and evaluation
• 🌍 Isomorphic: Ready for server and browser
• 📦 ESM support
• 📚 Supported CEL Features:
  • Literals
    • int
    • uint
    • double
    • bool
    • string
    • bytes
    • list
    • map
    • null
  • Conditional Operators
    • Ternary (condition ? true : false)
    • Logical And (&&)
    • Logical Or (||)
  • Equality Operators (==, !=)
  • Relational Operators (<, <=, >, >=, in)
  • Arithmetic Operators (+, -, *, /, %)
  • Identifiers
    • Dot Notation (foo.bar)
    • Index Notation (foo["bar"])
  • Macros: (exists, has, size, etc.)
    • Exists (exists(foo))
    • Has (has(foo, "bar"))
    • Size (size(foo))
  • Unary Operators (!true, -123)

Installation

To install cel-js, use npm:

npm i cel-js

Usage

evaluate

evaluate is the primary function for parsing and evaluating CEL expressions. It takes an expression string and an optional object of variables to use in the expression.

import { evaluate, parse } from 'cel-js'

// use `evaluate` to parse and evaluate an expression
evaluate('2 + 2 * 2') // => 6

evaluate('"foo" + "bar"') // => 'foobar'

evaluate('user.role == "admin"', { user: { role: 'admin' } }) // => true

parse

parse is a lower-level function that only parses an expression string into an AST. This can be useful if you want to evaluate the expression multiple times with different variables or if you want to validate the syntax of an expression.

// use `parse` to parse an expression, useful for validation purposes
const result = parse('2 + a')

if (!result.isSuccess) {
  // your business logic
}

// you can reuse the result of `parse` to evaluate the expression
evaluate(result.cst, { a: 2 }) // => 4
evaluate(result.cst, { a: 4 }) // => 6

Known Issues

• Errors types and messages are not 100% consistent with the cel-go implementation,

cel-js's Issues

Implement CEL Conformance Tests

The package should implement a gRPC server that conforms with the documentation on, so the conformance could be tested independently.

https://github.com/google/cel-spec/tree/master/tests

Comment support

https://github.com/google/cel-spec/blob/master/doc/langdef.md

COMMENT        ::= '//' ~NEWLINE* NEWLINE

0.1.0 release - MVP

This is my subject list of features that are bare minimum for v0.1.0 - MVP.

• ConditionalOr
• ConditionalAnd
• Adds conditional type checking (to prevent JS behaviour like 2 || 4)
• String concatenation
• Nested Identifiers (foo.bar)
• Unary operator (-123, !true)

Typecheck error - cannot find module helper.js

Hi, I am trying to run tsc to typecheck but I'm met with an error.

> tsc && tsc-alias

../node_modules/.pnpm/[email protected]/node_modules/cel-js/dist/errors/CelTypeError.d.ts:1:28 - error TS2307: Cannot find module '../helper.js' or its corresponding type declarations.

1 import { Operations } from '../helper.js';

Add list of reserved identifiers

https://github.com/google/cel-spec/blob/master/doc/langdef.md

The following identifiers are reserved to allow easier embedding of CEL into a host language.

as break const continue else for function if import let loop package
namespace return var void while

Identifiers support

Bytes support

https://github.com/google/cel-spec/blob/master/doc/langdef.md

bug: map with multiple nested properties is throwing an error

    it('should create a nested map', () => {
      const expr = '{"a": 1, "b": {"c": 2}}'

      // it explodes with error `invalid_argument: [object Object]`😞 
      const result = evaluate(expr)
      
      expect(result).toStrictEqual({ a: 1, b: { c: 2 } })
    })

uint are not supported as the spec

In CEL the uint type is written in the form of 1u, this is not currently supported by cel-js.

Macros support

https://github.com/google/cel-spec/blob/master/doc/langdef.md#macros