{"id":11165,"library":"jsep","title":"jsep: Tiny JavaScript Expression Parser","description":"jsep is a lightweight and tiny JavaScript expression parser, currently at a stable version 1.4.0. It is designed specifically for parsing JavaScript expressions, akin to formulas in a spreadsheet, rather than full JavaScript statements or operations. This focus allows it to remain compact compared to more comprehensive parsers like Esprima, while producing an Abstract Syntax Tree (AST) output that is largely compatible with Esprima and SpiderMonkey's Parser API. The library features a flexible plugin architecture, enabling users to extend its capabilities with support for custom operators, literals, and more advanced syntax (e.g., ternary, object literals, async/await) via separate `@jsep-plugin/*` packages. Recent updates, including features like nullish coalescing and exponentiation, suggest an active, albeit not rapid, release cadence.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/EricSmekens/jsep","tags":["javascript","typescript"],"install":[{"cmd":"npm install jsep","lang":"bash","label":"npm"},{"cmd":"yarn add jsep","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsep","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parsing function is the default export. For CommonJS, explicitly access `.default`.","wrong":"const jsep = require('jsep');","symbol":"jsep","correct":"import jsep from 'jsep';"},{"note":"The `Jsep` object provides static methods for parsing and configuration, distinct from the default `jsep` function. This is a named export.","wrong":"import Jsep from 'jsep';","symbol":"Jsep","correct":"import { Jsep } from 'jsep';"},{"note":"Plugin registration happens on the default `jsep` export. Plugins themselves are often default exports of their respective packages.","wrong":"import { Jsep } from 'jsep'; Jsep.plugins.register(myPlugin);","symbol":"jsep.plugins.register","correct":"import jsep from 'jsep';\nimport ternary from '@jsep-plugin/ternary';\njsep.plugins.register(ternary);"},{"note":"Custom operator methods are available directly on the `jsep` default export (the parsing function) as well as static methods on the `Jsep` named export.","wrong":"import { Jsep } from 'jsep'; Jsep.addBinaryOp('^', 10);","symbol":"jsep.addBinaryOp","correct":"import jsep from 'jsep';\njsep.addBinaryOp('^', 10);"}],"quickstart":{"code":"import jsep from 'jsep';\nimport ternary from '@jsep-plugin/ternary';\n\n// Register a built-in plugin (ternary is default but shown for illustration)\njsep.plugins.register(ternary);\n\n// Add a custom operator (e.g., bitwise XOR)\njsep.addBinaryOp('^', 10);\n\n// Parse a simple expression\nconst simpleAst = jsep('1 + 2 * 3');\nconsole.log('Simple AST:', JSON.stringify(simpleAst, null, 2));\n\n// Parse an expression with a custom operator\nconst customOpAst = jsep('5 ^ 3');\nconsole.log('Custom Operator AST:', JSON.stringify(customOpAst, null, 2));\n\n// Parse a complex expression with ternary operator\nconst complexAst = jsep('a > b ? a : b');\nconsole.log('Complex AST (ternary):', JSON.stringify(complexAst, null, 2));\n\n// Demonstrate AST structure for a nullish coalescing operator (introduced in v1.4.0)\nconst nullishCoalescingAst = jsep('value ?? defaultValue');\nconsole.log('Nullish Coalescing AST:', JSON.stringify(nullishCoalescingAst, null, 2));","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure input strings are valid JavaScript expressions. For full JavaScript parsing, consider alternatives like Esprima or Acorn.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install the relevant `@jsep-plugin/*` packages from npm and register them using `jsep.plugins.register(plugin)` before parsing expressions that use those features.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"},{"fix":"Carefully define `precedence` and `rightToLeft` parameters for `addBinaryOp` and `addUnaryOp`. Consult standard JavaScript operator precedence for guidance.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const jsep = require('jsep');` to `const jsep = require('jsep').default;`","cause":"In CommonJS environments, `require('jsep')` returns the module object, not the default parsing function directly. The parsing function is available via `.default`.","error":"TypeError: jsep is not a function"},{"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()`.","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.","error":"SyntaxError: Unexpected token"},{"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.","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`).","error":"TypeError: Cannot read properties of undefined (reading 'register')"}],"ecosystem":"npm"}