ldkit 1.1.0 → 2.1.0

package/README.md

@@ -40,7 +40,7 @@ import * as ldkit from "https://deno.land/x/ldkit/mod.ts";
 ### Create data schema and set up RDF source
 
 ```ts
-import { type Context, createLens } from "ldkit";
+import { createLens, type Options } from "ldkit";
 import { dbo, rdfs, xsd } from "ldkit/namespaces";
 
 // Create a schema
@@ -54,14 +54,14 @@ const PersonSchema = {
   },
 } as const;
 
-// Create a context for query engine
-const context: Context = {
+// Create options for query engine
+const options: Options = {
   sources: ["https://dbpedia.org/sparql"], // SPARQL endpoint
   language: "en", // Preferred language
 };
 
-// Create a resource using the data schema and context above
-const Persons = createLens(PersonSchema, context);
+// Create a resource using the data schema and options above
+const Persons = createLens(PersonSchema, options);
 ```
 
 ### List all available data
@@ -110,6 +110,16 @@ Persons.delete("http://dbpedia.org/resource/Alan_Turing");
 
 More complex examples can be found in [documentation](https://ldkit.io/docs).
 
+## Specification Compliance
+
+LDkit complies with the following specifications:
+
+- [RDF/JS: Data model specification](https://rdf.js.org/data-model-spec/)
+- [RDF/JS: Query specification](https://rdf.js.org/query-spec/)
+- [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/)
+- [SPARQL 1.1 Update](https://www.w3.org/TR/2013/REC-sparql11-update-20130321/)
+- [SPARQL 1.1 Protocol](https://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/)
+
 ## License
 
 [MIT License](./LICENSE.md)

package/esm/library/decoder.js

@@ -1,8 +1,11 @@
 import { fromRdf } from "./rdf.js";
-import ldkit from "./namespaces/ldkit.js";
-import rdf from "./namespaces/rdf.js";
+import { ldkit } from "../namespaces/ldkit.js";
+import { rdf } from "../namespaces/rdf.js";
+export const decode = (graph, schema, options) => {
+    return Decoder.decode(graph, schema, options);
+};
 class Decoder {
-    constructor(graph, schema, context) {
+    constructor(graph, schema, options) {
         Object.defineProperty(this, "graph", {
             enumerable: true,
             configurable: true,
@@ -15,7 +18,7 @@ class Decoder {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "context", {
+        Object.defineProperty(this, "options", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -29,10 +32,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)) {
@@ -75,7 +78,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;
@@ -88,20 +90,11 @@ class Decoder {
         this.setCachedNode(nodeIri, schema, output);
         return output;
     }
-    decodeNodeType(node) {
-        const typeTerms = node.get(rdf.type);
-        if (!typeTerms) {
-            return [];
-        }
-        return typeTerms.reduce((acc, term) => {
-            if (term.value !== ldkit.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.type
+            ? allTerms
+            : allTerms?.filter((term) => term.value !== ldkit.Resource);
         if (!terms) {
             if (!property["@optional"]) {
                 // No data, required property
@@ -109,7 +102,7 @@ class Decoder {
             }
             else {
                 // No data, optional property
-                return property["@array"] ? [] : undefined;
+                return property["@array"] ? [] : null;
             }
         }
         if (property["@multilang"]) {
@@ -141,13 +134,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 {
@@ -161,15 +154,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) {
@@ -199,6 +192,3 @@ class Decoder {
         }
     }
 }
-export const decode = (graph, schema, context) => {
-    return Decoder.decode(graph, schema, context);
-};

package/esm/library/encoder.js

@@ -1,12 +1,27 @@
 import { DataFactory, toRdf } from "./rdf.js";
-import xsd from "./namespaces/xsd.js";
-import rdf from "./namespaces/rdf.js";
-export const encode = (node, schema, context, variableInitCounter = 0) => {
-    return Encoder.encode(node, schema, context, variableInitCounter);
+import { xsd } from "../namespaces/xsd.js";
+import { rdf } from "../namespaces/rdf.js";
+import { ldkit } from "../namespaces/ldkit.js";
+export const encode = (node, schema, options, includeType = true, variableInitCounter = 0) => {
+    return Encoder.encode(node, schema, options, includeType, variableInitCounter);
+};
+export const encodeValue = (value, datatype, df) => {
+    if (datatype === ldkit.IRI) {
+        return df.namedNode(value);
+    }
+    return toRdf(value, {
+        datatype: df.namedNode(datatype),
+    });
 };
 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,
@@ -32,11 +47,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);
@@ -58,7 +74,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;
@@ -96,22 +114,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.string;
-            if (typeof val === "string" && this.context.language) {
+            if (typeof val === "string" && this.options.language) {
                 if (propertyType === xsd.string || propertyType === rdf.langString) {
-                    this.push(nodeId, propertyId, this.df.literal(val, this.context.language));
+                    this.push(nodeId, propertyId, this.df.literal(val, this.options.language));
                     return;
                 }
             }
-            const rdfValue = toRdf(val, {
-                datatype: this.df.namedNode(propertyType),
-            });
+            const rdfValue = encodeValue(val, propertyType, this.df);
             this.push(nodeId, propertyId, rdfValue);
         });
     }

package/esm/library/engine/mod.js

@@ -1,2 +1,2 @@
-export { QueryEngine } from "./query_engine.js";
-export { QueryEngineProxy } from "./query_engine_proxy.js";
+export * from "./query_engine.js";
+export * from "./types.js";

package/esm/library/engine/query_engine.js

@@ -1,4 +1,16 @@
 import { getResponseTypes, resolve, } from "./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.
+ */
 export class QueryEngine {
     getSparqlEndpoint(context) {
         if (!context) {
@@ -52,15 +64,43 @@ export class QueryEngine {
         }
         return resolve(type, response);
     }
+    /**
+     * 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);
     }
+    /**
+     * 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/esm/library/engine/query_engine_proxy.js

@@ -1,21 +1,20 @@
-import { quadsToGraph } from "../rdf.js";
-import { resolveContext, resolveEngine } from "../global.js";
+import { N3, quadsToGraph } from "../rdf.js";
 export 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 = resolveContext(context);
-        this.engine = resolveEngine(engine);
+        this.engine = engine;
+        this.context = context;
     }
     queryBoolean(query) {
         return this.engine.queryBoolean(query, this.context);
@@ -27,7 +26,8 @@ export class QueryEngineProxy {
     async queryGraph(query) {
         const quadStream = await this.engine.queryQuads(query, this.context);
         const quads = await (quadStream.toArray());
-        return quadsToGraph(quads);
+        const store = new N3.Store(quads);
+        return quadsToGraph(store);
     }
     queryVoid(query) {
         return this.engine.queryVoid(query, this.context);

package/esm/library/engine/types.js

@@ -0,0 +1 @@
+export {};