jsub

JavaScript library to create JavaScript subsets.

Usage

Simply require jsub and test your scripts against your own JavaScript subset syntax definition. Scripts must be provided as AST with tools like Esprima or the Reflect.parse API:

var jsub = require('jsub');
var esprima = require('esprima');

var syntax = {
  context: {
    categories: {
      fruits: [],
      vegetables: [],
    },
  },
  conditions: [{
    type: 'Program',
  }, {
    type: 'ExpressionStatement',
  }, {
    type: 'BinaryExpression',
    operator: ['*', '-'],
  }, {
    type: 'Literal',
    raw: /^[0-9]{1,5}$/,
  }, {
    type: 'CallExpression',
    // The $_ property creates a custom parser that will by-pass the actual
    // jsub embedded child expression checker. You should use this extremely
    // carefully and heavily test it. It must return an array of errors that
    // prevented the rule to apply, empty if it successfully applied.
    '$_': function(expression) {
      // Check function name
      if(
        (!expression.callee) ||
        'Identifier' !== expression.callee.type ||
        'lengthOf' !== expression.callee.name
      ) {
        return [new Error('E_BAD_FUNCTION_NAME')];
      }
      if(
        1 !== expression.arguments.length ||
        'Literal' !== expression.arguments[0].type ||
        !/^fruits|vegetables$/.test(expression.arguments[0].value)
      ) {
        return [new Error('E_BAD_FUNCTION_ARGS')];
      }
      return [];
    },
  }, {
    type: 'CallExpression',
    // The $_ property is also usefull to check sub syntaxes
    '$_': function(expression) {
      return jsub.bind(null, {
        type: 'Literal',
        raw: /^[0-9]{1,5}$/,
      });
    },
  }],
};

var checkJavaScriptSubset = jsub.bind(null, syntax);

var script = '2 * (lengthOf("fruits") - lengthOf("vegetables"))';

var javaScriptAST = esprima.parse(script);

checkJavaScriptSubset(javaScriptAST);
// []
// returns an empty array since there is no syntax violation

jsub uses a white list to check every AST node of your application so it fallbacks to security, you can now run your script safely without having to sandbox it!

var script = '2 * (lengthOf("fruits") - lengthOf("vegetables"))';

var context = {
  vegetables: ['salad', 'potato'],
  fruits: ['cherry'],
  lengthOf: function(arrayName) {
    return context[arrayName].length;
  },
};

runFunction = new Function(
  'var fruits = this.fruits;\n' +
  'var vegetables = this.vegetables;\n' +
  'var lengthOf = this.lengthOf;\n' +
  'return (' + script + ');'
);

console.log(runFunction.call(context));
// -2

API

jsub(syntax:Object, ast:Object):Array

Check the given ast script according to the syntax definition, returns an array containing the script syntax violations according to the definition.

Stats