@rdfx/resource 0.0.1

package/dist/ResourceSet.js

@@ -0,0 +1,76 @@
+import DefaultDataFactory from "@rdfjs/data-model";
+import TermSet from "@rdfjs/term-set";
+import { Resource } from "./Resource.js";
+import { rdf, rdfs } from "./vocabularies.js";
+/**
+ * A ResourceSet wraps an RDF/JS dataset with convenient resource factory methods.
+ */
+export class ResourceSet {
+    constructor(dataset, options) {
+        this.dataset = dataset;
+        this.dataFactory = options?.dataFactory ?? DefaultDataFactory;
+        this.graph = options?.graph;
+    }
+    *instancesOf(class_, options) {
+        for (const identifier of this.instanceIdentifiers(class_, options)) {
+            yield this.resource(identifier);
+        }
+    }
+    *namedInstancesOf(class_, options) {
+        for (const identifier of this.instanceIdentifiers(class_, options)) {
+            if (identifier.termType === "NamedNode")
+                yield this.resource(identifier);
+        }
+    }
+    resource(identifier) {
+        return new Resource(this.dataset, identifier, {
+            dataFactory: this.dataFactory,
+        });
+    }
+    *instanceIdentifiers(class_, options) {
+        yield* instanceIdentifiersRecursive({
+            class_,
+            dataset: this.dataset,
+            graph: options?.graph ?? this.graph,
+            visitedClasses: new TermSet(),
+            yieldedInstanceIdentifiers: new TermSet(),
+        });
+        function* instanceIdentifiersRecursive({ class_, dataset, graph, visitedClasses, yieldedInstanceIdentifiers, }) {
+            // Get instanceQuads of the class
+            for (const quad of dataset.match(null, options?.instanceOfPredicate ?? rdf.type, class_, graph)) {
+                switch (quad.subject.termType) {
+                    case "BlankNode":
+                    case "NamedNode":
+                        if (!yieldedInstanceIdentifiers.has(quad.subject)) {
+                            yield quad.subject;
+                            yieldedInstanceIdentifiers.add(quad.subject);
+                        }
+                        break;
+                    default:
+                        break;
+                }
+            }
+            visitedClasses.add(class_);
+            if (options?.excludeSubclasses) {
+                return;
+            }
+            // 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;
+                }
+                yield* instanceIdentifiersRecursive({
+                    class_: quad.subject,
+                    dataset,
+                    graph,
+                    visitedClasses,
+                    yieldedInstanceIdentifiers,
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=ResourceSet.js.map

package/dist/Term.d.ts

@@ -0,0 +1,6 @@
+import type { BlankNode, Literal, NamedNode } from "@rdfjs/types";
+export type Term = BlankNode | Literal | NamedNode;
+export declare namespace Term {
+    function toString(term: Term): string;
+}
+//# sourceMappingURL=Term.d.ts.map

package/dist/Term.js

@@ -0,0 +1,31 @@
+import { Identifier } from "./Identifier.js";
+import { xsd } from "./vocabularies.js";
+export var Term;
+(function (Term) {
+    // biome-ignore lint/suspicious/noShadowRestrictedNames: fine here
+    function toString(term) {
+        switch (term.termType) {
+            case "BlankNode":
+            case "NamedNode":
+                return Identifier.toString(term);
+            case "Literal": {
+                const literal = term;
+                const escaped = literal.value
+                    .replace(/\\/g, "\\\\")
+                    .replace(/"/g, '\\"')
+                    .replace(/\n/g, "\\n")
+                    .replace(/\r/g, "\\r");
+                const quoted = `"${escaped}"`;
+                if (literal.language) {
+                    return `${quoted}@${literal.language}`;
+                }
+                if (!literal.datatype.equals(xsd.string)) {
+                    return `${quoted}^^<${literal.datatype.value}>`;
+                }
+                return quoted;
+            }
+        }
+    }
+    Term.toString = toString;
+})(Term || (Term = {}));
+//# sourceMappingURL=Term.js.map

package/dist/Value.d.ts

@@ -0,0 +1,103 @@
+import type { BlankNode, DataFactory, Literal, NamedNode, Quad_Graph, Variable } from "@rdfjs/types";
+import { Either } from "purify-ts";
+import type { Identifier } from "./Identifier.js";
+import type { Primitive } from "./Primitive.js";
+import type { PropertyPath } from "./PropertyPath.js";
+import { Resource } from "./Resource.js";
+import { Term } from "./Term.js";
+import { Values } from "./Values.js";
+export declare class Value<TermT extends Term = Term> {
+    private readonly dataFactory;
+    readonly focusResource: Resource;
+    readonly propertyPath: PropertyPath;
+    readonly term: TermT;
+    constructor({ dataFactory, focusResource, propertyPath, term, }: {
+        dataFactory: DataFactory;
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+        term: TermT;
+    });
+    /**
+     * Try to convert this term to a bigint.
+     */
+    toBigInt(): Either<Error, bigint>;
+    toBigInt<T extends bigint>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to a blank node.
+     */
+    toBlankNode(): Either<Error, BlankNode>;
+    /**
+     * Try to convert this term to a boolean.
+     */
+    toBoolean(): Either<Error, boolean>;
+    toBoolean<T extends boolean>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to a date.
+     */
+    toDate(in_?: readonly Date[]): Either<Error, Date>;
+    /**
+     * Try to convert this term to a date-time.
+     */
+    toDateTime(in_?: readonly Date[]): Either<Error, Date>;
+    /**
+     * Try to convert this term to a float.
+     */
+    toFloat(): Either<Error, number>;
+    toFloat<T extends number>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to an identifier (blank node or IRI).
+     */
+    toIdentifier(): Either<Error, Identifier>;
+    toIdentifier<T extends Identifier>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to an int.
+     */
+    toInt(): Either<Error, number>;
+    toInt<T extends number>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to an IRI / NamedNode.
+     */
+    toIri(): Either<Error, NamedNode>;
+    toIri<T extends NamedNode>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to an RDF list.
+     */
+    toList(options?: {
+        graph?: Exclude<Quad_Graph, Variable>;
+    }): Either<Error, Values<Value>>;
+    /**
+     * Try to convert this term to a Literal.
+     */
+    toLiteral(in_?: readonly Literal[]): Either<Error, Literal>;
+    /**
+     * Try to convert this term to a number.
+     */
+    toNumber(): Either<Error, number>;
+    toNumber<T extends number>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to a JavaScript primitive (boolean | Date | number | string).
+     */
+    toPrimitive(): Either<Error, Primitive>;
+    toPrimitive<T extends Primitive>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to a resource (identified by a blank node or IRI).
+     */
+    toResource(): Either<Error, Resource>;
+    toResource<T extends Identifier>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Try to convert this term to a string.
+     */
+    toString(): Either<Error, string>;
+    toString<T extends string>(in_: readonly T[]): Either<Error, T>;
+    toTerm(): Either<Error, TermT>;
+    toTerm<T extends TermT>(in_: readonly T[]): Either<Error, T>;
+    /**
+     * Convert this term into a singleton sequence of values.
+     */
+    toValues(): Values<Value<TermT>>;
+    private constrainDate;
+    private constrainPrimitive;
+    private constrainTerm;
+    private newMistypedTermValueError;
+}
+//# sourceMappingURL=Value.d.ts.map

package/dist/Value.js

@@ -0,0 +1,173 @@
+import { LiteralDecoder } from "@rdfx/literal";
+import { Either, Left } from "purify-ts";
+import { MistypedPrimitiveValueError } from "./MistypedPrimitiveValueError.js";
+import { MistypedTermValueError } from "./MistypedTermValueError.js";
+import { Resource } from "./Resource.js";
+import { Term } from "./Term.js";
+import { Values } from "./Values.js";
+export class Value {
+    constructor({ dataFactory, focusResource, propertyPath, term, }) {
+        this.dataFactory = dataFactory;
+        this.focusResource = focusResource;
+        this.propertyPath = propertyPath;
+        this.term = term;
+    }
+    toBigInt(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeBigIntLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" | ") : "bigint"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    /**
+     * Try to convert this term to a blank node.
+     */
+    toBlankNode() {
+        return this.term.termType === "BlankNode"
+            ? Either.of(this.term)
+            : Left(this.newMistypedTermValueError("BlankNode"));
+    }
+    toBoolean(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeBooleanLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" |") : "boolean"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    /**
+     * Try to convert this term to a date.
+     */
+    toDate(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeDateLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toISOString()).join(" |") : "boolean"))
+            .chain((value) => this.constrainDate(value, in_));
+    }
+    /**
+     * Try to convert this term to a date-time.
+     */
+    toDateTime(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeDateTimeLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toISOString()).join(" |") : "boolean"))
+            .chain((value) => this.constrainDate(value, in_));
+    }
+    toFloat(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeFloatLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" | ") : "float"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    toIdentifier(in_) {
+        if (this.term.termType === "Literal") {
+            return Left(this.newMistypedTermValueError("Identifier"));
+        }
+        return this.constrainTerm(this.term, in_);
+    }
+    toInt(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeIntLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" | ") : "int"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    toIri(in_) {
+        if (this.term.termType !== "NamedNode") {
+            return Left(this.newMistypedTermValueError("IRI"));
+        }
+        return this.constrainTerm(this.term, in_);
+    }
+    /**
+     * Try to convert this term to an RDF list.
+     */
+    toList(options) {
+        return this.toResource().chain((resource) => resource.toList({ graph: options?.graph }));
+    }
+    /**
+     * Try to convert this term to a Literal.
+     */
+    toLiteral(in_) {
+        if (this.term.termType !== "Literal") {
+            return Left(this.newMistypedTermValueError(in_ ? in_.map((_) => Term.toString(_)).join(" | ") : "Literal"));
+        }
+        if (in_ && !in_.some((check) => check.equals(this.term))) {
+            return Left(this.newMistypedTermValueError(in_ ? in_.map((_) => Term.toString(_)).join(" | ") : "Literal"));
+        }
+        return Either.of(this.term);
+    }
+    toNumber(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeNumberLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" | ") : "float"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    toPrimitive(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodePrimitiveLiteral)
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => _.toString()).join(" | ") : "primitive"))
+            .chain((value) => this.constrainPrimitive(value, in_));
+    }
+    toResource(in_) {
+        return (in_ ? this.toIdentifier(in_) : this.toIdentifier()).map((identifier) => new Resource(this.focusResource.dataset, identifier, {
+            dataFactory: this.dataFactory,
+        }));
+    }
+    toString(in_) {
+        return this.toLiteral()
+            .chain(LiteralDecoder.decodeStringLiteral)
+            .chain((value) => this.constrainPrimitive(value, in_))
+            .mapLeft(() => this.newMistypedTermValueError(in_ ? in_.map((_) => JSON.stringify(_)).join(" | ") : "string"));
+    }
+    toTerm(in_) {
+        return this.constrainTerm(this.term, in_);
+    }
+    /**
+     * Convert this term into a singleton sequence of values.
+     */
+    toValues() {
+        return Values.fromValue({
+            focusResource: this.focusResource,
+            propertyPath: this.propertyPath,
+            value: this,
+        });
+    }
+    constrainDate(value, in_) {
+        if (in_ && !in_.some((check) => value.getTime() === check.getTime())) {
+            return Left(new MistypedPrimitiveValueError({
+                actualValue: value,
+                expectedValueType: in_.map((_) => _.toISOString()).join(" | "),
+                focusResource: this.focusResource,
+                propertyPath: this.propertyPath,
+            }));
+        }
+        return Either.of(value);
+    }
+    constrainPrimitive(value, in_) {
+        if (in_ && !in_.some((check) => value === check)) {
+            return Left(new MistypedPrimitiveValueError({
+                actualValue: value,
+                expectedValueType: in_.map((_) => _.toString()).join(" | "),
+                focusResource: this.focusResource,
+                propertyPath: this.propertyPath,
+            }));
+        }
+        return Either.of(value);
+    }
+    constrainTerm(value, in_) {
+        if (in_ && !in_.some((check) => value.equals(check))) {
+            return Left(new MistypedTermValueError({
+                actualValue: value,
+                expectedValueType: in_.map(Term.toString).join(" | "),
+                focusResource: this.focusResource,
+                propertyPath: this.propertyPath,
+            }));
+        }
+        return Either.of(value);
+    }
+    newMistypedTermValueError(expectedValueType) {
+        return new MistypedTermValueError({
+            actualValue: this.term,
+            expectedValueType,
+            focusResource: this.focusResource,
+            propertyPath: this.propertyPath,
+        });
+    }
+}
+//# sourceMappingURL=Value.js.map

package/dist/ValueError.d.ts

@@ -0,0 +1,12 @@
+import type { PropertyPath } from "./PropertyPath.js";
+import type { Resource } from "./Resource.js";
+export declare abstract class ValueError extends Error {
+    readonly focusResource: Resource;
+    readonly propertyPath: PropertyPath;
+    constructor({ focusResource, message, propertyPath, }: {
+        focusResource: Resource;
+        message: string;
+        propertyPath: PropertyPath;
+    });
+}
+//# sourceMappingURL=ValueError.d.ts.map

package/dist/ValueError.js

@@ -0,0 +1,8 @@
+export class ValueError extends Error {
+    constructor({ focusResource, message, propertyPath, }) {
+        super(message);
+        this.focusResource = focusResource;
+        this.propertyPath = propertyPath;
+    }
+}
+//# sourceMappingURL=ValueError.js.map

package/dist/Values.d.ts

@@ -0,0 +1,114 @@
+import { Either } from "purify-ts";
+import { MissingValueError } from "./MissingValueError.js";
+import type { PropertyPath } from "./PropertyPath.js";
+import type { Resource } from "./Resource.js";
+import type { Value } from "./Value.js";
+import type { ValueError } from "./ValueError.js";
+/**
+ * Iterable sequence of values of a given type.
+ *
+ * Resource.values returns instances of this class instead of a simple array of values in order to
+ * (1) preserve the focus resource that .values was invoked on, in case of errors
+ * (2) preserve the propertyPath that .values was invoked with, in case of errors
+ * (3) return purify types from methods like .find instead of null or undefined
+ * (4) add some methods that aren't on arrays, like .chainMap and .head
+ *
+ * The class doesn't try to implement the entire Array interface. Methods are added as needed by downstream code.
+ */
+export declare abstract class Values<T = Value> implements Iterable<T> {
+    readonly focusResource: Resource;
+    readonly propertyPath: PropertyPath;
+    abstract readonly length: number;
+    protected constructor({ focusResource, propertyPath, }: {
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+    });
+    /**
+     * Create a Values instance that is empty.
+     */
+    static empty<T>(parameters: {
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+    }): Values<T>;
+    /**
+     * Create a Values instance from an array of values.
+     */
+    static fromArray<T>(parameters: {
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+        values: readonly T[];
+    }): Values<T>;
+    /**
+     * Create a Values instance from a single value.
+     */
+    static fromValue<T>(parameters: {
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+        value: T;
+    }): SingletonValues<T>;
+    abstract [Symbol.iterator](): Iterator<T>;
+    /**
+     * For each value in the sequence, try to convert it to a new type / transform it using the provided callback.
+     *
+     * If any conversion fails, return the failure (the Left).
+     *
+     * If all of the conversions succeed, return a new Values with the converted values.
+     *
+     * This is a combination of Either.chain and Either.map.
+     */
+    chainMap<NewT>(callback: (value: T, index: number) => Either<Error, NewT>): Either<Error, Values<NewT>>;
+    /**
+     * Concatenate another values of the same type to this Values, returning a new Values instance.
+     */
+    concat(...values: readonly T[]): Values<T>;
+    /**
+     * Filter the values, returning a new Values instance.
+     */
+    filter(propertyPath: (value: T, index: number) => boolean): Values<T>;
+    /**
+     * Find a value that satisfies the given propertyPath.
+     *
+     * Return Right if a value satisfies the propertyPath, otherwise Left.
+     */
+    find(propertyPath: (value: T, index: number) => boolean): Either<MissingValueError, T>;
+    /**
+     * Flatten a Values of iterables into a new Values.
+     *
+     * Equivalent of Array.flat.
+     */
+    flat<NewT>(): Values<NewT>;
+    /**
+     * Map each value to an array of values of a new type. Flatten those arrays and return the result as a new Values.
+     */
+    flatMap<NewT>(callback: (value: T, index: number) => ReadonlyArray<NewT>): Values<NewT>;
+    /**
+     * Get the head of this sequence of values if the sequence is non-empty. Otherwise return Left.
+     */
+    head(): Either<ValueError, T>;
+    /**
+     * Map each value to a value of a new type and return a new Values with the mapped results.
+     */
+    map<NewT>(callback: (value: T, index: number) => NewT): Values<NewT>;
+    /**
+     * Convert this values to an array of the values.
+     */
+    abstract toArray(): readonly T[];
+}
+/**
+ * Private implementation of Values that iterates over a single value.
+ *
+ * Must be in the same file to avoid circular dependencies.
+ */
+declare class SingletonValues<T> extends Values<T> {
+    private readonly value;
+    readonly length = 1;
+    constructor({ value, ...superParameters }: {
+        focusResource: Resource;
+        propertyPath: PropertyPath;
+        value: T;
+    });
+    [Symbol.iterator](): Iterator<T>;
+    toArray(): readonly T[];
+}
+export {};
+//# sourceMappingURL=Values.d.ts.map