Node Code Query (NCQ)

Node.js is a JS runtime focused on development of server-side and console applications. A strong aspect of Node.js is the set of libraries offered by its package manager, NPM. Today, NPM lists over 1M packages on its database. It is likely that a developer will find a library that implements the functions she needs. The problem with that, however, is that deciding which package to use and quickly understanding these packages can be daunting for a developer, specially a novice developer on Node.js.

NCQ is a tool to help Node.js developers 1) locate packages for her needs and 2) (un)install and try those packages as they locate them.

NCQ enables users to write queries for packages and their samples in English. It provides a virtual environment for users to try different samples in isolation. The combination of 1) search (for packages and their samples) and 2) virtualization is what makes NCQ distinct.

15m Youtube Demo Video:

Pre-requisites

Latest LTS version of Node/NPM.
Hint: Use nvm to install node/npm. Install nvm. Then, run the command $> nvm install --lts

Installation

1. Clone this repository.

$> git clone <NCQ-repository-url>

2. Change to the corresponding directory.

$> cd node_code_query

3. Install the module. This step will take a while (around 5m) as, in addition to NCQ dependencies, it downloads a snapshot of the NPM data and creates a local database (for efficiency).

$> npm install

You should see:

> node_code_query@1.0.0 install /home/damorim/projects/node_code_query
> npm run setup
...
found 0 vulnerabilities

Illustrative Example

Let us consider the scenario where the developer wants to read a file (e.g., "/etc/passwd") and print its contents on screen. Here is how NCQ can help:

1. Start NPM by running the command npm start from within the repository directory.

$> npm start

Your screen should look like this:

2. Type repl to create an environment where you can play with different examples. The name REPL refers to "Read Eval Print Loop".
   Another option is to press F1 (to show suggestions), choose option repl, and press ENTER twice

NCQ  >  repl

Your screen should look like this:

The square brackets in the command prompt indicate that you successfully created a node repl, i.e., you can run any node.js code from the prompt now. However, you do not have any library installed!

Please note that there is a (context-sensitive) menu of (parameterless) function keys in the bottom of the screen. You can use any of these functions with the tool. We describe some of these functions as we move along this tutorial.

3. Type .packages read text file and read alternative packages.
   Hint: press F1 after .packages to choose a task from a pre-defined list. There is an auto-complete feature to guide the user to sentences similar to the one she is typing. The advantage of that approach is that you know there will be an associated packages for the task you choose.

NCQ [] >  .packages read text file
...
// a table of package options with descriptions (taken from NPM)
...

4. Before the user commmits to a certain package, she wants to search for possible choices. This step shows how to obtain samples for the package selected in the previous step. Let us say, the user selected package file-reader.
   Hint: Cycle through the alternative samples with F2/F3 function keys.

NCQ [] >  .samples file-reader
...

Note that when you press ENTER an exception is raised. The reason is that the module/package was not installed yet. So, at this point, you can see (the samples) but you can't run.

5. Install module file-reader

NCQ > .install file-reader
...
NCQ [file-reader] > _

The text within brackets shows the packages installed on your environment.

6. Select the snippet you want

NCQ [file-reader] >  .samples 
...

Let us consider the user selected the following sample (simplified):

var read = require('file-reader');
read('*.js');

It shows various objects on output, one for each .js file found in the current directory. As there is only one (index.js), it prints a single object.

7. Open the NCQ editor (F6) and modify the index.js file.

Modify the file to '/etc/passwd':

var read = require('file-reader');
blob = read('/etc/passwd')

Type F9 (Save & Exit) and check the object printed on screen. Inspect the object fields to locate where the data is store. You will see that the chain of field accesses blob.passwd.contents will produce a byte Buffer, which can be translated to a string with a call to method toString(). Type F6 again and change the file index.js as follows:

var read = require('file-reader');
str = read('/etc/passwd').passwd.contents.toString()
console.log(str)

Press F9 to save the file and return to the REPL. The code from index.js will be automatically loaded into the REPL and you should see the same contents as a that obtained with $> cat /etc/passwd on the shell.

7. Load the file from index.js. In fact, if you want you can use a different editor to change that file (from outside the REPL) and the reload the file in the REPL.

NCQ [file-reader] >  .load index.js
...