microcomps v0.1.0-build.60

MicroCOMPS1

The MicroCOMPS library is a streamlined, task-oriented, data-adapter library for COMPS that is specifically tailored towards getting data out of COMPS simulations for the purposes of visualization.

To make COMPS API calls, this library needs a valid COMPS token. If the page hosting MicroCOMPS is hosted within the iframe of the COMPS ContentControl, then the token can be obtained from the COMPS cookie. MicroCOMPS provides a set of static helper functions to make this easier.

Installation

Because MicroCOMPS is distributed as an NPM package, installation is handled by npm. Given a git bash prompt,

1. Create a folder for the new visualization.

   mkdir myvis
   cd myvis

2. Initialize NPM

   npm init

3. Answer the NPM-init questions. This establishes a package.json file for the new project.
4. Install MicroCOMPS as a dependency

   npm install --save microcomps

5. Import the library in your visualization's index.js

   import {MicroCOMPS} from "microcomps";

Minimal usage

Following is the code for a simple application using the MicroCOMPS library. (This example, minimal/, is included in the repo's examples/ directory.)

import {MicroCOMPS} from "microcomps";
import axios from "axios";

// Authenticate on page load
document.addEventListener("DOMContentLoaded", () => {
  const params = new URLSearchParams(window.location.search);
  const authPostData = {
    "UserName": params.get("username"),
    "Password": btoa(params.get("password")),
    "ApplicationName": "COMPS",
    "ClientVersion": 11,
  };
  if (!authPostData.UserName || !authPostData.Password) {
    alert("?username=...&password=... required on URL");
    return;
  }
  const authUrl = `https://comps-dev.idmod.org/api/tokens?format=json`;
  axios.post(authUrl, authPostData)
    .then(resp => {
      app(resp.data.Token);   // Run app on authentication success
      return Promise.resolve(resp.data);
    })
    .catch(reason => {
      return Promise.reject(reason);
    });
});

// Simple application that obtains a sim, then gets its flat-file listing.
function app(token) {
  const simId = "154d0a7f-fd23-ed11-92ee-f0921c167860";
  const mc = new MicroCOMPS({
    baseUrl: "https://comps-dev.idmod.org",
    token: token,
  });
  mc.getSimulation(simId)
    .then(sim => {
      const pre = document.createElement("pre");
      pre.textContent = `File listing for simulation ${simId}\n`;
      pre.textContent += sim.getFileTree().getFileList().join("\n");
      document.body.append(pre);
    });
}

For more information on this example, see the README.md in the example's folder.

Documentation

MicroCOMPS API is fully documented with JSDoc comments. In modern IDEs such as VSCode and Webstorm, the JSDoc documentation is available by hovering over the name of any MicroCOMPS function call and most object data types used by the library.

Philosophy

MicroCOMPS is a progressive JavaScript library that utilizes modern web technologies.

ES6

ES6-standard mechanisms such as fetch, Promise, and module import are utilized by this library. Modern browsers (i.e. recent versions of Chrome, Firefox, or Edge) will be required. In practice at IDM this is not a issue.

Asynchrony

Many operations in MicroCOMPS are asynchronous. For asynchronous I/O, MicroCOMPS uses the modern Promise mechanism. For information about using Promises, see here on MDN.

Object design

MicroCOMPS is composed of a small number of related classes that roughly model the way COMPS organizes its data. Classes shown here in red are planned but not yet implemented.

Build and deployment

NOTE: Since MicroCOMPS is distributed as an npm package and is cached at IDM's instance of Artifactory, normally it should not be necessary to build the MicroCOMPS library itself. These instructions are for the library maintainer.

Build only

MicroCOMPS is built and published as an NPM package. At IDM NPM packages are locally cached in Artifactory. The steps below assume you've cloned the repo and you've got a git bash prompt inside the cloned directory.

1. ./build.sh
2. The build script auto-increments the prerelease part of the semver by one on every build. (That's the "-4" in "0.1.0-4".) Here's what a successful build looks like in the console:

Build and deploy

To both build and deploy MicroCOMPS, again use the build.sh script:

1. npm login # to publish to npm, log in to the maintainer npm account.
2. ./build.sh --publish
3. The build script will auto-increment the prerelease part of the semver, build, pack a .tgz with the microcomps npm package, then publish it to npm.

Questions?

Bryan Ressler (bryan.ressler@gatesfoundation.org)

Footnotes

1. MicroCOMPS was originally known as GuerrillaCOMPS.