jsep: Tiny JavaScript Expression Parser

Common errors

• TypeError: jsep is not a function

  cause In CommonJS environments, `require('jsep')` returns the module object, not the default parsing function directly. The parsing function is available via `.default`.
  fix Change `const jsep = require('jsep');` to `const jsep = require('jsep').default;`

• SyntaxError: Unexpected token

  cause Attempting to parse a JavaScript statement (e.g., variable declarations, control flow) or an unsupported expression feature (like object literals, arrow functions) without the corresponding plugin registered.
  fix Ensure the input is a valid JavaScript expression. If using advanced syntax, verify that the necessary `@jsep-plugin/*` packages are installed and registered via `jsep.plugins.register()`.

• TypeError: Cannot read properties of undefined (reading 'register')

  cause Attempting to call `jsep.plugins.register` before `jsep` has been imported, or if `jsep` was imported incorrectly (e.g., `import { Jsep } from 'jsep';` and then trying `Jsep.plugins.register`).
  fix Ensure `jsep` is correctly imported as the default export (e.g., `import jsep from 'jsep';` for ESM or `const jsep = require('jsep').default;` for CJS) before attempting to access its `plugins` property.

Warnings

• gotcha jsep is strictly an 'expression parser' and cannot parse full JavaScript statements (e.g., `if`, `for`, `var`). Attempting to parse statements will result in syntax errors.
  Fix: Ensure input strings are valid JavaScript expressions. For full JavaScript parsing, consider alternatives like Esprima or Acorn.
• gotcha Many common JavaScript features (like object literals, arrow functions, `new` expressions, async/await, regex literals) are implemented as separate `@jsep-plugin/*` packages and are not included by default. These plugins must be explicitly installed and registered.
  Fix: Install the relevant `@jsep-plugin/*` packages from npm and register them using `jsep.plugins.register(plugin)` before parsing expressions that use those features.
• breaking Major version upgrades (e.g., from v0.x to v1.x) historically introduced breaking changes, particularly in the structure of the generated Abstract Syntax Tree (AST) and the API for developing custom plugins. Always consult the migration guide when upgrading major versions.
  Fix: Review the official changelog and migration guides for your specific version upgrade path to understand and adapt to AST structure changes or API modifications. Test thoroughly.
• gotcha When defining custom operators, incorrect precedence or associativity can lead to unexpected parsing results. Precedence is numerical (higher = tighter binding); associativity (left-to-right or right-to-left) is crucial for operators like exponentiation.
  Fix: Carefully define `precedence` and `rightToLeft` parameters for `addBinaryOp` and `addUnaryOp`. Consult standard JavaScript operator precedence for guidance.

Install

• npm install jsep npm
• yarn add jsep yarn
• pnpm add jsep pnpm

Imports

• jsep
  wrong:

  const jsep = require('jsep');

  correct:

  import jsep from 'jsep';

  The primary parsing function is the default export. For CommonJS, explicitly access `.default`.
• Jsep
  wrong:

  import Jsep from 'jsep';

  correct:

  import { Jsep } from 'jsep';

  The `Jsep` object provides static methods for parsing and configuration, distinct from the default `jsep` function. This is a named export.
• jsep.plugins.register
  wrong:

  import { Jsep } from 'jsep'; Jsep.plugins.register(myPlugin);

  correct:

  import jsep from 'jsep';
  import ternary from '@jsep-plugin/ternary';
  jsep.plugins.register(ternary);

  Plugin registration happens on the default `jsep` export. Plugins themselves are often default exports of their respective packages.
• jsep.addBinaryOp
  wrong:

  import { Jsep } from 'jsep'; Jsep.addBinaryOp('^', 10);

  correct:

  import jsep from 'jsep';
  jsep.addBinaryOp('^', 10);

  Custom operator methods are available directly on the `jsep` default export (the parsing function) as well as static methods on the `Jsep` named export.

Quickstart

This quickstart demonstrates importing `jsep`, registering an optional plugin (like ternary), adding a custom binary operator, and parsing various JavaScript expressions to observe their Abstract Syntax Tree (AST) output.

import jsep from 'jsep';
import ternary from '@jsep-plugin/ternary';

// Register a built-in plugin (ternary is default but shown for illustration)
jsep.plugins.register(ternary);

// Add a custom operator (e.g., bitwise XOR)
jsep.addBinaryOp('^', 10);

// Parse a simple expression
const simpleAst = jsep('1 + 2 * 3');
console.log('Simple AST:', JSON.stringify(simpleAst, null, 2));

// Parse an expression with a custom operator
const customOpAst = jsep('5 ^ 3');
console.log('Custom Operator AST:', JSON.stringify(customOpAst, null, 2));

// Parse a complex expression with ternary operator
const complexAst = jsep('a > b ? a : b');
console.log('Complex AST (ternary):', JSON.stringify(complexAst, null, 2));

// Demonstrate AST structure for a nullish coalescing operator (introduced in v1.4.0)
const nullishCoalescingAst = jsep('value ?? defaultValue');
console.log('Nullish Coalescing AST:', JSON.stringify(nullishCoalescingAst, null, 2));