@faubulous/mentor-rdf 2.1.0 → 2.1.2

package/dist/rdf/concept-repository.d.ts

@@ -1,4 +1,4 @@
-import { ResourceRepository } from "./resource-repository";
+import { DefinitionQueryOptions, ResourceRepository } from "./resource-repository";
 export declare class ConceptRepository extends ResourceRepository {
     /**
      * Get all concepts.
@@ -15,9 +15,120 @@ export declare class ConceptRepository extends ResourceRepository {
     /**
      * Get all collections.
      * @param graphUris URI of the graphs to search for collections.
+     * @param options Optional query parameters.
      * @returns An iterator of URIs of all collections.
      */
-    getCollections(graphUris: string | string[] | undefined): IterableIterator<string>;
+    getCollections(graphUris: string | string[] | undefined, options?: DefinitionQueryOptions): IterableIterator<string>;
+    /**
+     * Indicate if a collection should be excluded from a query result.
+     *
+     * Note: In contrast to other resource types, blank nodes and referenced collections are
+     * included by default so that the result is unchanged when no options are provided.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subject The collection to test.
+     * @param options Optional query parameters.
+     * @returns `true` if the collection should be excluded, `false` otherwise.
+     */
+    private _skipCollection;
+    /**
+     * Indicate if a resource is associated with any concept scheme via `skos:inScheme`.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param subjectUri URI of a resource.
+     * @returns `true` if the resource is in a concept scheme, `false` otherwise.
+     */
+    hasConceptScheme(graphUris: string | string[] | undefined, subjectUri: string): boolean;
+    /**
+     * Indicate if a resource is associated with a given concept scheme via `skos:inScheme`.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param subjectUri URI of a resource.
+     * @param schemeUri URI of a concept scheme.
+     * @returns `true` if the resource is in the given concept scheme, `false` otherwise.
+     */
+    isInScheme(graphUris: string | string[] | undefined, subjectUri: string, schemeUri: string): boolean;
+    /**
+     * Indicate if a concept is explicitly associated with a given concept scheme, either via
+     * `skos:inScheme` or via `skos:topConceptOf`.
+     *
+     * Note: The `skos:broader` and `skos:narrower` relations are *not* taken into account, because
+     * they may cross the boundaries of a concept scheme. Use {@link getAllConceptsInScheme} to get
+     * the concepts that are displayed below a concept scheme.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param subjectUri URI of a concept.
+     * @param schemeUri URI of a concept scheme.
+     * @returns `true` if the concept is associated with the concept scheme, `false` otherwise.
+     */
+    isConceptOfScheme(graphUris: string | string[] | undefined, subjectUri: string, schemeUri: string): boolean;
+    /**
+     * Indicate if a concept can be displayed below a given concept scheme.
+     *
+     * Concepts that are not associated with any concept scheme belong to every concept scheme they
+     * can be reached from, so that they are not hidden in vocabularies that only annotate their top
+     * concepts with `skos:inScheme`.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param subjectUri URI of a concept.
+     * @param schemeUri URI of a concept scheme.
+     * @returns `true` if the concept can be displayed below the concept scheme, `false` otherwise.
+     */
+    private _isVisibleInScheme;
+    /**
+     * Get the concepts that are explicitly associated with a concept scheme, either via
+     * `skos:inScheme` or via `skos:topConceptOf`.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param schemeUri URI of a concept scheme.
+     * @returns An iterator of URIs of the concepts of the concept scheme.
+     */
+    getConceptsOfScheme(graphUris: string | string[] | undefined, schemeUri: string): IterableIterator<string>;
+    /**
+     * Get the top concepts of a concept scheme.
+     *
+     * In addition to the concepts that are explicitly designated as top concepts via
+     * `skos:hasTopConcept` or `skos:topConceptOf`, this returns the concepts of the scheme that have
+     * no broader concept *within the same scheme*. Without the latter, concepts whose `skos:broader`
+     * property refers to a concept of another scheme would not be displayed below the scheme that
+     * they are associated with.
+     *
+     * Note: A concept that is its own broader concept is not excluded, so that recursive definitions
+     * do not remove it from the list of top concepts.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param schemeUri URI of a concept scheme.
+     * @returns An iterator of URIs of the top concepts of the concept scheme.
+     */
+    getTopConcepts(graphUris: string | string[] | undefined, schemeUri: string): IterableIterator<string>;
+    /**
+     * Get the concepts of a concept scheme that have a broader concept within the same scheme.
+     *
+     * The hierarchical relations are enumerated once and matched against the set of concepts of the
+     * scheme, which is considerably cheaper than querying the broader concepts of every single
+     * concept of the scheme.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param concepts Set of the concepts that are associated with the concept scheme.
+     * @returns A set of URIs of the concepts that are nested below another concept of the scheme.
+     */
+    private _nestedConceptsOfScheme;
+    /**
+     * Get all concepts that are displayed below a concept scheme, including indirectly narrower ones.
+     *
+     * The traversal starts at the {@link getTopConcepts} of the scheme and follows the narrower
+     * concepts that can be displayed below the scheme, so the result is exactly the set of concepts
+     * that a hierarchical view of the scheme can reach.
+     *
+     * Note: The hierarchical relations of the graphs are indexed once per call instead of querying
+     * the narrower concepts of every single concept, which is an order of magnitude faster on large
+     * thesauri. Prefer {@link getConceptsOfScheme} when the *associated* concepts are sufficient.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @param schemeUri URI of a concept scheme.
+     * @returns An iterator of URIs of all concepts below the concept scheme.
+     */
+    getAllConceptsInScheme(graphUris: string | string[] | undefined, schemeUri: string): IterableIterator<string>;
+    /**
+     * Index the narrower concept relations of the given graphs.
+     *
+     * All four hierarchical relations are enumerated once, which is considerably cheaper than
+     * querying {@link getNarrowerConcepts} for every concept of a large thesaurus.
+     * @param graphUris URIs of the graphs to search for concepts.
+     * @returns A map of concept URIs to the URIs of their narrower concepts.
+     */
+    private _getNarrowerConceptIndex;
     /**
      * Get the members of a collection. This includes both `skos:member` and `skos:memberList` properties.
      * @param graphUris URI of the graphs to search for collections.
@@ -39,6 +150,113 @@ export declare class ConceptRepository extends ResourceRepository {
      * @returns `true` if the collection is an ordered collection, `false` otherwise.
      */
     isOrderedCollection(graphUris: string | string[] | undefined, collectionUri: string): boolean;
+    /**
+     * Indicates whether a subject is a collection.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a subject.
+     * @returns `true` if the subject is a `skos:Collection` or a `skos:OrderedCollection`, `false` otherwise.
+     */
+    isCollection(graphUris: string | string[] | undefined, subjectUri: string): boolean;
+    /**
+     * Get the collections that have a given subject as a member. This includes both `skos:member`
+     * and `skos:memberList` properties.
+     *
+     * Note: A collection that is a member of itself is returned as its own super collection, which
+     * is consistent with {@link getBroaderConcepts}. Use {@link hasSuperCollections} to test whether
+     * a collection is a member of *another* collection.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection or concept.
+     * @returns An iterator of URIs of the collections that contain the subject.
+     */
+    getSuperCollections(graphUris: string | string[] | undefined, subjectUri: string): IterableIterator<string>;
+    /**
+     * Get the collections that reference a given subject in an ordered member list.
+     *
+     * Starting from the list nodes that have the subject as their first item, the `rdf:rest` chain
+     * is traversed *backwards* towards the head of the list, and every visited list node is tested
+     * for being the object of a `skos:memberList` property. This is considerably cheaper than
+     * expanding all member lists in the graph, and it also resolves collections that share a list.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection or concept.
+     * @returns An iterator of URIs of the collections that reference the subject in a member list.
+     */
+    private _getMemberListContainers;
+    /**
+     * Indicates whether a collection is a member of another collection.
+     *
+     * Note: A collection that is a member of itself is *not* considered to have a super collection,
+     * so that recursive definitions do not remove it from the list of root collections.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection.
+     * @returns `true` if the collection is a member of another collection, `false` otherwise.
+     */
+    hasSuperCollections(graphUris: string | string[] | undefined, subjectUri: string): boolean;
+    /**
+     * Get the members of a collection that are collections themselves, or all root collections.
+     *
+     * The order of the members of a `skos:OrderedCollection` is preserved.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection or `undefined` to get all root collections.
+     * @param options Optional query parameters.
+     * @returns An iterator of URIs of the nested collections of the given collection, or of the root collections if no subject is provided.
+     */
+    getSubCollections(graphUris: string | string[] | undefined, subjectUri?: string, options?: DefinitionQueryOptions): IterableIterator<string>;
+    /**
+     * Indicates whether a collection has members that are collections themselves.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection.
+     * @param options Optional query parameters.
+     * @returns `true` if the collection has nested collections, `false` otherwise.
+     */
+    hasSubCollections(graphUris: string | string[] | undefined, subjectUri: string, options?: DefinitionQueryOptions): boolean;
+    /**
+     * Get all collections that are not a member of another collection.
+     *
+     * Every collection returned by {@link getCollections} is either returned by this method, or is
+     * reachable from one of the returned collections via {@link getSubCollections}. If a group of
+     * collections is only reachable through a membership cycle, the first collection of that group
+     * is returned as a root collection so that no collection is lost.
+     *
+     * Note: Collections that are identified by a blank node cannot be queried for their members and
+     * are therefore always returned as root collections.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param options Optional query parameters.
+     * @returns An iterator of URIs of the root collections.
+     */
+    getRootCollections(graphUris: string | string[] | undefined, options?: DefinitionQueryOptions): IterableIterator<string>;
+    /**
+     * Mark all collections that can be reached from a given collection through nested collections.
+     *
+     * The traversal uses the same criteria as {@link getSubCollections} so that the marked
+     * collections are exactly the collections that are visible below the given collection. Since
+     * the set of reachable collections is shared between all calls, the members of a collection are
+     * enumerated at most once per {@link getRootCollections} call.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of the collection to start the traversal from.
+     * @param collections Set of all collections that are in the scope of the query.
+     * @param reachable Set of collections that have already been reached.
+     */
+    private _markReachableCollections;
+    /**
+     * Get the first discovered path from a given collection to a root collection.
+     *
+     * The path does not contain the given collection and is ordered from the closest super
+     * collection to the root collection. If the collection is part of a membership cycle, the path
+     * ends at the last collection that has not been visited yet and does not reach a root collection.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection.
+     * @returns The first path that is found from the given collection to a root collection.
+     */
+    getRootCollectionPath(graphUris: string | string[] | undefined, subjectUri: string): string[];
+    /**
+     * Recursively find the first path from a given collection to a root collection.
+     * @param graphUris URI of the graphs to search for collections.
+     * @param subjectUri URI of a collection.
+     * @param path The current collection path.
+     * @param backtrack Set of URIs that have already been visited.
+     * @returns The first path that is found from the given collection to a root collection.
+     */
+    private _getRootCollectionPath;
     /**
      * Get all broader concepts of a concept scheme.
      * @param graphUris URIs of the graphs to search for concepts.
@@ -52,11 +270,16 @@ export declare class ConceptRepository extends ResourceRepository {
      */
     hasBroaderConcepts(graphUris: string | string[] | undefined, subjectUri: string): boolean;
     /**
-     * Get all narrower concepts of a concept or top concepts of a concept scheme.
+     * Get all narrower concepts of a concept or the top concepts of a concept scheme.
+     *
+     * If the subject is a concept scheme, the {@link getTopConcepts} of that scheme are returned. If
+     * the `inScheme` option is set, only concepts that can be displayed below that concept scheme are
+     * returned, which excludes concepts that are associated with a *different* scheme.
      * @param graphUris URIs of the graphs to search for concepts.
-     * @param subjectUri URI of a concept or concept scheme.
+     * @param subjectUri URI of a concept or concept scheme, or `undefined` to get all concept schemes.
+     * @param options Optional query parameters.
      */
-    getNarrowerConcepts(graphUris: string | string[] | undefined, subjectUri?: string): IterableIterator<string>;
+    getNarrowerConcepts(graphUris: string | string[] | undefined, subjectUri?: string, options?: DefinitionQueryOptions): IterableIterator<string>;
     /**
      * Indicates whether a concept has narrower concepts.
      * @param graphUris URIs of the graphs to search for concepts.

package/dist/rdf/resource-repository.d.ts

@@ -30,6 +30,11 @@ export interface DefinitionQueryOptions extends QueryOptions {
      * Indicate if blank nodes should be included in the result (default: false).
      */
     includeBlankNodes?: boolean;
+    /**
+     * URI of the concept scheme the resources must be associated with via `skos:inScheme`.
+     * If `null`, returns only resources that have no `skos:inScheme` property.
+     */
+    inScheme?: string | null;
 }
 /**
  * Parameters for store queries that support filtering on the type of resource.

package/dist/rdf/store.d.ts

@@ -163,6 +163,13 @@ export declare class Store implements rdfjs.DatasetCore<rdfjs.Quad> {
      * @returns An array of URIs of the items in the list.
      */
     getListItems(graphUris: string | string[] | undefined, listUri: string): string[];
+    /**
+     * Recursively collect the items of an ordered list.
+     * @param graphUris Optional graph URI or array of graph URIs to query.
+     * @param subject The list node to collect the items from.
+     * @param visited Set of list nodes that have already been visited.
+     * @returns An array of the items in the list.
+     */
     private _getListItems;
     /**
      * Returns the exact cardinality of the quads matching the pattern.

package/package.json

@@ -10,7 +10,7 @@
     "ontology",
     "vocabulary"
   ],
-  "version": "2.1.0",
+  "version": "2.1.2",
   "private": false,
   "author": {
     "name": "Sebastian Faubel"