concrete-js for Node.js

This README describes the Node.js version of concrete-js. For the standard jQuery version, see README-js.md.

concrete-js is a Node.js library for working with Concrete, a set of NLP data types defined by a Thrift schema. Thrift makes it easy to use a shared set of data structures across multiple programming languages.

concrete-js is designed for visualization and annotation. While it is technically possible to implement NLP algorithms in JavaScript, you should instead use concrete-python or concrete-java.

In general, you should use concrete-js when you have a Concrete Communication object that was created by another tool, and need a UI that visually represents data in the Communication. You may also need the user/annotator to interactively modify Concrete data structures, and then save their modifications.

The concrete-js library contains:

• Serialization and deserialization code for Concrete data structures. The serialization code is generated by the Thrift compiler from the Thrift schema for Concrete.
• Utility code for working with Concrete objects

API documentation for concrete-js is available at: http://hltcoe.github.io/concrete-js/

Including concrete-js in your project

npm install @ccmaymay/concrete

import thrift from "thrift";
import concrete from "concrete";

Fetching Communications with JavaScript

Replace /FETCH/URL/PATH/, FETCH_HOST_ADDRESS, 9090, and ["FETCH-COMM-ID-1", "FETCH-COMM-ID-2"] with the appropriate values for your application:

import thrift from "thrift";
import concrete from "concrete";

var options = {
  transport: thrift.TBufferedTransport,
  protocol: thrift.TJSONProtocol,
  path: "/FETCH/URL/PATH/",
  https: false,
};

const connection = thrift.createXHRConnection(
  "FETCH-HOST-ADDRESS",
  9090,
  options
);
connection.on("error", function (err) {
  console.error(err);
});

const client = thrift.createXHRClient(
  concrete.access.FetchCommunicationService,
  connection
);

const request = new concrete.access.FetchRequest({
  communicationIds: ["FETCH-COMM-ID-1", "FETCH-COMM-ID-2"],
});
client.fetch(request).then((result) =>
  console.log(result.communications)
).catch((error) =>
  console.error("fetch error: " + error.message);
);

Building concrete-js

You do not need to build concrete-js in order to use concrete-js - a working copy of the library is included in the dist/ directory. The concrete-js library only needs to (re)built when the Thrift schema files for Concrete have been updated, or when the code in src/ is modified.

Requirements for building concrete-js:

• A copy of the Concrete repo in your home directory - ${HOME}/concrete
• Thrift
• Node
• Grunt - a JavaScript build tool

Install the Node packages required for building concrete-js using:

npm install

Build concrete-js using the command:

grunt

(or perhaps npx grunt) which will:

• call the Thrift compiler to generate JavaScript code for the Thrift schema under ${HOME}/concrete
• combine the Thrift-generated JavaScript code with the hand-written utility function JavaScript code in a single directory
• run JSHint on the combined JavaScript code to check for problems
• minify the combined code