node-turbo 1.0.0

package/lib/errors/index.js

@@ -0,0 +1,36 @@
+/** @module node-turbo/errors */
+
+/**
+ * Parent class for all validation errors.
+ * 
+ * @extends {node:Error}
+ * @since 1.0.0
+ */
+export class ValidationError extends Error {}
+
+
+/**
+ * Gets thrown when mandatory attributes are missing.
+ * 
+ * @extends {ValidationError}
+ * @since 1.0.0
+ */
+export class AttributeMissingError extends ValidationError {}
+
+
+/**
+ * Gets thrown when mandatory attributes are malformed.
+ * 
+ * @extends {ValidationError}
+ * @since 1.0.0
+ */
+export class AttributeMalformedError extends ValidationError {}
+
+
+/**
+ * Gets thrown when invalid attributes are discovered.
+ * 
+ * @extends {ValidationError}
+ * @since 1.0.0
+ */
+export class AttributeInvalidError extends ValidationError {}

package/lib/express/express-turbo-stream.js

@@ -0,0 +1,41 @@
+
+import { TurboStream } from '#core';
+
+
+/**
+ * This class represents a Turbo Stream message for Express.
+ * Introduces the function `send()` to send the rendered message
+ * as HTTP response with the correct MIME type.
+ * 
+ * @extends {TurboStream}
+ * @since 1.0.0
+ */
+export class ExpressTurboStream extends TurboStream {
+	
+	/**
+	 * Express' response object to send to.
+	 * 
+	 * @type {Object}
+	 */
+	res;
+
+	/**
+	 * Stores Express' response object and creates a `TurboStream` instance.
+	 * 
+	 * @param {Object} res - Express' response object to send to.
+	 * @param {Object} [attributes] - Attributes of the added element.
+	 * @param {String} [content] - The HTML content of the added element.
+	 */
+	constructor(res, ...args) {
+		super(...args);
+		this.res = res;
+	}
+
+	/**
+	 * Sends the rendered message as HTTP response with the correct MIME type.
+	 */
+	send() {
+		this.res.type(TurboStream.MIME_TYPE);
+		this.res.send(this.render());
+	}
+}

package/lib/express/index.js

@@ -0,0 +1,4 @@
+/** @module node-turbo/express */
+
+export * from './express-turbo-stream.js';
+export * from './turbocharge-express.js';

package/lib/express/turbocharge-express.js

@@ -0,0 +1,108 @@
+
+import { TurboStream, TurboFrame, isTurboStreamRequest, isTurboFrameRequest, getTurboFrameId } from '#core';
+import { ExpressTurboStream } from '#express';
+import { SseTurboStream } from '#sse';
+
+
+/**
+ * Default options.
+ * 
+ * @type {Object}
+ * @property {boolean} autoRender - Should the Turbo Frame be automatically sent as HTTP response? Default: true 
+ */
+const defaultOptions = {
+	autoSend: true
+};
+
+
+/**
+ * Adds the following functions to Express' request object:
+ *
+ * - `isTurboStreamRequest()`  
+ *   Checks if the request is a Turbo Stream request by looking for the MIME type in the `accept` headers.  
+ *   Returns `true`/`false`.
+ * - `isTurboFrameRequest()`  
+ *   Checks if the request is a Turbo Frame request by looking for the `turbo-frame` header.  
+ *   Returns `true`/`false`.
+ * - `getTurboFrameId()`
+ *   Returns the contents of the `turbo-frame` header.
+ * 
+ * Also adds the following functions to Express' `response` object:
+ * 
+ * - `turboStream()`  
+ *   Returns a chainable Turbo Stream instance which introduces the function `send()` which sends the rendered Turbo Stream message as HTTP response with the correct MIME type.
+ * - `turboFrame(id, content)`
+ *   Returns a Turbo Frame instance which directly sends the rendered Turbo Frame message as HTTP response.
+ * - `turboFrame(content)`
+ *   If you omit the `id` attribute, it is automatically added by using the ID from the `turbo-frame` header.
+ * - `sseTurboStream()`  
+ *   *Experimental*. Configures Express to keep the connection open and use a stream to pipe to `res`.
+ * 
+ * @param {Object} expressApp - The Express application object.
+ * @param {Object} opts - The options to override.
+ * @since 1.0.0
+ */
+export function turbochargeExpress(expressApp, opts) {
+
+	opts = Object.assign({}, defaultOptions, opts);
+
+	expressApp.request.isTurboStreamRequest = function() {
+		return isTurboStreamRequest(this);
+	}
+
+	expressApp.request.isTurboFrameRequest = function() {
+		return isTurboFrameRequest(this);
+	}
+
+	expressApp.request.getTurboFrameId = function() {
+		return getTurboFrameId(this);
+	}
+
+	expressApp.response.turboFrame = function(...args) {
+		let 
+			idOrAttributes,
+			content;
+
+		// Just the content.
+		if (args.length === 1 && typeof args[0] === 'string') {
+			idOrAttributes = this.req.getTurboFrameId();
+			content = args[0];
+		}
+		else if (args.length === 2) {
+			idOrAttributes = args[0];
+			content = args[1];
+		}
+
+		const tf = new TurboFrame(idOrAttributes, content);
+
+		if (opts.autoSend === true) {
+			this.send(tf.render());
+			return tf;
+		}
+		else {
+			return tf.render();
+		}			
+	}
+
+	expressApp.response.turboStream = function(attributes, content) {
+		return new ExpressTurboStream(this, ...arguments);
+	}
+
+	expressApp.response.sseTurboStream = function() {
+
+		this.set({
+			'Content-Type': SseTurboStream.MIME_TYPE,
+			'Cache-Control': 'no-cache',
+			'Connection': 'keep-alive'
+		});
+
+		this.flushHeaders();
+
+		const ssets = new SseTurboStream(); 
+		const stream = ssets.createReadableStream();
+		stream.pipe(this);
+
+		return ssets;
+	}
+
+}

package/lib/index.js

@@ -0,0 +1,8 @@
+/** @module node-turbo */
+
+export { TurboElement } from './turbo-element.js';
+export { TurboStreamElement } from './turbo-stream-element.js';
+export { TurboStream } from './turbo-stream.js';
+export { TurboFrame } from './turbo-frame.js';
+export * from './request-helpers.js';
+export * from './turbo-readable.js';

package/lib/koa/index.js

@@ -0,0 +1,4 @@
+/** @module node-turbo/koa */
+
+export * from './koa-turbo-stream.js';
+export * from './turbocharge-koa.js';

package/lib/koa/koa-turbo-stream.js

@@ -0,0 +1,44 @@
+
+import { TurboStream } from '#core';
+
+
+/**
+ * This class represents a Turbo Stream message with added functionality 
+ * for Koa. Renders directly to Koa's `ctx.body` whenever a Turbo Stream
+ * element gets added.
+ * 
+ * @extends {TurboStream}
+ * @since 1.0.0
+ */
+export class KoaTurboStream extends TurboStream {
+
+	/**
+	 * Koa's context object.
+	 * 
+	 * @type {Object}
+	 * @see https://koajs.com/#context 
+	 */
+	koaCtx;
+
+
+	/**
+	 * @param {Object} koaCtx - Koa's context object.
+	 */
+	constructor(koaCtx) {
+		super();
+		this.updateConfig({ buffer: false });
+
+		this.koaCtx = koaCtx;
+		this.koaCtx.type = TurboStream.MIME_TYPE;
+		this.koaCtx.status = 200;
+
+		if (typeof this.koaCtx.body !== 'string') {
+			this.koaCtx.body = '';	
+		}
+
+		this.on('element', el => {
+			this.koaCtx.body += el.render() + '\n';
+		});
+	}
+
+}

package/lib/koa/turbocharge-koa.js

@@ -0,0 +1,122 @@
+
+import { TurboStream, TurboFrame, isTurboStreamRequest, isTurboFrameRequest, getTurboFrameId } from '#core';
+import { KoaTurboStream } from '#koa';
+import { SseTurboStream } from '#sse';
+import { PassThrough } from 'node:stream';
+
+/**
+ * Default options.
+ * 
+ * @type {Object} 
+ * @property {Boolean} autoRender - Should elements directly render to ctx.body?  (Default: `true`)
+ */
+const defaultOptions = {
+	autoRender: true
+};
+
+
+/**
+ * Adds the following functions to Koa's context object:
+ * 
+ * - `turboStream()`  
+ *   Returns a chainable Turbo Stream instance which directly writes to `ctx.body` whenever an element is added. Also sets the correct `Content-Type` header.
+ * - `turboFrame()`  
+ *   Returns a Turbo Frame instance which directly writes to `ctx.body`. 
+ * - `isTurboStreamRequest()`  
+ *   Checks if the request is a Turbo Stream request by looking for the MIME type in the `accept` headers.  
+ *   Returns `true`/`false`.
+ * - `isTurboFrameRequest()`  
+ *   Checks if the request is a Turbo Frame request by looking for the `turbo-frame` header.  
+ *   Returns `true`/`false`.
+ * - `getTurboFrameId()`  
+ *   Returns the contents of the `turbo-frame` header.
+ * - `sseTurboStream()`  
+ *   *Experimental*. Configures Koa to keep the connection open and use a stream to pipe to `ctx.res`.  
+ * 
+ * @param {Object} koaApp - The Koa application object.
+ * @param {Object} opts - The options.
+ * @param {Boolean} opts.autoRender - Should Turbo Stream elements automatically be rendered and sent? (Default: `true`)
+ * @since 1.0.0
+ */
+export function turbochargeKoa(koaApp, opts = {}) {
+
+	opts = Object.assign({}, defaultOptions, opts);
+
+	koaApp.context = Object.assign(koaApp.context, {
+
+		getTurboFrameId: function() {
+			return getTurboFrameId(this.req);
+		},
+
+
+		isTurboFrameRequest: function() {
+			return isTurboFrameRequest(this.req);
+		},
+
+
+		isTurboStreamRequest: function() {
+			return isTurboStreamRequest(this.req);
+		},
+
+
+		turboFrame: function(idOrAttributes, content) {
+			// Just the content.
+			if (arguments.length === 1 && typeof idOrAttributes === 'string') {
+				content = idOrAttributes;
+				idOrAttributes = this.getTurboFrameId();
+			}
+
+			const tf = new TurboFrame(idOrAttributes, content);
+
+			if (opts.autoRender === true) {
+				this.status = 200;
+				this.type = TurboFrame.MIME_TYPE;
+				this.body = tf.render();
+			}
+			else {
+				return tf.render();
+			}			
+		},
+
+		turboStream: function(...args) {
+			if (opts.autoRender === true) {
+				const kts = new KoaTurboStream(this);
+				return kts;
+			}
+			else {
+				return new TurboStream(...args);
+			}
+		},
+
+
+		/**
+		 * @since 1.0
+		 * @inner 
+		 * @experimental
+		 */
+		sseTurboStream: function() {
+			// Disable koa-compress.
+			// @todo Adjust compression for SSE.
+			this.compress = false;
+
+			// Set connection to keep-alive.
+			this.set({
+				'Content-Type': SseTurboStream.MIME_TYPE,
+				'Cache-Control': 'no-cache',
+				'Connection': 'keep-alive'
+			});
+
+			// this.response.flushHeaders();
+
+			const 
+				ssets = new SseTurboStream(),
+				readable = ssets.createReadableStream();
+
+			this.status = 200;
+			this.body = readable;
+
+			return ssets;
+		}
+
+	});
+}

package/lib/request-helpers.js

@@ -0,0 +1,53 @@
+
+import { IncomingMessage } from 'node:http';
+import Negotiator from 'negotiator';
+import { TurboStream, TurboFrame } from '#core';
+
+/**
+ * Checks if the request is a Turbo Stream request.
+ * 
+ * @param {Object} request - The request object. Expects an object like an {http.ClientRequest} instance.
+ * @returns {Boolean} `true`, if the request has been identified as a Turbo Stream request. `false` otherwise.
+ * @since 1.0.0
+ */
+export function isTurboStreamRequest(request) {
+	if (request?.headers?.accept) {
+		const negotiator = new Negotiator(request);
+		return negotiator.mediaTypes().includes(TurboStream.MIME_TYPE);
+	}
+
+	return false;
+}
+
+
+/**
+ * Checks if the request is a Turbo Frame request.
+ * 
+ * @param {Object} request - The request object. Expects an object like an {http.ClientRequest} instance.
+ * @returns {Boolean} `true`, if the request has been identified as a Turbo Frame request. false otherwise.
+ * @since 1.0.0
+ */
+export function isTurboFrameRequest(request) {
+	if (request?.headers) {
+		return (typeof request.headers[TurboFrame.HEADER_KEY] !== 'undefined');	
+	}
+
+	return false;	
+}
+
+
+/**
+ * Returns the content of the 'turbo-frame' header, which is the ID of the requesting Turbo 
+ * Frame.
+ *
+ * @param {Object} request - The request object. Expects an object like an {http.ClientRequest} instance.
+ * @returns {String|null} The Turbo Frame ID or `null` if not found.
+ * @since 1.0.0
+ */
+export function getTurboFrameId(request) {
+	if (request?.headers) {
+		return request.headers[TurboFrame.HEADER_KEY];
+	}
+
+	return null;
+}

package/lib/sse/index.js

@@ -0,0 +1,3 @@
+/** @module turbo-node/sse */
+
+export * from './sse-turbo-stream.js';

package/lib/sse/sse-turbo-stream.js

@@ -0,0 +1,137 @@
+
+import { TurboStream, TurboReadable } from '#core';
+import { Writable, Transform } from 'node:stream';
+import db from 'debug';
+const debug = db('node-turbo:sse');
+
+
+/**
+ * This class represents a Turbo Stream message for SSE.  
+ * **Note**: This class is in __experimental__ stage.
+ * 
+ * @experimental
+ * @extends {TurboStream}
+ * @since 1.0.0
+ */
+export class SseTurboStream extends TurboStream {
+	
+	/**
+	 * MIME type for an SSE message (`text/event-stream`).
+	 *
+	 * @type {String}
+	 * @static
+	 * @since 1.0.0
+	 */
+	static MIME_TYPE = 'text/event-stream';
+
+
+	/** 
+	 * The optional name to send the event under.
+	 * 
+	 * @type {String}
+	 * @since 1.0.0
+	 */
+	eventName;
+
+
+	/**
+	 * Creates a Turbo Stream message instance which automatically writes to the
+	 * SSE stream as soon as a Turbo Stream element is added.
+	 * 
+	 * @param {String} [eventname] - The SSE event name to send the message under.
+	 * @since 1.0.0
+	 */
+	constructor(eventName) {
+		debug('new SseTurboStream()', eventName);
+		super();
+		this.eventName = eventName;
+	}
+
+
+	/**
+	 * Renders the Turbo Stream message and adds SSE specific syntax.
+	 *
+	 * @returns {String|null} The rendered SSE or null if there were no elements in the buffer.
+	 * @since 1.0.0
+	 */
+	render() {
+		const html = super.render();
+
+		if (html === null) {
+			debug('render() null');
+			return null;
+		}
+		debug('render()');
+
+		const event = this.renderSseEvent(html);
+
+		return event;
+	}
+
+
+	/**
+	 * Takes a HTML fragment string and converts it to an SSE event message.
+	 * 
+	 * @param {String} raw - The raw HTML string.
+	 * @returns {String|null} The converted SSE event message or null if no string has been passed.
+	 * @since 1.0.0
+	 */
+	renderSseEvent(raw) {
+		if (typeof raw !== 'string') {
+			return null;
+		}
+
+		debug('createSseEvent() raw:', raw);
+		const lines = raw.split('\n');
+		const data = lines.map(line => `data: ${line}`).join('\n');
+		const event = `${this.eventName ? `event: ${this.eventName}\n` : ''}${data}\n\n`;
+		debug('createSseEvent() event:', event);
+
+		return event;
+	}
+
+
+	/**
+	 * Creates a {TurboReadable} instance, which pipes to a {node:stream~Transform} to add 
+	 * SSE specific syntax.
+	 *
+	 * @returns {node:stream.Transform} The Transform stream instance.
+	 * @since 1.0.0
+	 */
+	createReadableStream() {
+		const readable = new TurboReadable(this);
+		const eventName = this.eventName;
+
+		const renderSseEvent = this.renderSseEvent.bind(this);
+
+		const sseTransform = new Transform({
+			transform(chunk, encoding, callback) {
+				if (encoding === 'buffer') {
+					chunk = chunk.toString();
+				}
+				const event = renderSseEvent(chunk);
+				this.push(event);
+				if (typeof callback === 'function') {
+					callback();	
+				}
+			}
+		});
+
+		return readable.pipe(sseTransform);
+	}
+
+
+	/**
+	 * Set the event name for the SSE data.
+	 * 
+	 * @param {String} eventName - The event name to send the message under.
+	 * @returns {SseTurboStream} The instance for chaining.
+	 * @since 1.0.0
+	 */
+	event(eventName) {
+		this.eventName = eventName;
+
+		return this;
+	}
+
+}

package/lib/turbo-element.js

@@ -0,0 +1,71 @@
+
+/**
+ * Base class with common functionality for Turbo Stream elements and Turbo Frames. 
+ * Not to be used directly.
+ * 
+ * @private
+ * @since 1.0.0
+ */
+export class TurboElement {
+	
+	/**
+	 * The attribute object.
+	 * @type {Object<String, String>}
+	 */
+	attributes = {};
+	
+
+	/**
+	 * The HTML content.
+	 * @type {String}
+	 */
+	content = '';
+
+
+	/**
+	 * Automatically calls validate().
+	 *
+	 * @param {Object} attributes - The attributes of this element.
+	 * @param {String} content - The HTML content of this element.
+	 */
+	constructor(attributes, content) {
+		this.attributes = attributes;
+		this.content = content;
+
+		this.validate();
+	}
+
+
+	/**
+	 * Converts the attributes object to a string in the form
+	 * of HTML attributes ({ name: value } -> 'name="value"').
+	 * 
+	 * @returns {String} The HTML attribute string. 
+	 */
+	renderAttributesAsHtml() {
+		return Object.entries(this.attributes)
+			.map(([name, value]) => `${name}="${value}"`)
+			.join(' ');
+	}
+
+
+	/* c8 ignore next 17 */
+
+	/**
+	 * Validation function to implement.
+	 * @abstract
+	 */
+	validate() {
+		throw new Error('validate() not implemented.');
+	}
+
+	
+	/**
+	 * Render function to implement.
+	 * @abstract
+	 */
+	render() {
+		throw new Error('render() not implemented.');
+	}
+
+}