Updated documentation to v2 (#105)

Resolves #104. Resolves #85. Resolves #34. Resolves #20. Resolves #19. Resolves #18. Resolves #16. Resolves #15.
karelklima · Mar 5, 2024 · a5c46fe · a5c46fe
1 parent 9a52cc3
commit a5c46fe
Show file tree

Hide file tree

Showing 19 changed files with 216 additions and 134 deletions.
diff --git a/README.md b/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

diff --git a/docs/about-ldkit/index.md b/docs/about-ldkit/index.md
@@ -9,12 +9,12 @@ LDkit lets you access, display and modify any RDF data, and it works in browser,
 
 The typical LDkit workflow to access Linked Data comprises of these protocols:
 
-- You define a data source and other options through
-  [Context](./components/context).
+- You define a data source and other settings through
+  [Options](./components/options).
 - You define a [Namespace](./components/namespaces) for the data to be
   retrieved, or use an existing one.
 - You define a data [Schema](./components/schema) with the help of namespaces.
-- You create a data [Lens](./components/lens) and pass it the schema and context
+- You create a data [Lens](./components/lens) and pass it the schema and options
   to query data.
 - Optionally, you can tweak the [Query Engine](./components/query-engine).
 

diff --git a/docs/components/context.md b/docs/components/context.md
diff --git a/docs/components/lens.md b/docs/components/lens.md
@@ -8,20 +8,19 @@ data easily.
 In background, Lens handle building and executing SPARQL queries, data retrieval
 and transformation according to the data Schema.
 
-## Creating a resource
+## Creating a Lens instance
 
-A Lens requires a [Schema](./schema), a [Context](./context), and a
-[Query Engine](./query-engine). If you do not specify context or engine, default
-ones will be used.
+A Lens requires a [Schema](./schema) and an [Options](./options) object. You can
+pass options either directly, or you can set up default global options.
 
 ```ts
-import { type Context, createLens } from "ldkit";
+import { createLens, type Options } from "ldkit";
 
-const context: Context = {
+const options = {
   sources: ["https://example.com/sparql"],
-};
+} satisfies Options;
 
-const MyLens = createLens(MySchema, context); // will use default query engine
+const MyLens = createLens(MySchema, options); // will use default query engine
 ```
 
 ## Lens usage
@@ -32,12 +31,12 @@ of entities of type _dbo:Person_ that have a name, an abstract and a birth date.
 ### Create a Lens instance to query persons
 
 ```ts
-import { type Context, createLens } from "ldkit";
+import { createLens, type Options } from "ldkit";
 import { dbo, rdfs, xsd } from "ldkit/namespaces";
 
-const context: Context = {
+const options = {
   sources: ["https://example.com/sparql"],
-};
+} satisfies Options;
 
 // Create a schema
 const PersonSchema = {
@@ -47,8 +46,8 @@ const PersonSchema = {
   birthDate: { "@id": dbo.birthDate, "@type": xsd.date },
 } as const;
 
-// Create a resource using the data schema and context above
-const Persons = createLens(PersonSchema, context);
+// Create a resource using the data schema and options object above
+const Persons = createLens(PersonSchema, options);
 ```
 
 ### List all matched persons

diff --git a/docs/components/namespaces.md b/docs/components/namespaces.md
@@ -45,7 +45,13 @@ console.log(schema.Person); // prints http://schema.org/Person
 > namespaces like this:
 >
 > ```ts
-> import { rdf, schema } from "https://deno.land/x/ldkit@$VERSION/mod.ts";
+> import { rdf, schema } from "https://deno.land/x/ldkit@$VERSION/namespaces.ts";
+> ```
+>
+> or directly like:
+>
+> ```ts
+> import { rdf } from "https://deno.land/x/ldkit@$VERSION/namespaces/rdf.ts";
 > ```
 
 ### List of included namespaces
@@ -57,6 +63,7 @@ console.log(schema.Person); // prints http://schema.org/Person
 | **dcterms** | DCMI Metadata Terms                         | http://purl.org/dc/terms/                   |
 | **foaf**    | FOAF ontology                               | http://xmlns.com/foaf/0.1/                  |
 | **gr**      | Good Relations                              | http://purl.org/goodrelations/v1#           |
+| **owl**     | OWL Web Ontology Language                   | http://www.w3.org/2002/07/owl#              |
 | **rdf**     | RDF vocabulary                              | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
 | **rdfs**    | RDF Schema 1.1                              | http://www.w3.org/2000/01/rdf-schema#       |
 | **schema**  | Schema.org                                  | https://schema.org/                         |

diff --git a/docs/components/options.md b/docs/components/options.md
@@ -0,0 +1,60 @@
+# Options
+
+_Options_ is a configuration object that hosts LDkit settings for various of its
+components.
+
+The only mandatory property of the options is to specify one or more RDF
+datasources. The minimum example of such context is the following:
+
+```ts
+import { type Options } from "ldkit";
+
+const options = {
+  sources: ["https://example.com/sparql"],
+} satisfies Options;
+```
+
+The _Options_ structure accepted by LDkit is a superset of query engine
+_Context_ defined in
+[RDF/JS Query specification](https://rdf.js.org/query-spec/) and made compatible
+with Comunica _Context_, for maximizing ease of adoption. Therefore, if you use
+Comunica as a query engine with LDkit, chances are you do not have to to any
+changes - just pass the Comunica context as LDkit options.
+
+## LDkit Options properties
+
+| Key          | Type                          | Description                                                                                                                     |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **engine**   | `IQueryEngine`                | Query engine to process SPARQL queries. LDkit uses the default query engine, unless specified otherwise.                        |
+| **sources**  | `string[]` or `IDataSource[]` | List of RDF sources. The default query engine included in LDkit accepts only a single source, and it must be a SPARQL endpoint. |
+| **fetch**    | `typeof fetch`                | Custom fetch function.                                                                                                          |
+| **language** | `string`                      | Preferred data language - for cases when you query multilingual data.                                                           |
+| **take**     | `number`                      | Number of resources to return by default by the Lens object. The `LIMIT` property of a `SELECT` query.                          |
+| **logQuery** | `(query: string) => void`     | Function that is called every time a query is processed by the query engine. Useful for logging purposes.                       |
+
+## Setting default Options
+
+Options object needs to be passed to a data [Lens](./lens) as a parameter, and
+there are two ways how to handle that. Either you can pass the object directly
+as an argument when creating the `Lens` instance, or you can set a global
+options. If there are global options set up, then the `Lens` will use the global
+options object, unless you provide one directly when creating the instance.
+
+```ts
+import { createLens, type Options, setGlobalOptions } from "ldkit";
+
+const options = {
+  sources: ["https://example.com/sparql"],
+  language: "en",
+} satisfies Options;
+
+setGlobalOptions(options);
+
+const customOptions = {
+  ...options,
+  language: "cs",
+} satisfies Options;
+
+const firstResource = createLens(FirstSchema); // will use the global options
+const secondResource = createLens(SecondSchema, customOptions); // will use custom options
+```
diff --git a/docs/components/query-engine.md b/docs/components/query-engine.md
@@ -20,15 +20,15 @@ The `QueryEngine` follows
 [RDF/JS Query specification](https://rdf.js.org/query-spec/) and implements the
 `StringSparqlQueryable` interface.
 
-The `QueryEngine` is configurable through [context](./context).
+The `QueryEngine` is configurable through [Options](./options) object.
 
 ```ts
-import { type Context, QueryEngine } from "ldkit";
+import { type Options, QueryEngine } from "ldkit";
 
-const context: Context = {
+const options = {
   sources: ["https://example.com/sparql"], // required, must include one SPARQL endpoint
   fetch: customFetchFunction, // optional, must follow standard fetch interface
-};
+} satisfies Options;
 const engine = new QueryEngine();
 
 const response = await engine.queryBoolean("ASK { ?s ?p ?o }", context);
@@ -37,7 +37,7 @@ const response = await engine.queryBoolean("ASK { ?s ?p ?o }", context);
 > Note: The default query engine supports all SPARQL endpoints that conform to
 > the SPARQL 1.1 specification and can return data of MIME
 > `application/sparql-results+json` for `SELECT` and `ASK` queries, and
-> `application/rdf+json` for `CONSTRUCT` queries.
+> `text/turtle` or `application/rdf+json` for `CONSTRUCT` queries.
 
 ## Custom query engine
 
@@ -53,16 +53,16 @@ Comunica, or a custom engine derived from that - see
 
 A query engine instance needs to be passed to a data [Lens](./lens) as a
 parameter in order to query data, and there are two ways how to handle that.
-Either you can pass the engine directly as an argument when creating the `Lens`,
-or you can set an engine instance as a default one. If there is a default engine
-instance, then the `Lens` will use that engine, if you do not provide one
-directly.
+Either you can pass the engine directly as part of options argument when
+creating the `Lens` instance, or you can set an engine instance as a default
+one. If there is a default engine instance, then the `Lens` will use that
+engine, if you do not provide one directly.
 
 ```ts
-import { createLens, setDefaultEngine } from "ldkit";
+import { createLens, setGlobalOptions } from "ldkit";
 
 const engine = new MyCustomQueryEngine();
-setDefaultEngine(engine);
+setGlobalOptions({ engine });
 
 const MyLens = createLens(MySchema); // will use the custom engine, which is now default
 ```
diff --git a/docs/components/schema.md b/docs/components/schema.md
@@ -42,7 +42,6 @@ following type:
 ```ts
 type PersonType = {
   $id: string; // IRI
-  $type: string[]; // defined in `@type`
   name: string;
   birthDate: Date;
 };
@@ -61,7 +60,8 @@ When defining a schema, you can specify:
 
 ### Entity type
 
-Each schema must have at least one entity type defined.
+You can define one or more entity RDF type to narrow the search results. Setting
+the RDF type is recommended for optimal performance.
 
 ```ts
 const MySchema = {
@@ -89,12 +89,13 @@ const MySchema = {
     "@optional": true, // if present, the property is optional
     "@array": true, // if present, the resulting property is always an array
     "@multilang": true, // if present, the resulting property is a map of languages and literals
+    "@schema": SomeSubschema, // if present, uses a nested schema
   },
 } as const;
 ```
 
 Unless specified otherwise, it is assumed that any property is of type
-`xsd:string`, required, and not an array. You can override these default
+`xsd:string`, required, and not an array. You can override these defaults
 per-property.
 
 In addition, there is a shortcut to specify default properties. The following
@@ -139,7 +140,6 @@ const schema = {
 
 const convertedData = {
   $id: x.A,
-  $type: [x.Item],
   multilangProperty: {
     cs: "CS",
     en: "EN",
@@ -160,6 +160,35 @@ const MySchema = {
 };
 ```
 
+### Explicitly infer resulting TypeScript type of entities
+
+If you need, to explicitly use the resulting type of entities, that is, the
+corresponding native TypeScript type of RDF data converted to JavaScript, you
+can use the `SchemaInterface` helper type.
+
+```ts
+import { type SchemaInterface } from "ldkit";
+import { dbo, rdfs, xsd } from "ldkit/namespaces";
+
+const PersonSchema = {
+  "@type": dbo.Person,
+  name: rdfs.label,
+  birthDate: {
+    "@id": dbo.birthDate,
+    "@type": xsd.date,
+  },
+} as const;
+
+type PersonType = SchemaInterface<typeof PersonSchema>;
+/**
+ * {
+ *   $id: IRI, // string alias
+ *   name: string,
+ *   birthDate: Date
+ * }
+ */
+```
+
 ## Complete schema reference
 
 The following schema showcases all possible supported variations.
@@ -212,7 +241,6 @@ And the resulting type will be:
 ```ts
 type ThingType = {
   $id: string;
-  $type: string[];
   required: string;
   optional: string | undefined;
   array: string[];
@@ -223,7 +251,6 @@ type ThingType = {
   date: Date;
   nested: {
     $id: string;
-    $type: string[];
     nestedValue: string;
   };
 };

diff --git a/docs/v2/filtering.md → docs/features/filtering.md b/docs/v2/filtering.md → docs/features/filtering.md
diff --git a/docs/how-to/index.md → docs/features/index.md b/docs/how-to/index.md → docs/features/index.md
diff --git a/docs/v2/inverse-properties.md → docs/features/inverse-properties.md b/docs/v2/inverse-properties.md → docs/features/inverse-properties.md
diff --git a/docs/v2/pagination.md → docs/features/pagination.md b/docs/v2/pagination.md → docs/features/pagination.md