@blackcatinformatics/purrdf 0.4.0 → 0.5.0

package/index.mjs

@@ -11,9 +11,10 @@
 // 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.
 
@@ -21,6 +22,7 @@ import init, {
   DataFactory,
   Dataset,
   Quad,
+  QueryEngine,
   shaclEntail,
   shaclValidateToSarif,
   Sink,
@@ -30,6 +32,126 @@ 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 length = raw.rowCount;
+  let closed = false;
+
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    raw.free?.();
+  };
+  if (length === 0) close();
+  const materialize = (row) => {
+    try {
+      const out = Object.create(null);
+      for (let index = 0; index < variables.length; index += 1) {
+        const variable = variables[index];
+        const value = row.takeValue(index);
+        if (value !== undefined) out[variable] = value;
+      }
+      return out;
+    } finally {
+      row.free?.();
+      if (raw.remaining === 0) close();
+    }
+  };
+  const rows = {
+    get length() {
+      return length;
+    },
+    get remaining() {
+      return closed ? 0 : raw.remaining;
+    },
+    take(index) {
+      if (closed) return undefined;
+      const row = raw.takeRow(index);
+      return row === undefined ? undefined : materialize(row);
+    },
+    next() {
+      if (closed) return { done: true, value: undefined };
+      const row = raw.nextRow();
+      if (row === undefined) {
+        close();
+        return { done: true, value: undefined };
+      }
+      return { done: false, value: materialize(row) };
+    },
+    return() {
+      close();
+      return { done: true, value: undefined };
+    },
+    toArray() {
+      return Array.from(this);
+    },
+    free: close,
+    [Symbol.iterator]() {
+      return this;
+    },
+  };
+  return { kind: "select", variables, rowCount: length, rows, free: close };
+}
+
+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
@@ -57,6 +179,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
@@ -91,21 +243,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;
 }
 
@@ -134,6 +331,7 @@ export {
   DataFactory,
   Dataset,
   Quad,
+  QueryEngine,
   shaclEntail,
   shaclValidateToSarif,
   Sink,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackcatinformatics/purrdf",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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

@@ -149,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.
      */
@@ -198,6 +210,126 @@ 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;
+    /**
+     * Move the next unconsumed row out of the result.
+     */
+    nextRow(): SelectRow | undefined;
+    /**
+     * Move a row out by result index. Each row can be consumed once.
+     */
+    takeRow(index: number): SelectRow | undefined;
+    /**
+     * The result discriminator.
+     */
+    readonly kind: string;
+    /**
+     * Number of rows that have not yet been consumed.
+     */
+    readonly remaining: number;
+    /**
+     * Total number of SELECT rows, including rows already consumed.
+     */
+    readonly rowCount: number;
+    /**
+     * 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;
+    /**
+     * Move one value out by projection index, or return `undefined` when the
+     * cell is unbound, absent, or was already consumed.
+     */
+    takeValue(index: number): 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()`.
@@ -306,6 +438,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;
@@ -332,6 +468,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;
@@ -340,6 +479,26 @@ 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_nextRow: (a: number) => number;
+    readonly selectresult_remaining: (a: number) => number;
+    readonly selectresult_row_count: (a: number) => number;
+    readonly selectresult_takeRow: (a: number, b: number) => number;
+    readonly selectresult_variables: (a: number, b: number) => void;
+    readonly selectrow_get: (a: number, b: number, c: number) => number;
+    readonly selectrow_takeValue: (a: number, b: 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;
@@ -356,6 +515,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;