@dwk/rdf 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# `@dwk/rdf`
+
+> Thin Turtle/JSON-LD parse and serialize layer over N3.js. Cross-standard reusable.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/rdf.md) for the full requirements.
+
+This package is **cross-standard reusable**: it takes plain-data inputs only,
+has no Workers-runtime dependency, and unit-tests in isolation (Node, no
+`workerd`).
+
+## API
+
+### Turtle family (over N3.js)
+
+```ts
+import { parseTurtle, writeTurtle } from "@dwk/rdf";
+
+const quads = parseTurtle(turtleString, { baseIRI });
+const out = await writeTurtle(quads, { format: "N-Triples" });
+```
+
+`format` accepts the N3.js identifiers `"Turtle"`, `"TriG"`, `"N-Triples"`,
+`"N-Quads"`.
+
+### JSON-LD
+
+```ts
+import { parseJsonLd, writeJsonLd } from "@dwk/rdf";
+
+const quads = await parseJsonLd(jsonLdStringOrObject, { base });
+const out = await writeJsonLd(quads); // expanded / flattened form
+```
+
+### Content negotiation
+
+`parse` / `serialize` dispatch by media type — the entry points
+`@dwk/solid-pod` uses for content negotiation:
+
+```ts
+import { parse, serialize, formatForMediaType } from "@dwk/rdf";
+
+const quads = await parse(body, request.headers.get("content-type")!);
+const body = await serialize(quads, "text/turtle");
+```
+
+Recognized media types: `text/turtle`, `application/trig`,
+`application/n-triples`, `application/n-quads`, `application/ld+json`.
+Media-type parameters (e.g. `; charset=utf-8`, `; profile=…`) and casing are
+ignored. Note `application/json` is **not** treated as RDF — JSON-LD's media
+type is `application/ld+json`, and auto-parsing arbitrary `application/json`
+bodies as a graph is a correctness/security hazard on write. (A read-only
+`application/json` → JSON-LD convenience can be opted into at the negotiation
+layer; `@dwk/solid-pod` does this on read.)
+
+### Triple ↔ store helpers
+
+`termToStored` / `storedToTerm` / `quadToStored` / `storedToQuad` convert
+between RDF-JS terms/quads and a flat, JSON-serializable `StoredQuad` shape that
+maps onto the DO-SQLite columns in [`@dwk/store`](../store) and survives a
+structured-clone boundary.
+
+```ts
+import { quadToStored, storedToQuad } from "@dwk/rdf";
+
+const row = quadToStored(quad); // { subject, predicate, object, graph }
+const quad = storedToQuad(row);
+```
+
+## JSON-LD: the chosen approach and supported subset
+
+N3.js does not handle JSON-LD, and `jsonld.js` is too large for the Worker
+script-size budget (see
+[non-functional-requirements.md](../../spec/non-functional-requirements.md#runtime-budget)).
+This package therefore ships a **dependency-free JSON-LD ⇄ RDF converter** (zero
+added bytes beyond N3.js) implementing a pragmatic subset of JSON-LD 1.0
+toRDF/fromRDF — the decision that resolves
+[open-questions.md §4](../../spec/open-questions.md).
+
+**Parse (JSON-LD → quads) supports:**
+
+- Inline `@context` (object, or array of objects); context arrays; resetting
+  with `null`.
+- Context features: term → IRI mappings, prefix/CURIE expansion (`prefix:term`),
+  `@vocab`, `@base`, default `@language`, and expanded term definitions with
+  `@id`, `@type` (datatype IRI, `@id`, or `@vocab`), `@language`, and
+  `@container: @list`.
+- Node objects with `@id` (IRIs and `_:` blank nodes), `@type`, nested node
+  objects, and node references.
+- Value objects (`@value` + `@type` / `@language`) and native scalars typed per
+  JSON-LD rules (string → `xsd:string` or a language string, integer →
+  `xsd:integer`, fractional → `xsd:double` in canonical lexical form, boolean →
+  `xsd:boolean`). A `@value` of `null` produces no triple. Relative `@id`/IRIs
+  that no `@base`/`base` resolves to an absolute IRI are dropped rather than
+  emitted as invalid terms.
+- Lists (`@container: @list` and inline `@list`) → `rdf:first`/`rdf:rest`/
+  `rdf:nil`.
+- `@graph`: top-level wrapper (default graph) and named graphs (a node with
+  `@id` + `@graph`).
+- `@reverse` properties.
+
+**Serialize (quads → JSON-LD)** emits **expanded / flattened** form (node
+objects keyed by full IRIs, no `@context`), reconstructing well-formed
+`rdf:first`/`rdf:rest`/`rdf:nil` chains back into `@list`. This form round-trips
+through `parseJsonLd` at the RDF (quad) level. One inherent caveat: an empty
+`@list` becomes `rdf:nil`, which the JSON-LD data model cannot distinguish from
+a property whose value is literally `rdf:nil`, so empty lists serialize as an
+`rdf:nil` reference.
+
+**Out of scope for v1** (documented limitations; `JsonLdError` is thrown where
+detectable):
+
+- **Remote / URL contexts** — contexts must be inlined. A string `@context`
+  throws.
+- Framing and `@reverse` containers, `@index` / `@included` maps, `@nest`,
+  scoped contexts, type-scoped contexts, and JSON-LD 1.1 `@json` / `@direction`.
+- Compaction to a supplied context on serialize — output is always expanded.
+
+These are sufficient for Solid/IndieWeb content negotiation, where documents are
+served with controlled, inlinable contexts. The subset can be widened later
+without changing the public API.
+
+## License
+
+[ISC](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { Quad } from "n3";
+/**
+ * `@dwk/rdf` — thin Turtle/JSON-LD parse and serialize layer over N3.js.
+ *
+ * Cross-standard reusable: plain-data inputs only, no Workers runtime
+ * dependency.
+ *
+ * @see spec/packages/rdf.md
+ */
+export { parseTurtle, writeTurtle, type ParseTurtleOptions, type WriteTurtleOptions, } from "./turtle";
+export { parseJsonLd, writeJsonLd, JsonLdError, type ParseJsonLdOptions, type WriteJsonLdOptions, type JsonValue, type JsonObject, } from "./jsonld";
+export { formatForMediaType, MEDIA_TYPE_FORMATS, type RdfFormat, } from "./media-types";
+export { termToStored, storedToTerm, quadToStored, storedToQuad, type StoredTerm, type StoredQuad, type StoredTermType, } from "./store";
+export type { Quad };
+/** Options for {@link parse} / {@link serialize}. */
+export interface NegotiationOptions {
+    /** Base IRI used to resolve relative IRIs (Turtle family + JSON-LD). */
+    readonly baseIRI?: string;
+    /** Prefixes to declare when serializing the Turtle family. */
+    readonly prefixes?: Record<string, string>;
+}
+/**
+ * Parse an RDF document by media type — the content-negotiation entry point for
+ * `@dwk/solid-pod`. Dispatches to the Turtle family or JSON-LD code path.
+ *
+ * @throws if the media type is not a supported RDF serialization.
+ */
+export declare function parse(input: string, mediaType: string, options?: NegotiationOptions): Promise<Quad[]>;
+/**
+ * Serialize quads by media type — the content-negotiation entry point for
+ * `@dwk/solid-pod`. Dispatches to the Turtle family or JSON-LD code path.
+ *
+ * @throws if the media type is not a supported RDF serialization.
+ */
+export declare function serialize(quads: Quad[], mediaType: string, options?: NegotiationOptions): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,IAAI,EAAE,CAAC;AAErB,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CACzB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,EAAE,CAAC,CASjB;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,CASjB"}

package/dist/index.js

@@ -0,0 +1,48 @@
+import { formatForMediaType } from "./media-types";
+import { parseJsonLd, writeJsonLd } from "./jsonld";
+import { parseTurtle, writeTurtle } from "./turtle";
+/**
+ * `@dwk/rdf` — thin Turtle/JSON-LD parse and serialize layer over N3.js.
+ *
+ * Cross-standard reusable: plain-data inputs only, no Workers runtime
+ * dependency.
+ *
+ * @see spec/packages/rdf.md
+ */
+export { parseTurtle, writeTurtle, } from "./turtle";
+export { parseJsonLd, writeJsonLd, JsonLdError, } from "./jsonld";
+export { formatForMediaType, MEDIA_TYPE_FORMATS, } from "./media-types";
+export { termToStored, storedToTerm, quadToStored, storedToQuad, } from "./store";
+/**
+ * Parse an RDF document by media type — the content-negotiation entry point for
+ * `@dwk/solid-pod`. Dispatches to the Turtle family or JSON-LD code path.
+ *
+ * @throws if the media type is not a supported RDF serialization.
+ */
+export async function parse(input, mediaType, options) {
+    const format = formatForMediaType(mediaType);
+    if (!format) {
+        throw new Error(`@dwk/rdf: unsupported media type "${mediaType}"`);
+    }
+    if (format === "JSON-LD") {
+        return parseJsonLd(input, { base: options?.baseIRI });
+    }
+    return parseTurtle(input, { format, baseIRI: options?.baseIRI });
+}
+/**
+ * Serialize quads by media type — the content-negotiation entry point for
+ * `@dwk/solid-pod`. Dispatches to the Turtle family or JSON-LD code path.
+ *
+ * @throws if the media type is not a supported RDF serialization.
+ */
+export async function serialize(quads, mediaType, options) {
+    const format = formatForMediaType(mediaType);
+    if (!format) {
+        throw new Error(`@dwk/rdf: unsupported media type "${mediaType}"`);
+    }
+    if (format === "JSON-LD") {
+        return writeJsonLd(quads);
+    }
+    return writeTurtle(quads, { format, prefixes: options?.prefixes });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGpD;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,GAGZ,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,GAKZ,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,GAIb,MAAM,SAAS,CAAC;AAYjB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,KAAa,EACb,SAAiB,EACjB,OAA4B;IAE5B,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,SAAS,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,WAAW,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAAa,EACb,SAAiB,EACjB,OAA4B;IAE5B,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,SAAS,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/jsonld.d.ts

@@ -0,0 +1,44 @@
+import type { Quad } from "n3";
+/**
+ * JSON-LD ⇄ RDF for the edge.
+ *
+ * N3.js does not handle JSON-LD, and `jsonld.js` is too large for the Worker
+ * script-size budget. This is a **dependency-free** JSON-LD ↔ quads converter
+ * covering the subset `@dwk/solid-pod` content negotiation needs. See
+ * `spec/open-questions.md` §4 and the README for the exact supported subset and
+ * its known limitations.
+ */
+/** A parsed JSON value. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON object. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** Error raised for malformed or unsupported JSON-LD input. */
+export declare class JsonLdError extends Error {
+    constructor(message: string);
+}
+/** Options for {@link parseJsonLd}. */
+export interface ParseJsonLdOptions {
+    /** Base IRI used to resolve relative `@id` / `@base` references. */
+    readonly base?: string;
+}
+/**
+ * Parse a JSON-LD document (string or already-parsed value) into quads.
+ *
+ * Supports the subset documented in the package README: inline contexts only —
+ * no remote (URL) contexts.
+ */
+export declare function parseJsonLd(input: string | JsonValue, options?: ParseJsonLdOptions): Promise<Quad[]>;
+/** Options for {@link writeJsonLd}. */
+export interface WriteJsonLdOptions {
+    /** `JSON.stringify` indentation width (default `2`). */
+    readonly space?: number;
+}
+/**
+ * Serialize quads into a JSON-LD document string (expanded / flattened form).
+ */
+export declare function writeJsonLd(quads: Quad[], options?: WriteJsonLdOptions): Promise<string>;
+//# sourceMappingURL=jsonld.d.ts.map

package/dist/jsonld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonld.d.ts","sourceRoot":"","sources":["../src/jsonld.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,IAAI,EAIL,MAAM,IAAI,CAAC;AAEZ;;;;;;;;GAQG;AAEH,2BAA2B;AAC3B,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,qBAAqB;AACrB,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,+DAA+D;AAC/D,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AA+hBD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,EAAE,CAAC,CAcjB;AA2LD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAEjB"}