Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »

sparqlee

0.0.2 • Public • Published

Sparqlee

Greenkeeper badge Build Status Coverage Status Gitter chat

A simple SPARQL expression evaluator library.

This package is available on npm, type definitions are provided.

Using Sparqlee

const expression = ...some sparql algebra expression...;
const bindings = ...some bindings/solution mapping...;
 
// Create an evaluator (a sync evaluator will exist in the future too)
const evaluator = new AsyncEvaluator(expression)
 
// evaluate it as a term
const result: RDF.Term = await evaluator.evaluate(bindings);
 
// or evaluate it as an Effective Boolean Value (for e.g in FILTER)
const result: boolean = await evaluator.evaluateAsEBV(bindings);
 

Note: If you want to use aggregates, or exists you should check out the stream section.

Errors

Sparqlee exports an Error class called ExpressionError from which all SPARQL related errors inherit. These might include unbound variables, wrong types, invalid lexical forms, and much more. More info on errors here. These errors can be caught, and may impact program execution in an expected way. All other errors are unexpected, and are thus programmer mistakes or mistakes in this library.

There is also the utility function isExpressionError for detecting these cases.

// Make sure to catch errors if you don't control binding input
try {
  const result = await evaluator.evaluate(bindings);
  consumeResult(result;)
} catch (error) {
  if (isExpressionError(error)) {
    console.log(error); // SPARQL related errors
    ...                 // Move on, ignore result, ...
  } else {
    throw error;        // Programming errors or missing features.
  }
}

Streams

'Aggregates' and 'Exists' operations are annoying problems to tackle in the context of an expression evaluator, since they make the whole thing stateful. They might span entire streams and, depending on the use case, have very different requirements for speed and memory consumption. Sparqlee has therefore decided to delegate this responsibility back to you (and might provide utility in the future). It accepts functions that will resolve the respective aggregate and exists operators, and will use those when needed. This way, the library can still be optimized for simple use cases, both in it's API as in it's development time, while it can still support the full spec.

NOTE: Aggregates and Exists are not implemented yet.

Spec compliance

TODO Add section about differences from the spec and which functions are affected (and which are implemented). See also extensible value testing and error handling.

TODO String literals (plain literals etc...)

TODO Replace with check marks

Function Implemented Tested Spec compliant
Operator Mapping
! (not)
+ (unary plus)
- (unary minus)
||
&&
=
!=
<
>
<=
>=
*
/
+
-
Notes Spec compliance depends on #13 and #14
Functional Forms
BOUND
IF
COALESCE
NOT EXISTS
EXISTS
logical-or
logical-and
RDFTerm-equal ?
sameTerm
IN
NOT IN
Notes
On RDF Terms
isIRI
isBlank
isLiteral
isNumeric
str
lang
datatype
IRI
BNODE
STRDT
STRLANG
UUID
STRUID
Notes
On Strings
STRLEN
SUBSTR
UCASE
LCASE
STRSTARTS
STRENDS
CONTAINS
STRBEFORE
STRAFTER
ENCODE_FOR_URI
CONCAT
langMatches ?
REGEX
REPLACE
Notes
On Numerics
abs
round
ceil
floor
RAND
_Notes
On Dates and Times
now
year
month
day
hours
minutes
seconds
timezone
tz
Notes
Hash Functions
SHA1
SHA256
SHA384
SHA512
Notes
XPath Constructor Functions
str (see 'On Terms')
flt
dbl
dec
int
dT
bool

Development

Setup locally

  1. Install yarn (or npm) and node.
  2. Run yarn install.
  3. Use these evident commands (or check package.json):
    • building once: yarn run build
    • build and watch: yarn run watch
    • testing: yarn run test
    • benchmarking: yarn run bench

Adding unimplemented functions

Functions are defined in the functions directory, and you can add them there. All definitions are defined using a builder model defined in Helpers.ts.

Three kinds exists:

  • Regular functions: Functions with a uniform interface, that only need their arguments to calculate their result.
  • Special functions: whose behaviour deviates enough from the norm to warrant the implementations taking full control over type checking and evaluation (these are mostly the functional forms).
  • Named functions: which correspond to the SPARQLAlgebra Named Expressions.

TODO: Explain this hot mess some more.

Layout and control flow

The only important external facing API is creating an Evaluator. When you create one, the SPARQL Algebra expression that is passed will be transformed to an internal representation (see Transformation.ts). This will build objects (see expressions module) that contain all the logic and data for evaluation, for example the implementations for SPARQL functions (see functions module). After transformation, the evaluator will recursively evaluate all the expressions.

Testing

Running tests will generate a test-report.html in the root dir. TODO Explain test organizatian and expression tables

install

npm i sparqlee

Downloadsweekly downloads

130

version

0.0.2

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability