Improved LDkit API documentation (#91)

Resolves #70.

.vscode/import_map.json

@@ -1,13 +1,13 @@
 {
   "imports": {
-    "$fresh/": "https://deno.land/x/[email protected]/",
-    "preact": "https://esm.sh/[email protected]",
-    "preact/": "https://esm.sh/[email protected]/",
-    "preact-render-to-string": "https://esm.sh/*[email protected]",
+    "$fresh/": "https://deno.land/x/[email protected]/",
+    "preact": "https://esm.sh/[email protected]",
+    "preact/": "https://esm.sh/[email protected]/",
     "@preact/signals": "https://esm.sh/*@preact/[email protected]",
     "@preact/signals-core": "https://esm.sh/*@preact/[email protected]",
     "twind": "https://esm.sh/[email protected]",
     "twind/": "https://esm.sh/[email protected]/",
+    "$doc_components/": "https://deno.land/x/[email protected]/",
 
     "$std/": "https://deno.land/[email protected]/",
 

examples/basic/main.ts

@@ -21,7 +21,7 @@ const PersonSchema = {
 // Create a resource using the data schema and context above
 const Persons = createLens(PersonSchema, options);
 
-// List all persons
+// List some persons
 const persons = await Persons.find({ take: 10 });
 for (const person of persons) {
   console.log(person.name); // string

library/decoder.ts

@@ -1,8 +1,8 @@
 import type { Options } from "./options.ts";
 import { fromRdf, Graph, Iri, Node, type RDF } from "./rdf.ts";
 import type { ExpandedProperty, ExpandedSchema } from "./schema/mod.ts";
-import ldkit from "./namespaces/ldkit.ts";
-import rdf from "./namespaces/rdf.ts";
+import { ldkit } from "../namespaces/ldkit.ts";
+import { rdf } from "../namespaces/rdf.ts";
 
 export const decode = (
   graph: Graph,

library/encoder.ts

@@ -1,8 +1,8 @@
 import type { Options } from "./options.ts";
 import { DataFactory, type Iri, type RDF, toRdf } from "./rdf.ts";
 import type { ExpandedProperty, ExpandedSchema } from "./schema/mod.ts";
-import xsd from "./namespaces/xsd.ts";
-import rdf from "./namespaces/rdf.ts";
+import { xsd } from "../namespaces/xsd.ts";
+import { rdf } from "../namespaces/rdf.ts";
 
 type DecodedNode = Record<string, unknown>;
 

library/engine/mod.ts

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

library/engine/query_engine.ts

@@ -1,12 +1,26 @@
-import { type IQueryEngine, type QueryContext, type RDF } from "../rdf.ts";
+import { type RDF } from "../rdf.ts";
+
+import { type IQueryEngine, type QueryContext } from "./types.ts";
 import {
   getResponseTypes,
   resolve,
   type ResolverType,
 } from "./query_resolvers.ts";
 
+/**
+ * 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 implements IQueryEngine {
-  protected getSparqlEndpoint(context?: QueryContext) {
+  protected getSparqlEndpoint(context?: QueryContext): string {
     if (!context) {
       throw new Error(
         "No context supplied to QueryEngine. You need to create a default context or pass one to a resource.",
@@ -40,11 +54,15 @@ export class QueryEngine implements IQueryEngine {
     );
   }
 
-  protected getFetch(context?: QueryContext) {
+  protected getFetch(context?: QueryContext): typeof fetch {
     return context && context.fetch ? context.fetch : fetch;
   }
 
-  query(query: string, responseType: string, context?: QueryContext) {
+  protected query(
+    query: string,
+    responseType: string,
+    context?: QueryContext,
+  ): Promise<Response> {
     const endpoint = this.getSparqlEndpoint(context);
     const fetchFn = this.getFetch(context);
     return fetchFn(endpoint, {
@@ -59,7 +77,7 @@ export class QueryEngine implements IQueryEngine {
     });
   }
 
-  async queryAndResolve<T extends ResolverType>(
+  protected async queryAndResolve<T extends ResolverType>(
     type: T,
     query: string,
     context?: QueryContext,
@@ -81,27 +99,55 @@ export class QueryEngine implements IQueryEngine {
     return resolve(type, response);
   }
 
-  queryBindings(
+  /**
+   * Executes a SPARQL SELECT query and returns a stream of bindings.
+   *
+   * @param query SPARQL query string
+   * @param context Engine context
+   * @returns Stream of bindings
+   */
+  public queryBindings(
     query: string,
     context?: QueryContext,
   ): Promise<RDF.ResultStream<RDF.Bindings>> {
     return this.queryAndResolve("bindings", query, context);
   }
 
-  queryBoolean(
+  /**
+   * Executes a SPARQL ASK query and returns a boolean result.
+   *
+   * @param query SPARQL query string
+   * @param context Engine context
+   * @returns Boolean result
+   */
+  public queryBoolean(
     query: string,
     context?: QueryContext,
   ): Promise<boolean> {
     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: string,
     context?: QueryContext,
   ): Promise<RDF.ResultStream<RDF.Quad>> {
     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: string,
     context?: QueryContext,

library/engine/query_engine_proxy.ts

@@ -1,12 +1,8 @@
-import {
-  IQueryEngine,
-  N3,
-  quadsToGraph,
-  type QueryContext,
-  type RDF,
-} from "../rdf.ts";
+import { N3, quadsToGraph, type RDF } from "../rdf.ts";
 import { type AsyncIterator } from "../asynciterator.ts";
 
+import type { IQueryEngine, QueryContext } from "./types.ts";
+
 export class QueryEngineProxy {
   private readonly engine: IQueryEngine;
   private readonly context: QueryContext;

library/engine/types.ts

@@ -0,0 +1,35 @@
+import type {
+  IDataSource,
+  IQueryContextCommon,
+} from "npm:@comunica/[email protected]";
+
+import { RDF } from "../rdf.ts";
+
+/**
+ * A set of context entries that can be passed to a query engine,
+ * such as data sources, fetch configuration, etc.
+ *
+ * @example
+ * ```typescript
+ * import { QueryContext, QueryEngine } from "ldkit";
+ *
+ * const context: QueryContext = {
+ *   sources: ["https://dbpedia.org/sparql"],
+ * };
+ *
+ * const engine = new QueryEngine();
+ * await engine.queryBoolean("ASK { ?s ?p ?o }", context);
+ * ```
+ */
+export type QueryContext =
+  & RDF.QueryStringContext
+  & RDF.QuerySourceContext<IDataSource>
+  & IQueryContextCommon;
+
+/**
+ * Interface of a query engine compatible with LDkit
+ */
+export type IQueryEngine = RDF.StringSparqlQueryable<
+  RDF.SparqlResultSupport,
+  QueryContext
+>;