rdf-wrapper

Use sparq-wrapper

Add the opt-in crate explicitly:

[dependencies]
sparq-core = "0.1"
sparq-wrapper = "0.1"
oxrdf = "0.3"

Load a graph, borrow it, and traverse with typed predicates:

use oxrdf::NamedNode;
use sparq_core::Graph;
use sparq_wrapper::Store;

let graph = Graph::load_str(
    "@prefix ex: <http://example.org/> . ex:alice ex:knows ex:bob . ex:bob ex:age 42 .",
    "turtle",
)?;
let store = Store::borrowed(&graph);
let alice = NamedNode::new("http://example.org/alice")?;
let knows = NamedNode::new("http://example.org/knows")?;
let age = NamedNode::new("http://example.org/age")?;

let bob = store.node(alice).out(&knows).next().expect("friend");
assert_eq!(bob.out(&age).next().expect("age").as_i64()?, 42);
# Ok::<(), Box<dyn std::error::Error>>(())

.out() and .r#in() return NodeSet, an ExactSizeIterator<Item = Node>; the raw identifier is Rust's required spelling for a method named in. Call .values() on a traversal to yield owned oxrdf::Terms. An absent focus or predicate is valid and yields an empty iterator. Node::dataset() exposes a borrowed dataset wrapper; .graph() is the raw sparq_core::Graph escape hatch.

Choose ownership deliberately:

• Store::borrowed(&graph) is read-only and tied to the graph's lifetime.
• Store::owned(graph) and Store::new() own the graph and allow insert/remove. Nodes borrow the store, so stop using them before a write and reacquire them afterwards.
• Traversal addresses the default graph in M1. Reach named graphs through the raw graph until a scoped-dataset surface lands.

Typed accessors are strict:

• as_str() accepts xsd:string and rdf:langString.
• as_i64() accepts the XML Schema integer family, enforces every derived datatype's exact bounds (byte through unsignedLong), then checks that the value is representable as i64.
• as_bool() accepts only xsd:boolean, including true/false/1/0.
• as_typed_literal() returns lexical form, datatype, and language.

All return Result<_, AccessError>; do not silently coerce a mismatched RDF datatype.

Eleven explicitly experimental, default-off features track proposals that remain unlanded in rdfjs/wrapper:

sparq-wrapper = { version = "0.1", features = [
  "proposed-async-events",
  "proposed-async-node",
  "proposed-async-store",
  "proposed-cardinality",
  "proposed-codecs",
  "proposed-distinct",
  "proposed-graph-scope",
  "proposed-graph-scope-events",
  "proposed-json",
  "proposed-observe",
  "proposed-typed-focus",
] }

The async events, async node, and graph-scope events features currently expose reserved, empty modules; enabling them adds no API. Every other proposal feature is implemented. proposed-distinct is exposed as inherent Dataset methods in the crate root rather than through a proposed:: module. See the per-feature proposal status pages for the implemented and reserved feature inventory.

proposed-async-store adds sparq_wrapper::proposed::async_store — the wrapper shape over a store whose reads are not synchronous (an HTTP endpoint, a Solid pod, an out-of-core on-disk index), based on rdfjs/wrapper issue #10 and draft PR #97. Implement AsyncStoreBackend for the backend, then use AsyncStore exactly like Store.

AsyncNode::out / AsyncNode::r#in return a NodeStream that wraps each term into an AsyncNode as it arrives: the first node is observable before the backend finishes producing, and there is deliberately no collect. Building a stream polls nothing; dropping one drops the backend stream, so the wrapper never polls or drains it again. NodeStream::next is cancellation-safe — the wrapper buffers nothing of its own.

Whether a dropped traversal also stops in-flight remote work is the backend's half of the contract: AsyncStoreBackend requires an implementation to start no I/O before the stream or future it returned is first polled, and to abandon that work on drop. Honour it and a partially consumed remote result set is abandoned rather than drained; a backend that instead spawns the request eagerly keeps it running, because the wrapper holds no handle to it.