node-turbo 1.0.0

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

@@ -0,0 +1,112 @@
+
+import { TurboStream } from '#core';
+
+
+/**
+ * This class represents a Turbo Stream message with added functionality for WebSockets.
+ * 
+ * @extends {TurboStream}
+ */
+export class WsTurboStream extends TurboStream {
+	
+	/**
+	 * The WebSocket instance to send to.
+	 * 
+	 * @type {WebSocket}
+	 */
+	ws;
+
+
+	/**
+	 * Ready-state `OPEN` of a WebSocket.
+	 * 
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState
+	 * @type {Number}
+	 * @static
+	 */
+	static OPEN = 1;
+
+
+	/**
+	 * Convenience function to create a non-buffering WsTurboStream 
+	 * instance, which uses the passed WebSocket.
+	 * 
+	 * @static
+	 * @param {WebSocket} ws - The WebSocket instance to send to.
+	 * @returns {WsTurboStream} - A new WsTurboStream instance.
+	 */
+	static use(ws) {
+		return new this(ws, { buffer: false });
+	}
+
+
+	/**
+	 * Listens for the event `config` and calls `handleConfig(config)` if it has been emitted.
+	 * 
+	 * @param {WebSocket} ws - The WebSocket to send to.
+	 * @param {Object} [config] - The config to override.
+	 * @listens config
+	 */
+	constructor(ws, config) {
+		super();
+		this.ws = ws;
+
+		this.on('config', this.handleConfig);
+
+		if (typeof config !== 'undefined') {
+			this.updateConfig(config);
+		}
+		else {
+			this.handleConfig(this.config);
+		}
+	}
+
+
+	/**
+	 * Changes event listeners depending on `config.buffer`:  
+	 * If `true`,  it will listen for the event `render` and call `handleRender()` when the event has been emitted.  
+	 * If `false`, it will listen for the event `element` and call `handleElement()` when the event has been emitted.
+	 *
+	 * @param {Object} config - The changed config object.
+	 * @listens element
+	 * @listens render
+	 */
+	handleConfig(config) {
+		if (config.buffer === true) {
+			/* c8 ignore next 3 */
+			if (this.listenerCount('element') > 0) {
+				this.removeListener('element', this.handleElement); 	
+			}
+
+			this.on('render', this.handleRender);
+		}
+		else {
+			/* c8 ignore next 3 */
+			if (this.listenerCount('render') > 0) {
+				this.removeListener('render', this.handleRender); 
+			}
+			this.on('element', this.handleElement);
+		}
+	}
+
+
+	/**
+	 * Sends the rendered HTML fragment to the WebSocket.
+	 * 
+	 * @param {String} html - The rendered HTML fragment.
+	 */
+	handleRender(html) {
+		this.ws.send(html);	
+	}
+
+
+	/**
+	 * Sends the Turbo Stream element to the WebSocket.
+	 * 
+	 * @param {TurboStreamElement} element - The Turbo Stream element to send.
+	 */
+	handleElement(element) {
+		this.ws.send(element.render());	
+	}
+
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "node-turbo",
+	"version": "1.0.0",
+	"description": "A library for Node.js to assist with the server side of 37signals' Hotwire Turbo framework. It provides classes and functions for Web servers and also convenience functions for the frameworks Koa and Express as well as for WebSocket and SSE.",
+	"keywords": ["turbo", "hotwire", "hotwired", "server", "http", "koa", "express", "sse", "websocket", "ws"],
+	"homepage": "https://github.com/VividVisions/node-turbo",
+	"bugs": "https://github.com/VividVisions/node-turbo/issues",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/VividVisions/node-turbo.git"
+	},
+	"author": "Walter Krivanek <walter@vividvisions.com>",
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">= 16.6"
+	},
+	"main": "./lib/index.js",
+	"exports": {
+		".": "./lib/index.js",
+		"./ws": "./lib/ws/index.js",
+		"./koa": "./lib/koa/index.js",
+		"./express": "./lib/express/index.js",
+		"./sse": "./lib/sse/index.js",
+		"./errors": "./lib/errors/index.js"
+	},
+	"imports": {
+		"#core": "./lib/index.js",
+		"#ws": "./lib/ws/index.js",
+		"#koa": "./lib/koa/index.js",
+		"#express": "./lib/express/index.js",
+		"#sse": "./lib/sse/index.js",
+		"#errors": "./lib/errors/index.js"
+	},
+	"scripts": {
+		"test": "NODE_ENV=testing mocha --require \"./test/hooks.js\"",
+		"test:unit": "NODE_ENV=testing mocha --ignore \"./test/integration/**\" --ignore \"./test/*\"",
+		"test:integration": "NODE_ENV=testing mocha --ignore \"./test/unit/**\" --ignore \"./test/*\"",
+		"test:package": "NODE_ENV=testing mocha --ignore \"./test/unit/**\" --ignore \"./test/integration/**\"",
+		"test:all": "NODE_ENV=testing mocha",
+		"test:coverage": "c8 -c './.c8rc.json' npm test",
+		"pretest:coverage": "rm -rd ./coverage",
+		"docs": "esdoc -c ./.esdoc.json",
+		"postdocs": "cp -f ./docs/internal/API.md ./docs"
+	},
+	"dependencies": {
+		"is-plain-object": "^5.0.0",
+		"negotiator": "^0.6.3"
+	},
+	"devDependencies": {
+		"@enterthenamehere/esdoc": "^2.6.0-dev.1",
+		"@enterthenamehere/esdoc-external-nodejs-plugin": "^2.6.0-dev.1",
+		"@enterthenamehere/esdoc-importpath-plugin": "^2.6.0-dev.1",
+		"@enterthenamehere/esdoc-standard-plugin": "^2.6.0-dev.2",
+		"@vividvisions/esdoc-api-doc-markdown-plugin": "file:../esdoc-api-doc-markdown-plugin",
+		"@hotwired/turbo": "^8.0.0-beta.1",
+		"c8": "^8.0.1",
+		"chai": "^4.3.10",
+		"chai-eventemitter2": "^0.2.1",
+		"chai-spies": "^1.1.0",
+		"colorette": "^2.0.20",
+		"debug": "^4.3.4",
+		"eventsource": "^2.0.2",
+		"express": "^4.18.2",
+		"git-repo-info": "^2.1.1",
+		"koa": "^2.14.2",
+		"koa-route": "^3.2.0",
+		"koa-static": "^5.0.0",
+		"mocha": "^10.2.0",
+		"node-mocks-http": "^1.14.0",
+		"nunjucks": "^3.2.4",
+		"supertest": "^6.3.3",
+		"ws": "^8.15.1"
+	}
+}

package/test/hooks.js

@@ -0,0 +1,46 @@
+
+// Dependencies.
+import getRepoInfo from 'git-repo-info';
+import os from 'node:os';
+import { green, yellow } from 'colorette';
+
+const
+	__dirname = new URL('.', import.meta.url).pathname,
+	gitInfo = getRepoInfo(__dirname);
+
+/**
+ * 
+ */
+export const mochaHooks = {
+	
+	beforeAll() {
+		console.log('');
+		console.log(`Testing time: ${green(new Date().toISOString())}`);
+
+		// Log info about application and environment.
+		console.log(`Package     : ${green(process.env.npm_package_name)}`);
+		console.log(`Version     : ${green(process.env.npm_package_version)}`);
+		console.log(`NODE_ENV    : ${'NODE_ENV' in process.env ? green(process.env['NODE_ENV']) : yellow('-')}`);
+
+		// Log info about Git branch, etc…
+		console.log(`Git branch  : ${gitInfo.branch ? green(gitInfo.branch) : yellow('-')}`);
+		if (gitInfo.sha) {
+			console.log(`Git revision: ${green(gitInfo.sha.substr(0, 8))} (${gitInfo.sha})`);
+		}
+		else {
+			console.log(`Git revision: ${yellow('-')}`);
+		}
+
+		// Log info about Node.js.
+		console.log(`Node.js     : ${green(process.version)}`);
+
+		// Log info about the machine.
+		console.log(`OS          : ${green(os.type())} ${green(os.release())} (${green(os.platform())})`);
+		console.log(`Hostname    : ${green(os.hostname())}`);
+		console.log(`CPUs        : ${green(os.cpus().length)}`);
+		console.log(`CPU arch    : ${green(os.arch())}`);
+		console.log(`Memory total: ${green('GB ' + Number(os.totalmem() / 1073741824).toFixed(1))}`);
+		console.log('');
+	}
+
+};

package/test/integration/express.test.js

@@ -0,0 +1,137 @@
+
+import { expect } from 'chai';
+import request from 'supertest';
+import express from 'express';
+import { TurboStream, TurboFrame } from '#core';
+import { turbochargeExpress } from '#express';
+
+describe('Express integration', function() {
+
+	before(function() {
+		const app = express();
+
+		turbochargeExpress(app);		
+		
+		app.use((req, res, next) => {
+			this.storedReq = req;
+			this.storedRes = res;
+			next();
+		});
+		
+		app.get('/frameautoid', (req, res) => {
+			if (req.isTurboFrameRequest()) {
+				res.turboFrame('<p>content</p>');	
+			}
+			else {
+				res.status(501).end();
+			}
+		});
+
+		app.get('/framesetid', (req, res) => {
+			if (req.isTurboFrameRequest()) {
+				res.turboFrame('set-id', '<p>content</p>');	
+			}
+			else {
+				res.status(501).end();
+			}
+		});
+
+		app.get('/stream', (req, res) => {
+			if (req.isTurboStreamRequest()) {
+				res
+					.turboStream()
+					.append('target-id', '<p>append</p>')
+					.send();
+			}
+			else {
+				res.status(501).end();
+			}
+		});
+		
+		this.app = app;
+	});
+
+	describe('turbochargeExpress()', function() {
+		
+		it('adds helper functions to Express\' request object', function() {
+			return request(this.app)
+				.get('/')
+				.then(response => {
+					expect(this.storedReq.getTurboFrameId).to.be.an('function');
+					expect(this.storedReq.isTurboFrameRequest).to.be.an('function');
+					expect(this.storedReq.isTurboStreamRequest).to.be.an('function');
+				});
+		});
+
+		it('adds turboStream() to Express\' response object', function() {
+			return request(this.app)
+				.get('/')
+				.then(response => {
+					expect(this.storedRes.turboStream).to.be.an('function');
+				});
+		});
+
+		it('adds turboFrame() to Express\' response object', function() {
+			return request(this.app)
+				.get('/')
+				.then(response => {
+					expect(this.storedRes.turboFrame).to.be.an('function');
+				});
+		});
+
+	});
+
+	describe('Turbo Frames', function() {
+		
+		it('res.turboFrame() autom. retrieves Turbo-Frame ID from request when not set', function() {
+			return request(this.app)
+				.get('/frameautoid')
+				.set(TurboFrame.HEADER_KEY, 'turbo-frame-id')
+				.expect(200)
+				.then(response => {
+					expect(response.text).to.equal('<turbo-frame id="turbo-frame-id"><p>content</p></turbo-frame>');
+				});
+		});
+
+
+		it('Turbo Frame request returns Turbo Frame message', function() {
+			return request(this.app)
+				.get('/framesetid')
+				.set(TurboFrame.HEADER_KEY, 'turbo-frame-id')
+				.expect(200)
+				.then(response => {
+					expect(response.text).to.equal('<turbo-frame id="set-id"><p>content</p></turbo-frame>');
+				});
+		});
+
+
+		it('Non Turbo Frame request returns status 501', function() {
+			return request(this.app)
+				.get('/frameautoid')
+				.expect(501);
+		});
+
+	});
+
+
+	describe('Turbo Streams', function() {
+		
+		it('Turbo Stream request returns Turbo Stream message', function() {
+			return request(this.app)
+				.get('/stream')
+				.set('Accept', TurboStream.MIME_TYPE)
+				.expect(200)
+				.then(response => {
+					expect(response.text.trim()).to.equal('<turbo-stream action="append" target="target-id"><template><p>append</p></template></turbo-stream>');
+				});
+		});
+
+		it('Non Turbo Stream request returns status 501', function() {
+			return request(this.app)
+				.get('/stream')
+				.expect(501);
+		});
+
+	});
+
+});

package/test/integration/koa.test.js

@@ -0,0 +1,125 @@
+
+import { expect } from 'chai';
+import request from 'supertest';
+import Koa from 'koa';
+import route from 'koa-route';
+import { TurboStream, TurboFrame } from '#core';
+import { turbochargeKoa } from '#koa';
+
+describe('Koa integration', function() {
+
+	before(function() {
+		const app = new Koa();
+
+		app.on('error', (err, ctx) => {
+			expect.fail(err);
+		});
+
+		turbochargeKoa(app);
+		
+		app.use(async (ctx, next) => {
+			this.storedCtx = ctx;
+			await next();
+		});
+		
+		app.use(route.get('/frame', ctx => {
+			if (ctx.isTurboFrameRequest()) {
+				ctx.turboFrame('<p>content</p>');
+			}
+			else {
+				ctx.status = 501;
+			}
+		}));
+
+		app.use(route.get('/stream', ctx => {
+			if (ctx.isTurboStreamRequest()) {
+				ctx
+					.turboStream()
+					.append('target-id', '<p>append</p>');
+			}
+			else {
+				ctx.status = 501;
+			}
+		}));
+		
+		this.app = app;
+	});
+
+	describe('turbochargeKoa()', function() {
+		
+		before(function() {
+			return new Promise((resolve, reject) => {;
+				request(this.app.callback())
+					.get('/')
+					.end((err, res) => {
+						if (err) {
+							return reject(err);
+						}
+						resolve(res);
+					});
+			});
+		});
+
+
+		it('adds helper functions to Koa\'s ctx', function() {
+			expect(this.storedCtx.getTurboFrameId).to.be.a('function');
+			expect(this.storedCtx.isTurboFrameRequest).to.be.a('function');
+			expect(this.storedCtx.isTurboStreamRequest).to.be.a('function');
+		});
+
+
+		it('adds turboStream() to Koa\'s ctx', function() {
+			expect(this.storedCtx.turboStream).to.be.a('function');
+		});
+
+
+		it('adds turboFrame() to Koa\'s ctx', function() {
+			expect(this.storedCtx.turboFrame).to.be.a('function');
+		});
+
+	});
+
+	describe('Turbo Frames', function() {
+		
+		it('Turbo Frame request returns Turbo Frame message', function() {
+			return request(this.app.callback())
+				.get('/frame')
+				.set(TurboFrame.HEADER_KEY, 'turbo-frame-id')
+				.expect(200)
+				.expect('Content-Type', /text\/html/)
+				.then(response => {
+					expect(response.text).to.equal('<turbo-frame id="turbo-frame-id"><p>content</p></turbo-frame>');
+				});
+		});
+
+		it('Non Turbo Frame request returns status 501', function() {
+			return request(this.app.callback())
+				.get('/frame')
+				.expect(501);
+		});
+
+	});
+
+
+	describe('Turbo Streams', function() {
+		
+		it('Turbo Stream request returns Turbo Stream message with correct MIME type', function() {
+			return request(this.app.callback())
+				.get('/stream')
+				.set('Accept', TurboStream.MIME_TYPE)
+				.expect(200)
+				.expect('Content-Type', new RegExp(TurboStream.MIME_TYPE))
+				.then(response => {
+					expect(response.text.trim()).to.equal('<turbo-stream action="append" target="target-id"><template><p>append</p></template></turbo-stream>');
+				});
+		});
+
+		it('Non Turbo Stream request returns status 501', function() {
+			return request(this.app.callback())
+				.get('/stream')
+				.expect(501);
+		});
+
+	});
+
+});

package/test/integration/sse.test.js

@@ -0,0 +1,80 @@
+
+import { expect } from 'chai';
+import request from 'supertest';
+import Koa from 'koa';
+import EventSource from 'eventsource';
+import { TurboStream } from '#core';
+import { SseTurboStream } from '#sse';
+import { PassThrough } from 'node:stream';
+
+const port = 8888;
+
+describe('SSE integration', function() {
+
+	before(function() {
+		this.app = new Koa();
+		this.sseTurboStream = new SseTurboStream();
+
+		this.app.on('error', (err, ctx) => {
+			expect.fail(err);
+		});
+
+		this.app.use(async (ctx, next) => {
+			if (ctx.path !== '/sse') {
+				return await next();
+			}
+
+			ctx.request.socket.setTimeout(0);
+			ctx.req.socket.setNoDelay(true);
+			ctx.req.socket.setKeepAlive(true);
+
+			ctx.set({
+				'Cache-Control': 'no-cache',
+				'Connection': 'keep-alive',
+			});
+
+			this.readable = this.sseTurboStream.createReadableStream();
+
+			ctx.type = SseTurboStream.MIME_TYPE;
+			ctx.status = 200;
+			ctx.body = this.readable;
+		});
+
+		this.server = this.app.listen(port);
+	});
+
+
+	after(function() {
+		this.readable.destroy();
+		this.eventSource.close();
+		this.server.close();
+	});
+
+
+	it('Turbo Stream messages get sent to EventSource as SSE messages', function(done) {
+		const messages = [];
+		
+		this.eventSource = new EventSource(`http://localhost:${port}/sse`);
+		
+		this.eventSource.addEventListener('error', e => {
+			expect.fail('An error occurred while attempting to connect');
+		});
+
+		this.eventSource.addEventListener('message', e => {
+			
+			messages.push(e.data);
+
+			if (messages.length === 2) {
+				expect(messages[0]).to.equal('<turbo-stream action="append" target="t1"><template>c1</template></turbo-stream>');
+				expect(messages[1]).to.equal('<turbo-stream action="replace" target="t2"><template>c2</template></turbo-stream>');
+				done();
+			}
+		});
+
+		// Send Turbo Stream messages.
+		this.sseTurboStream.append('t1', 'c1');
+		this.sseTurboStream.replace('t2', 'c2');
+	});
+
+
+});