@marcbachmann/cel-js
Advanced tools
A lightweight Common Expression Language (CEL) implementation in JavaScript with zero dependencies
A high-performance, zero-dependency implementation of the Common Expression Language (CEL) in JavaScript.
🚀 Use the CEL JS Playground to test expressions.
CEL (Common Expression Language) is a non-Turing complete language designed for simplicity, speed, safety, and portability. This JavaScript implementation provides a fast, lightweight CEL evaluator perfect for policy evaluation, configuration, and embedded expressions.
npm install @marcbachmann/cel-js
import {evaluate} from '@marcbachmann/cel-js'
// Simple evaluation
evaluate('1 + 2 * 3') // 7n
// With context
const allowed = evaluate(
'user.age >= 18 && "admin" in user.roles',
{user: {age: 30, roles: ['admin', 'user']}}
)
// true
import {evaluate, parse} from '@marcbachmann/cel-js'
// Direct evaluation
evaluate('1 + 2') // 3n
// With variables
evaluate('name + "!"', {name: 'Alice'}) // "Alice!"
// Parse once, evaluate multiple times for better performance
const expr = parse('user.age >= minAge')
expr({user: {age: 25}, minAge: 18}) // true
expr({user: {age: 16}, minAge: 18}) // false
// Access parsed AST and type checking
console.log(expr.ast) // AST representation
const typeCheck = expr.check() // Type check without evaluation
For type-safe expressions with custom functions and operators:
import {Environment} from '@marcbachmann/cel-js'
const env = new Environment()
.registerVariable('skipAgeCheck', 'bool')
.registerVariable('user', {
schema: {
email: 'string',
age: 'int',
}
})
.registerConstant('minAge', 'int', 18n)
.registerFunction('isAdult(int): bool', age => age >= 18n)
.registerOperator('string * int', (str, n) => str.repeat(Number(n)))
// Type-checked evaluation with constant
env.evaluate('isAdult(user.age) && (user.age >= minAge || skipAgeCheck)', {
user: {age: 25n}, skipAgeCheck: true
})
// Custom operators
env.evaluate('"Hi" * 3') // "HiHiHi"
Use registerConstant to expose shared configuration without passing it through every evaluation context.
import {Environment} from '@marcbachmann/cel-js'
const env = new Environment()
.registerConstant('minAge', 'int', 18n)
env.evaluate('user.age >= minAge', {user: {age: 20n}}) // true
Supported signatures:
env.registerConstant('minAge', 'int', 18n)
env.registerConstant({name: 'minAge', type: 'int', value: 18n, description: 'Minimum age'})
new Environment({
// Treat undeclared variables as dynamic type
unlistedVariablesAreDyn: false,
// Require list/map literals to stay strictly homogeneous (default: true)
homogeneousAggregateLiterals: true,
// Enable .?key/.[?key] optional chaining and optional.* helpers (default: false)
enableOptionalTypes: true,
// Optional structural limits (parse time)
limits: {
maxAstNodes: 100000,
maxDepth: 250,
maxListElements: 1000,
maxMapEntries: 1000,
maxCallArguments: 32
}
})
homogeneousAggregateLiterals to false if you need aggregate literals to accept mixed element/key/value types without wrapping everything in dyn(...).enableOptionalTypes to true to activate optional chaining.registerVariable(name, type) - Declare a variable with type checkingregisterType(typename, constructor) - Register custom typesregisterFunction(signature, handler) - Add custom functionsregisterOperator(signature, handler) - Add custom operatorsregisterConstant(name, type, value) - Provide immutable values without passing them in contextclone() - Create an isolated copy. Call that stops the parent from registering more entries.hasVariable(name) - Check if variable is registeredparse(expression) - Parse expression for reuseevaluate(expression, context) - Evaluate with contextcheck(expression) - Validate expression types without evaluationgetDefinitions() - Returns all registered variables and functions with their types, signatures, and descriptionsregisterVariable signaturesenv.registerVariable('user', 'map')
env.registerVariable('user', 'map', {description: 'The current user'})
env.registerVariable('user', {type: 'map', description: 'The current user'})
env.registerVariable({name: 'user', type: 'map', description: 'The current user'})
// Passing a schema property will implicitly create a custom type and
// convert objects/maps to a new class instance. Those values then behave similar like
// explicit types that are created using a constructor.
env.registerVariable({
name: 'user',
schema: {
email: 'string',
age: 'int',
profile: {
tags: 'list<string>',
avatar: 'string'
}
}
})
The type can be a type string (e.g. 'int', 'map', 'list<string>') or a TypeDeclaration obtained from another environment.
registerType signatures// Name + constructor class
// when fields are not provided, own properties are accessible automatically
env.registerType('Vector', Vector)
// Name + object with constructor and field types
env.registerType('Vector', {ctor: Vector, fields: {x: 'double', y: 'double'}})
// Name + object with fields only (auto-generates a wrapper class and convert function)
env.registerType('Vector', {fields: {x: 'double', y: 'double'}})
// Name + object with nested schema (registers nested types automatically)
env.registerType('Vector', {schema: {x: 'double', y: 'double'}})
// Single object with name and schema
env.registerType({name: 'Vector', schema: {x: 'double', y: 'double'}})
// Single object with constructor (name inferred from constructor)
env.registerType({ctor: Vector, fields: {x: 'double', y: 'double'}})
When fields or schema is provided without a ctor, an internal wrapper class is auto-generated and plain objects are automatically converted at runtime. A custom convert function can be passed to override this default conversion.
When using the schema declaration, we're creating a new Map instance for the specific type when retrieving the values by variable from a context object.
registerFunction signatures// Signature string + handler
env.registerFunction('greet(string): string', (name) => `Hello, ${name}!`)
env.registerFunction('greet(string): string', handler, {description: 'Greets someone'})
env.registerFunction('greet(string): string', {handler, description: 'Greets someone'})
// Single object with signature string
env.registerFunction({signature: 'add(int, int): int', handler, description: 'Adds two integers'})
// Single object with signature string and named params
env.registerFunction({
signature: 'formatDate(int, string): string',
handler,
description: 'Formats a timestamp',
params: [
{name: 'timestamp', description: 'Unix timestamp in seconds'},
{name: 'format', description: 'Date format string'}
]
})
// Single object without signature string
env.registerFunction({
name: 'multiply',
returnType: 'int',
handler: (a, b) => a * b,
description: 'Multiplies two integers',
params: [
{name: 'a', type: 'int', description: 'First number'},
{name: 'b', type: 'int', description: 'Second number'}
]
})
// Receiver method (called as 'hello'.shout())
env.registerFunction({
name: 'shout',
receiverType: 'string',
returnType: 'string',
handler: (str) => str.toUpperCase() + '!',
params: []
})
registerFunction (sync & async)registerFunction(signature, handler) accepts both synchronous and async handlers. When an async function (or a macro predicate/transform that uses async functions) participates in an expression, env.evaluate() returns a Promise that resolves with the final value. Consumers should await those evaluations when they register async behavior:
const env = new Environment()
.registerFunction('fetchUser(string): map', async (id) => {
const res = await fetch(`/users/${id}`)
return res.json()
})
const user = await env.evaluate('fetchUser(userId)', {userId: '42'})
Async handlers are primarily intended for latency-sensitive lookups (e.g., cache fetches, lightweight RPC). CEL’s goal is still deterministic, predictable evaluation, so avoid building expressions that trigger unbounded async work (like nested loops within macros or large fan-out requests) even though the engine will await those results.
import assert from 'node:assert/strict'
const parent = new Environment().registerVariable('user', 'map')
const child = parent.clone()
// Parent registries is frozen once cloned
assert.throws(() => parent.registerVariable('foo', 'dyn'))
// Child stays fully extensible without deep-copy overhead
child
.registerFunction('isAdult(map): bool', (u) => u.age >= 18n)
.registerVariable('minAge', 'int')
child.evaluate('isAdult(user) && user.age >= minAge', {
user: {age: 20n},
minAge: 18n
})
Supported Types: int, uint, double, string, bool, bytes, list, map, timestamp, duration, null_type, type, dyn, or custom types
Validate expressions before evaluation to catch type errors early:
import {Environment, TypeError} from '@marcbachmann/cel-js'
const env = new Environment()
.registerVariable('age', 'int')
.registerVariable('name', 'string')
// Check expression validity
const result = env.check('age >= 18 && name.startsWith("A")')
if (result.valid) {
console.log(`Expression is valid, returns: ${result.type}`) // bool
// Safe to evaluate
const value = env.evaluate('age >= 18 && name.startsWith("A")', {
age: 25n,
name: 'Alice'
})
} else {
console.error(`Type error: ${result.error.message}`)
}
// Detect errors without evaluation
const invalid = env.check('age + name') // Invalid: can't add int + string
console.log(invalid.valid) // false
console.log(invalid.error.message) // "Operator '+' not defined for types 'int' and 'string'"
Benefits:
// Arithmetic
evaluate('10 + 5 - 3') // 12n
evaluate('10 * 5 / 2') // 25n
evaluate('10 % 3') // 1n
// Comparison
evaluate('5 > 3') // true
evaluate('5 >= 5') // true
evaluate('5 == 5') // true
evaluate('5 != 4') // true
// Logical
evaluate('true && false') // false
evaluate('true || false') // true
evaluate('!false') // true
// Ternary
evaluate('5 > 3 ? "yes" : "no"') // "yes"
// Membership
evaluate('2 in [1, 2, 3]') // true
evaluate('"ell" in "hello"') // true
// Numbers (default to BigInt)
evaluate('42') // 42n
evaluate('3.14') // 3.14
evaluate('0xFF') // 255n
// Strings
evaluate('"hello"') // "hello"
evaluate('r"\\n"') // "\\n" (raw string)
evaluate('"""multi\nline"""') // "multi\nline\n"
// Bytes
evaluate('b"hello"') // Uint8Array
evaluate('b"\\xFF"') // Uint8Array [255]
// Collections
evaluate('[1, 2, 3]') // [1n, 2n, 3n]
evaluate('{name: "Alice"}') // {name: "Alice"}
// Other
evaluate('true') // true
evaluate('null') // null
// Type conversion
evaluate('string(123)') // "123"
evaluate('int("42")') // 42n
evaluate('double("3.14")') // 3.14
evaluate('bytes("hello")') // Uint8Array
evaluate('dyn(42)') // Converts to dynamic type
// Collections
evaluate('size([1, 2, 3])') // 3n
evaluate('size("hello")') // 5n
evaluate('size({a: 1, b: 2})') // 2n
// Time
evaluate('timestamp("2024-01-01T00:00:00Z")') // Date
// Type checking
evaluate('type(42)') // int
evaluate('type("hello")') // string
evaluate('"hello".contains("ell")') // true
evaluate('"hello".startsWith("he")') // true
evaluate('"hello".endsWith("lo")') // true
evaluate('"hello".matches("h.*o")') // true
evaluate('"hello".size()') // 5n
evaluate('"hello".indexOf("ll")') // 2n
evaluate('"hello world".indexOf("o", 5)') // 7n (search from index 5)
evaluate('"hello".lastIndexOf("l")') // 3n
evaluate('"hello".substring(1)') // "ello"
evaluate('"hello".substring(1, 4)') // "ell"
evaluate('[1, 2, 3].size()') // 3n
evaluate('["a", "b", "c"].join()') // "abc"
evaluate('["a", "b", "c"].join(", ")') // "a, b, c"
evaluate('b"hello".size()') // 5n
evaluate('b"hello".string()') // "hello"
evaluate('b"hello".hex()') // "68656c6c6f"
evaluate('b"hello".base64()') // "aGVsbG8="
evaluate('b"{\\"x\\": 42}".json()') // {x: 42n}
evaluate('b"hello".at(0)') // 104n (byte value at index)
All timestamp methods support an optional timezone parameter (e.g., "America/New_York", "UTC"):
const ctx = {t: new Date('2024-01-15T14:30:45.123Z')}
evaluate('t.getFullYear()', ctx) // 2024n
evaluate('t.getMonth()', ctx) // 0n (January, 0-indexed)
evaluate('t.getDayOfMonth()', ctx) // 15n
evaluate('t.getDayOfWeek()', ctx) // 1n (Monday, 0=Sunday)
evaluate('t.getDayOfYear()', ctx) // 15n
evaluate('t.getHours()', ctx) // 14n
evaluate('t.getMinutes()', ctx) // 30n
evaluate('t.getSeconds()', ctx) // 45n
evaluate('t.getMilliseconds()', ctx) // 123n
// With timezone
evaluate('t.getHours("America/New_York")', ctx) // 9n (UTC-5)
const ctx = {
numbers: [1, 2, 3, 4, 5],
users: [
{name: 'Alice', admin: true},
{name: 'Bob', admin: false}
]
}
// Check property exists
evaluate('has(user.email)', {user: {}}) // false
// All elements match
evaluate('numbers.all(n, n > 0)', ctx) // true
// Any element matches
evaluate('numbers.exists(n, n > 3)', ctx) // true
// Exactly one matches
evaluate('numbers.exists_one(n, n == 3)', ctx) // true
// Transform
evaluate('numbers.map(n, n * 2)', ctx)
// [2n, 4n, 6n, 8n, 10n]
// Filter
evaluate('numbers.filter(n, n > 2)', ctx)
// [3n, 4n, 5n]
// Filter + Transform
evaluate('users.filter(u, u.admin).map(u, u.name)', ctx)
// Bind a temporary value within the expression
evaluate('cel.bind(total, users.map(u, u.admin, u.score).sum(), total >= 90)', ctx)
// Or using three arg form of .map
evaluate('users.map(u, u.admin, u.name)', ctx)
// ["Alice"]
You can register your own macros by declaring overloads that accept ast arguments. The macro handler executes at parse time and must return an object that provides both typeCheck and evaluate hooks; these hooks are invoked later during env.check() and env.evaluate() so the macro lines up with the regular type-checker/evaluator pipeline.
import {Environment} from '@marcbachmann/cel-js'
const env = new Environment()
env.registerFunction('macro(ast): dyn', ({ast, args}) => {
// Any parameter on this object are available as
// the `macro` parameter within the `typeCheck` and `evaluate` functions below.
return {
// e.g. you can precompute values during parse time
firstArgument: args[0],
// Mandatory: called when the expression is type-checked
typeCheck(checker, macro, ctx) {
return checker.check(macro.firstArgument, ctx)
},
// Mandatory: called when the expression is evaluated
evaluate(evaluator, macro, ctx) {
return evaluator.eval(macro.firstArgument, ctx)
}
}
})
import {Environment} from '@marcbachmann/cel-js'
class Vector {
constructor(x, y) {
this.x = x
this.y = y
}
add(other) {
return new Vector(this.x + other.x, this.y + other.y)
}
}
const env = new Environment()
.registerType('Vector', Vector)
.registerVariable('v1', 'Vector')
.registerVariable('v2', 'Vector')
.registerOperator('Vector + Vector', (a, b) => a.add(b))
.registerFunction('magnitude(Vector): double', (v) =>
Math.sqrt(v.x * v.x + v.y * v.y)
)
const result = env.evaluate('magnitude(v1 + v2)', {
v1: new Vector(3, 4),
v2: new Vector(1, 2)
})
// 7.211102550927978
Benchmark results comparing against the cel-js package on Node.js v24.8.0 (Apple Silicon):
| Operation | Parsing | Evaluation |
|---|---|---|
| Simple number | 7.3x | 111x |
| Array creation | 10.1x | 57.9x |
| Map creation | 8.6x | 46x |
| Complex authorization | 1.3x | 5.5x |
Run benchmarks: npm run benchmark
import {evaluate, ParseError, EvaluationError, TypeError} from '@marcbachmann/cel-js'
try {
evaluate('invalid + + syntax')
} catch (error) {
if (error instanceof ParseError) {
console.error('Syntax error:', error.message)
} else if (error instanceof EvaluationError) {
console.error('Runtime error:', error.message)
}
}
// Type checking returns errors without throwing
const env = new Environment().registerVariable('x', 'int')
const result = env.check('x + "string"')
if (!result.valid && result.error instanceof TypeError) {
console.error('Type error:', result.error.message)
}
import {Environment} from '@marcbachmann/cel-js'
// Instantiating an environment is expensive, please do that outside hot code paths
const authEnv = new Environment()
.registerVariable('user', 'map')
.registerVariable('resource', 'map')
const canEdit = authEnv.parse(`
user.isActive &&
(user.role == "admin" ||
user.id == resource.ownerId)
`)
canEdit({
user: {id: 123, role: 'user', isActive: true},
resource: {ownerId: 123}
}) // true
import {Environment} from '@marcbachmann/cel-js'
// Instantiating an environment is expensive, please do that outside hot code paths
const validator = new Environment()
.registerVariable('email', 'string')
.registerVariable('age', 'int')
.registerFunction('isValidEmail(string): bool',
email => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
)
const valid = validator.evaluate(
'isValidEmail(email) && age >= 18 && age < 120',
{email: 'user@example.com', age: 25n}
)
import {parse} from '@marcbachmann/cel-js'
const flags = {
'new-dashboard': parse(
'user.betaUser || user.id in allowedUserIds'
),
'premium-features': parse(
'user.subscription == "pro" && !user.trialExpired'
)
}
function isEnabled(feature, context) {
return flags[feature]?.(context) ?? false
}
Full TypeScript support included:
import {Environment, evaluate, ParseError} from '@marcbachmann/cel-js'
// Instantiating an environment is expensive, please do that outside hot code paths
const env = new Environment()
.registerVariable('count', 'int')
.registerFunction('multiplyByTwo(int): int', (x) => x * 2n)
const result: any = env.evaluate('multiplyByTwo(count)', {count: 21n})
Contributions welcome! Please open an issue before submitting major changes.
# Run tests
npm test
# Run benchmarks
npm run benchmark
# Run in watch mode
npm run test:watch
MIT © Marc Bachmann
FAQs
A lightweight Common Expression Language (CEL) implementation in JavaScript with zero dependencies
The npm package @marcbachmann/cel-js receives a total of 329,701 weekly downloads. As such, @marcbachmann/cel-js popularity was classified as popular.
We found that @marcbachmann/cel-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
A fake corepack.org site is impersonating the Node.js tool and delivers an infostealer and proxyware to developers who download it.
Research
/Security News
A large-scale campaign abused GitHub Actions in compromised repositories to exploit CVE-2026-41940 in cPanel and WHM and steal server credentials.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.