@lde/fastify-rdf 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# Fastify RDF
+
+Fastify plugin for serving RDF data with automatic content negotiation.
+
+## Installation
+
+```bash
+npm install @lde/fastify-rdf
+```
+
+## Features
+
+- Content negotiation for all RDF serialisation formats supported by [rdf-serialize](https://github.com/rubensworks/rdf-serialize.js)
+- Handles `Accept` headers to serve data in the requested RDF format (Turtle, N-Triples, JSON-LD, etc.)
+- Defaults to Turtle when no `Accept` header is provided
+- Provides a `reply.sendRdf()` decorator for explicit RDF responses
+- Optional `overrideSend` mode to automatically serialise all responses as RDF
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import fastify from 'fastify';
+import fastifyRdf from '@lde/fastify-rdf';
+
+const app = fastify();
+await app.register(fastifyRdf);
+```
+
+### Explicit RDF Responses with `reply.sendRdf()`
+
+Use `reply.sendRdf()` to send RDF data with content negotiation:
+
+```typescript
+import { Store, DataFactory } from 'n3';
+
+const { namedNode, literal, quad } = DataFactory;
+
+app.get('/resource', async (request, reply) => {
+  const store = new Store();
+  store.add(
+    quad(
+      namedNode('http://example.org/subject'),
+      namedNode('http://example.org/predicate'),
+      literal('object')
+    )
+  );
+  return reply.sendRdf(store);
+});
+```
+
+### Automatic Serialisation with `overrideSend`
+
+Enable `overrideSend` to automatically serialise all responses as RDF. This is useful for APIs that exclusively serve RDF data:
+
+```typescript
+await app.register(fastifyRdf, {
+  overrideSend: true,
+});
+
+// Simply return DatasetCore or Stream - they will be serialised automatically
+app.get('/resource', async () => {
+  const store = new Store();
+  store.add(
+    quad(
+      namedNode('http://example.org/subject'),
+      namedNode('http://example.org/predicate'),
+      literal('object')
+    )
+  );
+  return store;
+});
+```
+
+### Custom Default Content Type
+
+By default, the plugin uses `text/turtle` when no `Accept` header is provided. You can change this:
+
+```typescript
+await app.register(fastifyRdf, {
+  defaultContentType: 'application/n-triples',
+});
+```
+
+## Content Negotiation
+
+The plugin supports all content types provided by [rdf-serialize](https://github.com/rubensworks/rdf-serialize.js), including:
+
+- `text/turtle` (Turtle)
+- `application/n-triples` (N-Triples)
+- `application/n-quads` (N-Quads)
+- `application/ld+json` (JSON-LD)
+- `application/rdf+xml` (RDF/XML)
+- And more...
+
+Clients can request their preferred format via the `Accept` header:
+
+```bash
+# Request Turtle
+curl -H "Accept: text/turtle" http://localhost:3000/resource
+
+# Request N-Triples
+curl -H "Accept: application/n-triples" http://localhost:3000/resource
+
+# No Accept header - defaults to Turtle
+curl http://localhost:3000/resource
+```
+
+## API
+
+### Plugin Options
+
+```typescript
+interface FastifyRdfOptions {
+  /**
+   * Default content type when no Accept header is provided.
+   * @default 'text/turtle'
+   */
+  defaultContentType?: string;
+
+  /**
+   * Override reply.send() to serialise all responses as RDF.
+   * When enabled, all payloads returned from route handlers will be
+   * serialised as RDF without type checking.
+   * @default false
+   */
+  overrideSend?: boolean;
+}
+```
+
+### Supported Data Types
+
+The plugin accepts the following RDF data types:
+
+- **DatasetCore**: RDF.js dataset (e.g., from n3 `Store`)
+- **Stream**: RDF.js quad stream (e.g., from parsers)
+
+```typescript
+import type { RdfData, FastifyRdfOptions } from '@lde/fastify-rdf';
+```
+
+## TypeScript
+
+The plugin includes full TypeScript support with type augmentation for Fastify's reply object:
+
+```typescript
+// reply.sendRdf() is automatically typed
+app.get('/data', async (request, reply) => {
+  return reply.sendRdf(dataset);
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { fastifyRdf } from './plugin.js';
+export { DEFAULT_CONTENT_TYPE, type FastifyRdfOptions, type RdfData } from './types.js';
+export { fastifyRdf as default } from './plugin.js';
+//# 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":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

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

package/dist/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyInstance } from 'fastify';
+import { type FastifyRdfOptions } from './types.js';
+/**
+ * Fastify plugin for serving RDF data with content negotiation.
+ *
+ * This plugin:
+ * - Adds a reply.sendRdf() decorator for sending RDF data
+ * - 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
+ */
+declare function fastifyRdfPlugin(server: FastifyInstance, options: FastifyRdfOptions): Promise<void>;
+/**
+ * Fastify plugin for serving RDF data with content negotiation.
+ */
+export declare const fastifyRdf: typeof fastifyRdfPlugin;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +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,EAAwB,KAAK,iBAAiB,EAAgB,MAAM,YAAY,CAAC;AA+CxF;;;;;;;;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"}

package/dist/plugin.js

@@ -0,0 +1,88 @@
+import { fastifyPlugin } from 'fastify-plugin';
+import { fastifyAccepts } from '@fastify/accepts';
+import { rdfSerializer } from 'rdf-serialize';
+import { Readable } from 'node:stream';
+import { DEFAULT_CONTENT_TYPE } from './types.js';
+/**
+ * Collect a readable stream into a string.
+ */
+async function streamToString(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Serialize RDF data to a string for the given content type.
+ */
+async function serializeRdfToString(data, contentType) {
+    const stream = typeof data[Symbol.iterator] === 'function'
+        ? Readable.from(data)
+        : data;
+    const outputStream = rdfSerializer.serialize(stream, {
+        contentType,
+    });
+    return streamToString(outputStream);
+}
+/**
+ * Find the best matching content type from supported types based on Accept header.
+ */
+function negotiateContentType(request, supportedTypes, defaultType) {
+    const acceptHeader = request.headers.accept;
+    if (!acceptHeader || acceptHeader === '*/*') {
+        return defaultType;
+    }
+    return (request.accepts().type(supportedTypes) || defaultType);
+}
+/**
+ * Fastify plugin for serving RDF data with content negotiation.
+ *
+ * This plugin:
+ * - Adds a reply.sendRdf() decorator for sending RDF data
+ * - 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
+ */
+async function fastifyRdfPlugin(server, options) {
+    const defaultContentType = options.defaultContentType ?? DEFAULT_CONTENT_TYPE;
+    const supportedContentTypes = await rdfSerializer.getContentTypes();
+    await server.register(fastifyAccepts);
+    if (options.overrideSend) {
+        // Serialize all responses as RDF via hooks
+        server.addHook('preSerialization', async (request, reply, payload) => {
+            const contentType = negotiateContentType(request, supportedContentTypes, defaultContentType);
+            reply.type(contentType);
+            return serializeRdfToString(payload, contentType);
+        });
+        server.addHook('onSend', async (request, reply, payload) => {
+            // Handle streams (preSerialization doesn't run for streams)
+            if (payload !== null && typeof payload !== 'string') {
+                const contentType = negotiateContentType(request, supportedContentTypes, defaultContentType);
+                reply.type(contentType);
+                return serializeRdfToString(payload, contentType);
+            }
+            return payload;
+        });
+        // sendRdf just returns data - hooks handle serialization
+        server.decorateReply('sendRdf', function (data) {
+            return data;
+        });
+    }
+    else {
+        // Manual serialization via sendRdf() only
+        server.decorateReply('sendRdf', async function (data) {
+            const contentType = negotiateContentType(this.request, supportedContentTypes, defaultContentType);
+            this.type(contentType);
+            const serialized = await serializeRdfToString(data, contentType);
+            return this.send(serialized);
+        });
+    }
+}
+/**
+ * Fastify plugin for serving RDF data with content negotiation.
+ */
+export const fastifyRdf = fastifyPlugin(fastifyRdfPlugin, {
+    fastify: '5.x',
+    name: '@lde/fastify-rdf',
+});

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+import type { DatasetCore, Stream } from '@rdfjs/types';
+/**
+ * Default content type when no Accept header is provided.
+ */
+export declare const DEFAULT_CONTENT_TYPE = "text/turtle";
+/**
+ * Options for the fastify-rdf plugin.
+ */
+export interface FastifyRdfOptions {
+    /**
+     * Default content type when no Accept header is provided.
+     * @default 'text/turtle'
+     */
+    defaultContentType?: string;
+    /**
+     * Override reply.send() to serialize all responses as RDF.
+     * When enabled, all payloads returned from route handlers will be
+     * serialized as RDF.
+     * @default false
+     */
+    overrideSend?: boolean;
+}
+/**
+ * RDF data that can be serialized: either a DatasetCore or an RDF.js Stream of quads.
+ */
+export type RdfData = DatasetCore | Stream;
+declare module 'fastify' {
+    interface FastifyReply {
+        /**
+         * Send RDF data with content negotiation based on Accept header.
+         * @param data - RDF DatasetCore or Stream to serialize
+         * @returns The data (when overrideSend is enabled) or Promise<FastifyReply>
+         */
+        sendRdf(data: RdfData): RdfData | Promise<FastifyReply>;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Default content type when no Accept header is provided.
+ */
+export const DEFAULT_CONTENT_TYPE = 'text/turtle';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@lde/fastify-rdf",
+  "version": "0.1.0",
+  "description": "Fastify plugin for serving RDF data with content negotiation",
+  "repository": {
+    "url": "https://github.com/ldengine/lde"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@fastify/accepts": "^5.0.0",
+    "fastify-plugin": "^5.0.0",
+    "rdf-serialize": "^5.0.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@rdfjs/types": "^2.0.0",
+    "fastify": "^5.0.0",
+    "n3": "^1.17.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}