@blackcatinformatics/purrdf 0.3.3 → 0.4.3

package/README.md

@@ -14,6 +14,10 @@ It is the same engine, byte-for-byte behavior, that ships as the `purrdf`
 Rust crates, the `purrdf` PyPI package, and `libpurrdf` — PurRDF's rule is
 **one engine, one behavior, every language**.
 
+> **Try it live** — the [RDF-1.2 playground](https://blackcat-informatics.github.io/purrdf/playground/)
+> runs this package in your browser: parse, SPARQL, SHACL, serialize, and
+> canonicalize/compare RDF-1.2 graphs client-side, with no install.
+
 ## Why this instead of an incumbent RDF/JS library?
 
 No incumbent RDF/JS library carries the RDF 1.2 features:
@@ -40,7 +44,7 @@ since ~2021 (Chrome/Edge 91+, Firefox 89+, Safari 16.4+) and Node ≥ 18.
 ## Quickstart
 
 ```js
-import { ready, DataFactory, Dataset } from "@blackcatinformatics/purrdf";
+import { ready, DataFactory, Dataset, QueryEngine } from "@blackcatinformatics/purrdf";
 
 await ready(); // one-time async wasm instantiation
 
@@ -63,6 +67,13 @@ ds.add(f.quad(f.namedNode("https://ex/stmt"), f.namedNode("https://ex/asserts"),
 // Quoted triples + directions survive a round-trip through N-Quads.
 const nq = ds.serialize("nquads");
 const reparsed = Dataset.parse(nq, "nquads");
+
+const engine = new QueryEngine();
+const names = engine.select(
+  reparsed,
+  "SELECT ?message WHERE { <https://ex/s> <https://ex/says> ?message }",
+);
+console.log(names.rows[0].message.value);
 ```
 
 ## API surface
@@ -73,18 +84,48 @@ const reparsed = Dataset.parse(nq, "nquads");
   `fromTerm`, `fromQuad`.
 - `Dataset` — `Dataset.parse(input, format, base?)`, `serialize(format)`,
   `add` / `delete` / `has` / `match` / `quads` / `size`, iteration.
-  Formats: `turtle`, `ntriples`, `nquads`, `trig`, `rdfxml`.
+  Formats: `turtle`, `ntriples`, `nquads`, `trig`, `rdfxml` (`serialize` also `jsonld`).
+- `Dataset.canonicalize()` / `Dataset.isomorphic(other)` — RDFC-1.0 canonical N-Quads
+  and RDF graph-identity (isomorphism under blank-node relabeling).
+- `Dataset.visualModel(options?)` / `visualExport(options?)` /
+  `visualSvg(options?)` — the renderer-neutral RDF 1.2 model, complete semantic
+  scene and deterministic geometry, or self-contained SVG paired with that export.
+  Returned objects are structured-clone-safe and preserve triple-term identity,
+  assertion graphs, reifier/annotation graph context, nesting, and diagnostics.
+- `QueryEngine` — a reusable SPARQL execution context with a native plan cache,
+  typed `select` / `ask` / `construct` / `describe` helpers, atomic `update`,
+  and `queryRaw` serialization for SPARQL Results JSON/XML/CSV/TSV plus graph
+  formats. `Dataset.query(...)` remains as the compatibility raw-string helper.
+- `shaclValidateToSarif(shapesTtl, dataNt)` / `shaclEntail(shapesTtl, dataNt)` — SHACL
+  validation to a SARIF 2.1.0 report and SHACL-AF `sh:rule` entailment to N-Triples.
 - `Sink`, `datasetToStream`, `streamToDataset` — the async RDF/JS
   Stream/Sink primitives over the synchronous engine surface.
 - SPARQL evaluation over the in-memory dataset (no server required).
 
 Full typings ship in `index.d.ts`.
 
+```js
+const { svg, export: graph } = reparsed.visualSvg({
+  mode: "compact",
+  vocabulary: [{ prefix: "ex", namespace: "https://ex/" }],
+  svg: { title: "RDF 1.2 graph", embedMetadata: true },
+});
+
+console.log(graph.model.statements, graph.model.relations);
+document.querySelector("#graph").innerHTML = svg;
+```
+
+Compact mode keeps ordinary asserted RDF as directed predicate-labelled edges and
+promotes statements only when they need identity. Incidence mode exposes exact
+subject/predicate/object ports. Table mode scales statement inspection without
+discarding the same underlying model.
+
 ## Scope
 
 In-memory only, by design: no persistent store and no network I/O inside the
-wasm module. For the container transport (GTS), SHACL validation, SPARQL
-result serializers, and the rest of the toolkit, see the
+wasm module. This package provides no network resolver, so remote `SERVICE`
+and `LOAD` fail explicitly. For the container transport (GTS), native APIs, and the
+rest of the toolkit, see the
 [main repository](https://github.com/Blackcat-Informatics/purrdf).
 
 ## Supply chain

package/index.d.ts

@@ -1,37 +1,403 @@
 // SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc. <paudley@blackcatinformatics.ca>
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-// The wasm-bindgen-generated class declarations (DataFactory/Dataset/Quad/Sink/Term
-// and the free `version()` function) are the source of truth for the engine surface.
-export {
-  DataFactory,
-  Dataset,
-  Quad,
-  Sink,
-  Term,
-  version,
-} from "./pkg/purrdf_wasm.js";
-
-import type { Dataset, Quad } from "./pkg/purrdf_wasm.js";
-
-/**
- * Instantiate the wasm module. Idempotent; await once before using any other API.
- * In Node the wasm bytes load from the colocated file automatically; in a browser,
- * pass the bytes/URL or omit to fetch the colocated `.wasm`.
- *
- * After `ready()`, the RDF/JS surface augmentations are live: `Dataset` is iterable
- * (`for (const quad of dataset)`); `Dataset.add`/`Dataset.delete` return the dataset
- * instance so calls chain (`ds.add(q1).add(q2)`); `Term.equals`/`Quad.equals` return
- * `false` for `null`/`undefined` instead of throwing; and
- * `DataFactory.literal(value, languageOrDatatype)` accepts a `NamedNode` datatype as
- * the RDF/JS spec allows (dispatching to `typedLiteral`).
- */
-export function ready(wasmBytesOrUrl?: BufferSource | URL | string): Promise<void>;
+export type LiteralDirection = "ltr" | "rtl";
 
-/** An RDF/JS Stream (async iterable) of the dataset's quads. */
-export function datasetToStream(dataset: Dataset): AsyncIterableIterator<Quad>;
+export type TermType =
+  | "NamedNode"
+  | "BlankNode"
+  | "Literal"
+  | "Variable"
+  | "DefaultGraph"
+  | "Quad";
+
+export interface DirectionalLanguage {
+  readonly language: string;
+  readonly direction: LiteralDirection;
+}
+
+export type LanguageOrDatatype =
+  | string
+  | NamedNode
+  | DirectionalLanguage
+  | null
+  | undefined;
+
+export type QuadGraph = NamedNode | BlankNode | DefaultGraph;
+export type RdfTerm = NamedNode | BlankNode | Literal | Variable | DefaultGraph | QuotedTriple;
+export type QueryGraphFormat =
+  | "turtle"
+  | "ttl"
+  | "ntriples"
+  | "nt"
+  | "nquads"
+  | "nq"
+  | "trig"
+  | "rdfxml"
+  | "jsonld"
+  | "text/turtle"
+  | "application/n-triples"
+  | "application/n-quads"
+  | "application/trig"
+  | "application/rdf+xml"
+  | "application/ld+json";
+export type QueryResultsFormat =
+  | "json"
+  | "srj"
+  | "xml"
+  | "csv"
+  | "tsv"
+  | "application/sparql-results+json"
+  | "application/sparql-results+xml"
+  | "text/csv"
+  | "text/tab-separated-values";
+export type QueryRawFormat = QueryGraphFormat | QueryResultsFormat;
+
+export interface QueryOptions {
+  readonly base?: string | null;
+}
+
+export interface QueryRawOptions extends QueryOptions {
+  readonly format?: QueryRawFormat | string | null;
+}
+
+export type QueryBindingRow = Record<string, RdfTerm | undefined>;
+
+export interface SelectResult {
+  readonly kind: "select";
+  readonly variables: string[];
+  readonly rows: QueryBindingRow[];
+}
+
+export interface AskResult {
+  readonly kind: "ask";
+  readonly boolean: boolean;
+}
+
+export interface GraphResult {
+  readonly kind: "graph";
+  readonly dataset: Dataset;
+}
+
+export type QueryResult = SelectResult | AskResult | GraphResult;
+
+export type VisualMode = "compact" | "incidence" | "table";
+export type VisualLabelPolicy = "compact" | "full";
+export type VisualTableField =
+  | "statement"
+  | "assertedIn"
+  | "reifiers"
+  | "annotations"
+  | "referencedBy"
+  | "depth"
+  | "diagnostics";
+
+export interface VisualVocabularyMapping {
+  readonly prefix: string;
+  readonly namespace: string;
+}
+
+export interface VisualRoleRule {
+  readonly predicateIri: string;
+  readonly role: string;
+}
+
+export interface VisualLayoutOptions {
+  readonly margin?: number;
+  readonly rankSpacing?: number;
+  readonly nodeSpacing?: number;
+  readonly componentSpacing?: number;
+  readonly componentWrapWidth?: number;
+  readonly crossingSweeps?: number;
+  readonly maxNodeWidth?: number;
+}
+
+export interface VisualSvgOptions {
+  readonly embedMetadata?: boolean;
+  readonly includeStyles?: boolean;
+  readonly title?: string;
+}
+
+export interface VisualizationOptions {
+  readonly mode?: VisualMode;
+  readonly focus?: string | null;
+  readonly roleRules?: readonly VisualRoleRule[];
+  readonly vocabulary?: readonly VisualVocabularyMapping[];
+  readonly graph?: string | null;
+  readonly graphs?: readonly string[];
+  readonly labelPolicy?: VisualLabelPolicy;
+  readonly maxStatements?: number;
+  readonly maxTerms?: number;
+  readonly tableFields?: readonly VisualTableField[];
+  readonly layout?: VisualLayoutOptions;
+  readonly svg?: VisualSvgOptions;
+}
+
+export type VisualValueRef =
+  | { readonly kind: "term"; readonly id: string }
+  | { readonly kind: "statement"; readonly id: string };
+
+export type VisualTermValue =
+  | { readonly kind: "iri"; readonly value: string }
+  | { readonly kind: "blank"; readonly label: string; readonly scope: number }
+  | {
+      readonly kind: "literal";
+      readonly lexical_form: string;
+      readonly datatype: string;
+      readonly language: string | null;
+      readonly direction: LiteralDirection | null;
+    };
+
+export interface VisualTerm {
+  readonly id: string;
+  readonly value: VisualTermValue;
+  readonly label: string;
+  readonly roles: readonly unknown[];
+}
+
+export interface VisualStatement {
+  readonly id: string;
+  readonly subject: VisualValueRef;
+  readonly predicate: string;
+  readonly object: VisualValueRef;
+  readonly asserted_in: readonly string[];
+  readonly nesting_depth: number;
+  readonly incoming_references: number;
+  readonly dialect: "rdf12" | "symmetricRdf12" | "generalizedRdf";
+  readonly roles: readonly unknown[];
+}
 
-/** Consume an (async) iterable of quads into a new Dataset via the engine's Sink. */
+export type VisualRelation =
+  | {
+      readonly kind: "reifies";
+      readonly id: string;
+      readonly reifier: string;
+      readonly statement: string;
+      readonly graph: string;
+    }
+  | {
+      readonly kind: "annotation";
+      readonly id: string;
+      readonly reifier: string;
+      readonly predicate: string;
+      readonly object: VisualValueRef;
+      readonly graph: string;
+    };
+
+export interface VisualDiagnostic {
+  readonly id: string;
+  readonly code: string;
+  readonly message: string;
+  readonly target: string | null;
+  readonly dialect: VisualStatement["dialect"];
+}
+
+export interface VisualModel {
+  readonly terms: readonly VisualTerm[];
+  readonly statements: readonly VisualStatement[];
+  readonly assertions: readonly Readonly<Record<string, unknown>>[];
+  readonly relations: readonly VisualRelation[];
+  readonly graphs: readonly Readonly<Record<string, unknown>>[];
+  readonly references: readonly Readonly<Record<string, unknown>>[];
+  readonly table: Readonly<Record<string, unknown>>;
+  readonly diagnostics: readonly VisualDiagnostic[];
+}
+
+export interface VisualScene {
+  readonly schema_version: "purrdf-viz-scene-1";
+  readonly mode: VisualMode;
+  readonly nodes: readonly Readonly<Record<string, unknown>>[];
+  readonly edges: readonly Readonly<Record<string, unknown>>[];
+  readonly groups: readonly Readonly<Record<string, unknown>>[];
+  readonly legend: readonly Readonly<Record<string, unknown>>[];
+  readonly table: Readonly<Record<string, unknown>> | null;
+}
+
+export interface VisualLayout {
+  readonly schema_version: "purrdf-viz-layout-1";
+  readonly mode: VisualMode;
+  readonly width: number;
+  readonly height: number;
+  readonly nodes: readonly Readonly<Record<string, unknown>>[];
+  readonly edges: readonly Readonly<Record<string, unknown>>[];
+  readonly table: Readonly<Record<string, unknown>> | null;
+  readonly legend: readonly Readonly<Record<string, unknown>>[];
+}
+
+export interface VisualExport {
+  readonly schema_version: "purrdf-viz-export-1";
+  readonly spec: Readonly<Record<string, unknown>>;
+  readonly spec_hash: string;
+  readonly model_hash: string;
+  readonly scene_hash: string;
+  readonly model: VisualModel;
+  readonly scene: VisualScene;
+  readonly layout: VisualLayout;
+  readonly element_index: readonly Readonly<Record<string, unknown>>[];
+  readonly diagnostics: readonly VisualDiagnostic[];
+}
+
+export interface VisualSvgDocument {
+  readonly svg: string;
+  readonly export: VisualExport;
+}
+
+export class Term {
+  private constructor();
+  free(): void;
+  readonly termType: TermType;
+  readonly value: string;
+  readonly language: string;
+  readonly direction: "" | LiteralDirection;
+  readonly datatype: NamedNode | undefined;
+  readonly subject: RdfTerm | undefined;
+  readonly predicate: NamedNode | undefined;
+  readonly object: RdfTerm | undefined;
+  readonly graph: DefaultGraph | undefined;
+  equals(other: Term | null | undefined): boolean;
+}
+
+export interface NamedNode extends Term {
+  readonly termType: "NamedNode";
+  readonly value: string;
+  readonly language: "";
+  readonly direction: "";
+  readonly datatype: undefined;
+}
+
+export interface BlankNode extends Term {
+  readonly termType: "BlankNode";
+  readonly value: string;
+  readonly language: "";
+  readonly direction: "";
+  readonly datatype: undefined;
+}
+
+export interface Literal extends Term {
+  readonly termType: "Literal";
+  readonly value: string;
+  readonly language: string;
+  readonly direction: "" | LiteralDirection;
+  readonly datatype: NamedNode;
+}
+
+export interface Variable extends Term {
+  readonly termType: "Variable";
+  readonly value: string;
+  readonly language: "";
+  readonly direction: "";
+  readonly datatype: undefined;
+}
+
+export interface DefaultGraph extends Term {
+  readonly termType: "DefaultGraph";
+  readonly value: "";
+  readonly language: "";
+  readonly direction: "";
+  readonly datatype: undefined;
+}
+
+export interface QuotedTriple extends Term {
+  readonly termType: "Quad";
+  readonly value: "";
+  readonly language: "";
+  readonly direction: "";
+  readonly datatype: undefined;
+  readonly subject: RdfTerm;
+  readonly predicate: NamedNode;
+  readonly object: RdfTerm;
+  readonly graph: DefaultGraph;
+}
+
+export class Quad {
+  private constructor();
+  free(): void;
+  readonly termType: "Quad";
+  readonly value: "";
+  readonly subject: RdfTerm;
+  readonly predicate: NamedNode;
+  readonly object: RdfTerm;
+  readonly graph: QuadGraph;
+  asTerm(): QuotedTriple;
+  equals(other: Quad | null | undefined): boolean;
+}
+
+export class DataFactory {
+  constructor();
+  namedNode(value: string): NamedNode;
+  blankNode(value?: string | null): BlankNode;
+  literal(value: string, languageOrDatatype?: LanguageOrDatatype): Literal;
+  typedLiteral(value: string, datatype: NamedNode): Literal;
+  directionalLiteral(
+    value: string,
+    language: string,
+    direction: LiteralDirection,
+  ): Literal;
+  variable(value: string): Variable;
+  defaultGraph(): DefaultGraph;
+  quad(
+    subject: RdfTerm,
+    predicate: NamedNode,
+    object: RdfTerm,
+    graph?: QuadGraph | null,
+  ): Quad;
+  quotedTriple(subject: RdfTerm, predicate: NamedNode, object: RdfTerm): QuotedTriple;
+  fromTerm<T extends Term>(original: T): T;
+  fromQuad(original: Quad): Quad;
+  dataset(quads?: Iterable<Quad> | null): Dataset;
+}
+
+export class Dataset implements Iterable<Quad> {
+  constructor();
+  static parse(input: string, format: string, base?: string | null): Dataset;
+  static from(quads?: Iterable<Quad> | null): Dataset;
+  readonly size: number;
+  add(quad: Quad): this;
+  delete(quad: Quad): this;
+  has(quad: Quad): boolean;
+  match(
+    subject?: Term | null,
+    predicate?: Term | null,
+    object?: Term | null,
+    graph?: Term | null,
+  ): Dataset;
+  quads(): Quad[];
+  visualModel(options?: VisualizationOptions | null): VisualModel;
+  visualExport(options?: VisualizationOptions | null): VisualExport;
+  visualSvg(options?: VisualizationOptions | null): VisualSvgDocument;
+  serialize(format: string): string;
+  query(sparql: string, base?: string | null): string;
+  canonicalize(): string;
+  isomorphic(other: Dataset): boolean;
+  toStream(): AsyncIterableIterator<Quad>;
+  [Symbol.iterator](): IterableIterator<Quad>;
+  free(): void;
+}
+
+export class QueryEngine {
+  constructor();
+  query(dataset: Dataset, sparql: string, options?: QueryOptions | null): QueryResult;
+  select(dataset: Dataset, sparql: string, options?: QueryOptions | null): SelectResult;
+  ask(dataset: Dataset, sparql: string, options?: QueryOptions | null): boolean;
+  construct(dataset: Dataset, sparql: string, options?: QueryOptions | null): Dataset;
+  describe(dataset: Dataset, sparql: string, options?: QueryOptions | null): Dataset;
+  update(dataset: Dataset, sparql: string, options?: QueryOptions | null): Dataset;
+  queryRaw(dataset: Dataset, sparql: string, options?: QueryRawOptions | null): string;
+  free(): void;
+}
+
+export class Sink {
+  constructor();
+  push(quad: Quad): void;
+  finish(): Dataset;
+  free(): void;
+}
+
+export function ready(wasmBytesOrUrl?: BufferSource | URL | string): Promise<void>;
+export function datasetToStream(dataset: Dataset): AsyncIterableIterator<Quad>;
 export function streamToDataset(
   quadStream: AsyncIterable<Quad> | Iterable<Quad>,
 ): Promise<Dataset>;
+export function shaclEntail(shapesTtl: string, dataNt: string): string;
+export function shaclValidateToSarif(shapesTtl: string, dataNt: string): string;
+export function version(): string;