rete-graph 0.3.2 → 0.3.5

package/README.md

@@ -28,7 +28,7 @@ for (const row of g.query("SELECT ?s ?label WHERE { ?s rdfs:label ?label } LIMIT
 One self-contained file, engine included — via any npm CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/rete-graph@0.1.0/dist/rete-graph.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/rete-graph@0.3.5/dist/rete-graph.min.js"></script>
 <script>
   (async () => {
     const g = await rete.open(await rete.build("<urn:a> <urn:knows> <urn:b> ."));
@@ -61,12 +61,80 @@ worker. The host serving the file must send CORS headers and honor `Range`.
 `query()` returns `{var: Term}` rows for SELECT, a boolean for ASK, and
 `[s, p, o]` Term triples for CONSTRUCT/DESCRIBE. A `Term` carries `.kind` /
 `.value` / `.datatype` / `.lang`, plus `.toJS()` (number/boolean/BigInt for
-common XSD types) and `.n3`. Also: `queryRaw`, `query(q, {reason: true})`
+common XSD types) and `.n3`. Also: `queryRaw`, `lastWarnings()` (why a FILTER silently dropped rows:
+CONTAINS on an IRI, STRSTARTS on a number, … — see the docs), `query(q, {reason: true})`
 (OWL 2 QL entailment), `prefixSearch`, `textSearch`, `schema`, `graphNames`,
 `info`, `card()` / `examples()` (the file's embedded Dataset Card and its
-example queries), `shacl(shapes)` (SHACL Core validation), and on lazily
-opened graphs `stats()` / `contentHash()`. `wasm` re-exports the raw engine
-for anything this wrapper doesn't wrap.
+example queries), `shacl(shapes)` (SHACL Core validation), `dump()` /
+`nquads()` / `writeNQuads()` / `toNQuads()` (the streaming export below), and
+on lazily opened graphs `stats()` / `contentHash()`. `wasm` re-exports the raw
+engine for anything this wrapper doesn't wrap.
+
+## Streaming the whole graph out
+
+`dump()` walks every quad lazily — the engine decodes one triple at a time and
+the wrapper never holds more than a batch of them, so memory does not grow with
+the graph:
+
+```js
+for await (const [s, p, o, g] of graph.dump()) {
+  // g is the graph Term, or null in the default graph
+}
+```
+
+`dump({graph})` narrows it: omit for the default graph followed by every named
+graph, `null` for the default graph only, an IRI for one named graph.
+`dump({raw: true})` yields the engine's N-Triples tokens instead of `Term`s.
+
+For handing a `.rete` to another store, `nquads()` streams ready-made N-Quads
+text (the engine writes the lines; nothing is re-serialized in JavaScript):
+
+```js
+import { Store } from "oxigraph";
+const store = new Store();
+for await (const chunk of graph.nquads()) store.load(chunk, { format: "application/n-quads" });
+
+await graph.writeNQuads(createWriteStream("out.nq"));  // Node stream, WritableStream, or fn
+const text = await graph.toNQuads();                   // one string — small graphs only
+```
+
+Under the hood each wasm call hands back **10 000 quads** (`batch`), which the
+generator yields one at a time: one call per quad would make the boundary the
+bottleneck, one call for the graph would rebuild the array these methods exist
+to avoid. `heapBytes()` lets you check the claim rather than take it — the
+engine heap is flat across a full dump, where materializing the same quads with
+`SELECT ?s ?p ?o` costs hundreds of MB (see `test/dump-memory.test.mjs`).
+
+This works on **remote graphs too**, with one honest caveat: a full dump
+resolves every term and visits every tile, so it ends up fetching essentially
+the whole file (and the tiles stay cached). It is how you *export* a remote
+graph, not how you peek at one — for that, run a `LIMIT` query.
+
+## RDF 1.2 and quoted triples
+
+The CLI's `--quoted-triple-syntax` vocabulary and defaults, in both directions:
+
+```js
+// Reading: what Turtle/TriG `<< s p o >>` means. "rdf-star" (default) = a quoted
+// triple, as before; "rdf12" = RDF 1.2 (`<<( s p o )>>` triple terms, `<< … >>`
+// reifiers, `{| … |}` annotations). N-Triples/N-Quads ignore it.
+await build(ttlText, "ttl", { quotedTripleSyntax: "rdf12" });
+await build(trigText, "trig", { quotedTripleSyntax: "rdf12" });
+
+// Writing: the N-Quads writers spell a quoted triple as the RDF 1.2 triple term
+// `<<( s p o )>>` by default — what Oxigraph 0.5 and Jena 5 load. "rdf-star"
+// writes rete's stored `<<s p o>>`. RDF 1.2 has no subject-position triple term,
+// so such a statement makes the stream throw under "rdf12".
+await graph.toNQuads();                                 // rdf12
+await graph.toNQuads({ quotedTripleSyntax: "rdf-star" });
+
+// The card says whether a file holds any — from its header, so old files answer:
+graph.card().signals.quoted_triples;
+// { present: true, export_surfaces: ["rdf12", "rdf-star"], export_default: "rdf12" }
+```
+
+`dump()` still yields the stored tokens. A graph with no quoted triples is
+written byte-for-byte the same under either value.
 
 ## Local files, read lazily (Node)