Merge pull request #37 from LDflex/feat/custom-engine

feat/custom engine

README.md

@@ -45,8 +45,86 @@ const ruben = paths.create({
 showPerson(ruben);
 ```
 
+## Features
+
+### Using a customised ComunicaEngine
+
+This example uses the comunica engine for local file queries.
+
+```JavaScript
+const { PathFactory } = require('ldflex');
+const { default: ComunicaEngine } = require('@ldflex/comunica');
+const { namedNode } = require('@rdfjs/data-model');
+const { newEngine: localFileEngine } = require('@comunica/actor-init-sparql-file');
+
+// The JSON-LD context for resolving properties
+const context = {
+  "@context": {
+    "@vocab": "http://xmlns.com/foaf/0.1/",
+    "friends": "knows",
+  }
+};
+// The query engine and its source
+const queryEngine = new ComunicaEngine(
+    path.join(__dirname, 'ruben-verborgh.ttl'),
+    { engine: localFileEngine() }
+  );
+// The object that can create new paths
+const paths = new PathFactory({ context, queryEngine });
+
+async function showPerson(person) {
+  console.log(`This person is ${await person.name}`);
+
+  console.log(`${await person.givenName} is friends with:`);
+  for await (const name of person.friends.givenName)
+    console.log(`- ${name}`);
+}
+
+const ruben = paths.create({
+  subject: namedNode('https://ruben.verborgh.org/profile/#me'),
+});
+showPerson(ruben);
+```
+### Adding custom options to the ComunicaEngine
+
+Add [comunica context options](https://comunica.dev/docs/query/advanced/context/) which are passed to the Comunica Engine. 
+
+```JavaScript
+const { PathFactory } = require('ldflex');
+const { default: ComunicaEngine } = require('@ldflex/comunica');
+const { namedNode } = require('@rdfjs/data-model');
+
+// The JSON-LD context for resolving properties
+const context = {
+  "@context": {
+    "@vocab": "http://xmlns.com/foaf/0.1/",
+    "friends": "knows",
+  }
+};
+
+// The query engine and its source
+const queryEngine = new ComunicaEngine(
+    'https://ruben.verborgh.org/profile/',
+    { options: {/* add options here */} },
+  );
+
+// The object that can create new paths
+const paths = new PathFactory({ context, queryEngine });
+
+async function showPerson(person) {
+  console.log(`This person is ${await person.name}`);
+
+  console.log(`${await person.givenName} is friends with:`);
+  for await (const name of person.friends.givenName)
+    console.log(`- ${name}`);
+}
+
+const ruben = paths.create({
+  subject: namedNode('https://ruben.verborgh.org/profile/#me'),
+});
+showPerson(ruben);
+```
+
 ## License
 ©2018–present
-[Ruben Verborgh](https://ruben.verborgh.org/),
-Joachim Van Herwegen.
-[MIT License](https://github.com/LDflex/LDflex-Comunica/blob/master/LICENSE.md).
+[Ruben Verborgh](https://ruben.verborgh.org/), Joachim Van Herwegen, [Jesse Wright](https://github.com/jeswr/). [MIT License](https://github.com/LDflex/LDflex-Comunica/blob/master/LICENSE.md).

package.json

@@ -30,14 +30,17 @@
     "@babel/cli": "^7.8.4",
     "@babel/core": "^7.9.6",
     "@babel/preset-env": "^7.9.6",
+    "@comunica/actor-http-proxy": "^1.21.1",
+    "@comunica/actor-init-sparql-file": "^1.21.3",
+    "@comunica/actor-init-sparql-rdfjs": "^1.21.3",
     "@pollyjs/adapter-node-http": "^5.1.1",
     "@pollyjs/core": "^4.2.1",
     "@pollyjs/persister-fs": "^5.1.1",
     "@rdfjs/data-model": "^1.1.2",
     "eslint": "^7.0.0",
     "eslint-plugin-jest": "^24.3.6",
     "husky": "^6.0.0",
-    "jest": "^26.0.1",
+    "jest": "^26.6.3",
     "mkdirp": "^1.0.4",
     "n3": "^1.10.0",
     "semantic-release": "^17.4.2",

src/ComunicaEngine.js

@@ -10,11 +10,12 @@ export default class ComunicaEngine {
    * The default source can be a single URL, an RDF/JS Datasource,
    * or an array with any of these.
    */
-  constructor(defaultSource) {
-    this._engine = DefaultEngine;
+  constructor(defaultSource, settings = {}) {
+    this._engine = settings.engine ? settings.engine : DefaultEngine;
     // Preload sources but silence errors; they will be thrown during execution
     this._sources = this.parseSources(defaultSource);
     this._sources.catch(() => null);
+    this._options = settings.options ? settings.options : {};
   }
 
   /**
@@ -28,7 +29,7 @@ export default class ComunicaEngine {
     const sources = await (source ? this.parseSources(source) : this._sources);
     if (sources.length !== 0) {
       // Execute the query and yield the results
-      const queryResult = await this._engine.query(sparql, { sources });
+      const queryResult = await this._engine.query(sparql, { sources, ...this._options });
       yield* this.streamToAsyncIterable(queryResult.bindingsStream);
     }
   }

test/ComunicaEngine-test.js

@@ -1,6 +1,6 @@
 import ComunicaEngine from '../src/ComunicaEngine';
 
-import { mockHttp } from './util';
+import { mockHttp, readAll } from './util';
 import { namedNode, defaultGraph, quad } from '@rdfjs/data-model';
 import { Store } from 'n3';
 import { Readable } from 'stream';
@@ -255,10 +255,3 @@ describe('An ComunicaEngine instance with a default source that errors', () => {
     await expect(readAll(result)).rejects.toThrow('my error');
   });
 });
-
-async function readAll(asyncIterator) {
-  const items = [];
-  for await (const item of asyncIterator)
-    items.push(item);
-  return items;
-}