@blackcatinformatics/purrdf 0.1.3

package/index.d.ts

@@ -0,0 +1,37 @@
+// 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>;
+
+/** An RDF/JS Stream (async iterable) of the dataset's quads. */
+export function datasetToStream(dataset: Dataset): AsyncIterableIterator<Quad>;
+
+/** Consume an (async) iterable of quads into a new Dataset via the engine's Sink. */
+export function streamToDataset(
+  quadStream: AsyncIterable<Quad> | Iterable<Quad>,
+): Promise<Dataset>;

package/index.mjs

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc. <paudley@blackcatinformatics.ca>
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+// 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
+// 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).
+//   * `Dataset` iterability (`for (const quad of dataset)`).
+//   * `datasetToStream` / `streamToDataset` — the async RDF/JS Stream/Sink primitives
+//     over the synchronous `Dataset.quads()` / `Sink` engine surface.
+
+import init, {
+  DataFactory,
+  Dataset,
+  Quad,
+  Sink,
+  Term,
+  version,
+} from "./pkg/purrdf_wasm.js";
+
+let _ready = false;
+
+/**
+ * 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
+ * `.wasm`). Must be awaited once before any other API is used.
+ */
+export async function ready(wasmBytesOrUrl) {
+  if (_ready) return;
+  if (wasmBytesOrUrl !== undefined) {
+    await init({ module_or_path: wasmBytesOrUrl });
+  } else if (typeof process !== "undefined" && process.versions?.node) {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const wasmPath = fileURLToPath(
+      new URL("./pkg/purrdf_wasm_bg.wasm", import.meta.url),
+    );
+    await init({ module_or_path: await readFile(wasmPath) });
+  } else {
+    await init();
+  }
+
+  // RDF/JS DatasetCore is iterable over its quads.
+  if (!Dataset.prototype[Symbol.iterator]) {
+    Dataset.prototype[Symbol.iterator] = function () {
+      return this.quads()[Symbol.iterator]();
+    };
+  }
+
+  // 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
+  // `size`). The guard applied here is the same boundary the equals/literal shims use.
+  for (const method of ["add", "delete"]) {
+    const flag = `__purrdfChaining_${method}`;
+    if (!Dataset.prototype[flag]) {
+      const wasmMutate = Dataset.prototype[method];
+      Dataset.prototype[method] = function (quad) {
+        wasmMutate.call(this, quad);
+        return this;
+      };
+      Dataset.prototype[flag] = true;
+    }
+  }
+
+  // RDF/JS spec: Term.equals(other) / Quad.equals(other) MUST return false when `other`
+  // is null or undefined — "Returns false if other is undefined or null." The wasm
+  // `equals` takes a borrowed `&Term`/`&Quad` (non-consuming — the argument stays usable
+  // afterwards), but wasm-bindgen throws on a null borrow, so the null/undefined guard is
+  // applied here, one layer out (the same boundary where the polymorphic literal() lives).
+  for (const Klass of [Term, Quad]) {
+    if (!Klass.prototype.__purrdfNullSafeEquals) {
+      const wasmEquals = Klass.prototype.equals;
+      Klass.prototype.equals = function (other) {
+        if (other === null || other === undefined) return false;
+        return wasmEquals.call(this, other);
+      };
+      Klass.prototype.__purrdfNullSafeEquals = true;
+    }
+  }
+
+  // Present the RDF/JS-spec polymorphic literal(value, languageOrDatatype). The wasm
+  // method takes `(value, language?)`; a NamedNode second argument is a datatype.
+  if (!DataFactory.prototype.__purrdfPolymorphicLiteral) {
+    const wasmLiteral = DataFactory.prototype.literal;
+    DataFactory.prototype.literal = function (value, languageOrDatatype) {
+      if (
+        languageOrDatatype != null &&
+        typeof languageOrDatatype === "object" &&
+        languageOrDatatype.termType === "NamedNode"
+      ) {
+        return this.typedLiteral(value, languageOrDatatype);
+      }
+      return wasmLiteral.call(this, value, languageOrDatatype ?? undefined);
+    };
+    DataFactory.prototype.__purrdfPolymorphicLiteral = true;
+  }
+
+  _ready = true;
+}
+
+/**
+ * An RDF/JS Stream of the dataset's quads — an async iterable. (The engine is
+ * synchronous; the async wrapper is the RDF/JS Stream contract.)
+ */
+export function datasetToStream(dataset) {
+  const quads = dataset.quads();
+  return (async function* () {
+    for (const quad of quads) yield quad;
+  })();
+}
+
+/**
+ * Consume an (async) iterable of quads into a new Dataset, via the engine's streaming
+ * Sink (the purrdf-events ingestion protocol + its finish() resolution).
+ */
+export async function streamToDataset(quadStream) {
+  const sink = new Sink();
+  for await (const quad of quadStream) sink.push(quad);
+  return sink.finish();
+}
+
+export { DataFactory, Dataset, Quad, Sink, Term, version };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@blackcatinformatics/purrdf",
+  "version": "0.1.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",
+  "author": "Blackcat Informatics® Inc. <paudley@blackcatinformatics.ca>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blackcat-Informatics/purrdf"
+  },
+  "keywords": [
+    "rdf",
+    "rdf-1.2",
+    "rdf-star",
+    "rdfjs",
+    "wasm",
+    "turtle",
+    "n-quads"
+  ],
+  "main": "./index.mjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "pkg/purrdf_wasm.js",
+    "pkg/purrdf_wasm.d.ts",
+    "pkg/purrdf_wasm_bg.wasm",
+    "pkg/purrdf_wasm_bg.wasm.d.ts"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pkg/purrdf_wasm.d.ts

@@ -0,0 +1,327 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * An RDF/JS `DataFactory`. Stateless except for the auto-generated blank-node
+ * counter (`blankNode()` with no argument mints a fresh label).
+ */
+export class DataFactory {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * `blankNode(value?)` → a `BlankNode` term; a fresh label is minted when omitted.
+     */
+    blankNode(value?: string | null): Term;
+    /**
+     * `defaultGraph()` → the `DefaultGraph` term.
+     */
+    defaultGraph(): Term;
+    /**
+     * `directionalLiteral(value, language, direction)` → an RDF-1.2 base-direction
+     * literal (`direction` is `"ltr"` or `"rtl"`). The deliberate extension to stock
+     * RDF/JS — no incumbent library carries base direction.
+     */
+    directionalLiteral(value: string, language: string, direction: string): Term;
+    /**
+     * `fromQuad(original)` → a copy of `original`.
+     */
+    fromQuad(original: Quad): Quad;
+    /**
+     * `fromTerm(original)` → a copy of `original` (RDF/JS structural clone).
+     */
+    fromTerm(original: Term): Term;
+    /**
+     * `literal(value, language?)` → a plain (`xsd:string`) or language-tagged literal.
+     *
+     * The RDF/JS spec's unified `literal(value, languageOrDatatype)` — where the second
+     * argument may be a string *or* a `NamedNode` — is presented by the TypeScript
+     * wrapper, which dispatches the `NamedNode` case to [`DataFactory::typed_literal`].
+     * (A `#[wasm_bindgen]`-exported type cannot be recovered from an untyped `JsValue`
+     * in Rust, so the polymorphism lives one layer out, in JS.) For base-direction
+     * literals (RDF 1.2) use [`DataFactory::directional_literal`].
+     */
+    literal(value: string, language?: string | null): Term;
+    /**
+     * `namedNode(value)` → a `NamedNode` term.
+     */
+    namedNode(value: string): Term;
+    constructor();
+    /**
+     * `quad(subject, predicate, object, graph?)` → a `Quad`. The graph defaults to the
+     * default graph. A quoted-triple term (from [`DataFactory::quoted_triple`]) may be
+     * passed as `subject` or `object` (the RDF-1.2 wedge).
+     */
+    quad(subject: Term, predicate: Term, object: Term, graph?: Term | null): Quad;
+    /**
+     * `quotedTriple(subject, predicate, object)` → a quoted-triple `Term`
+     * (`termType: "Quad"`) — the RDF-1.2 wedge. Embed it by passing it as the
+     * `subject`/`object` of another quad.
+     */
+    quotedTriple(subject: Term, predicate: Term, object: Term): Term;
+    /**
+     * `typedLiteral(value, datatype)` → a datatyped literal. `datatype` must be a
+     * `NamedNode`. (The RDF/JS `literal(value, datatype)` form, surfaced by the TS
+     * wrapper.)
+     */
+    typedLiteral(value: string, datatype: Term): Term;
+    /**
+     * `variable(value)` → a `Variable` term.
+     */
+    variable(value: string): Term;
+}
+
+/**
+ * An RDF/JS `DatasetCore` backed by the engine's COW mutable dataset.
+ */
+export class Dataset {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * `add(quad)` → insert a quad. Returns `true` if the effective set changed.
+     */
+    add(quad: Quad): boolean;
+    /**
+     * `delete(quad)` → remove a quad. Returns `true` if the effective set changed.
+     */
+    delete(quad: Quad): boolean;
+    /**
+     * `has(quad)` → whether the quad is in the dataset.
+     */
+    has(quad: Quad): boolean;
+    /**
+     * `match(subject?, predicate?, object?, graph?)` → a new dataset of the matching
+     * quads. An omitted (`undefined`) position is a wildcard; `defaultGraph()` matches
+     * only the default graph, a named node matches that graph.
+     */
+    match(subject?: Term | null, predicate?: Term | null, object?: Term | null, graph?: Term | null): Dataset;
+    /**
+     * An empty dataset.
+     */
+    constructor();
+    /**
+     * `parse(input, format, base?)` → a dataset of the parsed quads.
+     *
+     * `format` is a media type or short name (turtle/ntriples/nquads/trig/rdfxml).
+     * Ill-typed literals are preserved verbatim (RDFLib parity), not rejected.
+     */
+    static parse(input: string, format: string, base?: string | null): Dataset;
+    /**
+     * `quads()` → every effective quad, as a JS array.
+     */
+    quads(): Quad[];
+    /**
+     * `query(sparql, base?)` → run a SPARQL query against this dataset, offline.
+     *
+     * Returns **SPARQL Results JSON** for SELECT / ASK and **Turtle** for
+     * CONSTRUCT / DESCRIBE. A parse error, an evaluation error, or a `SERVICE` /
+     * `LOAD` clause (unresolvable in-browser) throws a JsError — never a silent
+     * empty result.
+     */
+    query(sparql: string, base?: string | null): string;
+    /**
+     * `serialize(format)` → the dataset rendered in `format` (a UTF-8 string).
+     *
+     * Formats: `turtle` / `ntriples` / `nquads` / `trig` / `rdfxml` (their media types
+     * too) plus `jsonld` (JSON-LD-star). Note: a quoted-triple term appearing as a quad
+     * object currently round-trips only through N-Quads (a serializer limitation for
+     * the other text formats).
+     */
+    serialize(format: string): string;
+    /**
+     * `size` — the number of effective quads.
+     */
+    readonly size: number;
+}
+
+/**
+ * An RDF/JS [Quad](https://rdf.js.org/data-model-spec/#quad-interface) — a statement
+ * `(subject, predicate, object, graph)` with `termType: "Quad"`.
+ */
+export class Quad {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * A quoted-triple [`Term`] (`termType: "Quad"`) viewing this quad's `(s, p, o)` —
+     * the RDF-1.2 wedge: pass the result as a subject/object to embed it.
+     */
+    asTerm(): Term;
+    /**
+     * Structural RDF/JS quad equality.
+     */
+    equals(other: Quad): boolean;
+    readonly graph: Term;
+    readonly object: Term;
+    readonly predicate: Term;
+    readonly subject: Term;
+    /**
+     * Always `"Quad"` (a Quad is itself an RDF/JS term).
+     */
+    readonly termType: string;
+    /**
+     * Empty for a Quad (per RDF/JS).
+     */
+    readonly value: string;
+}
+
+/**
+ * An RDF/JS `Sink` — a streaming consumer that interns pushed quads through the
+ * `purrdf-events` protocol and freezes them at `finish()`.
+ */
+export class Sink {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * `finish()` — run the protocol's forward-reference resolution and return the
+     * resulting dataset. The sink is consumed; further `push`/`finish` is an error.
+     */
+    finish(): Dataset;
+    constructor();
+    /**
+     * `push(quad)` — stream one quad into the sink (interned via the event protocol).
+     */
+    push(quad: Quad): void;
+}
+
+/**
+ * An RDF/JS [Term](https://rdf.js.org/data-model-spec/#term-interface).
+ */
+export class Term {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Structural RDF/JS term equality.
+     */
+    equals(other: Term): boolean;
+    /**
+     * `datatype` — the literal's datatype as a `NamedNode`, or `undefined` for a
+     * non-literal.
+     */
+    readonly datatype: Term | undefined;
+    /**
+     * `direction` — the RDF-1.2 base direction (`"ltr"`/`"rtl"`), or `""` when absent.
+     * The deliberate extension to stock RDF/JS (`.goals`: overcome, don't inherit).
+     */
+    readonly direction: string;
+    /**
+     * `graph` of a quoted-triple term — always the default graph (a quoted triple has
+     * no graph slot), else `undefined`.
+     */
+    readonly graph: Term | undefined;
+    /**
+     * `language` — the literal's language tag, or `""` for a non-language-tagged term
+     * (RDF/JS uses the empty string, not `undefined`).
+     */
+    readonly language: string;
+    /**
+     * `object` of a quoted-triple term, else `undefined`.
+     */
+    readonly object: Term | undefined;
+    /**
+     * `predicate` of a quoted-triple term as a `NamedNode`, else `undefined`.
+     */
+    readonly predicate: Term | undefined;
+    /**
+     * `subject` of a quoted-triple term (`termType: "Quad"`), else `undefined`.
+     */
+    readonly subject: Term | undefined;
+    /**
+     * `termType` — the RDF/JS discriminator.
+     */
+    readonly termType: string;
+    /**
+     * `value` — the IRI, blank label, lexical form, or variable name. Empty for a
+     * quoted triple and the default graph (per RDF/JS).
+     */
+    readonly value: string;
+}
+
+/**
+ * The purrdf engine version (the crate's SemVer), exposed to JS as `version()`.
+ *
+ * A liveness probe for the wasm build + the npm package: importing `purrdf` and
+ * calling `version()` proves the module instantiated and the engine linked.
+ */
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    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_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;
+    readonly datafactory_defaultGraph: (a: number) => number;
+    readonly datafactory_directionalLiteral: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly datafactory_fromQuad: (a: number, b: number) => number;
+    readonly datafactory_fromTerm: (a: number, b: number) => number;
+    readonly datafactory_literal: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly datafactory_namedNode: (a: number, b: number, c: number) => number;
+    readonly datafactory_new: () => number;
+    readonly datafactory_quad: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly datafactory_quotedTriple: (a: number, b: number, c: number, d: number, e: number) => void;
+    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_delete: (a: number, b: number, c: number) => void;
+    readonly dataset_has: (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;
+    readonly dataset_quads: (a: number, b: number) => void;
+    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 quad_asTerm: (a: number, b: number) => void;
+    readonly quad_equals: (a: number, b: number) => number;
+    readonly quad_graph: (a: number) => number;
+    readonly quad_object: (a: number) => number;
+    readonly quad_predicate: (a: number) => number;
+    readonly quad_subject: (a: number) => number;
+    readonly quad_term_type: (a: number, b: number) => void;
+    readonly quad_value: (a: number, b: number) => void;
+    readonly sink_finish: (a: number, b: number) => void;
+    readonly sink_new: () => number;
+    readonly sink_push: (a: number, b: number, c: number) => void;
+    readonly term_datatype: (a: number) => number;
+    readonly term_direction: (a: number, b: number) => void;
+    readonly term_equals: (a: number, b: number) => number;
+    readonly term_graph: (a: number) => number;
+    readonly term_language: (a: number, b: number) => void;
+    readonly term_object: (a: number) => number;
+    readonly term_predicate: (a: number) => number;
+    readonly term_subject: (a: number) => number;
+    readonly term_term_type: (a: number, b: number) => void;
+    readonly term_value: (a: number, b: number) => void;
+    readonly version: (a: 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;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;