@agentix-e/spel-ts

Pure TypeScript Spring Expression Language (SpEL) evaluator — zero native dependencies, browser & Node.js ready.

What is @agentix-e/spel-ts?

@agentix-e/spel-ts is a pure TypeScript implementation of the Spring Expression Language (SpEL). It parses and evaluates SpEL expressions in any JavaScript environment — browsers, Node.js, Deno, and edge runtimes — without any native dependencies or JVM requirement. It implements the full SpEL grammar (literals, operators, collections, type references, bean references, method invocation, constructor invocation, ternary/elvis operators, safe navigation, collection selection/projection) matching Spring Framework's official semantics exactly.

When should I use it?

• You need runtime expression evaluation in a TypeScript/JavaScript application
• You're building a rules engine, workflow system, or dynamic configuration platform
• You want Spring ecosystem compatibility without running a JVM
• You need an embeddable expression language with zero external dependencies

Quick Start

npm install @agentix-e/spel-ts

import { SpelExpressionParser, StandardEvaluationContext } from '@agentix-e/spel-ts';

const parser = new SpelExpressionParser();

// Simple evaluation
parser.parseExpression('2 + 3 * 4').getValue();        // 14
parser.parseExpression("'hello' + ' world'").getValue(); // 'hello world'

// With variables
const ctx = new StandardEvaluationContext();
ctx.setVariable('score', 85);
parser.parseExpression('#score >= 60 ? "PASS" : "FAIL"').getValueWithContext(ctx); // 'PASS'

// With root object
const dataCtx = new StandardEvaluationContext({ user: { name: 'Alice', age: 30 } });
parser.parseExpression('user.age > 18').getValueWithContext(dataCtx); // true

Supported Syntax

Literals

| Type | Example | |------|---------| | null | null | | boolean | true, false | | integer | 42, 0xFF | | long | 42L, 999l | | float/double | 3.14, 2.5F, 1.5E+2 | | string | 'hello', "world", 'it''s' |

Integers outside the range a JavaScript number represents exactly (beyond 2^53) are carried as BigInt, so 9007199254740993L keeps its exact value and getValue() returns a bigint for it. Smaller integers are returned as number, as before.

Operators

| Category | Operators | |----------|-----------| | Arithmetic | +, -, *, /, %, mod, ^ | | Comparison | ==, eq, !=, ne, <, lt, <=, le, >, gt, >=, ge | | Logical | &&, and, \|\|, or, !, not | | Special | matches, between, instanceof, .. (range) | | Conditional | ? : (ternary), ?: (elvis) | | Assignment | = | | Increment/Decrement | ++, -- (prefix & postfix) |

Collections & Navigation

| Feature | Syntax | |---------|--------| | Inline list | {1, 2, 3} | | Inline map | {'key': 'value', 'k2': 'v2'} | | Property chain | a.b.c | | Safe navigation | a?.b | | Selection | list.?[#this > 5] | | Selection (first) | list.^[#this > 5] | | Selection (last) | list.$[#this > 5] | | Projection | list.![#this.name] | | Indexer | a[0], map['key'] | | Variable | #varName, #this |

Types & Beans

| Feature | Syntax | |---------|--------| | Type reference | T(java.lang.Math) | | Constructor | new java.util.Date() | | Bean reference | @myBean | | Factory bean | &@factory |

API Reference

Full API documentation is available at: https://AgentiX-E.github.io/spel-ts/

Core Classes

import {
  SpelExpressionParser,    // Main entry point for parsing expressions
  SpelExpression,           // Compiled expression (AST)
  StandardEvaluationContext, // Default evaluation context
  SpelParserConfiguration,  // Parser options
  TypedValue,               // Value + type descriptor wrapper
  SpelMessage,              // Error code enum (49 entries)
  // Interfaces
  EvaluationContext,
  PropertyAccessor,
  MethodResolver,
  TypeLocator,
  BeanResolver,
} from '@agentix-e/spel-ts';

Project Status

| Metric | Value | |--------|-------| | Tests | 1,110 passing | | Coverage | 96.16% statements / 95.17% branches | | TypeScript | 5.x strict mode | | Bundles | ESM + CJS | | Dependencies | 0 runtime dependencies |

FAQ

Is spel-ts fully compatible with Spring's SpEL?

Yes. spel-ts implements the complete SpEL grammar specification and passes 1,110+ test cases covering all operator types, collection operations, type references, and edge cases defined in the Spring reference manual.

Can I use it in the browser?

Yes. spel-ts has zero native dependencies and ships as both ESM and CJS bundles. It has been tested in Chrome, Firefox, Safari, and Edge.

How does it compare to other expression evaluators?

Unlike generic expression parsers (mathjs, expr-eval), spel-ts specifically targets Spring SpEL compatibility — making it the only choice for projects migrating from or integrating with Spring ecosystems.

What's the performance like?

The parser is hand-written (not generated) and optimized for TypeScript. Typical expressions evaluate in microseconds. Over 1,500 tests validate correctness and performance characteristics, including an executable conformance corpus that cites the Spring Framework for every case.

License

MIT © AgentiX-E

Ecosystem

• @agentix-e/nl2spel — Natural language → SpEL expression generation engine
• @agentix-e/spel-editor — Web-embeddable SpEL editor (CodeMirror 6 + spel-ts powered)