node-turbo 1.0.0

package/lib/turbo-frame.js

@@ -0,0 +1,79 @@
+
+import { TurboElement } from './turbo-element.js';
+import { AttributeMissingError, AttributeMalformedError } from '#errors';
+import { isPlainObject } from 'is-plain-object'; 
+
+/**
+ * This class represents a Turbo Frame message.
+ *
+ * @extends {TurboElement}
+ * @since 1.0.0
+ */
+export class TurboFrame extends TurboElement {
+	
+	/**
+	 * The key which is added to the HTTP headers when the request
+	 * is made by a Turbo Frame.
+	 * 
+	 * @type {String}
+	 * @static
+	 */
+	static HEADER_KEY = 'turbo-frame';
+
+
+	/**
+	 * MIME type of a Turbo Frame HTTP response, which is just `text/html`.
+	 * 
+	 * @type {String}
+	 * @static
+	 */
+	static MIME_TYPE = 'text/html';
+
+
+	/**
+	 * @param {String|Object} idOrAttributes - Either the ID as string or an object 
+	 *  containing all attributes (including `id`).
+	 * @param {String} content - The HTML content of this Turbo Frame message.
+	 */
+	constructor(idOrAttributes, content) {
+		if (typeof idOrAttributes === 'string') {
+			super({ id: idOrAttributes }, content);	
+		}
+		else {
+			super(idOrAttributes, content);
+		}
+	}
+
+
+	/**
+	 * Validates the attributes. `attributes.id` is mandatory. 
+	 * Gets called automatically by the constructor.
+	 * 
+	 * @throws {AttributeMissingError} when mandatory attributes are missing.
+	 * @throws {AttributeMalformedError} when mandatory attributes are malformed.
+	 */
+	validate() {
+		if (typeof this.attributes === 'undefined' || !isPlainObject(this.attributes) || !('id' in this.attributes)) {
+			throw new AttributeMissingError('TurboFrame: Attribute "id" is missing.');
+		}
+
+		if (typeof this.attributes.id !== 'string') {
+			throw new AttributeMalformedError('TurboFrame: Attribute "id" must be a string.');
+		}
+
+		if (this.attributes.id.length === 0) {
+			throw new AttributeMalformedError('TurboFrame: Attribute "id" must be a string with non-zero length.');
+		}
+	}
+
+
+	/**
+	 * Renders the Turbo Frame message as HTML string and returns it.
+	 * 
+	 * @returns {String} The rendered HTML.
+	 */
+	render() {
+		return `<turbo-frame ${this.renderAttributesAsHtml()}>${this.content}</turbo-frame>`;
+	}
+
+}

package/lib/turbo-readable.js

@@ -0,0 +1,125 @@
+
+import { Readable } from 'node:stream';
+import { TurboStream } from '#core';
+import db from 'debug';
+const debug = db('node-turbo:readable');
+
+
+/**
+ * This class represents a readable stream which reads
+ * messages/elements from a Turbo Stream instance.
+ * 
+ * @extends {stream~Readable}
+ * @since 1.0.0
+ */
+export class TurboReadable extends Readable {
+
+	/**
+	 * The Turbo Stream instance to create the readable stream for.
+	 * 
+	 * @type {TurboStream}
+	 */
+	_turboStream;
+
+
+	/**
+	 * Creates the readable stream instance. 
+	 * Updates the Turbo Stream's configuration to not buffer elements 
+	 * and adds an event listener for `element` events to it, which get handled
+	 * by `_boundPush(el)`.
+	 * 
+	 * If there are already buffered elements, they get pushed into into the read 
+	 * queue immediately and the buffer is cleared afterwards.
+	 * 
+	 * @param {TurboStream} turboStream - The Turbo Stream instance to create the readable stream for.
+	 * @param {Object} [opts] - The options for the readable stream.
+	 * @throws {Error} if `turboStream` is not a TurboStream instance
+	 */
+	constructor(turboStream, opts) {
+		debug('new TurboReadable()', opts);
+
+		if (!(turboStream instanceof TurboStream)) {
+			throw new Error('TurboReadable(): Not a TurboStream instance.');
+		}
+
+		super(Object.assign({ encoding: 'utf8' }, opts));
+
+		this._turboStream = turboStream;
+		this._turboStream.updateConfig({ buffer: false });
+
+		// If we have Turbo Stream elements, push them immediately.
+		if (this._turboStream.length > 0) {
+			this._turboStream.elements.forEach(el => this._pushElement(el));
+			this._turboStream.clear();
+		}
+
+		this._turboStream.on('element', this._boundPush);
+	}
+
+
+	/**
+	 * Pushes a Turbo Stream element into the read queue.
+	 * 
+	 * @param {TurboStreamElement} el - The Turbo Stream element.
+	 */
+	_pushElement(el) {
+		debug('_pushElement()');
+		this.push(el.render());
+	}
+
+
+	/**
+	 * This is the bound variant of `_pushElement(el)`. This function serves
+	 * as handler for the `element` event. 
+	 * 
+	 * @type {Function}
+	 */
+	_boundPush = this._pushElement.bind(this);
+
+
+	/**
+	 * Gets called when data is available for reading. 
+	 * This implementation does nothing.
+	 * (Normally, push data would be pushed into the read queue here.)
+	 * 
+	 * @todo Do we need backpressure handling?
+	 */
+	_read() {
+		debug('_read()');
+	}
+
+
+	/**
+	 * Gets called when the stream is being destroyed. The event listener 
+	 * for the event `element` is removed and the configuration restored.
+	 * 
+	 * @param {Error} err - The error object, if thrown.
+	 */
+	_destroy(err) {
+		debug('_destroy()', err);
+		this._turboStream.removeListener('element', this._boundPush);
+		this._turboStream.updateConfig({ buffer: true });
+
+		// if (typeof callback === 'function') {
+		// 	if (err) {
+		// 		callback(err);	
+		// 	}
+		// 	else {
+		// 		callback();
+		// 	}
+		// }
+	}
+
+
+	/**
+	 * Pushes `null` to the readable buffer to signal the end of the input.
+	 * 
+	 * @todo Should we call this end() or is this confusing because normally  
+	 * only writable streams have this function.
+	 */
+	done() {
+		debug('done()');
+		this.push(null);
+	}
+
+}

package/lib/turbo-stream-element.js

@@ -0,0 +1,67 @@
+
+import { TurboElement } from './turbo-element.js';
+import { isPlainObject } from 'is-plain-object'; 
+import { AttributeMissingError, AttributeMalformedError, AttributeInvalidError } from '#errors';
+
+/**
+ * A Turbo Stream element. A Turbo Stream message consists of one or several Turbo Stream
+ * elements.
+ *
+ * @extends {TurboElement}
+ * @since 1.0.0
+ */
+ export class TurboStreamElement extends TurboElement {
+
+	/**
+	 * Validates the attributes. `attributes.target` (or `attributes.targets`) and `attributes.action` 
+	 * are mandatory. Gets called by the constructor.
+	 * 
+	 * @throws {AttributeMissingError} when mandatory attributes are missing.
+	 * @throws {AttributeMalformedError} when mandatory attributes are malformed.
+	 * @throws {AttributeInvalidError} when attributes are invalid.
+	 */
+	validate() {
+		if (typeof this.attributes === 'undefined' || !isPlainObject(this.attributes)) {
+			throw new AttributeMissingError('TurboStream: Attributes are missing.');
+		}
+
+		if (!('target' in this.attributes) && !('targets' in this.attributes)) {
+			throw new AttributeMissingError('TurboStream: Attribute "target" or "targets" is missing.');
+		}
+
+		if ('target' in this.attributes && 'targets' in this.attributes) {
+			throw new AttributeInvalidError('TurboStream: Attributes "target" and "targets" exclude each other.');
+		}
+
+		if ((typeof this.attributes.target !== 'string' || this.attributes.target.length === 0) && 
+			(typeof this.attributes.targets !== 'string' || this.attributes.targets.length === 0)) {
+			throw new AttributeMalformedError('TurboStream: Attribute "target"/"targets" must be a string with non-zero length.');
+		}
+
+		if (!('action' in this.attributes)) {
+			throw new AttributeMissingError('TurboStream: Attribute "action" is missing.');
+		}
+
+		if (typeof this.attributes.action !== 'string' || this.attributes.action.length === 0) {
+			throw new AttributeMalformedError('TurboStream: Attribute "action" must be a string with non-zero length.');
+		}
+	}
+
+
+	/**
+	 * Renders this Turbo Stream element as HTML string. Omits `<template>[content]<template>` when the attribute 
+	 * `action` is 'remove'.
+	 * 
+	 * @returns {String} The rendered HTML fragment.
+	 * @see https://turbo.hotwired.dev/handbook/streams#stream-messages-and-actions
+	 */
+	render() {
+		if (this.attributes.action === 'remove') {
+			return `<turbo-stream ${this.renderAttributesAsHtml()}></turbo-stream>`;
+		}
+		else {
+			return `<turbo-stream ${this.renderAttributesAsHtml()}><template>${this.content}</template></turbo-stream>`;
+		}
+	}
+
+}

package/lib/turbo-stream.js

@@ -0,0 +1,350 @@
+
+import { EventEmitter } from 'node:events';
+import { TurboStreamElement, TurboReadable } from '#core';
+import { Writable, Readable } from 'node:stream';
+import db from 'debug';
+const debug = db('node-turbo:turbostream');
+
+
+/**
+ * A Turbo Stream message.
+ * 
+ * @extends {events~EventEmitter}
+ * @since 1.0.0
+ */
+export class TurboStream extends EventEmitter {
+
+	/**
+	 * Default configuration.
+	 * 
+	 * @type {Object<String, String>}
+	 * @property {Boolean} buffer - Should elements be added to the buffer (default: true)?
+	 */
+	config = {
+		buffer: true
+	};
+
+
+	/**
+	 * Array of buffered elements. Gets filled if `config.buffer` is `true`.
+	 * 
+	 * @type {Array}
+	 */
+	elements = [];
+	
+
+	/**
+	 * MIME type for Turbo Stream messages.
+	 *
+	 * @see https://turbo.hotwired.dev/handbook/streams#streaming-from-http-responses
+	 * @type {String}
+	 * @static
+	 */
+	static MIME_TYPE = 'text/vnd.turbo-stream.html';
+
+
+	/**
+	 * List of all supported actions:
+	 * 'append', 'prepend', 'replace', 'update', 'remove', 'before' and 'after'.
+	 * 
+	 * @see https://turbo.hotwired.dev/handbook/streams#stream-messages-and-actions
+	 * @type {Array}
+	 * @static
+	 */
+	static ACTIONS = [
+		'append',
+		'prepend',
+		'replace',
+		'update',
+		'remove',
+		'before',
+		'after'
+	];
+
+
+	/** 
+	 * The number of buffered Turbo Stream elements.
+	 *
+	 * @type {Number}
+	 */
+	get length() {
+		return this.elements.length;
+	}
+
+
+	/**
+	 * If `attributes` and `content` are available, a Turbo Stream element is added to the buffer,
+	 * pending validation.
+	 * 
+	 * @param {Object<String, String>} [attributes] - The attributes of this element.
+	 * @param {String} [content] - The HTML content of this element.
+	 */
+	constructor(attributes, content) {
+		super();
+
+		if (typeof attributes !== 'undefined') {
+			return this.addElement(attributes, content);	
+		}
+	}
+
+
+	/**
+	 * Extends/Overwrites the configuration.
+	 *
+	 * @param {Object} config - New configuration.
+	 * @emits config
+	 * @returns {TurboStream} The instance for chaining.
+	 */
+	updateConfig(config) {
+		if (config) {
+			this.config = Object.assign(this.config, config);
+			this.emit('config', this.config);
+		}
+
+		return this;
+	}
+
+
+	/**
+	 * Adds a Turbo Stream element to the message. 
+	 * Adds the element to the buffer, if config.buffer === true.
+	 * Fires the event 'element' with the added element.
+	 *
+	 * @param {Object<String, String>|TurboFrameElement} attributesOrElement - 
+	 * @param {String} content - The HTML content of the element.
+	 * @emits element
+	 * @returns {TurboStream} The instance for chaining.
+	 */
+	addElement(attributesOrElement, content) {
+		let el;
+
+		if (attributesOrElement instanceof TurboStreamElement) {
+			el = attributesOrElement;
+		}
+		else {
+			el = new TurboStreamElement(attributesOrElement, content);	
+		}
+
+		if (this?.config?.buffer === true) {
+			this.elements.push(el);
+		}
+
+		this.emit('element', el);
+		
+		return this;
+	}
+
+
+	/**
+	 * Clears the buffer.
+	 * 
+	 * @emits clear
+	 * @returns {TurboStream} The instance for chaining.
+	 */
+	clear() {
+		this.elements = [];
+		this.emit('clear');
+
+		return this;
+	}
+
+
+	/**
+	 * Renders this Turbo Stream message if there are buffered elements.
+	 * 
+	 * @returns {String|null} The rendered Turbo Stream HTML fragment or null if there were no buffered elements.
+	 * @emits render
+	 */
+	render() {
+		const arr = this.renderElements();
+		if (arr !== null) {
+			const html = arr.join('\n');
+			this.emit('render', html);
+
+			return html;
+		}
+
+		return null;
+	}
+
+
+	/**
+	 * If there are buffered elements, renders them and returns an array with the HTML fragments.
+	 * 
+	 * @returns {Array|null} The rendered Turbo Stream HTML fragments as array or null if there were no buffered elements.
+	 */
+	renderElements() {
+		if (this.elements.length > 0) {
+			return this.elements.map(el => el.render());
+		}
+
+		return null;
+	}
+
+
+	/**
+	 * Renders this Turbo Stream message and clears the buffer.
+	 * 
+	 * @returns {String|null} The rendered Turbo Stream HTML fragment or null if there were no buffered elements.
+	 * @emits {render}
+	 * @emits {clear}
+	 */
+	flush() {
+		const html = this.render();
+		this.clear();
+
+		return html;
+	}
+
+
+	/**
+	 * Adds a Turbo Stream Element with a custom action.
+	 * 
+	 * @param {String} action - The name of the custom action.
+	 * @param {String} target - The target ID.
+	 * @param {String} content - The HTML content of the element. 
+	 * @returns {TurboStream} The instance for chaining.
+	 */
+	custom(action, target, content) {
+		return this.addElement({ action, target }, content);
+	}
+
+
+	/**
+	 * Adds a Turbo Stream Element with a custom action, targeting multiple DOM elements.
+	 * 
+	 * @param {String} action - The name of the custom action.
+	 * @param {String} targets - The query string targeting multiple DOM elements.
+	 * @param {String} content - The HTML content of the element. 
+	 * @returns {TurboStream} The instance for chaining.
+	 */
+	customAll(action, targets, content) {
+		return this.addElement({ action, targets }, content);
+	}
+
+
+	/**
+	 * 
+	 */
+	createReadableStream(opts, streamOptions = {}) {
+		opts = Object.assign({}, { continuous: true }, opts);
+		debug('createReadableStream()', opts, streamOptions);
+
+		if (opts.continuous === true) {
+			debug(' returns new TurboStreamReadable()');
+			return new TurboReadable(this, streamOptions);
+		}
+		else {
+			debug(' returns Readable.from()');
+			return Readable.from(this.length > 0 ? this.render().split('\n') : [], streamOptions);
+		}
+	}
+}
+
+
+// Add convenience functions for all supported actions.
+TurboStream.ACTIONS.forEach(action => {
+	TurboStream.prototype[action] = function(targetOrAttributes, content) {
+		if (typeof targetOrAttributes === 'string') {
+			return this.addElement({ action: action, target: targetOrAttributes }, content);	
+		}
+		else {
+			return this.addElement(Object.assign({ action: action }, targetOrAttributes), content);	
+		}
+	};
+
+	TurboStream.prototype[`${action}All`] = function(targets, content) {
+		return this.addElement({ action: action, targets }, content);	
+	};
+});
+
+// Dynamic functions:
+
+/**
+ * @name #append
+ * @function
+ * @description Adds a Turbo Stream element with the action 'append' to the message.
+ * @param {String|Object<String, String>} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name #prepend
+ * @function
+ * @description Adds a Turbo Stream element with the action 'prepend' to the message.
+ * @param {(String|Object<String, String>)} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name #replace
+ * @function
+ * @description Adds a Turbo Stream element with the action 'replace' to the message.
+ * @param {(String|Object<String, String>)} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name #update
+ * @function
+ * @description Adds a Turbo Stream element with the action 'update' to the message.
+ * @param {String|Object<String, String>} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name #remove
+ * @function
+ * @description Adds a Turbo Stream element with the action 'remove' to the message.
+ * @param {String|Object<String, String>} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name #before
+ * @function
+ * @description Adds a Turbo Stream element with the action 'before' to the message.
+ * @param {String|Object<String, String>} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+/**
+ * @name after
+ * @function
+ * @description Adds a Turbo Stream element with the action 'after' to the message.
+ * @param {String|Object<String, String>} targetOrAttributes - Either the target ID as string or all attributes as object.
+ * @param {String} content - The HTML content of the element.
+ */
+
+// Events:
+
+/**
+ * Event element.
+ * Gets fired when a Turbo Stream element has been added to a message.
+ *
+ * @event element
+ * @param {TurboStreamElement} - The added element.
+ */
+
+/**
+ * Event render.
+ * Gets fired when a Turbo Stream message has been rendered.
+ *
+ * @event render
+ * @param {String} - The rendered HTML fragment.
+ */
+
+/**
+ * Event config.
+ * Gets fired when the config has been updated.
+ *
+ * @event config
+ * @param {Object} - The updated config object.
+ */
+
+/**
+ * Event clear.
+ * Gets fired when the buffer is cleared.
+ *
+ * @event clear
+ */

package/lib/ws/index.js

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