feat(beta): add filters and rate limiters and update for NX beta

Author: solkimicreb

README.md

@@ -1,14 +1,14 @@
-# nx-compile
+# The compiler util
 
 This library is part of the [NX framework](http://nx-framework.com).
 
-The purpose of this library is to allow the execution of strings as code in the
-context of an object. It combines ES6 Proxies with the JavaScript `with` keyword to achieve this.
+The main purpose of this library is to allow the execution of strings as code in the
+context of an object.
 
 ## Installation
 
 ```
-$ npm install @risingstack/nx-compile
+$ npm install @nx-js/compiler-util
 ```
 
 ## Platform support
@@ -24,24 +24,24 @@ $ npm install @risingstack/nx-compile
 ## Usage
 
 ```js
-const compiler = require('@risingstack/nx-compile')
+const compiler = require('@nx-js/compiler-util')
 ```
 
-## API
+### Compiling code
 
-### compiler.compileCode(String)
-
-This method creates a function out of a string and returns it. The returned function takes
+`compiler.compileCode(string)` creates a function from a string. The returned function takes
 an object as argument and executes the string as code in the context of the passed object.
-The string can be any valid javascript code.
+The string can be any valid JavaScript code.
 
 ```js
 const code = compiler.compileCode('return prop1 + prop2')
 const sum = code({prop1: 1, prop2: 2}) // sum is 3
 ```
 
+#### Temporary variables
+
 The returned function also accepts a second object argument, that may contain temporary variables.
-Temporary variables are added to the context object while the code is executing and removed after.
+Temporary variables are added to the context object while the code is executing.
 They are favored over the permanent context variables.
 
 ```js
@@ -51,9 +51,58 @@ const temporary = {prop1: 2}
 const sum = code(context, temporary) // sum is 4, context is still {prop1: 1, prop2: 2}
 ```
 
-### compiler.compileExpression(String)
+#### Limiters
+
+Limiters 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 `&` symbol.
+
+```js
+// next is the code or the next limiter
+compiler.limiter('delay', next => setTimeout(next, 1000))
+
+const code = compiler.compileCode('console.log(message) & delay')
+const context = {message: 'Hello World'}
+code(context) // prints 'Hello World' to the console after a second
+```
+
+Limiters 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.
+
+```js
+compiler.limiter('debounce', debounce)
+
+function debounce (next, context) {
+  clearTimeout(context.timer)
+  context.timer = setTimeout(next, 200)
+}
+```
+
+After the context argument limiters accept any number of custom arguments. These can be passed after the limiter name in the code, separated by spaces.
+
+```js
+compiler.limiter('delay', (next, context, amount) => setTimeout(next, amount))
+
+const code = compiler.compileCode('console.log(message) & delay 2000')
+const code2 = compiler.compileCode('console.log(message) & delay amount')
+
+const context = {message: 'Hello World', amount: 3000}
+code(context) // prints 'Hello World' to the console after 2 seconds
+code2(context) // prints 'Hello World' to the console after 3 seconds
+```
+
+Multiple limiters can be piped with the `&` symbol.
+
+```js
+const code = compiler.compileCode('console.log(message) & delay 1000 & throttle 100')
+
+// this logs 'Hello World' a second after you click the button
+// and it logs a message once per 100 milliseconds at most, excess messages are not logged
+button.addEventListener('code', () => code({message: 'Hello World'}))
+```
+
+You can find some commonly used limiters in [this repo](https://github.com/nx-js/limiters).
 
-This method creates a function out of a string and returns it. The returned function takes
+### Compiling expressions
+
+`compiler.compileExpression(string)` creates a function from a string. The returned function takes
 an object as argument and executes the string as an expression in the context of the passed object.
 It returns the result of the evaluated expression. The string can be any javascript expression
 that may come after a return statement.
@@ -76,49 +125,65 @@ context.item = {name: 'item name'}
 result = expression(context) // result is 'item name'
 ```
 
-### compiler.expose(String, String, String, ...)
+#### Filters
 
-Use this method to expose globals to the compiler. Non of the globals are exposed by default.
+Filters 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.
 
 ```js
-const code = compiler.compileCode('console.log(Math.round(num))')
-compiler.expose('console', 'Math')
-code({num: 1.8}) // logs 2 to the console
+// txt is the result of the expression
+compiler.filter('upperCase', txt => txt.toUpperCase())
+
+const expr = compiler.compileExpression('message | upperCase')
+const context = {message: 'Hello World'}
+console.log(expr(context)) // prints 'HELLO WORLD' to the console
 ```
 
-Context variables are always favored over global ones, when both are present (with the same name).
+Filters accept any number of custom arguments. These can be passed after the filter name in the expression, separated by spaces.
+
+```js
+compiler.filter('splice', (txt, start, end) => txt.splice(start, end))
 
-### compiler.hide(String, String, String, ...)
+const expr = compiler.compileExpression('message | splice 0 6')
+const context = {message: 'Hello World'}
+console.log(expr(context)) // prints 'Hello' to the console
+```
 
-Use this method to hide exposed globals from the compiler.
+Multiple filters can be piped with the `|` symbol.
+
+```js
+const expr = compiler.compileExpression('message | splice 0 6 | upperCase')
+const context = {message: 'Hello World'}
+console.log(expr(context)) // prints 'HELLO' to the console
+```
+
+You can find some commonly used filters in [this repo](https://github.com/nx-js/filters).
+
+### Handling globals
+
+`compiler.expose('String, String, ...')` exposes globals by name for the compiler. Non of the globals are exposed by default.
 
 ```js
 const code = compiler.compileCode('console.log(Math.round(num))')
 compiler.expose('console', 'Math')
 code({num: 1.8}) // logs 2 to the console
-compiler.hide('console', 'Math')
-code({num: 1.8}) // throws an error, console and Math are undefined
 ```
 
-Context variables are always favored over global ones when both are present (with the same name).
+Context variables are always favored over global ones, when both are present with the same name.
 
-## Example
+`compiler.hide(String, String, ...)` hides globals by name, while `compiler.hideAll()` hides all globals.
 
 ```js
-const compiler = require('@risingstack/nx-compile')
-
-compiler.expose('console')
-const context = {name: 'nx-compile'}
-const tempVars = {version: '4.2.0'}
-const code = compiler.compileCode('console.log(name + version)')
-
-code(context, tempVars) // outputs 'nx-compile4.2.0' to console
+const code = compiler.compileCode('console.log(Math.round(num))')
+compiler.expose('console', 'Math')
+code({num: 1.8}) // logs 2 to the console
+compiler.hide('console', 'Math')
+code({num: 1.8}) // throws an error, console and Math are undefined
 ```
 
 ## Contributions
 
 This library has the very specific purpose of supporting the
-[NX framework](https://github.com/RisingStack/nx-framework).
+[NX framework](https://github.com/nx-js/framework).
 Features should only be added, if they are used by the framework. Otherwise please fork.
 
 Bug fixes, tests and doc updates are always welcome.

index.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const context = require('./src/context')
+const modifiers = require('./src/modifiers')
+const compiler = require('./src/compiler')
+
+module.exports = {
+  compileExpression: compiler.compileExpression,
+  compileCode: compiler.compileCode,
+  expose: context.expose,
+  hide: context.hide,
+  hideAll: context.hideAll,
+  filter: modifiers.filter,
+  limiter: modifiers.limiter
+}

package.json

@@ -1,32 +1,33 @@
 {
-  "name": "@risingstack/nx-compile",
-  "version": "4.2.0",
-  "description": "Execution of string as code in the context of an object, similarly to Object.eval().",
-  "main": "compiler.js",
+  "name": "@nx-js/compiler-util",
+  "version": "1.0.0",
+  "description": "An NX util, responsible for executing code in the context of an object.",
+  "main": "index.js",
   "scripts": {
-    "test": "mocha compiler.test.js",
-    "lint": "standard compiler.js"
+    "test": "mocha test",
+    "lint": "standard"
   },
   "author": {
     "name": "Miklos Bertalan",
     "email": "[email protected]"
   },
   "repository": {
     "type": "git",
-    "url": "[email protected]:RisingStack/nx-compile.git"
+    "url": "[email protected]:nx-js/compiler-util.git"
   },
   "bugs": {
-    "url": "https://github.com/RisingStack/nx-compile/issues"
+    "url": "https://github.com/nx-js/compiler-util/issues"
   },
-  "homepage": "https://github.com/RisingStack/nx-compile#readme",
+  "homepage": "https://github.com/nx-js/compiler-util#readme",
   "license": "MIT",
   "keywords": [
     "nx",
+    "util",
     "compile",
     "context",
     "eval",
-    "execution",
-    "code"
+    "code",
+    "expression"
   ],
   "devDependencies": {
     "chai": "3.5.0",
@@ -37,6 +38,11 @@
   "engines": {
     "node": ">=6.0.0"
   },
+  "standard": {
+    "ignore": [
+      "test"
+    ]
+  },
   "pre-push": [
     "lint",
     "test"

src/compiler.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const parser = require('./parser')
+
+const expressionCache = new Map()
+const codeCache = new Map()
+
+module.exports = {
+  compileExpression,
+  compileCode
+}
+
+function compileExpression (src) {
+  if (typeof src !== 'string') {
+    throw new TypeError('First argument must be a string.')
+  }
+  let expression = expressionCache.get(src)
+  if (!expression) {
+    expression = parser.parseExpression(src)
+    expressionCache.set(src, expression)
+  }
+
+  if (typeof expression === 'function') {
+    return expression
+  }
+
+  return function evaluateExpression (context) {
+    let value = expression.exec(context)
+    for (let filter of expression.filters) {
+      const args = filter.argExpressions.map(evaluateArgExpression, context)
+      value = filter.effect(value, ...args)
+    }
+    return value
+  }
+}
+
+function compileCode (src) {
+  if (typeof src !== 'string') {
+    throw new TypeError('First argument must be a string.')
+  }
+  let code = codeCache.get(src)
+  if (!code) {
+    code = parser.parseCode(src)
+    codeCache.set(src, code)
+  }
+
+  if (typeof code === 'function') {
+    return code
+  }
+
+  const context = {}
+  return function evaluateCode (state, tempVars) {
+    let i = 0
+    function next () {
+      Object.assign(context, tempVars)
+      if (i < code.limiters.length) {
+        const limiter = code.limiters[i++]
+        const args = limiter.argExpressions.map(evaluateArgExpression, state)
+        limiter.effect(next, context, ...args)
+      } else {
+        code.exec(state, tempVars)
+      }
+    }
+    next()
+  }
+}
+
+function evaluateArgExpression (argExpression) {
+  return argExpression(this)
+}