ldkit 0.8.0 → 2.0.0

package/esm/rdf.js

@@ -1 +1,14 @@
-export * from "./library/rdf.js";
+/**
+ * RDF utilities
+ *
+ * This module contains a re-export of external RDF libraries that are used
+ * in LDkit and may be used in tandem with LDkit in Linked Data applications as well.
+ *
+ * Included packages:
+ * - [@rdfjs/types](https://github.com/rdfjs/types) [RDF/JS](https://rdf.js.org/) authoritative TypeScript typings
+ * - [n3](https://rdf.js.org/N3.js/) RDF parser and serializer
+ * - [rdf-data-factory](https://github.com/rubensworks/rdf-data-factory.js) A TypeScript/JavaScript implementation of the RDF/JS data factory
+ * - [rdf-literal](https://github.com/rubensworks/rdf-literal.js) Translates between RDF literals and JavaScript primitives
+ * @module
+ */
+export { DataFactory, DefaultGraph, fromRdf, N3, toRdf, } from "./library/rdf.js";

package/esm/sparql.js

@@ -1 +1,14 @@
+/**
+ * SPARQL builders that provide a fluent interface for building SPARQL queries
+ *
+ * @example
+ * ```typescript
+ * import { SELECT } from "ldkit/sparql";
+ *
+ * const query = SELECT`?s ?p ?o`.WHERE`?s ?p ?o`.LIMIT(10).build();
+ * console.log(query); // SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10;
+ * ```
+ *
+ * @module
+ */
 export * from "./library/sparql/mod.js";

package/package.json

@@ -3,7 +3,7 @@
   "main": "./script/mod.js",
   "types": "./types/mod.d.ts",
   "name": "ldkit",
-  "version": "0.8.0",
+  "version": "2.0.0",
   "description": "LDkit, a Linked Data query toolkit for TypeScript developers",
   "homepage": "https://ldkit.io",
   "author": "Karel Klima <karelklima@gmail.com> (https://karelklima.com)",
@@ -65,9 +65,11 @@
   },
   "dependencies": {
     "@comunica/types": "2.6.8",
+    "@rdfjs/types": "*",
+    "@types/n3": "*",
     "asynciterator": "3.8.0",
+    "n3": "1.17.2",
     "rdf-data-factory": "1.1.1",
-    "rdf-js": "4.0.2",
     "rdf-literal": "1.3.1"
   }
 }

package/script/library/decoder.js

@@ -1,14 +1,15 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decode = void 0;
 const rdf_js_1 = require("./rdf.js");
-const ldkit_js_1 = __importDefault(require("./namespaces/ldkit.js"));
-const rdf_js_2 = __importDefault(require("./namespaces/rdf.js"));
+const ldkit_js_1 = require("../namespaces/ldkit.js");
+const rdf_js_2 = require("../namespaces/rdf.js");
+const decode = (graph, schema, options) => {
+    return Decoder.decode(graph, schema, options);
+};
+exports.decode = decode;
 class Decoder {
-    constructor(graph, schema, context) {
+    constructor(graph, schema, options) {
         Object.defineProperty(this, "graph", {
             enumerable: true,
             configurable: true,
@@ -21,7 +22,7 @@ class Decoder {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "context", {
+        Object.defineProperty(this, "options", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -35,10 +36,10 @@ class Decoder {
         });
         this.graph = graph;
         this.schema = schema;
-        this.context = context;
+        this.options = options;
     }
-    static decode(graph, schema, context) {
-        return new Decoder(graph, schema, context).decode();
+    static decode(graph, schema, options) {
+        return new Decoder(graph, schema, options).decode();
     }
     getCachedNode(nodeIri, schema) {
         if (!this.cache.has(schema)) {
@@ -55,17 +56,17 @@ class Decoder {
     decode() {
         const output = [];
         for (const [iri, properties] of this.graph) {
-            if (properties.has(rdf_js_2.default.type)) {
-                const types = properties.get(rdf_js_2.default.type);
+            if (properties.has(rdf_js_2.rdf.type)) {
+                const types = properties.get(rdf_js_2.rdf.type);
                 for (const type of types) {
-                    if (type.termType === "NamedNode" && type.value === ldkit_js_1.default.Resource) {
+                    if (type.termType === "NamedNode" && type.value === ldkit_js_1.ldkit.Resource) {
                         output.push(this.decodeNode(iri, this.schema));
                     }
                 }
             }
         }
         if (this.graph.size > 0 && output.length < 1) {
-            throw new Error(`Unable to decode graph - no resources with type <${ldkit_js_1.default.Resource}> found`);
+            throw new Error(`Unable to decode graph - no resources with type <${ldkit_js_1.ldkit.Resource}> found`);
         }
         return output;
     }
@@ -81,7 +82,6 @@ class Decoder {
         if (!node) {
             throw new Error(`Error decoding graph, <${nodeIri}> node not found.`);
         }
-        output.$type = this.decodeNodeType(node);
         Object.keys(schema).forEach((key) => {
             if (key === "@type") {
                 return;
@@ -94,20 +94,11 @@ class Decoder {
         this.setCachedNode(nodeIri, schema, output);
         return output;
     }
-    decodeNodeType(node) {
-        const typeTerms = node.get(rdf_js_2.default.type);
-        if (!typeTerms) {
-            return [];
-        }
-        return typeTerms.reduce((acc, term) => {
-            if (term.value !== ldkit_js_1.default.Resource) {
-                acc.push(term.value);
-            }
-            return acc;
-        }, []);
-    }
     decodeNodeProperty(nodeIri, node, propertyKey, property) {
-        const terms = node.get(property["@id"]);
+        const allTerms = node.get(property["@id"]);
+        const terms = property["@id"] !== rdf_js_2.rdf.type
+            ? allTerms
+            : allTerms?.filter((term) => term.value !== ldkit_js_1.ldkit.Resource);
         if (!terms) {
             if (!property["@optional"]) {
                 // No data, required property
@@ -115,7 +106,7 @@ class Decoder {
             }
             else {
                 // No data, optional property
-                return property["@array"] ? [] : undefined;
+                return property["@array"] ? [] : null;
             }
         }
         if (property["@multilang"]) {
@@ -147,13 +138,13 @@ class Decoder {
             }
         }
         if (property["@array"]) {
-            if (property["@context"]) {
+            if (property["@schema"]) {
                 // Collection of resources specified by sub schema
                 return terms.map((term) => {
                     if (term.termType !== "NamedNode" && term.termType !== "BlankNode") {
                         throw new Error(`Property "${propertyKey}" data type mismatch - expected a node, but received ${term.termType} instead on resource <${nodeIri}>`);
                     }
-                    return this.decodeNode(term.value, property["@context"]);
+                    return this.decodeNode(term.value, property["@schema"]);
                 });
             }
             else {
@@ -167,15 +158,15 @@ class Decoder {
             }
         }
         // Single return value expected from this point on
-        if (property["@context"]) {
+        if (property["@schema"]) {
             for (const term of terms) {
                 if (term.termType === "NamedNode" || term.termType === "BlankNode") {
-                    return this.decodeNode(term.value, property["@context"]);
+                    return this.decodeNode(term.value, property["@schema"]);
                 }
             }
             throw new Error(`Property "${propertyKey}" data type mismatch - expected a named node for context on resource <${nodeIri}>`);
         }
-        const preferredLanguage = this.context.language;
+        const preferredLanguage = this.options.language;
         if (preferredLanguage) {
             // Try to find a term that corresponds to the preferred language
             for (const term of terms) {
@@ -205,7 +196,3 @@ class Decoder {
         }
     }
 }
-const decode = (graph, schema, context) => {
-    return Decoder.decode(graph, schema, context);
-};
-exports.decode = decode;

package/script/library/encoder.js

@@ -1,19 +1,32 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encode = void 0;
+exports.encodeValue = exports.encode = void 0;
 const rdf_js_1 = require("./rdf.js");
-const xsd_js_1 = __importDefault(require("./namespaces/xsd.js"));
-const rdf_js_2 = __importDefault(require("./namespaces/rdf.js"));
-const encode = (node, schema, context, variableInitCounter = 0) => {
-    return Encoder.encode(node, schema, context, variableInitCounter);
+const xsd_js_1 = require("../namespaces/xsd.js");
+const rdf_js_2 = require("../namespaces/rdf.js");
+const ldkit_js_1 = require("../namespaces/ldkit.js");
+const encode = (node, schema, options, includeType = true, variableInitCounter = 0) => {
+    return Encoder.encode(node, schema, options, includeType, variableInitCounter);
 };
 exports.encode = encode;
+const encodeValue = (value, datatype, df) => {
+    if (datatype === ldkit_js_1.ldkit.IRI) {
+        return df.namedNode(value);
+    }
+    return (0, rdf_js_1.toRdf)(value, {
+        datatype: df.namedNode(datatype),
+    });
+};
+exports.encodeValue = encodeValue;
 class Encoder {
-    constructor(context, variableInitCounter) {
-        Object.defineProperty(this, "context", {
+    constructor(options, includeType, variableInitCounter) {
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "includeType", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -39,11 +52,12 @@ class Encoder {
             writable: true,
             value: []
         });
-        this.context = context;
+        this.options = options;
+        this.includeType = includeType;
         this.variableCounter = variableInitCounter;
     }
-    static encode(node, schema, context, variableInitCounter) {
-        return new Encoder(context, variableInitCounter).encode(node, schema);
+    static encode(node, schema, options, includeType, variableInitCounter) {
+        return new Encoder(options, includeType, variableInitCounter).encode(node, schema);
     }
     encode(node, schema) {
         const nodeId = this.getNodeId(node);
@@ -65,7 +79,9 @@ class Encoder {
         return node.$type ? [node.$type] : [];
     }
     encodeNode(node, schema, nodeId) {
-        this.encodeNodeType(node, schema["@type"], nodeId);
+        if (this.includeType) {
+            this.encodeNodeType(node, schema["@type"], nodeId);
+        }
         Object.keys(schema).forEach((key) => {
             if (key === "@type") {
                 return;
@@ -76,7 +92,7 @@ class Encoder {
     encodeNodeType(node, requiredTypes, nodeId) {
         const finalTypes = new Set([...this.getNodeTypes(node), ...requiredTypes]);
         finalTypes.forEach((type) => {
-            this.push(nodeId, this.df.namedNode(rdf_js_2.default.type), this.df.namedNode(type));
+            this.push(nodeId, this.df.namedNode(rdf_js_2.rdf.type), this.df.namedNode(type));
         });
     }
     encodeNodeProperty(value, property, nodeId) {
@@ -103,22 +119,20 @@ class Encoder {
         }
         const values = Array.isArray(value) ? value : [value];
         values.forEach((val) => {
-            if (property["@context"]) {
+            if (property["@schema"]) {
                 const subNodeId = this.getNodeId(val);
-                this.encodeNode(val, property["@context"], subNodeId);
+                this.encodeNode(val, property["@schema"], subNodeId);
                 this.push(nodeId, propertyId, subNodeId);
                 return;
             }
-            const propertyType = property["@type"] ? property["@type"] : xsd_js_1.default.string;
-            if (typeof val === "string" && this.context.language) {
-                if (propertyType === xsd_js_1.default.string || propertyType === rdf_js_2.default.langString) {
-                    this.push(nodeId, propertyId, this.df.literal(val, this.context.language));
+            const propertyType = property["@type"] ? property["@type"] : xsd_js_1.xsd.string;
+            if (typeof val === "string" && this.options.language) {
+                if (propertyType === xsd_js_1.xsd.string || propertyType === rdf_js_2.rdf.langString) {
+                    this.push(nodeId, propertyId, this.df.literal(val, this.options.language));
                     return;
                 }
             }
-            const rdfValue = (0, rdf_js_1.toRdf)(val, {
-                datatype: this.df.namedNode(propertyType),
-            });
+            const rdfValue = (0, exports.encodeValue)(val, propertyType, this.df);
             this.push(nodeId, propertyId, rdfValue);
         });
     }

package/script/library/engine/mod.js

@@ -1,7 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryEngineProxy = exports.QueryEngine = void 0;
-var query_engine_js_1 = require("./query_engine.js");
-Object.defineProperty(exports, "QueryEngine", { enumerable: true, get: function () { return query_engine_js_1.QueryEngine; } });
-var query_engine_proxy_js_1 = require("./query_engine_proxy.js");
-Object.defineProperty(exports, "QueryEngineProxy", { enumerable: true, get: function () { return query_engine_proxy_js_1.QueryEngineProxy; } });
+__exportStar(require("./query_engine.js"), exports);
+__exportStar(require("./types.js"), exports);

package/script/library/engine/query_engine.js

@@ -1,8 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryEngine = void 0;
-const rdf_js_1 = require("../rdf.js");
-const asynciterator_js_1 = require("../asynciterator.js");
+const query_resolvers_js_1 = require("./query_resolvers.js");
+/**
+ * A query engine that can query a SPARQL endpoint.
+ *
+ * Implements {@link IQueryEngine} interface.
+ *
+ * This engine is used by default if no other engine is configured.
+ * See {@link Options} for more details.
+ *
+ * If you need to query other data sources, or multiple SPARQL endpoints,
+ * you can use [Comunica](https://comunica.dev) instead, extend this engine,
+ * or implement your own.
+ */
 class QueryEngine {
     getSparqlEndpoint(context) {
         if (!context) {
@@ -33,10 +44,10 @@ class QueryEngine {
     getFetch(context) {
         return context && context.fetch ? context.fetch : fetch;
     }
-    async query(query, responseType, context) {
+    query(query, responseType, context) {
         const endpoint = this.getSparqlEndpoint(context);
         const fetchFn = this.getFetch(context);
-        const response = await fetchFn(endpoint, {
+        return fetchFn(endpoint, {
             method: "POST",
             headers: {
                 "accept": responseType,
@@ -46,36 +57,53 @@ class QueryEngine {
                 query,
             }),
         });
-        const json = await response.json();
-        return json;
     }
-    async queryBindings(query, context) {
-        const json = await this.query(query, "application/sparql-results+json", context);
-        if (!Array.isArray(json.results?.bindings)) {
-            throw new Error("Bindings SPARQL query result not found");
+    async queryAndResolve(type, query, context) {
+        const responseType = (0, query_resolvers_js_1.getResponseTypes)(type).join(", ");
+        const response = await this.query(query, responseType, context);
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Invalid query response status '${response.status} ${response.statusText}'`);
         }
-        const bindingsFactory = new rdf_js_1.BindingsFactory();
-        const bindingsIterator = new asynciterator_js_1.ArrayIterator(json.results.bindings);
-        // TODO: review the unknown type cast
-        return new asynciterator_js_1.MappingIterator(bindingsIterator, (i) => bindingsFactory.fromJson(i));
+        return (0, query_resolvers_js_1.resolve)(type, response);
     }
-    async queryBoolean(query, context) {
-        const json = await this.query(query, "application/sparql-results+json", context);
-        if ("boolean" in json) {
-            return Boolean(json.boolean);
-        }
-        throw new Error("Boolean SPARQL query result not found");
+    /**
+     * Executes a SPARQL SELECT query and returns a stream of bindings.
+     *
+     * @param query SPARQL query string
+     * @param context Engine context
+     * @returns Stream of bindings
+     */
+    queryBindings(query, context) {
+        return this.queryAndResolve("bindings", query, context);
     }
-    async queryQuads(query, context) {
-        const json = await this.query(query, "application/rdf+json", context);
-        if (!(json?.constructor === Object)) {
-            throw new Error("Quads SPARQL query result not found");
-        }
-        const quadFactory = new rdf_js_1.QuadFactory();
-        const treeIterator = new asynciterator_js_1.TreeIterator(json);
-        // TODO: review the unknown type cast
-        return new asynciterator_js_1.MappingIterator(treeIterator, (i) => quadFactory.fromJson(i));
+    /**
+     * Executes a SPARQL ASK query and returns a boolean result.
+     *
+     * @param query SPARQL query string
+     * @param context Engine context
+     * @returns Boolean result
+     */
+    queryBoolean(query, context) {
+        return this.queryAndResolve("boolean", query, context);
+    }
+    /**
+     * Executes a SPARQL CONSTRUCT query and returns a stream of quads.
+     *
+     * @param query SPARQL query string
+     * @param context Engine context
+     * @returns Stream of quads
+     */
+    queryQuads(query, context) {
+        return this.queryAndResolve("quads", query, context);
     }
+    /**
+     * Executes a SPARQL UPDATE query and returns nothing.
+     *
+     * @param query SPARQL query string
+     * @param context Engine context
+     * @returns Nothing
+     */
     async queryVoid(query, context) {
         await this.query(query, "application/sparql-results+json", context);
     }

package/script/library/engine/query_engine_proxy.js

@@ -2,23 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryEngineProxy = void 0;
 const rdf_js_1 = require("../rdf.js");
-const global_js_1 = require("../global.js");
 class QueryEngineProxy {
-    constructor(context, engine) {
-        Object.defineProperty(this, "context", {
+    constructor(engine, context) {
+        Object.defineProperty(this, "engine", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "engine", {
+        Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        this.context = (0, global_js_1.resolveContext)(context);
-        this.engine = (0, global_js_1.resolveEngine)(engine);
+        this.engine = engine;
+        this.context = context;
     }
     queryBoolean(query) {
         return this.engine.queryBoolean(query, this.context);
@@ -30,7 +29,8 @@ class QueryEngineProxy {
     async queryGraph(query) {
         const quadStream = await this.engine.queryQuads(query, this.context);
         const quads = await (quadStream.toArray());
-        return (0, rdf_js_1.quadsToGraph)(quads);
+        const store = new rdf_js_1.N3.Store(quads);
+        return (0, rdf_js_1.quadsToGraph)(store);
     }
     queryVoid(query) {
         return this.engine.queryVoid(query, this.context);

package/script/library/engine/query_resolvers.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolve = exports.getResponseTypes = void 0;
+const rdf_js_1 = require("../rdf.js");
+const asynciterator_js_1 = require("../asynciterator.js");
+class QueryResolver {
+}
+class BooleanJsonResolver extends QueryResolver {
+    async resolve(response) {
+        const json = await response.json();
+        if ("boolean" in json) {
+            return Boolean(json.boolean);
+        }
+        throw new Error("Boolean SPARQL query result not found");
+    }
+}
+class BindingsJsonResolver extends QueryResolver {
+    async resolve(response) {
+        const json = await response.json();
+        if (!Array.isArray(json.results?.bindings)) {
+            throw new Error("Bindings SPARQL query result not found");
+        }
+        const bindingsFactory = new rdf_js_1.BindingsFactory();
+        const bindingsIterator = new asynciterator_js_1.ArrayIterator(json.results.bindings);
+        // TODO: review the unknown type cast
+        return new asynciterator_js_1.MappingIterator(bindingsIterator, (i) => bindingsFactory.fromJson(i));
+    }
+}
+class QuadsJsonResolver extends QueryResolver {
+    async resolve(response) {
+        const json = await response.json();
+        if (!(json?.constructor === Object)) {
+            throw new Error("Quads SPARQL query result not found");
+        }
+        const quadFactory = new rdf_js_1.QuadFactory();
+        const treeIterator = new asynciterator_js_1.TreeIterator(json);
+        // TODO: review the unknown type cast
+        return new asynciterator_js_1.MappingIterator(treeIterator, (i) => quadFactory.fromJson(i));
+    }
+}
+class QuadsTurtleResolver extends QueryResolver {
+    async resolve(response) {
+        const text = await response.text();
+        const quads = new rdf_js_1.N3.Parser({ format: "turtle" }).parse(text);
+        return new asynciterator_js_1.ArrayIterator(quads);
+    }
+}
+const resolvers = {
+    "boolean": {
+        "application/sparql-results+json": new BooleanJsonResolver(),
+    },
+    "bindings": {
+        "application/sparql-results+json": new BindingsJsonResolver(),
+    },
+    "quads": {
+        "application/rdf+json": new QuadsJsonResolver(),
+        "text/turtle": new QuadsTurtleResolver(),
+    },
+};
+const getResponseTypes = (resolverType) => Object.keys(resolvers[resolverType]);
+exports.getResponseTypes = getResponseTypes;
+const resolve = (resolverType, response) => {
+    const contentType = response.headers.get("Content-type");
+    if (!contentType) {
+        throw new Error(`Content-type header was not found in response`);
+    }
+    const separatorPosition = contentType.indexOf(";");
+    const mime = separatorPosition > 0
+        ? contentType.substring(0, separatorPosition)
+        : contentType;
+    const resolver = resolvers[resolverType][mime];
+    if (!resolver) {
+        throw new Error(`No resolver exists for response type '${mime}'`);
+    }
+    return resolver.resolve(response);
+};
+exports.resolve = resolve;

package/script/library/engine/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });