{"id":19218148,"url":"https://github.com/nx-js/compiler-util","last_synced_at":"2025-04-07T11:09:17.677Z","repository":{"id":45788289,"uuid":"60166888","full_name":"nx-js/compiler-util","owner":"nx-js","description":"An NX utility, responsible for executing code in the context of an object.","archived":false,"fork":false,"pushed_at":"2018-06-08T15:28:22.000Z","size":115,"stargazers_count":164,"open_issues_count":5,"forks_count":19,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T10:03:14.732Z","etag":null,"topics":["compile","es6","eval","javascript","scoped"],"latest_commit_sha":null,"homepage":"http://www.nx-framework.com/","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/nx-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-01T10:13:56.000Z","updated_at":"2024-11-08T01:39:22.000Z","dependencies_parsed_at":"2022-07-16T14:46:59.411Z","dependency_job_id":null,"html_url":"https://github.com/nx-js/compiler-util","commit_stats":null,"previous_names":["risingstack/nx-compile"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nx-js%2Fcompiler-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nx-js%2Fcompiler-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nx-js%2Fcompiler-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nx-js%2Fcompiler-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nx-js","download_url":"https://codeload.github.com/nx-js/compiler-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"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":["compile","es6","eval","javascript","scoped"],"created_at":"2024-11-09T14:25:28.185Z","updated_at":"2025-04-07T11:09:17.643Z","avatar_url":"https://github.com/nx-js.png","language":"JavaScript","readme":"# The compiler util\n\nThis library is part of the [NX framework](http://nx-framework.com).\n\nThe main purpose of this library is to allow the execution of strings as code in the\ncontext of an object.\n\n## Installation\n\n```\n$ npm install @nx-js/compiler-util\n```\n\n## Platform support\n\n- Node: 6 and above\n- Chrome: 49 and above (after browserified)\n- Firefox: 38 and above (after browserified)\n- Safari: 10 and above (after browserified)\n- Edge: 12 and above (after browserified)\n- Opera: 36 and above (after browserified)\n- IE is not supported\n\n## Usage\n\n```js\nconst compiler = require('@nx-js/compiler-util')\n```\n\n### Compiling code\n\n`compiler.compileCode(string)` creates a function from a string. The returned function takes\nan object as argument and executes the string as code in the context of the passed object.\nThe string can be any valid JavaScript code.\n\n```js\nconst code = compiler.compileCode('return prop1 + prop2')\nconst sum = code({prop1: 1, prop2: 2}) // sum is 3\n```\n\n#### Temporary variables\n\nThe returned function also accepts a second object argument, that may contain temporary variables.\nTemporary variables are added to the context object while the code is executing.\nThey are favored over the permanent context variables.\n\n```js\nconst code = compiler.compileCode('return prop1 + prop2')\nconst context = {prop1: 1, prop2: 2}\nconst temporary = {prop1: 2}\nconst sum = code(context, temporary) // sum is 4, context is still {prop1: 1, prop2: 2}\n```\n\n#### Limiters\n\nLimiters are functions, which can defer or block code execution. Some popular limiters are debounce and throttle for example. Limiters can be registered by name with `compiler.limiter(name, function)` and used at the end of the code with the `\u0026` symbol.\n\n```js\n// next is the code or the next limiter\ncompiler.limiter('delay', next =\u003e setTimeout(next, 1000))\n\nconst code = compiler.compileCode('console.log(message) \u0026 delay')\nconst context = {message: 'Hello World'}\ncode(context) // prints 'Hello World' to the console after a second\n```\n\nLimiters accept a context object, which can be used to share a context between executions of the code. It makes the creation of rate limiters - like throttle and debounce - straightforward.\n\n```js\ncompiler.limiter('debounce', debounce)\n\nfunction debounce (next, context) {\n  clearTimeout(context.timer)\n  context.timer = setTimeout(next, 200)\n}\n```\n\nAfter the context argument limiters accept any number of custom arguments. These can be passed after the limiter name in the code, separated by spaces.\n\n```js\ncompiler.limiter('delay', (next, context, amount) =\u003e setTimeout(next, amount))\n\nconst code = compiler.compileCode('console.log(message) \u0026 delay 2000')\nconst code2 = compiler.compileCode('console.log(message) \u0026 delay amount')\n\nconst context = {message: 'Hello World', amount: 3000}\ncode(context) // prints 'Hello World' to the console after 2 seconds\ncode2(context) // prints 'Hello World' to the console after 3 seconds\n```\n\nMultiple limiters can be piped with the `\u0026` symbol.\n\n```js\nconst code = compiler.compileCode('console.log(message) \u0026 delay 1000 \u0026 throttle 100')\n\n// this logs 'Hello World' a second after you click the button\n// and it logs a message once per 100 milliseconds at most, excess messages are not logged\nbutton.addEventListener('code', () =\u003e code({message: 'Hello World'}))\n```\n\nYou can find some commonly used limiters in [this repo](https://github.com/nx-js/limiters).\n\n### Compiling expressions\n\n`compiler.compileExpression(string)` creates a function from a string. The returned function takes\nan object as argument and executes the string as an expression in the context of the passed object.\nIt returns the result of the evaluated expression. The string can be any javascript expression\nthat may come after a return statement.\n\n```js\nconst expression = compiler.compileExpression('prop1 || prop2')\nconst result = expression({prop2: 'Hello'}) // result is 'Hello'\n```\n\nExpressions return undefined instead of throwing a TypeError on invalid property access.\nThis allows lazy initialization of your data.\n\n```js\nconst expression = compiler.compileExpression('item.name')\nconst context = {}\n\nlet result = expression(context) // result is undefined, no error is thrown\n\ncontext.item = {name: 'item name'}\nresult = expression(context) // result is 'item name'\n```\n\n#### Filters\n\nFilters are functions, which can filter and modify expression result. Some popular filters are upperCase and trim for example. Filters can be registered by name with `compiler.filter(name, function)` and used at the end of the expression with the `|` symbol.\n\n```js\n// txt is the result of the expression\ncompiler.filter('upperCase', txt =\u003e txt.toUpperCase())\n\nconst expr = compiler.compileExpression('message | upperCase')\nconst context = {message: 'Hello World'}\nconsole.log(expr(context)) // prints 'HELLO WORLD' to the console\n```\n\nFilters accept any number of custom arguments. These can be passed after the filter name in the expression, separated by spaces.\n\n```js\ncompiler.filter('splice', (txt, start, end) =\u003e txt.splice(start, end))\n\nconst expr = compiler.compileExpression('message | splice 0 6')\nconst context = {message: 'Hello World'}\nconsole.log(expr(context)) // prints 'Hello' to the console\n```\n\nMultiple filters can be piped with the `|` symbol.\n\n```js\nconst expr = compiler.compileExpression('message | splice 0 6 | upperCase')\nconst context = {message: 'Hello World'}\nconsole.log(expr(context)) // prints 'HELLO' to the console\n```\n\nYou can find some commonly used filters in [this repo](https://github.com/nx-js/filters).\n\n### Handling globals\n\n`compiler.expose('String, String, ...')` exposes globals by name for the compiler. Non of the globals are exposed by default.\n\n```js\nconst code = compiler.compileCode('console.log(Math.round(num))')\ncompiler.expose('console', 'Math')\ncode({num: 1.8}) // logs 2 to the console\n```\n\nContext variables are always favored over global ones, when both are present with the same name.\n\n`compiler.hide(String, String, ...)` hides globals by name, while `compiler.hideAll()` hides all globals.\n\n```js\nconst code = compiler.compileCode('console.log(Math.round(num))')\ncompiler.expose('console', 'Math')\ncode({num: 1.8}) // logs 2 to the console\ncompiler.hide('console', 'Math')\ncode({num: 1.8}) // throws an error, console and Math are undefined\n```\n\n## Alternative builds\n\nThis library detects if you use ES or commonJS modules and serve the right format to you. The exposed bundles are transpiled to ES5 to support common tools - like UglifyJS. If you would like a finer control over the provided build, you can specify them in your imports.\n\n* `@nx-js/compiler-util/dist/es.es6.js` exposes an ES6 build with ES modules.\n* `@nx-js/compiler-util/dist/es.es5.js` exposes an ES5 build with ES modules.\n* `@nx-js/compiler-util/dist/cjs.es6.js` exposes an ES6 build with commonJS modules.\n* `@nx-js/compiler-util/dist/cjs.es5.js` exposes an ES5 build with commonJS modules.\n\nIf you use a bundler, set up an alias for `@nx-js/compiler-util` to point to your desired build. You can learn how to do it with webpack [here](https://webpack.js.org/configuration/resolve/#resolve-alias) and with rollup [here](https://github.com/rollup/rollup-plugin-alias#usage).\n\n## Contributions\n\nThis library has the very specific purpose of supporting the\n[NX framework](https://github.com/nx-js/framework).\nFeatures should only be added, if they are used by the framework. Otherwise please fork.\n\nBug fixes, tests and doc updates are always welcome.\nTests and linter (standardJS) must pass.\n\n## Authors\n\n  - [Miklos Bertalan](https://github.com/solkimicreb)\n\n# License\n\n  MIT\n","funding_links":[],"categories":["Proxy Resources"],"sub_categories":["Modules"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnx-js%2Fcompiler-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnx-js%2Fcompiler-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnx-js%2Fcompiler-util/lists"}