Introducing ESTR (ES traversals and transformations)

estr is a Javascript library for processing Javascript source code, building on the Esprima parser and AST. It comes with a commandline interface, based on nodejs, and an online demo, based on CodeMirror, showing how to use estr directly as a library, from the browser. A sample binding for using estr from Vim is also included.

What does this mean in practice: If your Javascript editor can be extended by calling out to Javascript code or commandline tools, you can now add scoped variable navigation (to binding, to next/previous occurrence) and variable renaming to your editor’s feature set.


In its current state, estr can:

  • generate (scope-aware) tags files for JS projects (for use with scoped_tags Vim mode); this replaces my earlier, doctorjs-based scoped tags generator
  • augment Esprima ASTs with scope information
  • locate identifier (with line/column info) in augmented AST, find its binding occurrence, scope, and other occurrences
  • transform JS source code to implement variable renaming, while preserving layout and comments (no pretty-printing)

The online demo shows how to use this functionality to enhance a standard CodeMirror JS editor. CodeMirror provides editing, its Javascript mode provides basic syntax highlighting, Esprima adds parsing and parse errors. On top of that, estr enables us to:

  • highlight unbound variables
  • highlight other occurrences of identifier under cursor (scope-aware)
  • navigate to next/previous identifier occurrence, or to the binding occurrence (scope-aware)
  • rename variables (scope-aware, with checks to prevent errors introduced by naive renaming)

The demo code is in the gh-pages branch of the estr repo.

If you find estr useful, please tell others;
if you find bugs in estr, please tell me!-)

If you have access to another JS renaming tool, you might want to try the estr renaming tests on it. If you want to integrate estr in your tool suite, please get in touch.


This entry was posted in Uncategorized and tagged , , , , , , . Bookmark the permalink.

3 Responses to Introducing ESTR (ES traversals and transformations)

  1. Pingback: Scoped tags support for Javascript, in Vim | Programming, Languages, Tools

  2. mcr says:

    I followed your article regarding jsctags and managed to set it up on my home computer (linux), but I was having problems with installing it on my work computer (windows). Than I saw this article and tried to use estr generated tags with vim.
    I’m able to make tags file with: “node c:\path_to_estr\estr.js tags .” – where dot is file containing my project .js file.
    tags file looks big but doesn’t contain much useful info. There are many lines like:

    advance ./node_modules/estr/esprima.js 1045;” f lineno:1045 scope:40:2-3550:1
    binding_scope ./node_modules/estr/scope_utils.js 69;” v lineno:69 scope:57:10-162:1

    There are only few lines which refer to my .js file, and they point to simple variable declarations like:
    var Main = { };
    var keyCode = event.keyCode;

    Moreover when I use default key bindings from scoped_tags vim plugin, I’m getting for e.g.:
    tag keyCode not found
    but “Ctrl + ]” works and I can jump to declaration.

    Jumping to declarations, finding definitions is essential for my work flow, and it’s only thing which is stopping me from using vim as my main toll for bigger javascript projects.
    Please could you guide me or make a tutorial on how to get such functionality in vim?

    • I haven’t used doctorjs/jsctags recently, but parts of my modifications/fork were to make it work in Windows (however, I consider the original project effectively dead, so won’t invest time in further fixes to my fork).

      estr tags . is recursively processing the directories for .js files, including code installed in ./node_modules. It is currently limited to scope-related tags (variable and function declarations, parameters; not object properties), whereas my earlier implementation also inherited some approximations for non-scope-related tags, from the original jsctags. I have filed a github issue to remind me to do something about this.

      Since Javascript mixes variables and properties for definitions, with no static restrictions for the latter, a proper “jump to definition” isn’t as easy as in other languages, but estr should do a better job, even if only adopting approximations.

      If you can reproduce the issue of keybindings not finding tags that should be in scope (“Ctrl + ]” will ignore scoping when looking for tags), please open an issue for this, with instructions on how to reproduce, and I’ll have a look.

Comments are closed.