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:
  • <input checked="" disabled="" type="checkbox"> Literals
    • <input checked="" disabled="" type="checkbox"> int
    • <input checked="" disabled="" type="checkbox"> uint
    • <input checked="" disabled="" type="checkbox"> double
    • <input checked="" disabled="" type="checkbox"> bool
    • <input checked="" disabled="" type="checkbox"> string
      • <input checked="" disabled="" type="checkbox"> single-quote string
      • <input checked="" disabled="" type="checkbox"> double-quote string
      • <input disabled="" type="checkbox"> raw string
      • <input disabled="" type="checkbox"> triple-quote string
      • <input disabled="" type="checkbox"> byte string
    • <input checked="" disabled="" type="checkbox"> hexadecimal
    • <input disabled="" type="checkbox"> bytes
    • <input checked="" disabled="" type="checkbox"> list
    • <input checked="" disabled="" type="checkbox"> map
    • <input checked="" disabled="" type="checkbox"> null
  • <input checked="" disabled="" type="checkbox"> Conditional Operators
    • <input checked="" disabled="" type="checkbox"> Ternary (condition ? true : false)
    • <input checked="" disabled="" type="checkbox"> Logical And (&&)
    • <input checked="" disabled="" type="checkbox"> Logical Or (||)
  • <input checked="" disabled="" type="checkbox"> Equality Operators (==, !=)
  • <input checked="" disabled="" type="checkbox"> Relational Operators (<, <=, >, >=, in)
  • <input checked="" disabled="" type="checkbox"> Arithmetic Operators (+, -, *, /, %)
  • <input checked="" disabled="" type="checkbox"> Identifiers
    • <input checked="" disabled="" type="checkbox"> Dot Notation (foo.bar)
    • <input checked="" disabled="" type="checkbox"> Index Notation (foo["bar"])
  • <input checked="" disabled="" type="checkbox"> Macros: (has, size, etc.)
    • <input disabled="" type="checkbox"> All (e.all(x, p))
    • <input disabled="" type="checkbox"> Exists (e.exists(x, p))
    • <input disabled="" type="checkbox"> Exists one (e.exists_one(x, p))
    • <input disabled="" type="checkbox"> Filter (e.filter(x, p))
    • <input checked="" disabled="" type="checkbox"> Has (has(foo.bar))
    • <input disabled="" type="checkbox"> Map (e.map(x, t) and e.map(x, p, t))
    • <input checked="" disabled="" type="checkbox"> Size (size(foo))
  • <input checked="" disabled="" type="checkbox"> Unary Operators (!true, -123)
  • <input checked="" disabled="" type="checkbox"> Custom Functions (myFunction())
  • <input checked="" disabled="" type="checkbox"> Comments (// This is a comment)

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,