ldkit 1.1.0 → 2.1.0

package/script/library/lens/lens.js

@@ -1,38 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Lens = exports.createResource = exports.createLens = void 0;
-const global_js_1 = require("../global.js");
+exports.Lens = exports.createLens = void 0;
+const options_js_1 = require("../options.js");
 const mod_js_1 = require("../schema/mod.js");
 const decoder_js_1 = require("../decoder.js");
 const query_builder_js_1 = require("./query_builder.js");
 const query_engine_proxy_js_1 = require("../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
  */
-const createLens = (schema, context, engine) => new Lens(schema, context, engine);
+function createLens(schema, options) {
+    return new Lens(schema, options);
+}
 exports.createLens = createLens;
 /**
- * @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.
  */
-const createResource = (schema, context, engine) => new Lens(schema, context, engine);
-exports.createResource = createResource;
 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,
@@ -51,56 +95,365 @@ class Lens {
             value: void 0
         });
         this.schema = (0, mod_js_1.expandSchema)(schema);
-        this.context = (0, global_js_1.resolveContext)(context);
-        this.engine = new query_engine_proxy_js_1.QueryEngineProxy(this.context, engine);
-        this.queryBuilder = new query_builder_js_1.QueryBuilder(this.schema, this.context);
+        this.options = (0, options_js_1.resolveOptions)(options);
+        const context = (0, options_js_1.resolveQueryContext)(this.options);
+        this.engine = new query_engine_proxy_js_1.QueryEngineProxy(this.options.engine, context);
+        this.queryBuilder = new query_builder_js_1.QueryBuilder(this.schema, this.options);
     }
     decode(graph) {
-        return (0, decoder_js_1.decode)(graph, this.schema, this.context);
+        return (0, decoder_js_1.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;
@@ -108,6 +461,41 @@ 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/script/library/lens/mod.js

@@ -1,6 +1,17 @@
 "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.createResource = exports.createLens = void 0;
-var lens_js_1 = require("./lens.js");
-Object.defineProperty(exports, "createLens", { enumerable: true, get: function () { return lens_js_1.createLens; } });
-Object.defineProperty(exports, "createResource", { enumerable: true, get: function () { return lens_js_1.createResource; } });
+__exportStar(require("./lens.js"), exports);