@blackcatinformatics/purrdf 0.6.0 → 0.8.0

package/README.md

@@ -76,6 +76,92 @@ const names = engine.select(
 console.log(names.rows.take(0)?.message.value);
 ```
 
+Configured JSON-LD/YAML-LD calls the same Rust context engine as native PurRDF:
+
+```js
+import { CompiledJsonLdContext } from "@blackcatinformatics/purrdf";
+
+const options = JSON.stringify({
+  version: 1,
+  mode: "context",
+  prefixes: { ex: "https://ex/" },
+});
+const context = new CompiledJsonLdContext(options);
+const jsonld = reparsed.serializeWithContext("jsonld", context);
+```
+
+`serializeConfigured` handles one-shot expanded, context, registry-backed, or
+derived requests. Matching `QueryEngine.queryRawConfigured` and
+`queryRawWithContext` methods serialize CONSTRUCT/DESCRIBE graph results.
+
+## Graph, tabular, and research-object projection archives
+
+Projection and lift run entirely in memory through the native Rust engine. The
+caller supplies strict profile-tagged JSON; PurRDF does not fabricate vocabulary,
+identity, or resource limits.
+
+```js
+import { Dataset, liftProjection, ready } from "@blackcatinformatics/purrdf";
+
+await ready();
+const config = JSON.stringify({
+  profile: "lpg-csv",
+  config: {
+    rdf_type: "https://example.org/type",
+    scope: { mode: "all" },
+    limits: {
+      max_artifacts: 16,
+      max_artifact_bytes: 1_000_000,
+      max_total_bytes: 4_000_000,
+      max_archive_bytes: 5_000_000,
+      max_term_depth: 16,
+    },
+    execution_limits: {
+      max_input_records: 1_000,
+      max_model_records: 1_000,
+      max_nodes: 1_000,
+      max_edges: 1_000,
+    },
+  },
+});
+const dataset = Dataset.parse(
+  "@prefix ex: <https://example.org/> . ex:alice ex:knows ex:bob .",
+  "turtle",
+);
+const projected = dataset.project("lpg-csv", config);
+const lifted = liftProjection(projected.archive, "lpg-csv", config);
+const roundTrip = lifted.takeDataset();
+console.log(roundTrip?.size, JSON.parse(projected.lossLedgerJson));
+```
+
+`lpg-csv`, `neo4j-csv`, `open-cypher`, `graphml`, `csvw-exact`, `croissant-1.1`,
+`ro-crate-1.3`, `datacite-4.6`, `dcat-3`, and `frictionless-data-package-1` are
+bidirectional. `csvw-terms`, `okf-terms`, `obo-graphs`, `skos`, `dcat-rdf`, and
+`void` are write-only, loss-ledgered views and are excluded from the
+`LiftProfile` TypeScript union.
+Research-object contexts, vocabularies, identities, and
+profiles are mandatory caller configuration. Archives are canonical
+deterministic USTAR bytes. Package/lift objects own wasm memory; call `free()`
+when finished, and remember that `takeDataset()` transfers its dataset exactly
+once. A runnable Node example is
+[`projection-roundtrip.mjs`](https://github.com/Blackcat-Informatics/purrdf/blob/main/crates/rdf-wasm/js/examples/projection-roundtrip.mjs).
+
+For native RDF dataset descriptions, parse the complete source dataset and pass
+the same strict caller-owned JSON used by Rust and the other hosts:
+
+```js
+const dataset = Dataset.parse(sourceTrig, "trig");
+const description = dataset.project("void", voidConfigJson);
+const archive = description.archive;
+description.free();
+dataset.free();
+```
+
+The `dcat-rdf` configuration selects mapped or bounded CONSTRUCT mode; the
+`void` configuration names exact graphs, every target role, dataset-prefix
+ownership, and all limits. Complete examples are in
+`crates/rdf/tests/fixtures/dataset-description/`.
+
 ## API surface
 
 - `ready(bytesOrUrl?)` — one-time async wasm instantiation.
@@ -83,10 +169,14 @@ console.log(names.rows.take(0)?.message.value);
   `directionalLiteral`, `variable`, `defaultGraph`, `quad`, `quotedTriple`,
   `fromTerm`, `fromQuad`.
 - `Dataset` — `Dataset.parse(input, format, base?)`, `serialize(format)`,
+  `serializeConfigured(format, optionsJson)`, `serializeWithContext(format, context)`,
   `add` / `delete` / `has` / `match` / `quads` / `size`, iteration.
   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.project(profile, configJson)` / `liftProjection(archive, profile,
+  configJson)` — canonical graph/tabular/research-object USTAR carriers with structured,
+  always-computed loss-ledger JSON.
 - `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.

package/index.d.ts

@@ -61,6 +61,20 @@ export interface QueryRawOptions extends QueryOptions {
   readonly format?: QueryRawFormat | string | null;
 }
 
+/** Closed, versioned options document consumed by the shared Rust JSON-LD engine. */
+export type JsonLdSerializeOptions =
+  | { readonly version: 1; readonly mode: "expanded"; readonly yaml_schema_url?: string }
+  | { readonly version: 1; readonly mode: "derived"; readonly yaml_schema_url?: string }
+  | {
+      readonly version: 1;
+      readonly mode: "context";
+      readonly prefixes?: Readonly<Record<string, string>>;
+      readonly context?: unknown;
+      readonly document_iri?: string;
+      readonly registry?: Readonly<Record<string, unknown>>;
+      readonly yaml_schema_url?: string;
+    };
+
 export type QueryBindingRow = Record<string, RdfTerm | undefined>;
 
 export interface QueryBindingRows extends IterableIterator<QueryBindingRow> {
@@ -378,10 +392,22 @@ export class Dataset implements Iterable<Quad> {
     graph?: Term | null,
   ): Dataset;
   quads(): Quad[];
+  project(profile: ProjectionProfile, configJson: string): ProjectionPackage;
+  projectWithAssets(
+    profile: "ro-crate-1.3",
+    configJson: string,
+    assetsArchive: Uint8Array,
+  ): ProjectionPackage;
   visualModel(options?: VisualizationOptions | null): VisualModel;
   visualExport(options?: VisualizationOptions | null): VisualExport;
   visualSvg(options?: VisualizationOptions | null): VisualSvgDocument;
   serialize(format: string): string;
+  serializeConfigured(format: "jsonld" | "yamlld" | string, optionsJson: string): string;
+  serializeWithContext(
+    format: "jsonld" | "yamlld" | string,
+    context: CompiledJsonLdContext,
+    yamlSchemaUrl?: string | null,
+  ): string;
   query(sparql: string, base?: string | null): string;
   canonicalize(): string;
   isomorphic(other: Dataset): boolean;
@@ -390,6 +416,62 @@ export class Dataset implements Iterable<Quad> {
   free(): void;
 }
 
+export class CompiledJsonLdContext {
+  constructor(optionsJson: string);
+  canonicalContextJson(): string;
+  free(): void;
+}
+
+export type ProjectionProfile =
+  | "lpg-csv"
+  | "neo4j-csv"
+  | "open-cypher"
+  | "graphml"
+  | "csvw-exact"
+  | "csvw-terms"
+  | "okf-terms"
+  | "obo-graphs"
+  | "skos"
+  | "croissant-1.1"
+  | "ro-crate-1.3"
+  | "datacite-4.6"
+  | "dcat-3"
+  | "dcat-rdf"
+  | "void"
+  | "frictionless-data-package-1";
+
+export type LiftProfile = Exclude<
+  ProjectionProfile,
+  "csvw-terms" | "okf-terms" | "obo-graphs" | "skos" | "dcat-rdf" | "void"
+>;
+
+export interface ProjectionLossLedger {
+  schema_version: 1;
+  losses: Array<{
+    code: string;
+    from: string;
+    to: string;
+    intentional: boolean;
+    note: string;
+    location?: string;
+  }>;
+}
+
+export class ProjectionPackage {
+  private constructor();
+  readonly profile: ProjectionProfile;
+  readonly archive: Uint8Array;
+  readonly lossLedgerJson: string;
+  free(): void;
+}
+
+export class ProjectionLift {
+  private constructor();
+  readonly lossLedgerJson: string;
+  takeDataset(): Dataset | undefined;
+  free(): void;
+}
+
 export class QueryEngine {
   constructor();
   query(dataset: Dataset, sparql: string, options?: QueryOptions | null): QueryResult;
@@ -399,6 +481,21 @@ export class QueryEngine {
   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;
+  queryRawConfigured(
+    dataset: Dataset,
+    sparql: string,
+    base: string | null | undefined,
+    format: "jsonld" | "yamlld" | string,
+    optionsJson: string,
+  ): string;
+  queryRawWithContext(
+    dataset: Dataset,
+    sparql: string,
+    base: string | null | undefined,
+    format: "jsonld" | "yamlld" | string,
+    context: CompiledJsonLdContext,
+    yamlSchemaUrl?: string | null,
+  ): string;
   free(): void;
 }
 
@@ -414,6 +511,11 @@ export function datasetToStream(dataset: Dataset): AsyncIterableIterator<Quad>;
 export function streamToDataset(
   quadStream: AsyncIterable<Quad> | Iterable<Quad>,
 ): Promise<Dataset>;
+export function liftProjection(
+  archive: Uint8Array,
+  profile: LiftProfile,
+  configJson: string,
+): ProjectionLift;
 export function shaclEntail(shapesTtl: string, dataNt: string): string;
 export function shaclValidateToSarif(shapesTtl: string, dataNt: string): string;
 export function version(): string;

package/index.mjs

@@ -19,8 +19,12 @@
 //     over the synchronous `Dataset.quads()` / `Sink` engine surface.
 
 import init, {
+  CompiledJsonLdContext,
   DataFactory,
   Dataset,
+  liftProjection,
+  ProjectionLift,
+  ProjectionPackage,
   Quad,
   QueryEngine,
   shaclEntail,
@@ -328,8 +332,12 @@ export async function streamToDataset(quadStream) {
 }
 
 export {
+  CompiledJsonLdContext,
   DataFactory,
   Dataset,
+  liftProjection,
+  ProjectionLift,
+  ProjectionPackage,
   Quad,
   QueryEngine,
   shaclEntail,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackcatinformatics/purrdf",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -43,6 +43,7 @@
     "typecheck": "tsc -p tsconfig.types.json"
   },
   "devDependencies": {
+    "graphql": "16.14.0",
     "typescript": "7.0.2"
   },
   "engines": {

package/pkg/purrdf_wasm.d.ts

@@ -1,6 +1,22 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * An immutable JSON-LD 1.1 context compiled once and reusable across datasets.
+ */
+export class CompiledJsonLdContext {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Return the recursively canonical context document as JSON.
+     */
+    canonicalContextJson(): string;
+    /**
+     * Compile the context branch of a versioned JSON-LD options document.
+     */
+    constructor(options_json: string);
+}
+
 /**
  * An RDF/JS `DataFactory`. Stateless except for the auto-generated blank-node
  * counter (`blankNode()` with no argument mints a fresh label).
@@ -123,10 +139,19 @@ export class Dataset {
     /**
      * `parse(input, format, base?)` → a dataset of the parsed quads.
      *
-     * `format` is a media type or short name (turtle/ntriples/nquads/trig/rdfxml).
+     * `format` is a media type or short name
+     * (turtle/ntriples/nquads/trig/rdfxml/jsonld/yamlld).
      * Ill-typed literals are preserved verbatim (RDFLib parity), not rejected.
      */
     static parse(input: string, format: string, base?: string | null): Dataset;
+    /**
+     * Project this dataset into a deterministic graph, tabular, or research-object USTAR package.
+     */
+    project(profile: string, config_json: string): ProjectionPackage;
+    /**
+     * Project this dataset plus a canonical payload-only USTAR into an attached RO-Crate.
+     */
+    projectWithAssets(profile: string, config_json: string, assets_archive: Uint8Array): ProjectionPackage;
     /**
      * `quads()` → every effective quad, as a JS array.
      */
@@ -143,12 +168,23 @@ export class Dataset {
     /**
      * `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).
+     * Formats: `turtle` / `ntriples` / `nquads` / `trig` / `rdfxml` / `jsonld`
+     * (JSON-LD-star) / `yamlld` (YAML-LD-star), and their media types — all resolved
+     * through the one core registry.
+     *
+     * Object-position quoted-triple terms (RDF-1.2 triple terms) are preserved
+     * through N-Quads, JSON-LD, and YAML-LD; the other text syntaxes (Turtle,
+     * N-Triples, TriG, RDF/XML) flatten them.
      */
     serialize(format: string): string;
+    /**
+     * Serialize JSON-LD/YAML-LD using the shared versioned options decoder.
+     */
+    serializeConfigured(format: string, options_json: string): string;
+    /**
+     * Serialize JSON-LD/YAML-LD using a reusable compiled context.
+     */
+    serializeWithContext(format: string, context: CompiledJsonLdContext, yaml_schema_url?: string | null): string;
     /**
      * `visualExportJson(optionsJson?)` -> model, scene, geometry, and index as JSON.
      */
@@ -167,6 +203,44 @@ export class Dataset {
     readonly size: number;
 }
 
+/**
+ * Result of lifting a strict carrier package into an in-memory RDF dataset.
+ */
+export class ProjectionLift {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Move the lifted dataset out of this result. The dataset can be taken once.
+     */
+    takeDataset(): Dataset | undefined;
+    /**
+     * Canonical, versioned runtime loss-ledger JSON.
+     */
+    readonly lossLedgerJson: string;
+}
+
+/**
+ * A deterministic USTAR projection package and its canonical runtime ledger.
+ */
+export class ProjectionPackage {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Canonical deterministic USTAR bytes.
+     */
+    readonly archive: Uint8Array;
+    /**
+     * Canonical, versioned runtime loss-ledger JSON.
+     */
+    readonly lossLedgerJson: string;
+    /**
+     * Stable carrier profile name.
+     */
+    readonly profile: string;
+}
+
 /**
  * An RDF/JS [Quad](https://rdf.js.org/data-model-spec/#quad-interface) — a statement
  * `(subject, predicate, object, graph)` with `termType: "Quad"`.
@@ -240,6 +314,14 @@ export class QueryEngine {
      * Run any SPARQL query and serialize its raw result.
      */
     queryRaw(dataset: Dataset, sparql: string, base?: string | null, format?: string | null): string;
+    /**
+     * Serialize a CONSTRUCT/DESCRIBE result with configured JSON-LD/YAML-LD.
+     */
+    queryRawConfigured(dataset: Dataset, sparql: string, base: string | null | undefined, format: string, options_json: string): string;
+    /**
+     * Serialize a CONSTRUCT/DESCRIBE result with a reusable compiled context.
+     */
+    queryRawWithContext(dataset: Dataset, sparql: string, base: string | null | undefined, format: string, context: CompiledJsonLdContext, yaml_schema_url?: string | null): string;
     /**
      * Run a SELECT query and return typed rows.
      */
@@ -406,6 +488,11 @@ export class Term {
     readonly value: string;
 }
 
+/**
+ * Lift a strict bidirectional USTAR package into an in-memory RDF dataset.
+ */
+export function liftProjection(archive: Uint8Array, profile: string, config_json: string): ProjectionLift;
+
 /**
  * `shaclEntail(shapesTtl, dataNt)` → the materialized dataset as an N-Triples
  * string (the base graph plus every inferred triple).
@@ -435,8 +522,11 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_compiledjsonldcontext_free: (a: number, b: number) => void;
     readonly __wbg_datafactory_free: (a: number, b: number) => void;
     readonly __wbg_dataset_free: (a: number, b: number) => void;
+    readonly __wbg_projectionlift_free: (a: number, b: number) => void;
+    readonly __wbg_projectionpackage_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;
@@ -444,6 +534,8 @@ export interface InitOutput {
     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 compiledjsonldcontext_canonicalContextJson: (a: number, b: number) => void;
+    readonly compiledjsonldcontext_new: (a: number, b: number, c: 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;
@@ -464,13 +556,23 @@ export interface InitOutput {
     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_project: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly dataset_projectWithAssets: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: 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_serializeConfigured: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly dataset_serializeWithContext: (a: number, b: number, c: number, d: number, e: number, f: number, g: 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 liftProjection: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly projectionlift_lossLedgerJson: (a: number, b: number) => void;
+    readonly projectionlift_takeDataset: (a: number) => number;
+    readonly projectionpackage_archive: (a: number, b: number) => void;
+    readonly projectionpackage_lossLedgerJson: (a: number, b: number) => void;
+    readonly projectionpackage_profile: (a: number, b: number) => void;
     readonly quad_asTerm: (a: number, b: number) => void;
     readonly quad_equals: (a: number, b: number) => number;
     readonly quad_graph: (a: number) => number;
@@ -484,6 +586,8 @@ export interface InitOutput {
     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_queryRawConfigured: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly queryengine_queryRawWithContext: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: 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;
@@ -516,10 +620,10 @@ export interface InitOutput {
     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;
-    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;