@lde/fastify-rdf 0.2.12 → 0.4.0

package/README.md

@@ -43,8 +43,8 @@ app.get('/resource', async (request, reply) => {
     quad(
       namedNode('http://example.org/subject'),
       namedNode('http://example.org/predicate'),
-      literal('object')
-    )
+      literal('object'),
+    ),
   );
   return reply.sendRdf(store);
 });
@@ -66,13 +66,61 @@ app.get('/resource', async () => {
     quad(
       namedNode('http://example.org/subject'),
       namedNode('http://example.org/predicate'),
-      literal('object')
-    )
+      literal('object'),
+    ),
   );
   return store;
 });
 ```
 
+### Parsing RDF Request Bodies
+
+The plugin registers content type parsers for all RDF formats supported by [rdf-parse](https://github.com/rubensworks/rdf-parse.js). Individual routes opt in via `config: { parseRdf: true }` — the body is then parsed into a `DatasetCore`:
+
+```typescript
+app.post('/data', { config: { parseRdf: true } }, async (request) => {
+  const dataset = request.body as DatasetCore; // N3 Store
+  console.log(`Received ${dataset.size} quads`);
+});
+```
+
+To parse RDF bodies on **all** routes, enable `parseRdf` at the plugin level:
+
+```typescript
+await app.register(fastifyRdf, { parseRdf: true });
+```
+
+Routes without per-route or plugin-level `parseRdf` get JSON fallback for `application/ld+json` (parsed as plain JSON) and 415 Unsupported Media Type for other RDF content types.
+
+### Hydra Error Responses with `reply.sendHydraError()`
+
+Send [Hydra](https://www.hydra-cg.com/spec/latest/core/) error responses with content negotiation. This maps `error.message` to `hydra:title` and `error.cause` (when it is a string) to `hydra:description`:
+
+```typescript
+app.get('/resource', async (request, reply) => {
+  const error = new Error('Not Found', {
+    cause: 'The requested dataset was not found',
+  }) as Error & { statusCode: number };
+  error.statusCode = 404;
+  return reply.sendHydraError(error);
+});
+```
+
+The status code is taken from `error.statusCode` (standard in Fastify and http-errors), defaulting to 500.
+
+For `Accept: application/ld+json`, the response is compact JSON-LD — no `jsonld` dependency needed:
+
+```json
+{
+  "@context": "http://www.w3.org/ns/hydra/core#",
+  "@type": "Error",
+  "title": "Not Found",
+  "description": "The requested dataset was not found"
+}
+```
+
+For all other RDF formats (Turtle, N-Triples, etc.), the error is serialised through the standard RDF pipeline.
+
 ### Custom Default Content Type
 
 By default, the plugin uses `text/turtle` when no `Accept` header is provided. You can change this:
@@ -126,6 +174,12 @@ interface FastifyRdfOptions {
    * @default false
    */
   overrideSend?: boolean;
+
+  /**
+   * Parse RDF request bodies into a DatasetCore on all routes.
+   * @default false
+   */
+  parseRdf?: boolean;
 }
 ```
 

package/dist/hydra-error.d.ts

@@ -0,0 +1,10 @@
+import { Store } from 'n3';
+/**
+ * Serialize a Hydra error as compact JSON-LD without needing the `jsonld` dependency.
+ */
+export declare function serializeHydraErrorAsJsonLd(title: string, description?: string): string;
+/**
+ * Create an N3 Store with Hydra error triples.
+ */
+export declare function createHydraErrorDataset(title: string, description?: string): Store;
+//# sourceMappingURL=hydra-error.d.ts.map

package/dist/hydra-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydra-error.d.ts","sourceRoot":"","sources":["../src/hydra-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,EAAE,MAAM,IAAI,CAAC;AAWxC;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,KAAK,CAWP"}

package/dist/hydra-error.js

@@ -0,0 +1,33 @@
+import { DataFactory, Store } from 'n3';
+const { namedNode, blankNode, literal } = DataFactory;
+const RDF_TYPE = namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');
+const HYDRA_ERROR = namedNode('http://www.w3.org/ns/hydra/core#Error');
+const HYDRA_TITLE = namedNode('http://www.w3.org/ns/hydra/core#title');
+const HYDRA_DESCRIPTION = namedNode('http://www.w3.org/ns/hydra/core#description');
+/**
+ * Serialize a Hydra error as compact JSON-LD without needing the `jsonld` dependency.
+ */
+export function serializeHydraErrorAsJsonLd(title, description) {
+    const obj = {
+        '@context': 'http://www.w3.org/ns/hydra/core#',
+        '@type': 'Error',
+        title,
+    };
+    if (description !== undefined) {
+        obj['description'] = description;
+    }
+    return JSON.stringify(obj);
+}
+/**
+ * Create an N3 Store with Hydra error triples.
+ */
+export function createHydraErrorDataset(title, description) {
+    const store = new Store();
+    const subject = blankNode();
+    store.add(DataFactory.quad(subject, RDF_TYPE, HYDRA_ERROR));
+    store.add(DataFactory.quad(subject, HYDRA_TITLE, literal(title)));
+    if (description !== undefined) {
+        store.add(DataFactory.quad(subject, HYDRA_DESCRIPTION, literal(description)));
+    }
+    return store;
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { fastifyRdf } from './plugin.js';
 export { DEFAULT_CONTENT_TYPE, type FastifyRdfOptions, type RdfData, } from './types.js';
+export { createHydraErrorDataset } from './hydra-error.js';
 export { fastifyRdf as default } from './plugin.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { fastifyRdf } from './plugin.js';
 export { DEFAULT_CONTENT_TYPE, } from './types.js';
+export { createHydraErrorDataset } from './hydra-error.js';
 export { fastifyRdf as default } from './plugin.js';

package/dist/plugin.d.ts

@@ -8,6 +8,7 @@ import { type FastifyRdfOptions } from './types.js';
  * - Optionally overrides reply.send() to serialize all responses as RDF
  * - Handles content negotiation via Accept headers
  * - Defaults to Turtle when no Accept header is provided
+ * - Registers content type parsers for RDF request bodies
  */
 declare function fastifyRdfPlugin(server: FastifyInstance, options: FastifyRdfOptions): Promise<void>;
 /**

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAM7E,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AA+CpB;;;;;;;;GAQG;AACH,iBAAe,gBAAgB,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA0Df;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,yBAGrB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAQ7E,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AAgIpB;;;;;;;;;GASG;AACH,iBAAe,gBAAgB,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqFf;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,yBAGrB,CAAC"}

package/dist/plugin.js

@@ -1,8 +1,11 @@
 import { fastifyPlugin } from 'fastify-plugin';
 import { fastifyAccepts } from '@fastify/accepts';
 import { rdfSerializer } from 'rdf-serialize';
+import { rdfParser } from 'rdf-parse';
+import { Store } from 'n3';
 import { Readable } from 'node:stream';
 import { DEFAULT_CONTENT_TYPE, } from './types.js';
+import { serializeHydraErrorAsJsonLd, createHydraErrorDataset, } from './hydra-error.js';
 /**
  * Collect a readable stream into a string.
  */
@@ -35,6 +38,69 @@ function negotiateContentType(request, supportedTypes, defaultType) {
     }
     return (request.accepts().type(supportedTypes) || defaultType);
 }
+/**
+ * Collect quads from a readable stream into an N3 Store.
+ */
+async function streamToDataset(stream) {
+    const store = new Store();
+    for await (const quad of stream) {
+        store.add(quad);
+    }
+    return store;
+}
+/**
+ * Register Fastify content type parsers for all RDF formats.
+ *
+ * When `parseAll` is true (from the plugin-level `parseRdf` option), every
+ * route gets RDF body parsing. Otherwise, routes opt in individually via
+ * `config: { parseRdf: true }`. Non-opted-in routes get JSON fallback for
+ * `application/ld+json` and 415 for other RDF types.
+ */
+async function registerRdfParsers(server, parseAll) {
+    const contentTypes = (await rdfParser.getContentTypes()).filter((type) => type !== 'application/json');
+    server.addContentTypeParser(contentTypes, function (_request, payload, done) {
+        // Collect the raw body; the preParsing hook is not needed because
+        // Fastify passes the raw payload stream here.
+        const chunks = [];
+        payload.on('data', (chunk) => chunks.push(chunk));
+        payload.on('end', () => done(null, Buffer.concat(chunks)));
+        payload.on('error', done);
+    });
+    server.addHook('preHandler', async (request) => {
+        // Only act on requests that matched an RDF content type parser.
+        if (!request.body ||
+            !Buffer.isBuffer(request.body) ||
+            !request.headers['content-type']) {
+            return;
+        }
+        const contentType = request.headers['content-type'].split(';')[0].trim();
+        if (!contentTypes.includes(contentType)) {
+            return;
+        }
+        if (parseAll || request.routeOptions.config.parseRdf) {
+            try {
+                const bodyStream = Readable.from(request.body);
+                const quadStream = rdfParser.parse(bodyStream, { contentType });
+                request.body = await streamToDataset(quadStream);
+            }
+            catch (cause) {
+                const error = new Error('Invalid RDF body', {
+                    cause,
+                });
+                error.statusCode = 400;
+                throw error;
+            }
+        }
+        else if (contentType === 'application/ld+json') {
+            request.body = JSON.parse(request.body.toString('utf8'));
+        }
+        else {
+            const error = new Error(`Unsupported Media Type: ${contentType}`);
+            error.statusCode = 415;
+            throw error;
+        }
+    });
+}
 /**
  * Fastify plugin for serving RDF data with content negotiation.
  *
@@ -43,6 +109,7 @@ function negotiateContentType(request, supportedTypes, defaultType) {
  * - Optionally overrides reply.send() to serialize all responses as RDF
  * - Handles content negotiation via Accept headers
  * - Defaults to Turtle when no Accept header is provided
+ * - Registers content type parsers for RDF request bodies
  */
 async function fastifyRdfPlugin(server, options) {
     const defaultContentType = options.defaultContentType ?? DEFAULT_CONTENT_TYPE;
@@ -78,6 +145,20 @@ async function fastifyRdfPlugin(server, options) {
             return this.send(serialized);
         });
     }
+    server.decorateReply('sendHydraError', async function (error) {
+        this.status(error.statusCode ?? 500);
+        const title = error.message;
+        const description = typeof error.cause === 'string' ? error.cause : undefined;
+        const contentType = negotiateContentType(this.request, supportedContentTypes, defaultContentType);
+        if (contentType === 'application/ld+json') {
+            this.type('application/ld+json');
+            return this.send(serializeHydraErrorAsJsonLd(title, description));
+        }
+        const dataset = createHydraErrorDataset(title, description);
+        this.type(contentType);
+        return this.send(await serializeRdfToString(dataset, contentType));
+    });
+    await registerRdfParsers(server, options.parseRdf ?? false);
 }
 /**
  * Fastify plugin for serving RDF data with content negotiation.

package/dist/types.d.ts

@@ -19,6 +19,12 @@ export interface FastifyRdfOptions {
      * @default false
      */
     overrideSend?: boolean;
+    /**
+     * Parse RDF request bodies into a DatasetCore on all routes.
+     * When not set, individual routes can opt in via `config: { parseRdf: true }`.
+     * @default false
+     */
+    parseRdf?: boolean;
 }
 /**
  * RDF data that can be serialized: either a DatasetCore or an RDF.js Stream of quads.
@@ -32,6 +38,17 @@ declare module 'fastify' {
          * @returns The data (when overrideSend is enabled) or Promise<FastifyReply>
          */
         sendRdf(data: RdfData): RdfData | Promise<FastifyReply>;
+        /**
+         * Send a Hydra error response with content negotiation.
+         * Uses `error.message` as `hydra:title` and `error.cause` (if a string) as `hydra:description`.
+         * Status code defaults to `error.statusCode` or 500.
+         */
+        sendHydraError(error: Error & {
+            statusCode?: number;
+        }): Promise<FastifyReply>;
+    }
+    interface FastifyContextConfig {
+        parseRdf?: boolean;
     }
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAE3C,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,YAAY;QACpB;;;;WAIG;QACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;KACzD;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAE3C,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,YAAY;QACpB;;;;WAIG;QACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAExD;;;;WAIG;QACH,cAAc,CACZ,KAAK,EAAE,KAAK,GAAG;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,GACrC,OAAO,CAAC,YAAY,CAAC,CAAC;KAC1B;IAED,UAAU,oBAAoB;QAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB;CACF"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@lde/fastify-rdf",
-  "version": "0.2.12",
+  "version": "0.4.0",
   "description": "Fastify plugin for serving RDF data with content negotiation",
   "repository": {
-    "url": "https://github.com/ldengine/lde",
+    "url": "git+https://github.com/ldengine/lde.git",
     "directory": "packages/fastify-rdf"
   },
   "type": "module",
@@ -26,13 +26,14 @@
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
     "fastify-plugin": "^5.0.0",
+    "n3": "^2.0.1",
+    "rdf-parse": "^5.0.0",
     "rdf-serialize": "^5.1.0",
     "tslib": "^2.3.0"
   },
   "devDependencies": {
     "@rdfjs/types": "^2.0.0",
-    "fastify": "^5.7.4",
-    "n3": "^1.17.0"
+    "fastify": "^5.7.4"
   },
   "peerDependencies": {
     "fastify": "^5.7.4"