@rdfx/resource 0.0.1

package/dist/PropertyPath.js

@@ -0,0 +1,179 @@
+import dataFactory from "@rdfjs/data-model";
+import datasetFactory from "@rdfjs/dataset";
+import { Either, Left } from "purify-ts";
+import { Resource } from "./Resource.js";
+import { ResourceSet } from "./ResourceSet.js";
+import { sh } from "./vocabularies.js";
+export var PropertyPath;
+(function (PropertyPath) {
+    function equals(left, right) {
+        if (left.termType !== right.termType) {
+            return false;
+        }
+        switch (left.termType) {
+            case "AlternativePath":
+            case "SequencePath": {
+                const right_ = right;
+                if (left.members.length !== right_.members.length) {
+                    return false;
+                }
+                for (let memberI = 0; memberI < left.members.length; memberI++) {
+                    if (!PropertyPath.equals(left.members[memberI], right_.members[memberI])) {
+                        return false;
+                    }
+                }
+                return true;
+            }
+            case "NamedNode":
+                return left.equals(right);
+            case "InversePath":
+            case "OneOrMorePath":
+            case "ZeroOrMorePath":
+            case "ZeroOrOnePath":
+                return PropertyPath.equals(left.path, right.path);
+        }
+    }
+    PropertyPath.equals = equals;
+    function fromResource(resource, options) {
+        // Predicate path
+        // sh:path ex:parent
+        if (resource.identifier.termType === "NamedNode") {
+            return Either.of(resource.identifier);
+        }
+        // The other property path types are BlankNodes
+        const getPropertyPathList = (list) => {
+            return list.chain((values) => {
+                const members = [];
+                for (const value of values) {
+                    const resource = value.toResource().toMaybe();
+                    if (resource.isNothing()) {
+                        return Left(new Error("non-identifier in property path list"));
+                    }
+                    const member = PropertyPath.fromResource(resource.unsafeCoerce(), options);
+                    if (member.isLeft()) {
+                        return member;
+                    }
+                    members.push(member.unsafeCoerce());
+                }
+                return Either.of(members);
+            });
+        };
+        // Sequence path
+        // sh:path ( ex:parent ex:firstName )
+        {
+            const list = resource.toList();
+            if (list.isRight()) {
+                return getPropertyPathList(list).map((members) => ({
+                    termType: "SequencePath",
+                    members,
+                }));
+            }
+        }
+        for (const quad of resource.dataset.match(resource.identifier, null, null, options?.graph)) {
+            switch (quad.object.termType) {
+                case "BlankNode":
+                case "NamedNode":
+                    break;
+                default:
+                    return Left(new Error(`non-BlankNode/NamedNode property path object on path ${Resource.Identifier.toString(resource.identifier)}: ${quad.object.termType} ${quad.object.value}`));
+            }
+            const objectResource = new Resource(resource.dataset, quad.object);
+            // Alternative path
+            // sh:path: [ sh:alternativePath ( ex:father ex:mother  ) ]
+            if (quad.predicate.equals(sh.alternativePath)) {
+                return getPropertyPathList(objectResource.toList()).map((members) => ({
+                    termType: "AlternativePath",
+                    members,
+                }));
+            }
+            // Inverse path
+            // sh:path: [ sh:inversePath ex:parent ]
+            if (quad.predicate.equals(sh.inversePath)) {
+                return PropertyPath.fromResource(objectResource, options).map((path) => ({
+                    termType: "InversePath",
+                    path,
+                }));
+            }
+            // One or more path
+            if (quad.predicate.equals(sh.oneOrMorePath)) {
+                return PropertyPath.fromResource(objectResource, options).map((path) => ({
+                    termType: "OneOrMorePath",
+                    path,
+                }));
+            }
+            // Zero or more path
+            if (quad.predicate.equals(sh.zeroOrMorePath)) {
+                return PropertyPath.fromResource(objectResource).map((path) => ({
+                    termType: "ZeroOrMorePath",
+                    path,
+                }));
+            }
+            if (quad.predicate.equals(sh.zeroOrOnePath)) {
+                return PropertyPath.fromResource(objectResource).map((path) => ({
+                    termType: "ZeroOrOnePath",
+                    path,
+                }));
+            }
+        }
+        return Left(new Error(`unrecognized or ill-formed SHACL property path ${Resource.Identifier.toString(resource.identifier)}`));
+    }
+    PropertyPath.fromResource = fromResource;
+    function toResource(propertyPath, options) {
+        const graph = options?.graph;
+        const resourceSet = options?.resourceSet ??
+            new ResourceSet(datasetFactory.dataset(), { dataFactory: dataFactory });
+        if (propertyPath.termType === "NamedNode") {
+            return resourceSet.resource(propertyPath);
+        }
+        const resource = resourceSet.resource(dataFactory.blankNode());
+        switch (propertyPath.termType) {
+            case "AlternativePath":
+            case "SequencePath": {
+                const members = propertyPath.members.map((member) => PropertyPath.toResource(member, { graph, resourceSet }).identifier);
+                if (propertyPath.termType === "AlternativePath") {
+                    resource.addList(sh.alternativePath, members, { graph });
+                }
+                else {
+                    resource.addListItems(members, { graph });
+                }
+                return resource;
+            }
+        }
+        let predicate;
+        switch (propertyPath.termType) {
+            case "InversePath":
+                predicate = sh.inversePath;
+                break;
+            case "OneOrMorePath":
+                predicate = sh.oneOrMorePath;
+                break;
+            case "ZeroOrMorePath":
+                predicate = sh.zeroOrMorePath;
+                break;
+            case "ZeroOrOnePath":
+                predicate = sh.zeroOrOnePath;
+                break;
+        }
+        resource.add(predicate, PropertyPath.toResource(propertyPath.path, { graph, resourceSet })
+            .identifier, graph);
+        return resource;
+    }
+    PropertyPath.toResource = toResource;
+    // biome-ignore lint/suspicious/noShadowRestrictedNames: intentional
+    function toString(propertyPath) {
+        switch (propertyPath.termType) {
+            case "AlternativePath":
+            case "SequencePath":
+                return `${propertyPath.termType}([${propertyPath.members.map(PropertyPath.toString).join(", ")}])`;
+            case "InversePath":
+            case "OneOrMorePath":
+            case "ZeroOrMorePath":
+            case "ZeroOrOnePath":
+                return `${propertyPath.termType}(${PropertyPath.toString(propertyPath.path)})`;
+            case "NamedNode":
+                return `PredicatePath(${propertyPath.value})`;
+        }
+    }
+    PropertyPath.toString = toString;
+})(PropertyPath || (PropertyPath = {}));
+//# sourceMappingURL=PropertyPath.js.map

package/dist/Resource.d.ts

@@ -0,0 +1,112 @@
+import type { BlankNode, DataFactory, DatasetCore, Literal, NamedNode, Quad_Graph, Variable } from "@rdfjs/types";
+import { Either } from "purify-ts";
+import { Identifier as _Identifier, type Identifier } from "./Identifier.js";
+import { ListStructureError as _ListStructureError } from "./ListStructureError.js";
+import { MistypedTermValueError as _MistypedTermValueError } from "./MistypedTermValueError.js";
+import type { Primitive } from "./Primitive.js";
+import type { PropertyPath } from "./PropertyPath.js";
+import type { Term } from "./Term.js";
+import { Value as _Value } from "./Value.js";
+import { ValueError as _ValueError } from "./ValueError.js";
+import { Values as _Values } from "./Values.js";
+/**
+ * A Resource abstraction over subjects or objects in an RDF/JS dataset.
+ */
+export declare class Resource<IdentifierT extends Resource.Identifier = Resource.Identifier> {
+    readonly dataset: DatasetCore;
+    readonly identifier: IdentifierT;
+    private readonly dataFactory;
+    private readonly graph?;
+    private readonly literalFactory;
+    constructor(dataset: DatasetCore, identifier: IdentifierT, options?: {
+        dataFactory?: DataFactory;
+    });
+    /**
+     * Add zero or more values to this resource.
+     */
+    add(propertyPath: InversePath, value: AddableSubject | readonly AddableSubject[], graph?: Graph): this;
+    add(propertyPath: NamedNode, value: AddableObject | readonly AddableObject[], graph?: Graph): this;
+    /**
+     * Create a new list, add items to it, and attach it to this resource via predicate in a
+     * (this, predicate, newList) statement.
+     *
+     * Returns the list resource.
+     */
+    addList(predicate: NamedNode, items: Iterable<AddableObject>, options?: Parameters<Resource["addListItems"]>[1]): Resource;
+    /**
+     * Add rdf:first and rdf:rest predicates to the current Resource.
+     */
+    addListItems(items: Iterable<AddableObject>, options?: {
+        addSubListResourceValues?: (subListResource: Resource) => void;
+        graph?: Graph;
+        mintSubListIdentifier?: (item: AddableObject, itemIndex: number) => Identifier;
+    }): this;
+    /**
+     * Delete zero or more values from this resource.
+     *
+     * If value is empty, delete all values of p
+     * Else delete (p, arrayValue) for each value in the array.
+     */
+    delete(propertyPath: InversePath, value?: AddableSubject | readonly AddableSubject[], graph?: Graph): this;
+    delete(propertyPath: NamedNode, value?: AddableObject | readonly AddableObject[], graph?: Graph): this;
+    isInstanceOf(class_: NamedNode, options?: {
+        excludeSubclasses?: boolean;
+        graph?: Graph;
+        instanceOfPredicate?: NamedNode;
+        subClassOfPredicate?: NamedNode;
+    }): boolean;
+    isSubClassOf(class_: NamedNode, options?: {
+        graph?: Graph;
+        subClassOfPredicate?: NamedNode;
+    }): boolean;
+    /**
+     * Delete all existing values of p and then add the specified values.
+     */
+    set(propertyPath: InversePath, value: AddableSubject | readonly AddableSubject[], graph?: Graph): this;
+    set(propertyPath: NamedNode, value: AddableObject | readonly AddableObject[], graph?: Graph): this;
+    /**
+     * Consider the resource itself as an RDF list.
+     */
+    toList(options?: {
+        graph?: Graph;
+    }): Either<Resource.ValueError, Resource.Values>;
+    /**
+     * Get the first matching value for the property path.
+     */
+    value(propertyPath: PropertyPath, options?: {
+        graph?: Graph;
+    }): Either<Resource.ValueError, Resource.Value>;
+    /**
+     * Get all values for the property path.
+     */
+    values(propertyPath: PropertyPath, options?: {
+        graph?: Graph;
+        unique?: boolean;
+    }): Resource.Values;
+    private addableObjectToTerm;
+    private addableObjectsToTerms;
+    private addableSubjectsToTerms;
+}
+type AddableSubject = BlankNode | NamedNode;
+type AddableObject = BlankNode | Literal | NamedNode | Exclude<Primitive, Date>;
+type Graph = Exclude<Quad_Graph, Variable>;
+type InversePath = {
+    readonly path: NamedNode;
+    readonly termType: "InversePath";
+};
+export declare namespace Resource {
+    const Identifier: typeof _Identifier;
+    type Identifier = _Identifier;
+    const ListStructureError: typeof _ListStructureError;
+    type ListStructureError = _ListStructureError;
+    const MistypedTermValueError: typeof _MistypedTermValueError;
+    type MistypedTermValueError = _MistypedTermValueError;
+    const ValueError: typeof _ValueError;
+    type ValueError = _ValueError;
+    const Value: typeof _Value;
+    type Value<TermT extends Term = Term> = _Value<TermT>;
+    const Values: typeof _Values;
+    type Values<T = Value> = _Values<T>;
+}
+export {};
+//# sourceMappingURL=Resource.d.ts.map

package/dist/Resource.js

@@ -0,0 +1,354 @@
+import DefaultDataFactory from "@rdfjs/data-model";
+import TermSet from "@rdfjs/term-set";
+import { LiteralFactory } from "@rdfx/literal";
+import { Either, Left } from "purify-ts";
+import { DatasetValues } from "./DatasetValues.js";
+import { Identifier as _Identifier } from "./Identifier.js";
+import { ListStructureError as _ListStructureError } from "./ListStructureError.js";
+import { MistypedTermValueError as _MistypedTermValueError } from "./MistypedTermValueError.js";
+import { Value as _Value } from "./Value.js";
+import { ValueError as _ValueError } from "./ValueError.js";
+import { Values as _Values } from "./Values.js";
+import { rdf, rdfs } from "./vocabularies.js";
+/**
+ * A Resource abstraction over subjects or objects in an RDF/JS dataset.
+ */
+export class Resource {
+    constructor(dataset, identifier, options) {
+        this.dataset = dataset;
+        this.identifier = identifier;
+        this.dataFactory = options?.dataFactory ?? DefaultDataFactory;
+        this.literalFactory = new LiteralFactory({ dataFactory: this.dataFactory });
+    }
+    add(propertyPath, value, graph) {
+        if (!graph) {
+            graph = this.graph;
+        }
+        switch (propertyPath.termType) {
+            case "InversePath":
+                for (const subject of this.addableSubjectsToTerms(value)) {
+                    this.dataset.add(this.dataFactory.quad(subject, propertyPath.path, this.identifier, graph));
+                }
+                break;
+            case "NamedNode":
+                for (const object of this.addableObjectsToTerms(value)) {
+                    this.dataset.add(this.dataFactory.quad(this.identifier, propertyPath, object, graph));
+                }
+                break;
+        }
+        return this;
+    }
+    /**
+     * Create a new list, add items to it, and attach it to this resource via predicate in a
+     * (this, predicate, newList) statement.
+     *
+     * Returns the list resource.
+     */
+    addList(predicate, items, options) {
+        const itemsArray = [...items];
+        if (itemsArray.length === 0) {
+            return new Resource(this.dataset, rdf.nil, {
+                dataFactory: this.dataFactory,
+            });
+        }
+        const mintSubListIdentifier = options?.mintSubListIdentifier ?? (() => this.dataFactory.blankNode());
+        const listResource = new Resource(this.dataset, mintSubListIdentifier(itemsArray[0], 0), { dataFactory: this.dataFactory });
+        listResource.addListItems(itemsArray, {
+            graph: options?.graph,
+            mintSubListIdentifier,
+        });
+        this.add(predicate, listResource.identifier, options?.graph);
+        return listResource;
+    }
+    /**
+     * Add rdf:first and rdf:rest predicates to the current Resource.
+     */
+    addListItems(items, options) {
+        const addSubListResourceValues = options?.addSubListResourceValues ?? (() => { });
+        const graph = options?.graph ?? this.graph;
+        const mintSubListIdentifier = options?.mintSubListIdentifier ?? (() => this.dataFactory.blankNode());
+        let currentHead = this;
+        let itemIndex = 0;
+        for (const item of items) {
+            if (itemIndex > 0) {
+                // If currentHead !== this, then create a new head and point the current head's rdf:rest at it
+                const newHead = new Resource(this.dataset, mintSubListIdentifier(item, itemIndex), { dataFactory: this.dataFactory });
+                addSubListResourceValues(newHead);
+                currentHead.add(rdf.rest, newHead.identifier, graph);
+                currentHead = newHead;
+            }
+            currentHead.add(rdf.first, item, graph);
+            itemIndex++;
+        }
+        if (itemIndex > 0) {
+            // If there were any items there was an rdf:first on the current head
+            // Close that head by adding an rdf:rest rdf:nil
+            currentHead.add(rdf.rest, rdf.nil, graph);
+        }
+        return this;
+    }
+    delete(propertyPath, value, graph) {
+        if (!graph) {
+            graph = this.graph;
+        }
+        switch (propertyPath.termType) {
+            case "InversePath": {
+                if (value) {
+                    for (const subject of this.addableSubjectsToTerms(value)) {
+                        for (const quad of [
+                            ...this.dataset.match(subject, propertyPath.path, this.identifier, graph),
+                        ]) {
+                            this.dataset.delete(quad);
+                        }
+                    }
+                }
+                else {
+                    for (const quad of [
+                        ...this.dataset.match(null, propertyPath.path, this.identifier, graph),
+                    ]) {
+                        this.dataset.delete(quad);
+                    }
+                }
+                break;
+            }
+            case "NamedNode": {
+                if (value) {
+                    for (const object of this.addableObjectsToTerms(value)) {
+                        for (const quad of [
+                            ...this.dataset.match(this.identifier, propertyPath, object, graph),
+                        ]) {
+                            this.dataset.delete(quad);
+                        }
+                    }
+                }
+                else {
+                    for (const quad of [
+                        ...this.dataset.match(this.identifier, propertyPath, null, graph),
+                    ]) {
+                        this.dataset.delete(quad);
+                    }
+                }
+                break;
+            }
+        }
+        return this;
+    }
+    isInstanceOf(class_, options) {
+        return isInstanceOfRecursive({
+            class_,
+            dataset: this.dataset,
+            graph: options?.graph ?? this.graph,
+            instance: this.identifier,
+            visitedClasses: new TermSet(),
+        });
+        function isInstanceOfRecursive({ class_, dataset, graph, instance, visitedClasses, }) {
+            for (const _ of dataset.match(instance, options?.instanceOfPredicate ?? rdf.type, class_, graph)) {
+                return true;
+            }
+            visitedClasses.add(class_);
+            if (options?.excludeSubclasses) {
+                return false;
+            }
+            // Recurse into class's sub-classes that haven't been visited yet.
+            for (const quad of dataset.match(null, options?.subClassOfPredicate ?? rdfs.subClassOf, class_, graph)) {
+                if (quad.subject.termType !== "NamedNode") {
+                    continue;
+                }
+                if (visitedClasses.has(quad.subject)) {
+                    continue;
+                }
+                if (isInstanceOfRecursive({
+                    class_: quad.subject,
+                    dataset,
+                    graph,
+                    instance,
+                    visitedClasses,
+                })) {
+                    return true;
+                }
+            }
+            return false;
+        }
+    }
+    isSubClassOf(class_, options) {
+        return isSubClassOfRecursive({
+            class_,
+            dataset: this.dataset,
+            graph: options?.graph ?? this.graph,
+            thisIdentifier: this.identifier,
+            visitedClasses: new TermSet(),
+        });
+        function isSubClassOfRecursive({ class_, dataset, graph, thisIdentifier, visitedClasses, }) {
+            for (const _ of dataset.match(thisIdentifier, options?.subClassOfPredicate ?? rdfs.subClassOf, class_, graph)) {
+                return true;
+            }
+            visitedClasses.add(class_);
+            // Recurse into class's sub-classes that haven't been visited yet.
+            for (const quad of dataset.match(null, options?.subClassOfPredicate ?? rdfs.subClassOf, class_, graph)) {
+                if (quad.subject.termType !== "NamedNode") {
+                    continue;
+                }
+                if (visitedClasses.has(quad.subject)) {
+                    continue;
+                }
+                if (isSubClassOfRecursive({
+                    class_: quad.subject,
+                    dataset,
+                    graph,
+                    thisIdentifier,
+                    visitedClasses,
+                })) {
+                    return true;
+                }
+            }
+            return false;
+        }
+    }
+    set(propertyPath, value, graph) {
+        switch (propertyPath.termType) {
+            case "InversePath":
+                this.delete(propertyPath, undefined, graph);
+                return this.add(propertyPath, value, graph);
+            case "NamedNode":
+                this.delete(propertyPath, undefined, graph);
+                return this.add(propertyPath, value, graph);
+        }
+    }
+    /**
+     * Consider the resource itself as an RDF list.
+     */
+    toList(options) {
+        if (this.identifier.equals(rdf.nil)) {
+            return Either.of(Resource.Values.fromArray({
+                focusResource: this,
+                propertyPath: rdf.nil,
+                values: [],
+            }));
+        }
+        const graph = options?.graph ?? this.graph;
+        const firstObjects = [
+            ...new TermSet([...this.dataset.match(this.identifier, rdf.first, null, graph)].map((quad) => quad.object)),
+        ];
+        if (firstObjects.length === 0) {
+            return Left(new Resource.ListStructureError({
+                focusResource: this,
+                message: "list has no rdf:first statements",
+                propertyPath: rdf.first,
+            }));
+        }
+        if (firstObjects.length > 1) {
+            return Left(new Resource.ListStructureError({
+                focusResource: this,
+                message: "list has multiple rdf:first statements",
+                propertyPath: rdf.first,
+            }));
+        }
+        const firstObject = firstObjects[0];
+        switch (firstObject.termType) {
+            case "BlankNode":
+            case "Literal":
+            case "NamedNode":
+                break;
+            default:
+                return Left(new Resource.MistypedTermValueError({
+                    actualValue: firstObject,
+                    expectedValueType: "BlankNode | Literal | NamedNode",
+                    focusResource: this,
+                    propertyPath: rdf.first,
+                }));
+        }
+        const restObjects = [
+            ...new TermSet([...this.dataset.match(this.identifier, rdf.rest, null, graph)].map((quad) => quad.object)),
+        ];
+        if (restObjects.length === 0) {
+            return Left(new Resource.ListStructureError({
+                focusResource: this,
+                message: "list has no rdf:rest statements",
+                propertyPath: rdf.rest,
+            }));
+        }
+        if (restObjects.length > 1) {
+            return Left(new Resource.ListStructureError({
+                focusResource: this,
+                message: "list has multiple rdf:rest statements",
+                propertyPath: rdf.rest,
+            }));
+        }
+        const restObject = restObjects[0];
+        switch (restObject.termType) {
+            case "BlankNode":
+            case "NamedNode":
+                break;
+            default:
+                return Left(new Resource.MistypedTermValueError({
+                    actualValue: restObject,
+                    expectedValueType: "BlankNode | NamedNode",
+                    focusResource: this,
+                    propertyPath: rdf.rest,
+                }));
+        }
+        return Either.of(new Resource.Value({
+            dataFactory: this.dataFactory,
+            focusResource: this,
+            propertyPath: rdf.first,
+            term: firstObject,
+        }).toValues()).chain((items) => new Resource(this.dataset, restObject, {
+            dataFactory: this.dataFactory,
+        })
+            .toList({ graph })
+            .map((restItems) => items.concat(...restItems)));
+    }
+    /**
+     * Get the first matching value for the property path.
+     */
+    value(propertyPath, options) {
+        return this.values(propertyPath, options).head();
+    }
+    /**
+     * Get all values for the property path.
+     */
+    values(propertyPath, options) {
+        return new DatasetValues({
+            dataFactory: this.dataFactory,
+            focusResource: this,
+            graph: options?.graph ?? this.graph ?? null,
+            propertyPath,
+            unique: !!options?.unique,
+        });
+    }
+    addableObjectToTerm(object) {
+        switch (typeof object) {
+            case "bigint":
+                return this.literalFactory.bigint(object);
+            case "boolean":
+                return this.literalFactory.boolean(object);
+            case "number":
+                return this.literalFactory.number(object);
+            case "string":
+                return this.literalFactory.string(object);
+            case "object":
+                return object;
+        }
+    }
+    addableObjectsToTerms(objects) {
+        if (Array.isArray(objects)) {
+            return objects.map((value) => this.addableObjectToTerm(value));
+        }
+        return [this.addableObjectToTerm(objects)];
+    }
+    addableSubjectsToTerms(subjects) {
+        if (Array.isArray(subjects)) {
+            return subjects;
+        }
+        return [subjects];
+    }
+}
+(function (Resource) {
+    Resource.Identifier = _Identifier;
+    Resource.ListStructureError = _ListStructureError;
+    Resource.MistypedTermValueError = _MistypedTermValueError;
+    Resource.ValueError = _ValueError;
+    Resource.Value = _Value;
+    Resource.Values = _Values;
+})(Resource || (Resource = {}));
+//# sourceMappingURL=Resource.js.map

package/dist/ResourceSet.d.ts

@@ -0,0 +1,24 @@
+import type { DataFactory, DatasetCore, NamedNode, Quad_Graph, Variable } from "@rdfjs/types";
+import { Resource } from "./Resource.js";
+/**
+ * A ResourceSet wraps an RDF/JS dataset with convenient resource factory methods.
+ */
+export declare class ResourceSet {
+    readonly dataset: DatasetCore;
+    private readonly dataFactory;
+    private readonly graph?;
+    constructor(dataset: DatasetCore, options?: {
+        dataFactory?: DataFactory;
+        graph?: Exclude<Quad_Graph, Variable>;
+    });
+    instancesOf(class_: NamedNode, options?: {
+        excludeSubclasses?: boolean;
+        graph?: Exclude<Quad_Graph, Variable>;
+        instanceOfPredicate?: NamedNode;
+        subClassOfPredicate?: NamedNode;
+    }): Generator<Resource>;
+    namedInstancesOf(class_: NamedNode, options?: Parameters<ResourceSet["instancesOf"]>[1]): Generator<Resource<NamedNode>>;
+    resource<IdentifierT extends Resource.Identifier>(identifier: IdentifierT): Resource<IdentifierT>;
+    private instanceIdentifiers;
+}
+//# sourceMappingURL=ResourceSet.d.ts.map