Manage data using Node.js

Manage data using Node.js and the JSON DB API tutorials

Abstract

Manage data using Node.js and the JSON DB API tutorials

The JSON DB API allows users to access rich database functionality using JSON messages over HTTP(S) without any local binary dependencies.

While the API is easy to use, and writing a driver from scratch is simple, FairCom provides drivers for the most common programming languages to make usage even easier.

This section covers the Node.js driver for the JSON DB API and explains how to use it.

The Node.js driver for the JSON DB API makes requests using an HTTP client library as its only direct dependency.

First steps

Note

These procedures were written and tested using Windows 11 and Python 3.9.1.

Prerequisites:

Ensure the FairCom server is installed and that it is running.
Ensure that the latest version of Node.js is installed and executable from a command line.

Establish FairCom DB server communications

Inside the FairCom DB folder, open the SDK folder.
Locate and open the drivers\nodejs.json.db (or nodejs.json.nav) in your command prompt.
To install the node-fetch library, run > npm install.
Run > cd examples.
Run > node ping.js.
Observe the ping successful message.
myArgs: [ 'ping' ]
response: pong
This indicates that your FairCom DB server is running, that the JSON DB API is accessible, and the Node.js driver can communicate successfully with the server.

Create test data

Run the following commands in order:
1. node createDatabase.js
2. node createTable.js
3. node createIndex.js
4. node insertRecords.js
5. node getRecordsByTable.js

Observe the results:

[4, 13358, 'Ian Nepomniachtchi', 2789]
[1, 13358, 'Magnus Carlsen', 2847]
[2, 13358, 'Fabiano Caruana', 2820]
[3, 13358, 'Ding Liren', 2791]
[5, 13358, 'Levon Aronian', 2781]
[6, 13358, 'Alexander Grischuk', 2777]
[7, 13358, 'Anish Giri', 2776]

Confirm the successful creation of the table inside the FairCom Data Explorer.

Example source code

Example 1. Source code

const JNAClient = require('../JNAClient');
var jnaClient = new JNAClient("http://localhost:8080/api")

const dbName = "test_js";

async function createDB() {
  try {
    await jnaClient.login("ADMIN", "ADMIN");
    await jnaClient.createDatabase(dbName);
    console.log("created new db: " + dbName);
  } catch(error) {
    console.log(error);
  }
  await jnaClient.logout();
}
createDB();

About the Example 1, “Source code”:

In Example 1, “Source code”, a new JNAClient is instantiated.
We pass in the URL of the server that runs the FairCom DB server. If you want to use HTTPS you need a real SSL certificate.
Attempt to login to the server using username and password ADMIN. This is the default and it should be changed for servers in production.
If the login was successful the high-level API function createDatabase inside of a try/catch/finally block is called.
If the call is successful a success message is printed.
If the call is NOT successful a JNAException is thrown and caught and a failure message is printed.
Finally, the logout function is called. This is important because the server caches a lot of resources associated with every session. Always make sure that you log out when you are done with the JSON DB API or that you keep the session alive using ping calls. A ping call once per minute should be enough for long-running tasks.

Debug

To look at the messages that are passed back and forth between the client and the server, specify your preference with the second parameter when calling JNAClient.

Example 2. jnaClient

var jnaClient = new JNAClient("http://localhost:8080/api", 3)

In the second parameter:

1 means print client request
2 means print server response
3 prints both

Use the Node.js driver for the JSON DB API in your own projects

Create and open a new, empty folder named my_test.
Run > npm init -y, using a command prompt, to create a package.json file with default values.

Edit the package.json file to add a new section:

"dependencies": {
    "node-fetch": "^2.6.7"
  }

Copy JNAClient.js from the nodejs.json.db (or nodejs.json.db) folder into the new folder.
Create a new file named my_test.js.
Open the my_test.js file in a text editor.

Change my_test.js to:

const JNAClient = require('./JNAClient');
var jnaClient = new JNAClient("http://localhost:8080/api")

async function ping() {
  try {
    await jnaClient.open();

    await jnaClient.ping();
    console.log("ping success.");
  
  } catch(error) {
    console.log(error);
  }
  jnaClient.close();
}

ping();

Using the command prompt, run > node my_test.js.
Observer the ping successful message:
> ping successful.
This indicates that you have successfully created your own project using the Node.js driver for FairCom DB.

Enable HTTP on port 8080

This FairCom tutorial uses HTTP to communicate with the server on port 8080. Because HTTP is insecure, this port is typically disabled.

Do the following to enable the HTTP protocol on port 8080:

Shut down the FairCom server.
Edit the services.json file located in the <faircom>/config folder.
Find the listener service named "http8080".
Change "enabled":false to "enabled":true.
Restart the FairCom server.

The modified listener configuration object in services.json should look something like this:

{
  "serviceName": "http8080",
  "description": "Port 8080 using insecure HTTP protocol...",
  "port": 8080,
  "protocol": "http",
  "enabled": true
}