petrsimon / stardog.js

Stardog JavaScript Framework for node.js and the browser

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

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

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.

Version details

The current version of stardog.js has been tested against version 5.0.0 of Stardog. You are encouraged to use this library if you are using version 5 or greater of Stardog. However, there is very little code that is version specific in stardog.js. It is essentially just a convenience wrapper around fetch. It is very likely that many of the exposed methods will work on older versions of Stardog, but this has not been tested.

If you are using a really old version of Stardog (<= 3.0.0) you should stick with the legacy version of the library which is version 0.3.1.

Discontinued Versions

All versions of stardog.js prior to v1.0.0 have been discontinued and will not receive updates of any kind. If you are using a legacy version of stardog.js you can find the original documentation here. The most recent legacy version is 0.3.1.

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 }', {
  limit: 10,
  offset: 0,
}).then(({ body }) => {
  console.log(body.results.bindings);
});

API

HTTP

ContentMimeTypes

One of the following values:

'application/x-turtle' | 'text/turtle' | 'application/rdf+xml' | 'text/plain' | 'application/x-trig' | 'text/x-nquads' | 'application/trix'

AcceptMimeTypes

One of the following values:

'text/plain' | 'application/json' | 'text/boolean'

Body

Object with the following values:

• status (string)
• statusText (string)
• result (object | string | boolean | null)
• ok (boolean)
• headers (Headers)

ConnectionOptions

Object with the following values:

• endpoint (string)
• username (string)
• password (string)

Connection (Class)

Constructed with:

• options (ConnectionOptions)

Connection.config(options)

Takes the following params:

• options (ConnectionOptions)

Returns void

Connection.headers()

Returns Headers

Connection.uri(resource)

Takes the following params:

• resource (string[])

Returns string

server

server.shutdown(conn, params)

Shuts down a Stardog server.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

db

db.create(conn, database, databaseOptions, options, params)

Creates a new database.

Expects the following parameters:

• conn (Connection)

• database (string)

• databaseOptions (object)

• options ({ files: string[] })

• params (object)

Returns Promise<HTTP.Body>

db.drop(conn, database, params)

Deletes a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.get(conn, database, params)

Gets an RDF representation of a database. See: https://www.w3.org/TR/sparql11-http-rdf-update/#http-get

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.offline(conn, database, params)

Sets a database offline.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.online(conn, database, params)

Sets a database online.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.optimize(conn, database, params)

Optimizes a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.copy(conn, database, destination, params)

Makes a copy of a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• destination (string)

• params (object)

Returns Promise<HTTP.Body>

db.list(conn, params)

Gets a list of all databases on a Stardog server.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

db.size(conn, database, params)

Gets number of triples in a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.clear(conn, database, transactionId, params)

Clears the contents of a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• params (object)

Returns Promise<HTTP.Body>

db.add(conn, database, transactionId, content, options, params)

Adds data within a transaction.

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• content (string)

• options (TransactionOptions)

• params (object)

Returns Promise<TransactionResponse>

db.remove(conn, database, transactionId, content, options, params)

Removes data within a transaction.

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• content (string)

• options (TransactionOptions)

• params (object)

Returns Promise<TransactionResponse>

db.namespaces(conn, database, params)

Gets a mapping of the namespaces used in a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.exportData(conn, database, options, params)

Exports the contents of a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• options ({ mimeType: AcceptMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

options

db.options.get(conn, database, params)

Gets set of options on a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.options.set(conn, database, databaseOptions, params)

Sets options on a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• databaseOptions (object)

• params (object)

Returns Promise<HTTP.Body>

transaction

Encodings

One of the following values:

'gzip' | 'compress' | 'deflate' | 'identity' | 'br'

TransactionResponse extends HTTP.Body

Object with the following values:

• transactionId (string)

TransactionOptions

Object with the following values:

• contentType (HTTP.ContentMimeTypes)
• encoding (Encodings)

db.transaction.begin(conn, database, params)

Begins a new transaction.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<TransactionResponse>

db.transaction.rollback(conn, database, transactionId, params)

Rolls back a transaction, removing the transaction and undoing all changes

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• params (object)

Returns Promise<TransactionResponse>

db.transaction.commit(conn, database, transactionId, params)

Commits a transaction to the database, removing the transaction and making its changes permanent.

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• params (object)

Returns Promise<TransactionResponse>

icv

db.icv.get(conn, database, params)

Gets the set of integrity constraints on a given database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.icv.add(conn, database, icvAxioms, options, params)

Adds integrity constraints to a given database.

Expects the following parameters:

• conn (Connection)

• database (string)

• icvAxioms (string)

• options ({ contentType: ContentMimeTypes })

• params (object)

Returns Promise<HTTP.Body>

db.icv.remove(conn, database, icvAxioms, options, params)

Removes integrity constraints from a given database.

Expects the following parameters:

• conn (Connection)

• database (string)

• icvAxioms (string)

• options ({ contentType: ContentMimeTypes })

• params (object)

Returns Promise<HTTP.Body>

db.icv.clear(conn, database, params)

Removes all integrity constraints from a given database.

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

db.icv.convert(conn, database, icvAxioms, options, params)

Converts a set of integrity constraints into an equivalent SPARQL query for a given database.

Expects the following parameters:

• conn (Connection)

• database (string)

• icvAxioms (string)

• options ({ contentType: ContentMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

db.icv.validate(conn, database, constraints, options, params)

Checks constraints to see if they are valid

Expects the following parameters:

• conn (Connection)

• database (string)

• constraints (string)

• options ({ contentType: ContentMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

db.icv.validateInTx(conn, database, constraints, transactionId, options, params)

Checks constraints to see if they are valid within a transaction

Expects the following parameters:

• conn (Connection)

• database (string)

• constraints (string)

• transactionId (string)

• options ({ contentType: ContentMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

db.icv.violations(conn, database, constraints, options, params)

Accepts integrity constraints as RDF and returns the violation explanations, if any, as RDF.

Expects the following parameters:

• conn (Connection)

• database (string)

• constraints (string)

• options ({ contentType: ContentMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

db.icv.violationsInTx(conn, database, constraints, options, params)

Accepts integrity constraints as RDF and returns the violation explanations, if any, as RDF.

Expects the following parameters:

• conn (Connection)

• database (string)

• constraints (string)

• options ({ contentType: ContentMimeTypes })

• params ({ graphUri: string })

Returns Promise<HTTP.Body>

reasoning

db.reasoning.consistency(conn, database, options, params)

Returns if the database is consistent

Expects the following parameters:

• conn (Connection)

• database (string)

• options ({ namedGraph: string })

• params (object)

Returns Promise<HTTP.Body>

db.reasoning.explainInference(conn, database, inference, config, params)

Provides an explanation for an inference

Expects the following parameters:

• conn (Connection)

• database (string)

• inference (string)

• config ({ contentType: string })

• params (object)

Returns Promise<HTTP.Body>

db.reasoning.explainInconsistency(conn, database, options, params)

Provides the reason why a database is inconsistent, as reported by db.reasoning.consistency

Expects the following parameters:

• conn (Connection)

• database (string)

• options ({ namedGraph: string })

• params (object)

Returns Promise<HTTP.Body>

db.reasoning.explainInferenceInTransaction(conn, database, transactionId, inference, config, params)

Provides an explanation for an inference within a transaction

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• inference (string)

• config (TransactionOptions)

• params (object)

Returns Promise<HTTP.Body>

db.reasoning.explainInconsistencyInTransaction(conn, database, transactionId, options, params)

Provides the reason why a database is inconsistent, as reported by db.reasoning.consistency

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• options ({ namedGraph: string })

• params (object)

Returns Promise<HTTP.Body>

db.reasoning.schema(conn, database, params)

Gets the reasoning schema of the database

Expects the following parameters:

• conn (Connection)

• database (string)

• params (object)

Returns Promise<HTTP.Body>

query

PropertyOptions

Object with the following values:

• uri (string)
• property (string)

query.property(conn, database, config, params)

Gets the values for a specific property of a URI individual.

Expects the following parameters:

• conn (Connection)

• database (string)

• config (PropertyOptions)

• params (object)

Returns Promise<HTTP.Body>

query.explain(conn, database, query, params)

Gets the query plan generated by Stardog for a given SPARQL query.

Expects the following parameters:

• conn (Connection)

• database (string)

• query (string)

• params (object)

Returns Promise<HTTP.Body>

query.execute(conn, database, query, params)

Executes a query against a database.

Expects the following parameters:

• conn (Connection)

• database (string)

• query (string)

• params (object)

Returns Promise<HTTP.Body>

query.executeInTransaction(conn, database, transactionId, query, params)

Executes a query against a database within a transaction.

Expects the following parameters:

• conn (Connection)

• database (string)

• transactionId (string)

• query (string)

• params (object)

Returns Promise<HTTP.Body>

query.list(conn)

Gets a list of actively running queries.

Expects the following parameters:

• conn (Connection)

Returns Promise<HTTP.Body>

query.kill(conn, queryId)

Kills an actively running query.

Expects the following parameters:

• conn (Connection)

• queryId (string)

Returns Promise<HTTP.Body>

query.get(conn, queryId)

Gets information about an actively running query.

Expects the following parameters:

• conn (Connection)

• queryId (string)

Returns Promise<HTTP.Body>

StoredQueryOptions

Object with the following values:

• name (string)
• database (string)
• query (string)
• shared (boolean)

stored

query.stored.create(conn, config, params)

Stores a query in Stardog, either on the system level or for a given database.

Expects the following parameters:

• conn (Connection)

• config (StoredQueryOptions)

• params (object)

Returns Promise<HTTP.Body>

query.stored.list(conn, params)

Lists all stored queries.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

query.stored.remove(conn, storedQuery, params)

Removes a given stored query.

Expects the following parameters:

• conn (Connection)

• storedQuery (string)

• params (object)

Returns Promise<HTTP.Body>

user

User

Object with the following values:

• username (string)
• password (string)
• superuser (boolean)

Action

One of the following values:

'CREATE' | 'DELETE' | 'READ' | 'WRITE' | 'GRANT' | 'REVOKE' | 'EXECUTE'

ResourceType

One of the following values:

'db' | 'user' | 'role' | 'admin' | 'metadata' | 'named-graph' | 'icv-constraints'

user.list(conn, params)

Gets a list of users.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

user.get(conn, username, params)

Gets all information for a given user.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.create(conn, user, params)

Creates a new user.

Expects the following parameters:

• conn (Connection)

• user (User)

• params (object)

Returns Promise<HTTP.Body>

user.changePassword(conn, username, password, params)

Changes a user's password.

Expects the following parameters:

• conn (Connection)

• username (string)

• password (string)

• params (object)

Returns Promise<HTTP.Body>

user.valid(conn, params)

Verifies that a Connection's credentials are valid.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

user.enabled(conn, username, params)

Verifies that a user is enabled.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.enable(conn, username, enabled, params)

Enables/disables a user.

Expects the following parameters:

• conn (Connection)

• username (string)

• enabled (boolean)

• params (object)

Returns Promise<HTTP.Body>

user.setRoles(conn, username, roles, params)

Sets roles for a user.

Expects the following parameters:

• conn (Connection)

• username (string)

• roles (string[])

• params (object)

Returns Promise<HTTP.Body>

user.listRoles(conn, username, params)

Gets a list of roles assigned to a user.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.assignPermission(conn, username, permission, params)

Creates a new permission for a user over a given resource.

Expects the following parameters:

• conn (Connection)

• username (string)

• permission (Permission)

• params (object)

Returns Promise<HTTP.Body>

user.deletePermission(conn, username, permission, params)

Removes a permission for a user over a given resource.

Expects the following parameters:

• conn (Connection)

• username (string)

• permission (Permission)

• params (object)

Returns Promise<HTTP.Body>

user.permissions(conn, username, params)

Gets a list of permissions assigned to user.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.effectivePermissions(conn, username, params)

Gets a list of a user's effective permissions.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.superUser(conn, username, params)

Specifies whether a user is a superuser.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

user.remove(conn, username, params)

Deletes a user.

Expects the following parameters:

• conn (Connection)

• username (string)

• params (object)

Returns Promise<HTTP.Body>

Role

Object with the following values:

• rolename (string)

Permission

Object with the following values:

• action (Action)
• resourceType (ResourceType)
• resources (string[])

role

user.role.create(conn, role, params)

Creates a new role.

Expects the following parameters:

• conn (Connection)

• role (Role)

• params (object)

Returns Promise<HTTP.Body>

user.role.list(conn, params)

Lists all existing roles.

Expects the following parameters:

• conn (Connection)

• params (object)

Returns Promise<HTTP.Body>

user.role.remove(conn, role, params)

Deletes an existing role from the system.

Expects the following parameters:

• conn (Connection)

• role (Role)

• params (object)

Returns Promise<HTTP.Body>

user.role.usersWithRole(conn, role, params)

Lists all users that have been assigned a given role.

Expects the following parameters:

• conn (Connection)

• role (Role)

• params (object)

Returns Promise<HTTP.Body>

user.role.assignPermission(conn, role, permission, params)

Adds a permission over a given resource to a given role.

Expects the following parameters:

• conn (Connection)

• role (Role)

• permission (Permission)

• params (object)

Returns Promise<HTTP.Body>

user.role.deletePermission(conn, role, permission, params)

Removes a permission over a given resource from a given role.

Expects the following parameters:

• conn (Connection)

• role (Role)

• permission (Permission)

• params (object)

Returns Promise<HTTP.Body>

user.role.permissions(conn, role, params)

Lists all permissions assigned to a given role.

Expects the following parameters:

• conn (Connection)

• role (Role)

• params (object)

Returns Promise<HTTP.Body>