Stardog.js

Universal Javascript fetch wrapper for communicating with the Stardog HTTP server.

What is it?

This framework wraps all the functionality of a client for the Stardog DBMS, and provides access to a full set of functions such as executing SPARQL queries, administrative tasks on Stardog, and the use of the Reasoning API.

All the implementation uses the HTTP protocol, since most of Stardog functionality is available using this protocol. For more information, go to the Stardog's HTTP Programming documentation.

This is a universal library and as such can be used in both the browser and Node.js.

Installation

To install stardog.js run:

npm install stardog

Usage

Stardog.js conforms to the Universal Module Definition API. To use it in Node.js, simply require or import it as you would any other Node module. To use it in the browser, you can either:

1. Do the same as you would with Node.js, in which case you'll have to use webpack, parcel, browserify, or some other module bundler,
2. Use require.js or some other module loader, or
3. Directly import the built stardog.js file in your HTML (e.g., <script src="./node_modules/stardog/dist/stardog.js"></script>) and then reference the global stardogjs object (e.g., stardogjs.query.execute(/* . . . */)).

Development

To get started, just clone the project. You'll need a local copy of Stardog to be able to run the tests. For more information on starting the Stardog DB service and how it works, go to Stardog's documentation, where you'll find everything you need to get up and running with Stardog.

Go to http://stardog.com, download and install the database and load the data provided in data/ using the script in the repository.

1. Start the Stardog server

stardog-admin server start

2. Install stardog.js dependencies:

npm install

Running Tests

In order to contribute changes, all test cases must pass. With the Stardog server running, execute the following command to run all test cases in test/spec:

npm test

To test the cluster commands you will need to first start a Stardog cluster then run the cluster suite. The easiest way to do this is to run docker-compose to start a cluster:

docker-compose -f .circleci/docker-compose.yml up

Then run the cluster test suite in test/cluster:

npm run test:cluster

Contributing

Fork, clone and develop, write or amend tests, and then open a PR. All PRs go against "master". This project uses prettier on file commit, so don't worry about style as it'll just get rewritten when you commit your changes.

Releasing

First, ensure that there is a milstone for the release version, and that all PRs that you want to appear in the CHANGELOG are tagged with that milestone. The milestone must be closed before publishing.

If you have publishing rights, BE SURE TO RUN npm version (major|minor|patch) IMMEDIATELY BEFORE PUBLISHING. This will ensure that the build is up-to-date and will also (1) bump the version number in package.json accordingly, (2) create a git tag matching the version number, and (3) automatically update the README and the CHANGELOG using our type declarations and data from the stardog.js GitHub repo. For this process to work correctly, you will need to have generated a GitHub OAuth token and assigned it to the MDCHANGELOG_TOKEN environment variable (the name of the token is a relic of the fact that this repo once used mdchangelog to generate changelogs; it now uses a custom script). You can then publish by running npm publish. In order to ensure that this process is followed, there will be a very annoying alert triggered whenever you publish; if you're all set, just ignore the alert.

After releasing, be sure to push to master, including the tags (so that the release is reflected on GitHub).

Version/Support Details

Each release of stardog.js is tested against the most recent version of Stardog available at the time of the release. The relationship between versions of stardog.js and versions of Stardog is detailed in the following table:

| stardog.js Version | Supported Stardog Version(s) | | ------------------ | ---------------------------- | | 6.x.x | 10.x.x | | 5.x.x | 9.x.x | | 4.x.x | 8.x.x | | 3.x.x | 7.x.x | | 2.x.x* | 6.x.x | | 1.x.x* | 5.x.x | | 0.x.x* | any version < 5 |

* = No longer supported

We support and maintain a particular version of stardog.js only if the corresponding Stardog version(s) is (are) officially supported and maintained. For example, we no longer support v0.x.x of stardog.js, as the corresponding Stardog versions are no longer supported. (That said, later versions of stardog.js will often mostly work with earlier Stardog versions. We just don't test this or make any guarantees to that effect.)

Quick Example

const { Connection, query } = require('stardog');

const conn = new Connection({
  username: 'admin',
  password: 'admin',
  endpoint: 'http://localhost:5820',
});

query
  .execute(
    conn,
    'myDatabaseName',
    'select distinct ?s where { ?s ?p ?o }',
    'application/sparql-results+json',
    {
      limit: 10,
      reasoning: true,
      offset: 0,
    }
  )
  .then(({ body }) => {
    console.log(body.results.bindings);
  });