{"id":13438835,"url":"https://github.com/EricSmekens/jsep","last_synced_at":"2025-03-20T06:31:27.667Z","repository":{"id":3458721,"uuid":"4512746","full_name":"EricSmekens/jsep","owner":"EricSmekens","description":"JavaScript Expression Parser","archived":false,"fork":false,"pushed_at":"2024-10-27T20:47:39.000Z","size":1837,"stargazers_count":835,"open_issues_count":40,"forks_count":136,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-30T05:09:58.953Z","etag":null,"topics":["expression-parser","hacktoberfest","javascript","jsep"],"latest_commit_sha":null,"homepage":"http://ericsmekens.github.io/jsep/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EricSmekens.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-05-31T20:48:09.000Z","updated_at":"2024-10-30T04:48:15.000Z","dependencies_parsed_at":"2024-03-27T05:22:38.087Z","dependency_job_id":"4cdf8b13-176b-436e-81d4-281dc74d1e2c","html_url":"https://github.com/EricSmekens/jsep","commit_stats":{"total_commits":349,"total_committers":27,"mean_commits":"12.925925925925926","dds":0.6361031518624642,"last_synced_commit":"72e045878a8237f30184cc7d6ae3f0dcd58a4ef5"},"previous_names":["soney/jsep"],"tags_count":104,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricSmekens%2Fjsep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricSmekens%2Fjsep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricSmekens%2Fjsep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricSmekens%2Fjsep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EricSmekens","download_url":"https://codeload.github.com/EricSmekens/jsep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244502511,"owners_count":20463026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["expression-parser","hacktoberfest","javascript","jsep"],"created_at":"2024-07-31T03:01:08.838Z","updated_at":"2025-03-20T06:31:27.661Z","avatar_url":"https://github.com/EricSmekens.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"## jsep: A Tiny JavaScript Expression Parser\n\n[jsep](https://ericsmekens.github.io/jsep/) is a simple expression parser written in JavaScript. It can parse JavaScript expressions but not operations. The difference between expressions and operations is akin to the difference between a cell in an Excel spreadsheet vs. a proper JavaScript program.\n\n### Why jsep?\n\nI wanted a lightweight, tiny parser to be included in one of my other libraries. [esprima](http://esprima.org/) and other parsers are great, but had more power than I need and were *way* too large to be included in a library that I wanted to keep relatively small.\n\njsep's output is almost identical to [esprima's](http://esprima.org/doc/index.html#ast), which is in turn based on [SpiderMonkey's](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API).\n\n### Custom Build\n\nWhile in the jsep project directory, run:\n\n```bash\nnpm install\nnpm run default\n```\n\nThe jsep built files will be in the build/ directory.\n\n### Usage\n\n#### Client-side\n\n```html\n\u003cscript type=\"module\"\u003e\n  import jsep from '/PATH/TO/jsep.min.js';\n  const parsed = jsep('1 + 1');\n\u003c/script\u003e\n\n\u003cscript src=\"/PATH/TO/jsep.iife.min.js\"\u003e\u003c/script\u003e\n  ...\nlet parse_tree = jsep(\"1 + 1\");\n```\n\n#### Node.JS\n\nFirst, run `npm install jsep`. Then, in your source file:\n\n```javascript\n// ESM:\nimport jsep from 'jsep';\nconst parse_tree = jsep('1 + 1');\n\n// or:\nimport { Jsep } from 'jsep';\nconst parse_tree = Jsep.parse('1 + 1');\n\n\n// CJS:\nconst jsep = require('jsep').default;\nconst parsed = jsep('1 + 1');\n\n// or:\nconst { Jsep } = require('jsep');\nconst parse_tree = Jsep.parse('1 + 1');\n```\n\n#### Custom Operators\n\n```javascript\n// Add a custom ^ binary operator with precedence 10\n// (Note that higher number = higher precedence)\njsep.addBinaryOp(\"^\", 10);\n\n// Add exponentiation operator (right-to-left)\njsep.addBinaryOp('**', 11, true); // now included by default\n\n// Add a custom @ unary operator\njsep.addUnaryOp('@');\n\n// Remove a binary operator\njsep.removeBinaryOp(\"\u003e\u003e\u003e\");\n\n// Remove a unary operator\njsep.removeUnaryOp(\"~\");\n```\n\n#### Custom Identifiers\n\nYou can add or remove additional valid identifier chars. ('_' and '$' are already treated like this.)\n\n```javascript\n// Add a custom @ identifier\njsep.addIdentifierChar(\"@\");\n\n// Removes a custom @ identifier\njsep.removeIdentifierChar('@');\n```\n\n#### Custom Literals\n\nYou can add or remove additional valid literals. By default, only `true`, `false`, and `null` are defined\n```javascript\n// Add standard JS literals:\njsep.addLiteral('undefined', undefined);\njsep.addLiteral('Infinity', Infinity);\njsep.addLiteral('NaN', NaN);\n\n// Remove \"null\" literal from default definition\njsep.removeLiteral('null');\n```\n\n### Plugins\nJSEP supports defining custom hooks for extending or modifying the expression parsing.\nPlugins are registered by calling `jsep.plugins.register()` with the plugin(s) as the argument(s).\n\n#### JSEP-provided plugins:\n|                                   |                                                                                           |\n|-----------------------------------|-------------------------------------------------------------------------------------------|\n| [ternary](packages/ternary)       | Built-in by default, adds support for ternary `a ? b : c` expressions                     |\n| [arrow](packages/arrow)           | Adds arrow-function support: `v =\u003e !!v`                                                   |\n| [assignment](packages/assignment) | Adds assignment and update expression support: `a = 2`, `a++`                             |\n| [comment](packages/comment)       | Adds support for ignoring comments: `a /* ignore this */ \u003e 1 // ignore this too`          |\n| [new](packages/new)               | Adds 'new' keyword support: `new Date()`                                                  |\n| [numbers](packages/numbers)       | Adds hex, octal, and binary number support, ignore _ char                                 |\n| [object](packages/object)         | Adds object expression support: `{ a: 1, b: { c }}`                                       |\n| [regex](packages/regex)           | Adds support for regular expression literals: `/[a-z]{2}/ig`                              |\n| [spread](packages/spread)         | Adds support for the spread operator, `fn(...[1, ...a])`. Works with `object` plugin, too |\n| [template](packages/template)     | Adds template literal support: `` `hi ${name}` ``                                         |\n|                                   |                                                                                           |\n\n#### How to add plugins:\nPlugins have a `name` property so that they can only be registered once.\nAny subsequent registrations will have no effect. Add a plugin by registering it with JSEP:\n\n```javascript\nimport jsep from 'jsep';\nimport ternary from '@jsep-plugin/ternary';\nimport object from '@jsep-plugin/object';\njsep.plugins.register(object);\njsep.plugins.register(ternary, object);\n```\n\n#### List plugins:\nPlugins are stored in an object, keyed by their name.\nThey can be retrieved through `jsep.plugins.registered`.\n\n#### Writing Your Own Plugin:\nPlugins are objects with two properties: `name` and `init`.\nHere's a simple plugin example:\n```javascript\nconst plugin = {\n  name: 'the plugin',\n  init(jsep) {\n    jsep.addIdentifierChar('@');\n    jsep.hooks.add('gobble-expression', function myPlugin(env) {\n      if (this.char === '@') {\n        this.index += 1;\n        env.node = {\n          type: 'MyCustom@Detector',\n        };\n      }\n    });\n  },\n};\n```\nThis example would treat the `@` character as a custom expression, returning\na node of type `MyCustom@Detector`.\n\n##### Hooks\nMost plugins will make use of hooks to modify the parsing behavior of jsep.\nAll hooks are bound to the jsep instance, are called with a single argument, and return void.\nThe `this` context provides access to the internal parsing methods of jsep\nto allow reuse as needed. Some hook types will pass an object that allows reading/writing\nthe `node` property as needed.\n\n##### Hook Types\n* `before-all`: called just before starting all expression parsing.\n* `after-all`: called after parsing all. Read/Write `arg.node` as required.\n* `gobble-expression`: called just before attempting to parse an expression. Set `arg.node` as required.\n* `after-expression`: called just after parsing an expression. Read/Write `arg.node` as required.\n* `gobble-token`: called just before attempting to parse a token. Set `arg.node` as required.\n* `after-token`: called just after parsing a token. Read/Write `arg.node` as required.\n* `gobble-spaces`: called when gobbling whitespace.\n\n##### The `this` context of Hooks\n```typescript\nexport interface HookScope {\n    index: number;\n    readonly expr: string;\n    readonly char: string; // current character of the expression\n    readonly code: number; // current character code of the expression\n    gobbleSpaces: () =\u003e void;\n    gobbleExpressions: (untilICode?: number) =\u003e Expression[];\n    gobbleExpression: () =\u003e Expression;\n    gobbleBinaryOp: () =\u003e PossibleExpression;\n    gobbleBinaryExpression: () =\u003e PossibleExpression;\n    gobbleToken: () =\u003e PossibleExpression;\n    gobbleTokenProperty: (node: Expression) =\u003e Expression;\n    gobbleNumericLiteral: () =\u003e PossibleExpression;\n    gobbleStringLiteral: () =\u003e PossibleExpression;\n    gobbleIdentifier: () =\u003e PossibleExpression;\n    gobbleArguments: (untilICode: number) =\u003e PossibleExpression;\n    gobbleGroup: () =\u003e Expression;\n    gobbleArray: () =\u003e PossibleExpression;\n    throwError: (msg: string) =\u003e never;\n}\n```\n\n### License\n\njsep is under the MIT license. See LICENSE file.\n\n### Thanks\n\nSome parts of the latest version of jsep were adapted from the esprima parser.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEricSmekens%2Fjsep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEricSmekens%2Fjsep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEricSmekens%2Fjsep/lists"}