ldkit 1.1.0 → 2.1.0

package/esm/library/lens/lens.js

@@ -1,33 +1,78 @@
-import { resolveContext } from "../global.js";
+import { resolveOptions, resolveQueryContext, } from "../options.js";
 import { expandSchema, } from "../schema/mod.js";
 import { decode } from "../decoder.js";
 import { QueryBuilder } from "./query_builder.js";
 import { QueryEngineProxy } from "../engine/query_engine_proxy.js";
 /**
- * Lens lets you query and update RDF data via data schema using TypeScript native data types.
+ * Creates an instance of Lens that lets you query and update RDF data
+ * via data schema using TypeScript native data types.
  *
- * https://ldkit.io/docs/components/lens
+ * In order to create a Lens instance, you need to provide a data schema
+ * that describes the data model which serves to translate data between
+ * Linked Data and TypeScript native types (see {@link Schema} for details).
  *
- * @param schema data schema which extends `SchemaPrototype`
- * @param context optional `Context` - contains LDkit and query engine configuration
- * @param engine optional Query Engine
- * @returns Lens instance
+ * You can also pass a set of options for LDkit and a query engine that
+ * specify the data source, preferred language, etc. (see {@link Options} for details).
+ *
+ * @example
+ * ```typescript
+ * import { createLens, type Options } from "ldkit";
+ * import { dbo, rdfs, xsd } from "ldkit/namespaces";
+ *
+ * // Create options for query engine
+ * const options: Options = {
+ *   sources: ["https://dbpedia.org/sparql"], // SPARQL endpoint
+ *   language: "en", // Preferred language
+ * };
+ *
+ * // Create a schema
+ * const PersonSchema = {
+ *   "@type": dbo.Person,
+ *   name: rdfs.label,
+ *   abstract: dbo.abstract,
+ *   birthDate: {
+ *     "@id": dbo.birthDate,
+ *     "@type": xsd.date,
+ *   },
+ * } as const;
+ *
+ * // Create a resource using the data schema and options above
+ * const Persons = createLens(PersonSchema, options);
+ *
+ * // List some persons
+ * const persons = await Persons.find({ take: 10 });
+ * for (const person of persons) {
+ *   console.log(person.name); // string
+ *   console.log(person.birthDate); // Date
+ * }
+ *
+ * // Get a particular person identified by IRI
+ * const ada = await Persons.findByIri("http://dbpedia.org/resource/Ada_Lovelace");
+ * console.log(ada?.name); // string "Ada Lovelace"
+ * console.log(ada?.birthDate); // Date object of 1815-12-10
+ * ```
+ *
+ * @param schema data schema which extends {@link Schema}
+ * @param options optional {@link Options} - contains LDkit and query engine configuration
+ * @returns Lens instance that provides interface to Linked Data based on the schema
  */
-export const createLens = (schema, context, engine) => new Lens(schema, context, engine);
+export function createLens(schema, options) {
+    return new Lens(schema, options);
+}
 /**
- * @deprecated
- * Use `createLens` instead
+ * Lens provides an interface to Linked Data based on the data schema.
+ *
+ * For the best developer experience, use the {@link createLens} function to create the instance.
  */
-export const createResource = (schema, context, engine) => new Lens(schema, context, engine);
 export class Lens {
-    constructor(schema, context, engine) {
+    constructor(schema, options) {
         Object.defineProperty(this, "schema", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "context", {
+        Object.defineProperty(this, "options", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -46,56 +91,365 @@ export class Lens {
             value: void 0
         });
         this.schema = expandSchema(schema);
-        this.context = resolveContext(context);
-        this.engine = new QueryEngineProxy(this.context, engine);
-        this.queryBuilder = new QueryBuilder(this.schema, this.context);
+        this.options = resolveOptions(options);
+        const context = resolveQueryContext(this.options);
+        this.engine = new QueryEngineProxy(this.options.engine, context);
+        this.queryBuilder = new QueryBuilder(this.schema, this.options);
     }
     decode(graph) {
-        return decode(graph, this.schema, this.context);
+        return decode(graph, this.schema, this.options);
     }
-    async count() {
-        const q = this.queryBuilder.countQuery();
-        // TODO: console.log(q);
+    log(query) {
+        this.options.logQuery(query);
+    }
+    /**
+     * Returns the total number of entities corresponding to the data schema.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Count all persons
+     * const count = await Persons.count(); // number
+     * ```
+     *
+     * @returns total number of entities corresponding to the data schema
+     */
+    async count(max) {
+        const q = this.queryBuilder.countQuery(max);
+        this.log(q);
         const bindings = await this.engine.queryBindings(q);
         return parseInt(bindings[0].get("count").value);
     }
-    //exists(entity: Identity) {}
+    /**
+     * Find entities with a custom SPARQL query.
+     *
+     * The query must be a CONSTRUCT query, and the root nodes must be of type `ldkit:Resource`.
+     * So that the decoder can decode the results, the query must also return all properties
+     * according to the data schema.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { ldkit, schema } from "ldkit/namespaces";
+     * import { CONSTRUCT } from "ldkit/sparql";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Query to find all persons named "Doe"
+     * const query = CONSTRUCT`?s a <${ldkit.Resource}>; <${schema.name}> ?name`
+     *   .WHERE`?s <${schema.name}> ?name; <${schema.familyName}> "Doe"`.build();
+     *
+     * // Find all persons that match the custom query
+     * const doePersons = await Persons.query(query);
+     * ```
+     *
+     * @param sparqlConstructQuery CONSTRUCT SPARQL query
+     * @returns Found entities
+     */
     async query(sparqlConstructQuery) {
+        this.log(sparqlConstructQuery);
         const graph = await this.engine.queryGraph(sparqlConstructQuery);
         return this.decode(graph);
     }
-    async find(where, limit) {
-        const q = this.queryBuilder.getQuery(where, limit);
-        // TODO: console.log(q);
+    /**
+     * Find entities that match the given search criteria.
+     *
+     * The search criteria is a JSON object that may contain properties from the data schema.
+     * In addition you can specify how many results to return and how many to skip
+     * for pagination purposes.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Find 100 persons with name that starts with "Ada"
+     * const persons = await Persons.find({
+     *   where: {
+     *     name: { $strStarts: "Ada" },
+     *   },
+     *   take: 100,
+     * });
+     * ```
+     *
+     * @param options Search criteria and pagination options
+     * @returns entities that match the given search criteria
+     */
+    async find(options = {}) {
+        const { where, take, skip } = {
+            take: this.options.take,
+            skip: 0,
+            ...options,
+        };
+        const isRegularQuery = typeof where === "string" ||
+            typeof where === "undefined" || Array.isArray(where);
+        const q = isRegularQuery
+            ? this.queryBuilder.getQuery(where, take, skip)
+            : this.queryBuilder.getSearchQuery(where ?? {}, take, skip);
+        this.log(q);
         const graph = await this.engine.queryGraph(q);
         return this.decode(graph);
     }
+    /**
+     * Find one entity that matches the given search criteria.
+     *
+     * The search criteria is a JSON object that may contain properties from the data schema.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Find one person with name that starts with "Ada"
+     * const person = await Persons.findOne({
+     *   name: { $strStarts: "Ada" },
+     * });
+     * ```
+     *
+     * @param options Search criteria and pagination options
+     * @returns entities that match the given search criteria
+     */
+    async findOne(where) {
+        const results = await this.find({ where, take: 1 });
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Find a single entity that matches the given IRI.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Get a particular person identified by IRI
+     * const ada = await Persons.findByIri("http://dbpedia.org/resource/Ada_Lovelace");
+     * console.log(ada?.name); // string "Ada Lovelace"
+     * ```
+     *
+     * @param iri IRI of the entity to find
+     * @returns Entity if found, null otherwise
+     */
     async findByIri(iri) {
         const results = await this.findByIris([iri]);
-        return results.length > 0 ? results[0] : undefined;
+        return results.length > 0 ? results[0] : null;
     }
+    /**
+     * Find entities that match the given IRIs.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Get specific persons identified by IRIs
+     * const matches = await Persons.findByIris([
+     *   "http://dbpedia.org/resource/Ada_Lovelace",
+     *   "http://dbpedia.org/resource/Alan_Turing"
+     * ]);
+     * console.log(matches[0].name); // string "Ada Lovelace"
+     * console.log(matches[1].name); // string "Alan Turing"
+     * ```
+     *
+     * @param iris IRIs of the entities to find
+     * @returns Array of found entities, empty array if there are no matches
+     */
     async findByIris(iris) {
         const q = this.queryBuilder.getByIrisQuery(iris);
-        // TODO: console.log(q);
+        this.log(q);
         const graph = await this.engine.queryGraph(q);
         return this.decode(graph);
     }
     updateQuery(query) {
-        // TODO: console.log(query);
+        this.log(query);
         return this.engine.queryVoid(query);
     }
+    /**
+     * Inserts one or more entities to the data store.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Insert a new person
+     * await Persons.insert({
+     *   $id: "http://example.org/Alan_Turing",
+     *   name: "Alan Turing",
+     * });
+     * ```
+     *
+     * @param entities Entities to insert
+     * @returns Nothing
+     */
     insert(...entities) {
         const q = this.queryBuilder.insertQuery(entities);
         return this.updateQuery(q);
     }
+    /**
+     * Inserts raw RDF quads to the data store.
+     *
+     * This method is useful when you need to insert data that is not covered by the data schema.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     * import { DataFactory } from "ldkit/rdf";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Create a custom quad to insert
+     * const df = new DataFactory();
+     * const quad = df.quad(
+     *   df.namedNode("http://example.org/Alan_Turing"),
+     *   df.namedNode("http://schema.org/name"),
+     *   df.literal("Alan Turing"),
+     * );
+     *
+     * // Insert the quad
+     * await Persons.insertData(quad);
+     * ```
+     *
+     * @param quads Quads to insert to the data store
+     * @returns Nothing
+     */
     insertData(...quads) {
         const q = this.queryBuilder.insertDataQuery(quads);
         return this.updateQuery(q);
     }
+    /**
+     * Updates one or more entities in the data store.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Update Alan Turing's name
+     * await Persons.update({
+     *   $id: "http://example.org/Alan_Turing",
+     *   name: "Not Alan Turing",
+     * });
+     * ```
+     *
+     * @param entities Partial entities to update
+     * @returns Nothing
+     */
     update(...entities) {
         const q = this.queryBuilder.updateQuery(entities);
         return this.updateQuery(q);
     }
+    /**
+     * Deletes one or more entities from the data store.
+     *
+     * This method accepts IRIs of the entities to delete and attemps
+     * to delete all triples from the database that corresponds to
+     * the data schema. Other triples that are not covered by the data
+     * schema will not be deleted.
+     *
+     * If you need to have more control of what triples to delete,
+     * use {@link deleteData} instead.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Delete a person
+     * await Persons.delete("http://example.org/Alan_Turing");
+     * ```
+     *
+     * @param identities Identities or IRIs of the entities to delete
+     * @returns Nothing
+     */
     delete(...identities) {
         const iris = identities.map((identity) => {
             return typeof identity === "string" ? identity : identity.$id;
@@ -103,6 +457,41 @@ export class Lens {
         const q = this.queryBuilder.deleteQuery(iris);
         return this.updateQuery(q);
     }
+    /**
+     * Deletes raw RDF quads from the data store.
+     *
+     * This method is useful when you need to delete data that is not covered by the data schema.
+     *
+     * @example
+     * ```typescript
+     * import { createLens } from "ldkit";
+     * import { schema } from "ldkit/namespaces";
+     * import { DataFactory } from "ldkit/rdf";
+     *
+     * // Create a schema
+     * const PersonSchema = {
+     *   "@type": schema.Person,
+     *   name: schema.name,
+     * } as const;
+     *
+     * // Create a resource using the data schema and context above
+     * const Persons = createLens(PersonSchema);
+     *
+     * // Create a custom quad to insert
+     * const df = new DataFactory();
+     * const quad = df.quad(
+     *   df.namedNode("http://example.org/Alan_Turing"),
+     *   df.namedNode("http://schema.org/name"),
+     *   df.literal("Alan Turing"),
+     * );
+     *
+     * // Delete the quad
+     * await Persons.deleteData(quad);
+     * ```
+     *
+     * @param quads Quads to delete from the data store
+     * @returns Nothing
+     */
     deleteData(...quads) {
         const q = this.queryBuilder.deleteDataQuery(quads);
         return this.updateQuery(q);

package/esm/library/lens/mod.js

@@ -1 +1 @@
-export { createLens, createResource } from "./lens.js";
+export * from "./lens.js";