@lde/fastify-rdf 0.3.0 → 0.4.1

package/README.md

@@ -92,6 +92,35 @@ 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:

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.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;AAQ7E,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AA4HpB;;;;;;;;;GASG;AACH,iBAAe,gBAAgB,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA4Df;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;AAwIpB;;;;;;;;;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

@@ -5,6 +5,7 @@ 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.
  */
@@ -57,45 +58,53 @@ async function streamToDataset(stream) {
  */
 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 jsonLdType = 'application/ld+json';
+    // JSON-LD is JSON.parse'd eagerly so the body is a plain object when
+    // Fastify runs preValidation (schema checks happen before preHandler).
+    // Other RDF types are stored as a raw Buffer for the preHandler hook.
+    server.addContentTypeParser(contentTypes, function (request, payload, done) {
+        const isJsonLd = request.headers['content-type']?.split(';')[0].trim() === jsonLdType;
         const chunks = [];
         payload.on('data', (chunk) => chunks.push(chunk));
-        payload.on('end', () => done(null, Buffer.concat(chunks)));
+        payload.on('end', () => {
+            if (!isJsonLd)
+                return done(null, Buffer.concat(chunks));
+            try {
+                done(null, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            }
+            catch (err) {
+                done(err);
+            }
+        });
         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']) {
+        if (!request.body || !request.headers['content-type'])
             return;
-        }
         const contentType = request.headers['content-type'].split(';')[0].trim();
-        if (!contentTypes.includes(contentType)) {
+        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;
+        if (!(parseAll || request.routeOptions.config.parseRdf)) {
+            // Not a parseRdf route: JSON-LD is already parsed; reject other RDF.
+            if (contentType !== jsonLdType) {
+                const error = new Error(`Unsupported Media Type: ${contentType}`);
+                error.statusCode = 415;
                 throw error;
             }
+            return;
         }
-        else if (contentType === 'application/ld+json') {
-            request.body = JSON.parse(request.body.toString('utf8'));
+        try {
+            // JSON-LD body is already an object; re-stringify for rdf-parse.
+            const raw = Buffer.isBuffer(request.body)
+                ? request.body
+                : Buffer.from(JSON.stringify(request.body));
+            request.body = await streamToDataset(rdfParser.parse(Readable.from(raw), { contentType }));
         }
-        else {
-            const error = new Error(`Unsupported Media Type: ${contentType}`);
-            error.statusCode = 415;
+        catch (cause) {
+            const error = new Error('Invalid RDF body', {
+                cause,
+            });
+            error.statusCode = 400;
             throw error;
         }
     });
@@ -144,6 +153,19 @@ 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);
 }
 /**

package/dist/types.d.ts

@@ -38,6 +38,14 @@ 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;

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;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;KACzD;IAED,UAAU,oBAAoB;QAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB;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,6 +1,6 @@
 {
   "name": "@lde/fastify-rdf",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Fastify plugin for serving RDF data with content negotiation",
   "repository": {
     "url": "git+https://github.com/ldengine/lde.git",