SpEL2JS Parser

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in a pure ES module environment (e.g., in a modern Node.js project with `"type": "module"` in `package.json` or in a browser via modern bundlers).
  fix Change `const spel2js = require('spel2js');` to `import spel2js from 'spel2js';` and `const { StandardContext, SpelExpressionEvaluator } = require('spel2js');` to `import { StandardContext, SpelExpressionEvaluator } from 'spel2js';`.

• TypeError: spel2js is not a constructor

  cause Attempting to instantiate `spel2js` using `new spel2js()`. The library exports a pre-made singleton object, not a class or constructor.
  fix Remove `new` keyword. Access its members directly, e.g., `spel2js.StandardContext` or `spel2js.SpelExpressionEvaluator`.

• Error: Invalid argument type: null. Expected: [object Object]

  cause Passing `null` or `undefined` for `authentication` or `principal` arguments to `StandardContext.create()` when the SpEL expression expects properties from these objects, or when the library internally expects object references.
  fix Ensure that `authentication` and `principal` passed to `StandardContext.create()` are always valid object structures, even if empty, to avoid type validation errors within the library. Initialize them as `{}` if no specific data is available.

Warnings

• breaking The license for spel2js was changed from MIT to Apache License. This change affects how the software can be used and distributed, requiring adherence to the Apache License 2.0 terms.
  Fix: Review and comply with the Apache License 2.0 terms. If prior versions under MIT were used, consider implications of updating.
• gotcha SpEL2JS aims to replicate Java SpEL behavior but may exhibit subtle differences for complex expressions due to inherent differences between Java and JavaScript runtimes. The project maintainer explicitly states, 'if you come accross an expression that behaves differently than you would expect then please open an issue.'
  Fix: Thoroughly test complex SpEL expressions in JavaScript to ensure they produce identical results to their Java counterparts, especially for security-sensitive logic. Open issues for discrepancies.
• gotcha The project appears to be unmaintained, with the last significant release activity around 2016. This means it may not be compatible with modern JavaScript features, build tools, or Node.js versions beyond `8.x` (as specified in `engines`). It also implies potential unaddressed security vulnerabilities or bugs.
  Fix: Exercise caution when using in new projects. Consider forking and updating for modern compatibility, or carefully vetting for security issues. Expect manual intervention for ESM compatibility in many build environments.
• gotcha The `StandardContext.create()` method expects `authentication` and `principal` arguments that mimic Spring Security's `Authentication` class and a principal object. Developers must construct these JavaScript objects manually to match the expected structure, which can be error-prone if not accurately replicated.
  Fix: Ensure the `authentication` and `principal` objects passed to `StandardContext.create()` precisely match the structure and properties expected by `spel2js` as documented or reverse-engineered from its source code, especially for properties accessed within SpEL expressions (e.g., `authentication.details.name`).

Install

• npm install spel2js npm
• yarn add spel2js yarn
• pnpm add spel2js pnpm

Imports

• spel2js
  wrong:

  import { spel2js } from 'spel2js';

  correct:

  import spel2js from 'spel2js';

  The library exports a default singleton object containing `StandardContext` and `SpelExpressionEvaluator`.
• StandardContext, SpelExpressionEvaluator
  wrong:

  const { StandardContext, SpelExpressionEvaluator } = require('spel2js');

  correct:

  import { StandardContext, SpelExpressionEvaluator } from 'spel2js';

  While CommonJS `require` might work in older Node.js environments, modern projects should use ES module imports for direct access to these properties from the default export object.
• require('spel2js')
  wrong:

  import spel2js from 'spel2js';

  correct:

  const spel2js = require('spel2js');

  For CommonJS environments, the entire module is imported as a singleton object. Direct named imports (`import { Name } from 'pkg'`) may not work as expected in pure CJS without transpilation or specific interop settings.

Quickstart

This quickstart demonstrates how to set up an evaluation context, define local variables, and then evaluate a Spring Expression Language (SpEL) expression using `SpelExpressionEvaluator.eval()` or a pre-compiled expression.

import { StandardContext, SpelExpressionEvaluator } from 'spel2js';

// Mock Spring Security Authentication object and a principal object
const mockAuthentication = {
  details: {
    name: 'Darth Vader'
  },
  isAuthenticated: true
};

const mockPrincipal = {
  username: 'dvader',
  roles: ['SITH_LORD', 'EMPIRE_ADMIRAL']
};

// Locals represent specific objects in the expression context
const locals = {
  toDoList: {
    owner: 'Darth Vader',
    items: ['Destroy Alderaan', 'Build Death Star']
  }
};

const expression = '#toDoList.owner == authentication.details.name && authentication.isAuthenticated';

// Create an evaluation context with mock data
const spelContext = StandardContext.create(mockAuthentication, mockPrincipal);

// Evaluate the expression directly
const result = SpelExpressionEvaluator.eval(expression, spelContext, locals);

console.log(`Expression: "${expression}"`);
console.log(`Result: ${result}`); // Expected: true

// Example of pre-compiling an expression for reuse
const compiledExpression = SpelExpressionEvaluator.compile('#toDoList.items.size() > 1');
const compiledResult = compiledExpression.eval(spelContext, locals);
console.log(`Compiled expression result: ${compiledResult}`); // Expected: true