ldkit 1.1.0 → 2.1.0

package/types/library/lens/lens.d.ts

@@ -1,38 +1,415 @@
-import type { Context, IQueryEngine, Iri, RDF } from "../rdf.js";
-import { type SchemaInterface, type SchemaInterfaceIdentity, type SchemaPrototype } from "../schema/mod.js";
-import type { Entity } from "./types.js";
+import type { IRI, RDF } from "../rdf.js";
+import { type Options } from "../options.js";
+import { type Identity, type Schema, type SchemaInterface, type SchemaSearchInterface, type SchemaUpdateInterface } from "../schema/mod.js";
+import type { Entity, Unite } from "./types.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 declare const createLens: <T extends SchemaPrototype>(schema: T, context?: Context, engine?: IQueryEngine) => Lens<T, SchemaInterface<T>>;
+export declare function createLens<T extends Schema>(schema: T, options?: Options): Lens<T>;
 /**
- * @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 declare const createResource: <T extends SchemaPrototype>(schema: T, context?: Context, engine?: IQueryEngine) => Lens<T, SchemaInterface<T>>;
-export declare class Lens<S extends SchemaPrototype, I = SchemaInterface<S>> {
+export declare class Lens<T extends Schema> {
     private readonly schema;
-    private readonly context;
+    private readonly options;
     private readonly engine;
     private readonly queryBuilder;
-    constructor(schema: S, context?: Context, engine?: IQueryEngine);
+    constructor(schema: T, options?: Options);
     private decode;
-    count(): Promise<number>;
-    query(sparqlConstructQuery: string): Promise<I[]>;
-    find(where?: string | RDF.Quad[], limit?: number): Promise<I[]>;
-    findByIri(iri: Iri): Promise<I | undefined>;
-    findByIris(iris: Iri[]): Promise<I[]>;
+    private log;
+    /**
+     * 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
+     */
+    count(max?: number): Promise<number>;
+    /**
+     * 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
+     */
+    query(sparqlConstructQuery: string): Promise<Unite<SchemaInterface<T>>[]>;
+    /**
+     * 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
+     */
+    find(options?: {
+        where?: SchemaSearchInterface<T> | string | RDF.Quad[];
+        take?: number;
+        skip?: number;
+    }): Promise<Unite<SchemaInterface<T>>[]>;
+    /**
+     * 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
+     */
+    findOne(where?: SchemaSearchInterface<T>): Promise<Unite<SchemaInterface<T>> | 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
+     */
+    findByIri(iri: IRI): Promise<Unite<SchemaInterface<T>> | 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
+     */
+    findByIris(iris: IRI[]): Promise<Unite<SchemaInterface<T>>[]>;
     private updateQuery;
-    insert(...entities: Entity<I>[]): Promise<void>;
+    /**
+     * 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: Entity<SchemaInterface<T>>[]): Promise<void>;
+    /**
+     * 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: RDF.Quad[]): Promise<void>;
-    update(...entities: Entity<I>[]): Promise<void>;
-    delete(...identities: SchemaInterfaceIdentity[] | Iri[]): Promise<void>;
+    /**
+     * 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: SchemaUpdateInterface<T>[]): Promise<void>;
+    /**
+     * 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: Identity[] | IRI[]): Promise<void>;
+    /**
+     * 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: RDF.Quad[]): Promise<void>;
 }

package/types/library/lens/mod.d.ts

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

package/types/library/lens/query_builder.d.ts

@@ -1,22 +1,22 @@
-import type { Schema } from "../schema/mod.js";
-import { type Context, type Iri, type RDF } from "../rdf.js";
-import type { Entity } from "./types.js";
+import { type Options } from "../options.js";
+import { type ExpandedSchema, type SearchSchema } from "../schema/mod.js";
+import { type IRI, type RDF } from "../rdf.js";
+import { type Entity } from "./types.js";
 export declare class QueryBuilder {
     private readonly schema;
-    private readonly schemaProperties;
-    private readonly context;
+    private readonly options;
     private readonly df;
-    constructor(schema: Schema, context: Context);
+    constructor(schema: ExpandedSchema, options: Options);
     private getResourceSignature;
-    private getTypesSignature;
     private entitiesToQuads;
     private getShape;
-    countQuery(): string;
-    getQuery(where?: string | RDF.Quad[], limit?: number): string;
-    getByIrisQuery(iris: Iri[]): string;
+    countQuery(max?: number): string;
+    getQuery(where: string | RDF.Quad[] | undefined, limit: number, offset: number): string;
+    getSearchQuery(where: SearchSchema, limit: number, offset: number): string;
+    getByIrisQuery(iris: IRI[], where?: SearchSchema): string;
     insertQuery(entities: Entity[]): string;
     insertDataQuery(quads: RDF.Quad[]): string;
-    deleteQuery: (iris: Iri[]) => string;
+    deleteQuery: (iris: IRI[]) => string;
     deleteDataQuery(quads: RDF.Quad[]): string;
     updateQuery(entities: Entity[]): string;
 }

package/types/library/lens/search_helper.d.ts

@@ -0,0 +1,21 @@
+import { type SparqlValue } from "../sparql/mod.js";
+import { type ExpandedProperty, type SearchSchema } from "../schema/mod.js";
+export declare class SearchHelper {
+    private readonly property;
+    private readonly propertyType;
+    private readonly varName;
+    private readonly searchSchema;
+    private df;
+    readonly sparqlValues: SparqlValue[];
+    constructor(property: ExpandedProperty, varName: string, searchSchema: SearchSchema);
+    process(): void;
+    private processOperators;
+    private processStringFunctions;
+    private processRegex;
+    private processLangMatches;
+    private processArrayFunctions;
+    private processFilter;
+    private addFilter;
+    private encode;
+    private isPlainObject;
+}

package/types/library/lens/types.d.ts

@@ -1,5 +1,8 @@
-import type { SchemaInterfaceIdentity } from "../schema/mod.js";
-export type Entity<T extends unknown = Record<string, unknown>> = DeepPartial<T> & SchemaInterfaceIdentity;
+import type { Identity } from "../schema/mod.js";
+export type Entity<T extends unknown = Record<string, unknown>> = DeepPartial<T> & Identity;
 export type DeepPartial<T> = T extends Record<string, unknown> ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+export type Unite<T> = T extends Record<string, unknown> ? {
+    [Key in keyof T]: T[Key];
+} : T;

package/types/library/lens/update_helper.d.ts

@@ -0,0 +1,23 @@
+import type { Options } from "../options.js";
+import type { RDF } from "../rdf.js";
+import { type SparqlValue } from "../sparql/mod.js";
+import { type ExpandedSchema } from "../schema/mod.js";
+import type { Entity } from "./types.js";
+export declare class UpdateHelper {
+    private readonly schema;
+    private readonly properties;
+    private readonly options;
+    private variableCounter;
+    readonly deleteQuads: RDF.Quad[];
+    readonly insertQuads: RDF.Quad[];
+    readonly whereQuads: SparqlValue[];
+    constructor(schema: ExpandedSchema, options: Options, variableInitCounter?: number);
+    process(entity: Entity): void;
+    private processProperty;
+    private processSingleProperty;
+    private processArrayProperty;
+    private processArraySet;
+    private processArrayAddRemove;
+    private parseArrayUpdateConfig;
+    private encode;
+}

package/types/library/namespace.d.ts

@@ -0,0 +1,41 @@
+/** Original type of namespace specification */
+export type Namespace = {
+    iri: string;
+    prefix: string;
+    terms: readonly string[];
+};
+/** Resulting type of namespace providing access to all terms, prefix and IRI */
+export type NamespaceInterface<NamespaceSpec extends Namespace> = {
+    [Term in NamespaceSpec["terms"][number]]: `${NamespaceSpec["prefix"]}${Term}`;
+} & {
+    $prefix: NamespaceSpec["prefix"];
+    $iri: NamespaceSpec["iri"];
+};
+/**
+ * Creates a strongly typed container for Linked Data vocabulary to provide
+ * type safe access to all vocabulary terms as well as IDE autocompletion.
+ *
+ * @example
+ * ```typescript
+ * import { createNamespace } from "ldkit";
+ *
+ * const onto = createNamespace(
+ *   {
+ *     iri: "http://www.example.com/ontology#",
+ *     prefix: "onto:",
+ *     terms: [
+ *       "object",
+ *       "predicate",
+ *       "subject",
+ *     ],
+ *   } as const,
+ * );
+ *
+ * console.log(onto.subject); // prints http://www.example.com/ontology#subject
+ * console.log(onto.unknown); // TypeScript error! This term does not exist
+ * ```
+ *
+ * @param namespaceSpec Specification of the namespace
+ * @returns
+ */
+export declare function createNamespace<N extends Namespace>(namespaceSpec: N): NamespaceInterface<N>;

package/types/library/options.d.ts

@@ -0,0 +1,70 @@
+import { type IQueryEngine, type QueryContext } from "./engine/mod.js";
+/**
+ * LDkit options and query engine context
+ *
+ * LDkit-specific options are:
+ * - `engine` - a query engine to use for querying data sources
+ * - `language` - a preferred language for literals
+ * - `take` - a default number of results to take (limit of SELECT queries)
+ * - `logQuery` - a function that will be called for each SPARQL query
+ */
+export type Options = {
+    engine?: IQueryEngine;
+    language?: string;
+    take?: number;
+    logQuery?: (query: string) => void;
+} & Partial<QueryContext>;
+/**
+ * Sets global configuration {@link Options} for LDkit that will be used
+ * by default in all queries, unless overridden in {@link Lens}.
+ *
+ * LDkit-specific options are:
+ * - `engine` - a query engine to use for querying data sources
+ * - `language` - a preferred language for literals
+ * - `take` - a default number of results to take (limit of SELECT queries)
+ * - `logQuery` - a function that will be called for each SPARQL query
+ *
+ * Default values for these options are:
+ * ```typescript
+ * const defaultOptions = {
+ *   engine: new QueryEngine(),
+ *   take: 1000,
+ *   logQuery: () => {},
+ * };
+ * ```
+ * The default configuration uses built-in {@link QueryEngine}. Language is not set by default.
+ *
+ * @param options LDkit options and query engine context
+ */
+export declare function setGlobalOptions(options: Options): void;
+export declare function resolveOptions(options?: Options): {
+    engine: IQueryEngine;
+    language?: string | undefined;
+    take: number;
+    logQuery: (query: string) => void;
+    queryFormat?: import("@rdfjs/types").QueryFormat | undefined;
+    baseIRI?: string | undefined;
+    queryTimestamp?: Date | undefined;
+    sources?: [import("@comunica/types").QuerySourceUnidentified, ...import("@comunica/types").QuerySourceUnidentified[]] | undefined;
+    destination?: import("@comunica/types").IDataDestination | undefined;
+    initialBindings?: import("@rdfjs/types").Bindings | undefined;
+    log?: import("@comunica/types").Logger | undefined;
+    datetime?: Date | undefined;
+    httpProxyHandler?: import("@comunica/types").IProxyHandler | undefined;
+    lenient?: boolean | undefined;
+    httpIncludeCredentials?: boolean | undefined;
+    httpAuth?: string | undefined;
+    httpTimeout?: number | undefined;
+    httpBodyTimeout?: boolean | undefined;
+    httpRetryCount?: number | undefined;
+    httpRetryDelayFallback?: number | undefined;
+    httpRetryDelayLimit?: number | undefined;
+    fetch?: typeof fetch | undefined;
+    readOnly?: boolean | undefined;
+    extensionFunctionCreator?: ((functionNamedNode: import("@rdfjs/types").NamedNode<string>) => ((args: import("@rdfjs/types").Term[]) => Promise<import("@rdfjs/types").Term>) | undefined) | undefined;
+    functionArgumentsCache?: import("@comunica/types").FunctionArgumentsCache | undefined;
+    extensionFunctions?: Record<string, (args: import("@rdfjs/types").Term[]) => Promise<import("@rdfjs/types").Term>> | undefined;
+    explain?: import("@comunica/types").QueryExplainMode | undefined;
+    recoverBrokenLinks?: boolean | undefined;
+};
+export declare function resolveQueryContext(options: Options): QueryContext;