@dwk/rdf 0.1.0-beta.0

package/src/media-types.ts

@@ -0,0 +1,36 @@
+/**
+ * RDF media-type registry for content negotiation. Maps the RDF serializations
+ * `@dwk/solid-pod` negotiates over to the internal format identifier used by
+ * the Turtle ({@link ./turtle}) and JSON-LD ({@link ./jsonld}) code paths.
+ */
+
+/** Serialization formats this package can parse and write. */
+export type RdfFormat = "Turtle" | "TriG" | "N-Triples" | "N-Quads" | "JSON-LD";
+
+/**
+ * Canonical media type → format. Keys are lowercase essence (no parameters).
+ *
+ * Note `application/json` is deliberately **not** an RDF type here: JSON-LD's
+ * media type is `application/ld+json`, and treating arbitrary `application/json`
+ * bodies as a graph would let non-RDF JSON be misparsed on write/PATCH. A
+ * read-only `application/json` → JSON-LD convenience can be opted into at the
+ * content-negotiation layer instead (see `@dwk/solid-pod` negotiation).
+ */
+export const MEDIA_TYPE_FORMATS: Readonly<Record<string, RdfFormat>> = {
+  "text/turtle": "Turtle",
+  "application/trig": "TriG",
+  "application/n-triples": "N-Triples",
+  "application/n-quads": "N-Quads",
+  "application/ld+json": "JSON-LD",
+};
+
+/**
+ * Resolve a media type (with optional parameters / charset, any casing) to its
+ * RDF format, or `undefined` when the media type is not an RDF serialization.
+ */
+export function formatForMediaType(mediaType: string): RdfFormat | undefined {
+  // Guard against a missing Content-Type header passed straight through.
+  if (typeof mediaType !== "string") return undefined;
+  const essence = mediaType.split(";")[0]?.trim().toLowerCase();
+  return essence ? MEDIA_TYPE_FORMATS[essence] : undefined;
+}

package/src/store.ts

@@ -0,0 +1,106 @@
+import { DataFactory } from "n3";
+import type { Quad, Quad_Graph, Quad_Object, Term } from "n3";
+
+/**
+ * Triple ↔ store helpers.
+ *
+ * The quad store in `@dwk/store` (DO-SQLite) and `@dwk/solid-pod` content
+ * negotiation need a flat, JSON-serializable representation of RDF terms that
+ * maps cleanly onto SQLite columns and survives a structured-clone boundary.
+ * These helpers convert between N3.js / RDF-JS {@link Quad}s and that
+ * representation without pulling in any storage backend.
+ */
+
+/** RDF term kinds representable in the store. */
+export type StoredTermType =
+  | "NamedNode"
+  | "BlankNode"
+  | "Literal"
+  | "DefaultGraph";
+
+/** Flat, JSON-serializable representation of a single RDF term. */
+export interface StoredTerm {
+  readonly termType: StoredTermType;
+  /** Lexical value: IRI, blank-node label, literal value, or `""` for the default graph. */
+  readonly value: string;
+  /** Literals only: the datatype IRI (omitted for `rdf:langString`). */
+  readonly datatype?: string;
+  /** Language-tagged literals only: the BCP-47 language tag. */
+  readonly language?: string;
+}
+
+/** Flat, JSON-serializable representation of a single quad. */
+export interface StoredQuad {
+  readonly subject: StoredTerm;
+  readonly predicate: StoredTerm;
+  readonly object: StoredTerm;
+  readonly graph: StoredTerm;
+}
+
+const XSD_STRING = "http://www.w3.org/2001/XMLSchema#string";
+
+/** Convert an RDF term into its flat store representation. */
+export function termToStored(term: Term): StoredTerm {
+  switch (term.termType) {
+    case "NamedNode":
+      return { termType: "NamedNode", value: term.value };
+    case "BlankNode":
+      return { termType: "BlankNode", value: term.value };
+    case "DefaultGraph":
+      return { termType: "DefaultGraph", value: "" };
+    case "Literal":
+      return term.language
+        ? { termType: "Literal", value: term.value, language: term.language }
+        : {
+            termType: "Literal",
+            value: term.value,
+            datatype: term.datatype.value,
+          };
+    default:
+      throw new Error(`@dwk/rdf: cannot store term of type "${term.termType}"`);
+  }
+}
+
+/** Reconstruct an RDF term from its flat store representation. */
+export function storedToTerm(stored: StoredTerm): Term {
+  switch (stored.termType) {
+    case "NamedNode":
+      return DataFactory.namedNode(stored.value);
+    case "BlankNode":
+      return DataFactory.blankNode(stored.value);
+    case "DefaultGraph":
+      return DataFactory.defaultGraph();
+    case "Literal":
+      if (stored.language) {
+        return DataFactory.literal(stored.value, stored.language);
+      }
+      return DataFactory.literal(
+        stored.value,
+        DataFactory.namedNode(stored.datatype ?? XSD_STRING),
+      );
+    default:
+      throw new Error(
+        `@dwk/rdf: unknown stored term type "${String(stored.termType)}"`,
+      );
+  }
+}
+
+/** Convert a quad into its flat store representation. */
+export function quadToStored(quad: Quad): StoredQuad {
+  return {
+    subject: termToStored(quad.subject),
+    predicate: termToStored(quad.predicate),
+    object: termToStored(quad.object),
+    graph: termToStored(quad.graph),
+  };
+}
+
+/** Reconstruct a quad from its flat store representation. */
+export function storedToQuad(stored: StoredQuad): Quad {
+  return DataFactory.quad(
+    storedToTerm(stored.subject) as Quad["subject"],
+    DataFactory.namedNode(stored.predicate.value),
+    storedToTerm(stored.object) as Quad_Object,
+    storedToTerm(stored.graph) as Quad_Graph,
+  );
+}

package/src/turtle.ts

@@ -0,0 +1,55 @@
+import { Parser, Writer } from "n3";
+import type { Quad } from "n3";
+
+/**
+ * Turtle-family (Turtle / TriG / N-Triples / N-Quads) parse and serialize over
+ * N3.js. Plain-data inputs only — no Workers-runtime dependency.
+ */
+
+/** Options for {@link parseTurtle}. */
+export interface ParseTurtleOptions {
+  /**
+   * N3.js format hint (e.g. `"Turtle"`, `"TriG"`, `"N-Triples"`, `"N-Quads"`).
+   * When omitted, N3.js sniffs the format and defaults to Turtle/TriG.
+   */
+  readonly format?: string;
+  /** Base IRI used to resolve relative IRIs in the document. */
+  readonly baseIRI?: string;
+}
+
+/** Parse a Turtle (or N-Triples / N-Quads / TriG) document into quads. */
+export function parseTurtle(
+  input: string,
+  options?: ParseTurtleOptions,
+): Quad[] {
+  return new Parser({
+    format: options?.format,
+    baseIRI: options?.baseIRI,
+  }).parse(input);
+}
+
+/** Options for {@link writeTurtle}. */
+export interface WriteTurtleOptions {
+  /**
+   * N3.js output format (e.g. `"Turtle"`, `"TriG"`, `"N-Triples"`,
+   * `"N-Quads"`). Defaults to Turtle/TriG.
+   */
+  readonly format?: string;
+  /** Prefixes to declare in the serialized output. */
+  readonly prefixes?: Record<string, string>;
+}
+
+/** Serialize quads back into a Turtle-family document. */
+export function writeTurtle(
+  quads: Quad[],
+  options?: WriteTurtleOptions,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const writer = new Writer({
+      format: options?.format,
+      prefixes: options?.prefixes,
+    });
+    writer.addQuads(quads);
+    writer.end((error, result) => (error ? reject(error) : resolve(result)));
+  });
+}