Have ideas to improve npm?Join in the discussion! »

    esniff

    1.1.0 • Public • Published

    esniff

    Low footprint JavaScript source code parser

    Low footprint, fast source code parser, which allows you to find all code fragment occurrences with respect to all syntax rules that cannot be handled with plain regular expression search.

    It aims at use cases where we need to quickly find usage of given function, property etc. in syntactically valid code.

    Installation

    npm

    $ npm install esniff
    

    To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: Browserify, Webmake or Webpack

    Usage

    Using main module you can configure sophisticated parser on your own. However, first, see preprared API utilities that may already address use cases you have.

    esniff(code, triggerChar, callback)

    • code Code to parse
    • triggerChar Character which is expected to trigger custom handling via callback
    • callback To detect and eventually handle case we're after

    Example: Find all require(..) calls:

    var esniff = require('esniff');
     
    var result = esniff('var x = require(\'foo/bar\')', 'r', function (index, previous, nest) {
      if (previous === '.') return next(); // Ignore x.require calls
      if (code.indexOf('require', index) !== index) return esniff.next(); // Not really `require` call
      next('require'.length); // Move after `require` and skip any following whitespace
      index = esniff.index; // Update index
      if (code[i] !== '(') return resume(); // Not `require(`
      return collectNest(); // Collect all code between parenthesis
    });
     
    console.log(result);  [{ point: 17, column: 17, line: 1, raw: '\'foo/bar\'' }]

    API

    accessedProperties(objName) (esniff/accessed-properties)

    Returns function which allows us to find all accessed property names on given object name

    var findProperties = require('esniff/accessed-properties');
    var findContextProperties = findProperties('this');
     
    var result = findContextProperties('var foo = "0"; this.bar = foo; this.someMethod(); otherFunction()');
    console.log(result); // [ { name: 'bar', start: 20, end: 23 }, { name: 'someMethod', start: 36, end: 46 } ]

    function(name[, options]) (esniff/function)

    Returns function which allows us to find all occurrences of given function (or method) being invoked

    Through options we can restrict cases which we're after:

    • asProperty (default: false), on true will allow x.name() when we search for name calls
    • asPlain (default: true), on true it allows plain calls e.g. name() when we search for name. Should be set to false if we're strictly about method calls.

    Setting both asProperty and asPlain to false, will always produce empty result

    var findRequires = require('esniff/function')('require');
     
    findRequires('var x = require(\'foo/bar\')');
    // [{ point: 17, column: 17, line: 1, raw: '\'foo/bar\'' }]

    resolveArguments(code[, limit]) (esniff/resolve-arguments)

    Resolves expressions separated with commas, with additional limit you can specify after which number of arguments resolver should stop

    var resolveArgs = require('esniff/resolve-arguments');
     
    var result = resolveArgs('"raz", "dwa", [\'raz\'\'dwa\'], "trzy"', 3));
     
    console.log(result); // ['"raz"', ' "dwa"', ' [\'raz\', \'dwa\']']

    Limitations

    • esniff assumes code that you pass is syntactically correct, it won't inform you about any syntax errors and may produce unexpected and nonsense results when such code is used.
    • There's single case of syntactically correct code, which will make esniff produce incorrect results, it's division made directly on object literal (e.g. x = { foo: 'bar' } / 14, esniff in that case will assume that / starts regular expression). Still there's not known use case where such code may make any sense, and many popular JS source code parsers share very same vulnerability.
    • esniff may work with new syntax introduced by ECMAScript 6 but it has not been fully revised in that matter yet. Pull requests are welcome.

    Tests Build Status

    $ npm test
    

    Install

    npm i esniff

    DownloadsWeekly Downloads

    550,131

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • avatar