@blackcatinformatics/purrdf 0.3.3 → 0.4.3

package/index.mjs

@@ -3,14 +3,18 @@
 
 // purrdf — the idiomatic RDF/JS surface over the wasm engine.
 //
-// The wasm-bindgen-generated classes (DataFactory/Dataset/Quad/Sink/Term) are
-// re-exported as-is; this wrapper adds the isomorphic glue that the synchronous
+// The wasm-bindgen-generated classes (DataFactory/Dataset/Quad/Sink/Term) and the
+// free functions (version, shaclValidateToSarif, shaclEntail) are re-exported as-is —
+// the whole `#[wasm_bindgen]` surface is reachable from the package root, so
+// SHACL validation/entailment and Dataset.canonicalize()/isomorphic() need no deep
+// `./pkg/` import. This wrapper adds the isomorphic glue that the synchronous
 // wasm boundary cannot express in Rust:
 //   * `ready()` — one-time async wasm instantiation (required for the `web` target).
 //   * the polymorphic RDF/JS `DataFactory.literal(value, languageOrDatatype)` —
-//     dispatching a NamedNode datatype argument to `typedLiteral` (a wasm-bindgen
-//     exported type can't be recovered from an untyped value in Rust).
+//     dispatching a NamedNode datatype argument to `typedLiteral` and a
+//     `{ language, direction }` argument to `directionalLiteral`.
 //   * `Dataset` iterability (`for (const quad of dataset)`).
+//   * `Dataset.from`, `Dataset#toStream`, and `DataFactory#dataset`.
 //   * `datasetToStream` / `streamToDataset` — the async RDF/JS Stream/Sink primitives
 //     over the synchronous `Dataset.quads()` / `Sink` engine surface.
 
@@ -18,6 +22,9 @@ import init, {
   DataFactory,
   Dataset,
   Quad,
+  QueryEngine,
+  shaclEntail,
+  shaclValidateToSarif,
   Sink,
   Term,
   version,
@@ -25,6 +32,84 @@ import init, {
 
 let _ready = false;
 
+function isNamedNodeTerm(value) {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    value.termType === "NamedNode"
+  );
+}
+
+function isDirectionalLanguage(value) {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof value.language === "string" &&
+    (value.direction === "ltr" || value.direction === "rtl")
+  );
+}
+
+function normalizeQueryOptions(options) {
+  if (options == null) return { base: undefined, format: undefined };
+  if (typeof options !== "object") {
+    throw new TypeError("query options must be an object when supplied");
+  }
+  return {
+    base: options.base ?? undefined,
+    format: options.format ?? undefined,
+  };
+}
+
+function visualizationOptionsJson(options) {
+  if (options == null) return undefined;
+  if (typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("visualization options must be an object when supplied");
+  }
+  return JSON.stringify(options);
+}
+
+function selectResultToObject(raw) {
+  const variables = raw.variables;
+  const rawRows = raw.rows;
+  try {
+    const rows = rawRows.map((row) => {
+      const out = Object.create(null);
+      for (const variable of variables) {
+        const value = row.get(variable);
+        if (value !== undefined) out[variable] = value;
+      }
+      return out;
+    });
+    return { kind: "select", variables, rows };
+  } finally {
+    for (const row of rawRows) row.free?.();
+    raw.free?.();
+  }
+}
+
+function queryResultToObject(raw) {
+  try {
+    switch (raw.kind) {
+      case "select": {
+        const select = raw.takeSelect();
+        if (select === undefined) throw new Error("SELECT result was already consumed");
+        return selectResultToObject(select);
+      }
+      case "ask":
+        return { kind: "ask", boolean: raw.boolean };
+      case "graph": {
+        const dataset = raw.takeDataset();
+        if (dataset === undefined) throw new Error("graph result was already consumed");
+        return { kind: "graph", dataset };
+      }
+      default:
+        throw new Error(`unknown SPARQL result kind ${raw.kind}`);
+    }
+  } finally {
+    raw.free?.();
+  }
+}
+
 /**
  * Instantiate the wasm module. Idempotent. In Node the wasm bytes are read from the
  * colocated file; in a browser, pass the bytes/URL (or omit to fetch the colocated
@@ -52,6 +137,36 @@ export async function ready(wasmBytesOrUrl) {
     };
   }
 
+  if (!Dataset.from) {
+    Dataset.from = function (quads = []) {
+      const dataset = new Dataset();
+      for (const quad of quads ?? []) dataset.add(quad);
+      return dataset;
+    };
+  }
+
+  if (!Dataset.prototype.toStream) {
+    Dataset.prototype.toStream = function () {
+      return datasetToStream(this);
+    };
+  }
+
+  if (!Dataset.prototype.__purrdfVisualizationApi) {
+    const visualModelJson = Dataset.prototype.visualModelJson;
+    const visualExportJson = Dataset.prototype.visualExportJson;
+    const visualSvgJson = Dataset.prototype.visualSvgJson;
+    Dataset.prototype.visualModel = function (options) {
+      return JSON.parse(visualModelJson.call(this, visualizationOptionsJson(options)));
+    };
+    Dataset.prototype.visualExport = function (options) {
+      return JSON.parse(visualExportJson.call(this, visualizationOptionsJson(options)));
+    };
+    Dataset.prototype.visualSvg = function (options) {
+      return JSON.parse(visualSvgJson.call(this, visualizationOptionsJson(options)));
+    };
+    Dataset.prototype.__purrdfVisualizationApi = true;
+  }
+
   // RDF/JS DatasetCore.add(quad)/delete(quad) MUST return the dataset instance so calls
   // chain (`ds.add(q1).add(q2)`). The wasm methods return a bool ("did the effective set
   // change?"); the spec surface returns `this` (the changed-bit stays observable via
@@ -86,21 +201,66 @@ export async function ready(wasmBytesOrUrl) {
 
   // Present the RDF/JS-spec polymorphic literal(value, languageOrDatatype). The wasm
   // method takes `(value, language?)`; a NamedNode second argument is a datatype.
+  // PurRDF also accepts `{ language, direction }` for RDF 1.2 dirLangString literals.
   if (!DataFactory.prototype.__purrdfPolymorphicLiteral) {
     const wasmLiteral = DataFactory.prototype.literal;
     DataFactory.prototype.literal = function (value, languageOrDatatype) {
-      if (
-        languageOrDatatype != null &&
-        typeof languageOrDatatype === "object" &&
-        languageOrDatatype.termType === "NamedNode"
-      ) {
+      if (isNamedNodeTerm(languageOrDatatype)) {
         return this.typedLiteral(value, languageOrDatatype);
       }
+      if (isDirectionalLanguage(languageOrDatatype)) return this.directionalLiteral(value, languageOrDatatype.language, languageOrDatatype.direction);
       return wasmLiteral.call(this, value, languageOrDatatype ?? undefined);
     };
     DataFactory.prototype.__purrdfPolymorphicLiteral = true;
   }
 
+  if (!DataFactory.prototype.dataset) {
+    DataFactory.prototype.dataset = function (quads = []) {
+      return Dataset.from(quads ?? []);
+    };
+  }
+
+  if (!QueryEngine.prototype.__purrdfPackageRootApi) {
+    const wasmQuery = QueryEngine.prototype.query;
+    const wasmSelect = QueryEngine.prototype.select;
+    const wasmAsk = QueryEngine.prototype.ask;
+    const wasmConstruct = QueryEngine.prototype.construct;
+    const wasmDescribe = QueryEngine.prototype.describe;
+    const wasmUpdate = QueryEngine.prototype.update;
+    const wasmQueryRaw = QueryEngine.prototype.queryRaw;
+
+    QueryEngine.prototype.query = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      return queryResultToObject(wasmQuery.call(this, dataset, sparql, base));
+    };
+    QueryEngine.prototype.select = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      return selectResultToObject(wasmSelect.call(this, dataset, sparql, base));
+    };
+    QueryEngine.prototype.ask = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      return wasmAsk.call(this, dataset, sparql, base);
+    };
+    QueryEngine.prototype.construct = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      return wasmConstruct.call(this, dataset, sparql, base);
+    };
+    QueryEngine.prototype.describe = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      return wasmDescribe.call(this, dataset, sparql, base);
+    };
+    QueryEngine.prototype.update = function (dataset, sparql, options) {
+      const { base } = normalizeQueryOptions(options);
+      wasmUpdate.call(this, dataset, sparql, base);
+      return dataset;
+    };
+    QueryEngine.prototype.queryRaw = function (dataset, sparql, options) {
+      const { base, format } = normalizeQueryOptions(options);
+      return wasmQueryRaw.call(this, dataset, sparql, base, format);
+    };
+    QueryEngine.prototype.__purrdfPackageRootApi = true;
+  }
+
   _ready = true;
 }
 
@@ -125,4 +285,14 @@ export async function streamToDataset(quadStream) {
   return sink.finish();
 }
 
-export { DataFactory, Dataset, Quad, Sink, Term, version };
+export {
+  DataFactory,
+  Dataset,
+  Quad,
+  QueryEngine,
+  shaclEntail,
+  shaclValidateToSarif,
+  Sink,
+  Term,
+  version,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackcatinformatics/purrdf",
-  "version": "0.3.3",
+  "version": "0.4.3",
   "description": "A wasm32, in-memory RDF 1.2 engine with an idiomatic RDF/JS (DataFactory/Dataset/Stream) API. Quoted-triple terms and directional literals included.",
   "type": "module",
   "license": "MIT OR Apache-2.0",
@@ -37,7 +37,13 @@
     "pkg/purrdf_wasm_bg.wasm.d.ts"
   ],
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "check": "npm run typecheck && npm test && npm run smoke:pack",
+    "smoke:pack": "node tests/pack-smoke.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.types.json"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
   },
   "engines": {
     "node": ">=18"

package/pkg/purrdf_wasm.d.ts

@@ -45,6 +45,9 @@ export class DataFactory {
      * `namedNode(value)` → a `NamedNode` term.
      */
     namedNode(value: string): Term;
+    /**
+     * `new DataFactory()` — a fresh factory with its blank-node counter at zero.
+     */
     constructor();
     /**
      * `quad(subject, predicate, object, graph?)` → a `Quad`. The graph defaults to the
@@ -80,6 +83,15 @@ export class Dataset {
      * `add(quad)` → insert a quad. Returns `true` if the effective set changed.
      */
     add(quad: Quad): boolean;
+    /**
+     * `canonicalize()` → the dataset as canonical, flat N-Quads under RDFC-1.0
+     * (SHA-256).
+     *
+     * The deterministic identity string for the graph: two datasets denote the same
+     * RDF graph (under blank-node relabeling) iff their canonical forms are
+     * byte-identical. This is the same RDFC-1.0 output the conformance gate pins.
+     */
+    canonicalize(): string;
     /**
      * `delete(quad)` → remove a quad. Returns `true` if the effective set changed.
      */
@@ -88,6 +100,16 @@ export class Dataset {
      * `has(quad)` → whether the quad is in the dataset.
      */
     has(quad: Quad): boolean;
+    /**
+     * `isomorphic(other)` → whether this dataset and `other` are the same RDF graph
+     * under blank-node relabeling.
+     *
+     * The formal RDF graph-identity check, backed by full RDFC-1.0 canonicalization:
+     * an exact oracle with no false positives or false negatives. Equivalent to
+     * comparing the two [`canonicalize`](Self::canonicalize) strings, but avoids
+     * materializing them for obviously-different inputs.
+     */
+    isomorphic(other: Dataset): boolean;
     /**
      * `match(subject?, predicate?, object?, graph?)` → a new dataset of the matching
      * quads. An omitted (`undefined`) position is a wildcard; `defaultGraph()` matches
@@ -127,6 +149,18 @@ export class Dataset {
      * the other text formats).
      */
     serialize(format: string): string;
+    /**
+     * `visualExportJson(optionsJson?)` -> model, scene, geometry, and index as JSON.
+     */
+    visualExportJson(options_json?: string | null): string;
+    /**
+     * `visualModelJson(optionsJson?)` -> the renderer-neutral RDF 1.2 model as JSON.
+     */
+    visualModelJson(options_json?: string | null): string;
+    /**
+     * `visualSvgJson(optionsJson?)` -> deterministic SVG and its complete export.
+     */
+    visualSvgJson(options_json?: string | null): string;
     /**
      * `size` — the number of effective quads.
      */
@@ -150,9 +184,21 @@ export class Quad {
      * Structural RDF/JS quad equality.
      */
     equals(other: Quad): boolean;
+    /**
+     * The graph [`Term`] of the quad (`DefaultGraph` when unnamed).
+     */
     readonly graph: Term;
+    /**
+     * The object [`Term`] of the quad.
+     */
     readonly object: Term;
+    /**
+     * The predicate [`Term`] of the quad.
+     */
     readonly predicate: Term;
+    /**
+     * The subject [`Term`] of the quad.
+     */
     readonly subject: Term;
     /**
      * Always `"Quad"` (a Quad is itself an RDF/JS term).
@@ -164,6 +210,109 @@ export class Quad {
     readonly value: string;
 }
 
+/**
+ * A reusable SPARQL engine that keeps the native plan cache alive across calls.
+ */
+export class QueryEngine {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Run an ASK query and return the boolean result.
+     */
+    ask(dataset: Dataset, sparql: string, base?: string | null): boolean;
+    /**
+     * Run a CONSTRUCT query and return its result dataset.
+     */
+    construct(dataset: Dataset, sparql: string, base?: string | null): Dataset;
+    /**
+     * Run a DESCRIBE query and return its result dataset.
+     */
+    describe(dataset: Dataset, sparql: string, base?: string | null): Dataset;
+    /**
+     * Create a reusable offline SPARQL engine.
+     */
+    constructor();
+    /**
+     * Run any SPARQL query and return a typed raw wasm result wrapper.
+     */
+    query(dataset: Dataset, sparql: string, base?: string | null): QueryResult;
+    /**
+     * Run any SPARQL query and serialize its raw result.
+     */
+    queryRaw(dataset: Dataset, sparql: string, base?: string | null, format?: string | null): string;
+    /**
+     * Run a SELECT query and return typed rows.
+     */
+    select(dataset: Dataset, sparql: string, base?: string | null): SelectResult;
+    /**
+     * Apply a SPARQL UPDATE atomically to the supplied dataset.
+     */
+    update(dataset: Dataset, sparql: string, base?: string | null): void;
+}
+
+/**
+ * A typed SPARQL result returned by the raw wasm binding.
+ */
+export class QueryResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Move the graph dataset out of this wrapper.
+     */
+    takeDataset(): Dataset | undefined;
+    /**
+     * Move the SELECT result out of this wrapper.
+     */
+    takeSelect(): SelectResult | undefined;
+    /**
+     * The ASK boolean when `kind === "ask"`, otherwise `undefined`.
+     */
+    readonly boolean: boolean | undefined;
+    /**
+     * The result discriminator: `"select"`, `"ask"`, or `"graph"`.
+     */
+    readonly kind: string;
+}
+
+/**
+ * A typed SELECT result returned by the raw wasm binding.
+ */
+export class SelectResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The result discriminator.
+     */
+    readonly kind: string;
+    /**
+     * SELECT rows, one object-like row per solution.
+     */
+    readonly rows: SelectRow[];
+    /**
+     * Projected variables, in SELECT projection order.
+     */
+    readonly variables: string[];
+}
+
+/**
+ * One SELECT binding row.
+ */
+export class SelectRow {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Return the bound term for a variable name, or `undefined` for unbound/absent.
+     */
+    get(variable: string): Term | undefined;
+    /**
+     * Variables projected by this row, in SELECT projection order.
+     */
+    readonly variables: string[];
+}
+
 /**
  * An RDF/JS `Sink` — a streaming consumer that interns pushed quads through the
  * `purrdf-events` protocol and freezes them at `finish()`.
@@ -176,6 +325,9 @@ export class Sink {
      * resulting dataset. The sink is consumed; further `push`/`finish` is an error.
      */
     finish(): Dataset;
+    /**
+     * `new Sink()` — an empty sink ready to accept quads via `push`.
+     */
     constructor();
     /**
      * `push(quad)` — stream one quad into the sink (interned via the event protocol).
@@ -269,6 +421,10 @@ export interface InitOutput {
     readonly __wbg_datafactory_free: (a: number, b: number) => void;
     readonly __wbg_dataset_free: (a: number, b: number) => void;
     readonly __wbg_quad_free: (a: number, b: number) => void;
+    readonly __wbg_queryengine_free: (a: number, b: number) => void;
+    readonly __wbg_queryresult_free: (a: number, b: number) => void;
+    readonly __wbg_selectresult_free: (a: number, b: number) => void;
+    readonly __wbg_selectrow_free: (a: number, b: number) => void;
     readonly __wbg_sink_free: (a: number, b: number) => void;
     readonly __wbg_term_free: (a: number, b: number) => void;
     readonly datafactory_blankNode: (a: number, b: number, c: number) => number;
@@ -284,8 +440,10 @@ export interface InitOutput {
     readonly datafactory_typedLiteral: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly datafactory_variable: (a: number, b: number, c: number) => number;
     readonly dataset_add: (a: number, b: number, c: number) => void;
+    readonly dataset_canonicalize: (a: number, b: number) => void;
     readonly dataset_delete: (a: number, b: number, c: number) => void;
     readonly dataset_has: (a: number, b: number, c: number) => void;
+    readonly dataset_isomorphic: (a: number, b: number, c: number) => void;
     readonly dataset_match: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly dataset_new: (a: number) => void;
     readonly dataset_parse: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
@@ -293,6 +451,9 @@ export interface InitOutput {
     readonly dataset_query: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly dataset_serialize: (a: number, b: number, c: number, d: number) => void;
     readonly dataset_size: (a: number) => number;
+    readonly dataset_visualExportJson: (a: number, b: number, c: number, d: number) => void;
+    readonly dataset_visualModelJson: (a: number, b: number, c: number, d: number) => void;
+    readonly dataset_visualSvgJson: (a: number, b: number, c: number, d: number) => void;
     readonly quad_asTerm: (a: number, b: number) => void;
     readonly quad_equals: (a: number, b: number) => number;
     readonly quad_graph: (a: number) => number;
@@ -301,6 +462,22 @@ export interface InitOutput {
     readonly quad_subject: (a: number) => number;
     readonly quad_term_type: (a: number, b: number) => void;
     readonly quad_value: (a: number, b: number) => void;
+    readonly queryengine_ask: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly queryengine_construct: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly queryengine_new: () => number;
+    readonly queryengine_query: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly queryengine_queryRaw: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly queryengine_select: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly queryengine_update: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly queryresult_boolean: (a: number) => number;
+    readonly queryresult_kind: (a: number, b: number) => void;
+    readonly queryresult_takeDataset: (a: number) => number;
+    readonly queryresult_takeSelect: (a: number) => number;
+    readonly selectresult_kind: (a: number, b: number) => void;
+    readonly selectresult_rows: (a: number, b: number) => void;
+    readonly selectresult_variables: (a: number, b: number) => void;
+    readonly selectrow_get: (a: number, b: number, c: number) => number;
+    readonly selectrow_variables: (a: number, b: number) => void;
     readonly shaclEntail: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly shaclValidateToSarif: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly sink_finish: (a: number, b: number) => void;
@@ -317,6 +494,7 @@ export interface InitOutput {
     readonly term_term_type: (a: number, b: number) => void;
     readonly term_value: (a: number, b: number) => void;
     readonly version: (a: number) => void;
+    readonly queryengine_describe: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;