Documentation: Document what happens when data does not conform to object structure

[jeswr]

What happens if I expect person.name to return a string but the dataset contains e.g. a numeric literal:

• Runtime error
• Error at wrapping time
• Is this configurable?

[langsamu]

I agree, these are reasonable questions that should be documented.

They should also, in my opinion, be shown by tests, examples and usage pattern guides.

While we're working on those, let me just put a few unstructured relevant thoughts here.

---

First of all, wrapping is inherently and exclusively runtime behavior.
Unless a consumer specifically invokes wrapping at a time that is considered 'build' for their environment, wrapping is always an 'online' operation. When you call a property read accessor on a mapping class that is a TermWrapper then that invocation is dispatched to an RDF/JS DatasetCore.match call.
There is no preprocessing or 'build' time requirement.

---

Regarding errors, there are two architectural points where errors might surface: Arity and ValueMapping / TermMapping.

Specifically to your question: Whether an error is thrown when the term underlying person.name is a numeric literal depends on how the consumer wishes to handle it.

Let's assume the following RDF:

<> :name "n1" .

and the following wrapper:

class Person extends TermWrapper {
  get name(): string {
    return this.singular(p, valueMapping)
  }
}

where p is just the predicate URI for :name and valueMapping is a lambda that adheres to ValueMapping.

It is then the responsibility and autonomy of valueMapping to do whatever it pleases: Be strict or not, coerce or not, fallback or not, throw or not.

I could say

function valueMapping(n: TermWrapper): string {
  return n.term.value
}

which would always return a string, no matter what type of term the object is.

I could also write (intentionally contrived example)

function valueMapping(n: TermWrapper): string {
  if(n.term.termType !== "Literal") throw new Error("was expecting a literal")
  if(n.term.datatype !== "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString") throw new Error("was expecting a language-tagged string")
  if(n.term.language !== "en-GB") throw new Error("was expecting English")

  return n.term.value
}

One of the goals I would like to reach is tens of these value mappings and term mappings built into this library and exposed easily to developers so they can choose from a variety of well documented, well tested, robust common transformations. And they should also always be able to supply their own in the form of ad hoc lambdas.

[langsamu]

• Overhaul mapping API #37
• Add NamedNodeAs #41
• Generate documentation from comments to GitHub Pages #44
• More docs #50

[langsamu]

I think that this is done with the various PRs listed above.
There's both a convention for strict mappers and infrastructure for documentation.
Not all done but I'm closing as the rest will come organically.