Overhaul mapping API (#37)

* Introduce errors

* Simplify mapping from value to term

1. It need not produce a wrapper but only a term, because it's used in a context that already has dataset & factory.
2. It need not support undefined returns, because those are handled elsewhere in the transformation pipeline.

* Overhaul mapping values to terms

* Overhaul mapping terms to values

* Don't reference file direct

* Use new nomenclature

* Fix unrelated test

* Accommodate stricter mapping

* Partially cover

* XSD NS

* Mitigate binary conversion in Node 24

* Apply new mapper naming everywhere

Co-authored-by: Matthieu Bosquet <matthieubosquet@gmail.com>

* Remove DS param from `ITermFrom`

* Explode `TermFrom` & `TermAs` by term type

Co-authored-by: Matthieu Bosquet <matthieubosquet@gmail.com>

* Consistent guards in TermAs

* Tidy

---------

Co-authored-by: Matthieu Bosquet <matthieubosquet@gmail.com>

Author: langsamu

src/ListItem.ts

@@ -1,30 +1,30 @@
 import { TermWrapper } from "./TermWrapper.js"
 import type { DataFactory, DatasetCore, Term } from "@rdfjs/types"
-import { ValueMapping } from "./mapping/ValueMapping.js"
-import { TermMapping } from "./mapping/TermMapping.js"
 import { RDF } from "./vocabulary/RDF.js"
-import type { IValueMapping } from "./type/IValueMapping"
-import type { ITermMapping } from "./type/ITermMapping.js"
+import type { ITermAsValueMapping } from "./type/ITermAsValueMapping"
+import type { ITermFromValueMapping } from "./type/ITermFromValueMapping.js"
+import { TermAs } from "./mapping/TermAs.js"
+import { TermFrom } from "./mapping/TermFrom.js"
 
 export class ListItem<T> extends TermWrapper {
-    constructor(term: Term, dataset: DatasetCore, factory: DataFactory, private readonly valueMapping: IValueMapping<T>, private readonly termMapping: ITermMapping<T>) {
+    constructor(term: Term, dataset: DatasetCore, factory: DataFactory, private readonly termAs: ITermAsValueMapping<T>, private readonly termFrom: ITermFromValueMapping<T>) {
         super(term, dataset, factory)
     }
 
     public get firstRaw(): Term | undefined {
-        return this.singularNullable(RDF.first, ValueMapping.asIs)
+        return this.singularNullable(RDF.first, TermAs.term)
     }
 
     public set firstRaw(value: Term | undefined) {
-        this.overwriteNullable(RDF.first, value, TermMapping.asIs)
+        this.overwriteNullable(RDF.first, value, TermFrom.itself)
     }
 
     public get restRaw(): Term | undefined {
-        return this.singularNullable(RDF.rest, ValueMapping.asIs)
+        return this.singularNullable(RDF.rest, TermAs.term)
     }
 
     public set restRaw(value: Term | undefined) {
-        this.overwriteNullable(RDF.rest, value, TermMapping.asIs)
+        this.overwriteNullable(RDF.rest, value, TermFrom.itself)
     }
 
     public get isListItem(): boolean {
@@ -36,19 +36,19 @@ export class ListItem<T> extends TermWrapper {
     }
 
     public get first(): T {
-        return this.singular(RDF.first, this.valueMapping)
+        return this.singular(RDF.first, this.termAs)
     }
 
     public set first(value: T) {
-        this.overwrite(RDF.first, value, this.termMapping)
+        this.overwrite(RDF.first, value, this.termFrom)
     }
 
     public get rest(): ListItem<T> {
-        return this.singular(RDF.rest, w => new ListItem(w as Term, w.dataset, w.factory, this.valueMapping, this.termMapping))
+        return this.singular(RDF.rest, w => new ListItem(w as Term, w.dataset, w.factory, this.termAs, this.termFrom))
     }
 
     public set rest(value: ListItem<T>) {
-        this.overwrite(RDF.rest, value, TermMapping.identity)
+        this.overwrite(RDF.rest, value, TermFrom.instance)
     }
 
     public pop(): T {

src/Overwriter.ts

@@ -1,14 +1,14 @@
 import { TermWrapper } from "./TermWrapper.js"
 import { ListItem } from "./ListItem.js"
-import { TermMapping } from "./mapping/TermMapping.js"
 import type { Term } from "@rdfjs/types"
+import { TermFrom } from "./mapping/TermFrom.js"
 
 export class Overwriter<T> extends TermWrapper {
     constructor(subject: TermWrapper, private readonly p: string) {
         super(subject as Term, subject.dataset, subject.factory);
     }
 
     set listNode(object: ListItem<T>) {
-        this.overwrite(this.p, object, TermMapping.identity)
+        this.overwrite(this.p, object, TermFrom.instance)
     }
 }

src/RdfList.ts

@@ -1,6 +1,6 @@
 import { TermWrapper } from "./TermWrapper.js"
-import type { IValueMapping } from "./type/IValueMapping.js"
-import type { ITermMapping } from "./type/ITermMapping.js"
+import type { ITermAsValueMapping } from "./type/ITermAsValueMapping.js"
+import type { ITermFromValueMapping } from "./type/ITermFromValueMapping.js"
 import { IndexerInterceptor } from "./IndexerInterceptor.js"
 import { ListItem } from "./ListItem.js"
 import { RDF } from "./vocabulary/RDF.js"
@@ -10,8 +10,8 @@ import { Overwriter } from "./Overwriter.js"
 export class RdfList<T> implements Array<T> {
     private root: ListItem<T>
 
-    constructor(root: Term, private readonly subject: TermWrapper, private readonly predicate: string, private readonly valueMapping: IValueMapping<T>, private readonly termMapping: ITermMapping<T>) {
-        this.root = new ListItem(root, this.subject.dataset, this.subject.factory, valueMapping, termMapping)
+    constructor(root: Term, private readonly subject: TermWrapper, private readonly predicate: string, private readonly termAs: ITermAsValueMapping<T>, private readonly termFrom: ITermFromValueMapping<T>) {
+        this.root = new ListItem(root, this.subject.dataset, this.subject.factory, termAs, termFrom)
 
         // TODO: Singleton interceptor?
         return new Proxy(this, new IndexerInterceptor<T>)
@@ -120,7 +120,7 @@ export class RdfList<T> implements Array<T> {
 
         for (const item of items) {
             // A node will be needed either to replace rdf:nil in an empty list or to add a new one to the end of an existing list
-            const newNode = new ListItem(this.subject.factory.blankNode(), this.subject.dataset, this.subject.factory, this.valueMapping, this.termMapping)
+            const newNode = new ListItem(this.subject.factory.blankNode(), this.subject.dataset, this.subject.factory, this.termAs, this.termFrom)
 
             const lastNode = this.root.isNil ?
                 // The statement representing an empty list is replaced by a new one whose object is the new node
@@ -188,7 +188,7 @@ export class RdfList<T> implements Array<T> {
     unshift(...items: T[]): number {
         for (const item of items.reverse()) {
             const firstNode = this.root
-            this.root = new Overwriter<T>(this.subject, this.predicate).listNode = new ListItem(this.subject.factory.blankNode(), this.subject.dataset, this.subject.factory, this.valueMapping, this.termMapping)
+            this.root = new Overwriter<T>(this.subject, this.predicate).listNode = new ListItem(this.subject.factory.blankNode(), this.subject.dataset, this.subject.factory, this.termAs, this.termFrom)
             this.root.first = item
             this.root.rest = firstNode
         }

src/TermWrapper.ts

@@ -1,6 +1,6 @@
 import type { Quad_Object, Quad_Subject, Term } from "@rdfjs/types"
-import type { ITermMapping } from "./type/ITermMapping.js"
-import type { IValueMapping } from "./type/IValueMapping.js"
+import type { ITermFromValueMapping } from "./type/ITermFromValueMapping.js"
+import type { ITermAsValueMapping } from "./type/ITermAsValueMapping.js"
 import { WrappingSet } from "./WrappingSet.js"
 import { WrappingMap } from "./WrappingMap.js"
 import { AnyTermWithContext } from "./AnyTermWithContext.js"
@@ -10,7 +10,7 @@ export class TermWrapper extends AnyTermWithContext {
         return this.constructor.name
     }
 
-    protected singular<T>(p: string, valueMapping: IValueMapping<T>): T {
+    protected singular<T>(p: string, termAs: ITermAsValueMapping<T>): T {
         const predicate = this.factory.namedNode(p)
         const matches = this.dataset.match(this as Term, predicate)[Symbol.iterator]()
 
@@ -25,28 +25,28 @@ export class TermWrapper extends AnyTermWithContext {
             throw new Error(`More than one value for predicate ${p} on term ${this.value}`)
         }
 
-        return valueMapping(new TermWrapper(first.object, this.dataset, this.factory))
+        return termAs(new TermWrapper(first.object, this.dataset, this.factory))
     }
 
-    protected singularNullable<T>(p: string, valueMapping: IValueMapping<T>): T | undefined {
+    protected singularNullable<T>(p: string, termAs: ITermAsValueMapping<T>): T | undefined {
         const predicate = this.factory.namedNode(p)
 
         for (const q of this.dataset.match(this as Term, predicate)) {
-            return valueMapping(new TermWrapper(q.object, this.dataset, this.factory))
+            return termAs(new TermWrapper(q.object, this.dataset, this.factory))
         }
 
         return
     }
 
-    protected overwrite<T>(p: string, value: T, nodeMapping: ITermMapping<T>): void {
+    protected overwrite<T>(p: string, value: T, termFrom: ITermFromValueMapping<T>): void {
         if (value === undefined) {
             throw new Error("value cannot be undefined")
         }
 
-        this.overwriteNullable(p, value, nodeMapping)
+        this.overwriteNullable(p, value, termFrom)
     }
 
-    protected overwriteNullable<T>(p: string, value: T | undefined, termMapping: ITermMapping<T>): void {
+    protected overwriteNullable<T>(p: string, value: T | undefined, termFrom: ITermFromValueMapping<T>): void {
         const predicate = this.factory.namedNode(p)
 
         for (const q of this.dataset.match(this as Term, predicate)) {
@@ -65,7 +65,7 @@ export class TermWrapper extends AnyTermWithContext {
         }
 
         // TODO: TermMapping undefined: the term mapping is not invoked if undefined
-        const o = termMapping(value, this.dataset, this.factory)
+        const o = termFrom(value, this.factory)
 
         if (o === undefined) {
             return // TODO: throw error?
@@ -79,12 +79,12 @@ export class TermWrapper extends AnyTermWithContext {
         this.dataset.add(q)
     }
 
-    protected objects<T>(p: string, valueMapping: IValueMapping<T>, termMapping: ITermMapping<T>): Set<T> {
-        return new WrappingSet(this, p, valueMapping, termMapping)
+    protected objects<T>(p: string, termAs: ITermAsValueMapping<T>, termFrom: ITermFromValueMapping<T>): Set<T> {
+        return new WrappingSet(this, p, termAs, termFrom)
     }
 
-    protected map<TKey, TValue>(p: string, valueMapping: IValueMapping<[TKey, TValue]>, termMapping: ITermMapping<[TKey, TValue]>): Map<TKey, TValue> {
-        return new WrappingMap(this, p, valueMapping, termMapping)
+    protected map<TKey, TValue>(p: string, termAs: ITermAsValueMapping<[TKey, TValue]>, termFrom: ITermFromValueMapping<[TKey, TValue]>): Map<TKey, TValue> {
+        return new WrappingMap(this, p, termAs, termFrom)
     }
 
     private static isQuadSubject(term: Term): term is Quad_Subject {

src/WrappingMap.ts

@@ -1,10 +1,10 @@
 import { TermWrapper } from "./TermWrapper.js"
-import type { IValueMapping } from "./type/IValueMapping.js"
-import type { ITermMapping } from "./type/ITermMapping.js"
+import type { ITermAsValueMapping } from "./type/ITermAsValueMapping.js"
+import type { ITermFromValueMapping } from "./type/ITermFromValueMapping.js"
 import type { Quad, Quad_Object, Quad_Subject, Term } from "@rdfjs/types"
 
 export class WrappingMap<TKey, TValue> implements Map<TKey, TValue> {
-    constructor(private readonly subject: TermWrapper, private readonly predicate: string, private readonly valueMapping: IValueMapping<[TKey, TValue]>, private readonly termMapping: ITermMapping<[TKey, TValue]>) {
+    constructor(private readonly subject: TermWrapper, private readonly predicate: string, private readonly termAs: ITermAsValueMapping<[TKey, TValue]>, private readonly termFrom: ITermFromValueMapping<[TKey, TValue]>) {
     }
 
     clear(): void {
@@ -25,7 +25,7 @@ export class WrappingMap<TKey, TValue> implements Map<TKey, TValue> {
                 this.subject.factory.quad(
                     this.subject as Quad_Subject,
                     p,
-                    this.termMapping(entry, this.subject.dataset, this.subject.factory) as Quad_Object))
+                    this.termFrom(entry, this.subject.factory) as Quad_Object))
 
             return true
         }
@@ -72,7 +72,7 @@ export class WrappingMap<TKey, TValue> implements Map<TKey, TValue> {
 
     * entries(): MapIterator<[TKey, TValue]> {
         for (const quad of this.matches) {
-            yield this.valueMapping(new TermWrapper(quad.object, this.subject.dataset, this.subject.factory))
+            yield this.termAs(new TermWrapper(quad.object, this.subject.dataset, this.subject.factory))
         }
     }
 
@@ -109,6 +109,6 @@ export class WrappingMap<TKey, TValue> implements Map<TKey, TValue> {
             this.subject.factory.quad(
                 this.subject as Quad_Subject,
                 p,
-                this.termMapping([k, v], this.subject.dataset, this.subject.factory) as Quad_Object))
+                this.termFrom([k, v], this.subject.factory) as Quad_Object))
     }
 }

src/WrappingSet.ts

@@ -1,11 +1,11 @@
-import type { IValueMapping } from "./type/IValueMapping.js"
-import type { ITermMapping } from "./type/ITermMapping.js"
+import type { ITermAsValueMapping } from "./type/ITermAsValueMapping.js"
+import type { ITermFromValueMapping } from "./type/ITermFromValueMapping.js"
 import type { DatasetCore, Quad, Quad_Object, Quad_Subject, Term } from "@rdfjs/types"
 import { TermWrapper } from "./TermWrapper.js"
 
 export class WrappingSet<T> implements Set<T> {
     // TODO: Direction
-    public constructor(private readonly subject: TermWrapper, private readonly predicate: string, private readonly valueMapping: IValueMapping<T>, private readonly termMapping: ITermMapping<T>) {
+    public constructor(private readonly subject: TermWrapper, private readonly predicate: string, private readonly termAs: ITermAsValueMapping<T>, private readonly termFrom: ITermFromValueMapping<T>) {
     }
 
     add(value: T): this {
@@ -24,7 +24,7 @@ export class WrappingSet<T> implements Set<T> {
             return false
         }
 
-        const o = this.termMapping(value, this.subject.dataset, this.subject.factory) // TODO: guards
+        const o = this.termFrom(value, this.subject.factory) // TODO: guards
         const p = this.subject.factory.namedNode(this.predicate)
 
         for (const q of this.subject.dataset.match(this.subject as Term, p, o as Term)) {
@@ -64,7 +64,7 @@ export class WrappingSet<T> implements Set<T> {
 
     * values(): SetIterator<T> {
         for (const q of this.matches) {
-            yield this.valueMapping(new TermWrapper(q.object, this.subject.dataset, this.subject.factory))
+            yield this.termAs(new TermWrapper(q.object, this.subject.dataset, this.subject.factory))
         }
     }
 
@@ -75,7 +75,7 @@ export class WrappingSet<T> implements Set<T> {
     private quad(value: T): Quad {
         const s = this.subject as Quad_Subject // TODO: guard
         const p = this.subject.factory.namedNode(this.predicate)
-        const o = this.termMapping(value, this.subject.dataset, this.subject.factory) as Quad_Object // TODO: guards
+        const o = this.termFrom(value, this.subject.factory) as Quad_Object // TODO: guards
         const q = this.subject.factory.quad(s, p, o)
         return q
     }

src/decorators/getter.ts

@@ -1,20 +1,20 @@
-import type { ITermMapping } from "../type/ITermMapping.js"
-import type { IValueMapping } from "../type/IValueMapping.js"
+import type { ITermFromValueMapping } from "../type/ITermFromValueMapping.js"
+import type { ITermAsValueMapping } from "../type/ITermAsValueMapping.js"
 import type { TermWrapper } from "../TermWrapper.js"
 
 import { GetterArity } from "./GetterArity.js"
-import { TermMapping } from "../mapping/TermMapping.js"
+import { LiteralFrom } from "../mapping/LiteralFrom.js"
 
-export function getter(predicate: string, getterArity: GetterArity, valueMapping: IValueMapping<any>, termMapping: ITermMapping<any> = TermMapping.stringToLiteral): any {
+export function getter(predicate: string, getterArity: GetterArity, termAs: ITermAsValueMapping<any>, termFrom: ITermFromValueMapping<any> = LiteralFrom.string): any {
     return function (target: any, context: ClassGetterDecoratorContext): any {
         return function (this: TermWrapper): any {
             switch (getterArity) {
                 case GetterArity.Singular:
-                    return this.singular(predicate, valueMapping)
+                    return this.singular(predicate, termAs)
                 case GetterArity.SingularNullable:
-                    return this.singularNullable(predicate, valueMapping)
+                    return this.singularNullable(predicate, termAs)
                 case GetterArity.Set:
-                    return this.objects(predicate, valueMapping, termMapping)
+                    return this.objects(predicate, termAs, termFrom)
             }
         }
     }

src/decorators/setter.ts

@@ -1,16 +1,16 @@
-import type { ITermMapping } from "../type/ITermMapping.js"
+import type { ITermFromValueMapping } from "../type/ITermFromValueMapping.js"
 import type { TermWrapper } from "../TermWrapper.js"
 import { SetterArity } from "./SetterArity.js"
 
-export function setter(predicate: string, setterArity: SetterArity, termMapping: ITermMapping<any>): any {
+export function setter(predicate: string, setterArity: SetterArity, termFrom: ITermFromValueMapping<any>): any {
     return function (target: any, context: ClassSetterDecoratorContext): any {
         return function (this: TermWrapper, value: any): void {
             switch (setterArity) {
                 case SetterArity.Singular:
-                    this.overwrite(predicate, value, termMapping)
+                    this.overwrite(predicate, value, termFrom)
                     break
                 case SetterArity.SingularNullable:
-                    this.overwriteNullable(predicate, value, termMapping)
+                    this.overwriteNullable(predicate, value, termFrom)
                     break
             }
         }

src/errors/LiteralDatatypeError.ts

@@ -0,0 +1,8 @@
+import { TermError } from "./TermError.js"
+import type { Term } from "@rdfjs/types"
+
+export class LiteralDatatypeError extends TermError {
+    constructor(term: Term, public readonly datatypes: Iterable<string>, cause?: any) {
+        super(term, `Literal datatype must be one of ${[...datatypes].map(d => `<${d}>`).join(", ")}`, cause)
+    }
+}

src/errors/TermError.ts

@@ -0,0 +1,8 @@
+import { WrapperError } from "./WrapperError.js"
+import type { Term } from "@rdfjs/types"
+
+export class TermError extends WrapperError {
+    constructor(public readonly term: Term, message?: string, cause?: any) {
+        super(message, cause)
+    }
+}