gruber 0.1.0

package/core/http.js

@@ -0,0 +1,91 @@
+/**
+ * @typedef {"GET"|"HEAD"|"POST"|"PUT"|"PATCH"|"DELETE"|"CONNECT"} HTTPMethod
+ */
+
+/**
+ * @typedef {object} RouteContext
+ * @property {Request} request
+ * @property {URL} url
+ * @property {Record<string, string>} params
+ */
+
+/**
+ * @typedef {(context: RouteContext) => Response | Promise<Response>} RouteHandler
+ */
+
+/**
+ * @typedef {object} RouteOptions
+ * @property {HTTPMethod} method
+ * @property {pathname} pathname
+ * @property {RouteHandler} handler
+ */
+
+/**
+ * @typedef {object} RouteDefinition
+ * @property {HTTPMethod} method
+ * @property {URLPattern} pattern
+ * @property {RouteHandler} handler
+ */
+
+/**
+ * @param {RouteOptions} options
+ * @returns {RouteDefinition}
+ */
+export function defineRoute(options) {
+	return {
+		method: options.method,
+		pattern: new URLPattern({ pathname: options.pathname }),
+		handler: options.handler,
+	};
+}
+
+// NOTE: add more error codes as needed
+// NOTE: design an API for setting the body on static errors
+export class HTTPError extends Error {
+	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 */
+	static badRequest() {
+		return new HTTPError(400, "Bad Request");
+	}
+
+	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 */
+	static unauthorized() {
+		return new HTTPError(401, "Unauthorized");
+	}
+
+	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 */
+	static notFound() {
+		return new HTTPError(404, "Not Found");
+	}
+
+	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 */
+	static internalServerError() {
+		return new HTTPError(500, "Internal Server Error");
+	}
+
+	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501 */
+	static notImplemented() {
+		return new HTTPError(501, "Not Implemented");
+	}
+
+	/** @type {number} */ status;
+	/** @type {string}*/ statusText;
+
+	/**
+	 * @param {number} status
+	 * @param {string} statusText
+	 */
+	constructor(status = 200, statusText = "OK") {
+		super(statusText);
+		this.status = status;
+		this.statusText = statusText;
+		this.name = "HTTPError";
+		Error.captureStackTrace(this, HTTPError);
+	}
+
+	toResponse() {
+		return new Response(null, {
+			status: this.status,
+			statusText: this.statusText,
+		});
+	}
+}

package/core/http.test.js

@@ -0,0 +1,68 @@
+import { assertInstanceOf, assertEquals } from "./test-deps.js";
+import { defineRoute, HTTPError } from "./http.js";
+
+Deno.test("defineRoute", async (t) => {
+	await t.step("sets the method", () => {
+		const result = defineRoute({
+			method: "GET",
+			pathname: "/",
+			handler() {},
+		});
+		assertEquals(result.method, "GET");
+	});
+
+	await t.step("creates a URLPattern", () => {
+		const result = defineRoute({
+			method: "GET",
+			pathname: "/hello/:name",
+			handler() {},
+		});
+		assertInstanceOf(result.pattern, URLPattern);
+		assertEquals(result.pattern.pathname, "/hello/:name");
+	});
+});
+
+Deno.test("HTTPError", async (t) => {
+	await t.step("constructor", () => {
+		const result = new HTTPError(418, "I'm a teapot");
+		assertEquals(result.status, 418);
+		assertEquals(result.statusText, "I'm a teapot");
+		assertEquals(result.name, "HTTPError");
+	});
+
+	await t.step("toResponse", () => {
+		const result = new HTTPError(200, "OK").toResponse();
+		assertEquals(result.status, 200);
+		assertEquals(result.statusText, "OK");
+	});
+
+	await t.step("badRequest", () => {
+		const result = HTTPError.badRequest("body");
+		assertEquals(result.status, 400);
+		assertEquals(result.statusText, "Bad Request");
+	});
+
+	await t.step("unauthorized", () => {
+		const result = HTTPError.unauthorized();
+		assertEquals(result.status, 401);
+		assertEquals(result.statusText, "Unauthorized");
+	});
+
+	await t.step("notFound", () => {
+		const result = HTTPError.notFound();
+		assertEquals(result.status, 404);
+		assertEquals(result.statusText, "Not Found");
+	});
+
+	await t.step("internalServerError", () => {
+		const result = HTTPError.internalServerError();
+		assertEquals(result.status, 500);
+		assertEquals(result.statusText, "Internal Server Error");
+	});
+
+	await t.step("notImplemented", () => {
+		const result = HTTPError.notImplemented();
+		assertEquals(result.status, 501);
+		assertEquals(result.statusText, "Not Implemented");
+	});
+});

package/core/migrator.js

@@ -0,0 +1,68 @@
+/**
+ * @template [T=unknown]
+ * @typedef {object} MigrationOptions
+ * @property {(value: T) => void | Promise<void>} up
+ * @property {(value: T) => void | Promise<void>} down
+ */
+
+/**
+ * @template [T=unknown]
+ * @typedef {object} MigrationDefinition
+ * @property {string} name
+ * @property {(value: T) => void | Promise<void>} up
+ * @property {(value: T) => void | Promise<void>} down
+ */
+
+/**
+ * @typedef {object} MigrationRecord
+ * @property {string} name
+ */
+
+/**
+ * @template T @param {MigrationOptions<T>} options
+ * @returns {MigrationOptions<T>}
+ */
+export function defineMigration(options) {
+	return {
+		up: options.up,
+		down: options.down,
+	};
+}
+
+/**
+ * @template T
+ * @typedef {object} MigratorOptions
+ * @property {() => Promise<MigrationDefinition<T>[]>} getDefinitions
+ * @property {() => Promise<MigrationRecord[]>} getRecords
+ * @property {(def: MigrationDefinition<T>, direction: "up"|"down") => void | Promise<void>} execute
+ */
+
+/** @template T */
+export class Migrator {
+	/** @param {MigratorOptions<T>} options */
+	constructor(options) {
+		this.options = options;
+	}
+
+	async up() {
+		for (const def of await this._getTodo("up", -1)) {
+			await this.options.execute(def, "up");
+		}
+	}
+
+	async down() {
+		for (const def of await this._getTodo("down", -1)) {
+			await this.options.execute(def, "down");
+		}
+	}
+
+	async _getTodo(direction, count) {
+		const defs = await this.options.getDefinitions();
+		const records = await this.options.getRecords();
+		const ran = new Set(records.map((r) => r.name));
+
+		return (direction === "up" ? defs : Array.from(defs).reverse())
+			.filter((def) => ran.has(def.name) === (direction === "down"))
+			.slice(0, count === -1 ? Infinity : count);
+	}
+}

package/core/migrator.test.js

@@ -0,0 +1,116 @@
+import { Migrator, defineMigration } from "./migrator.js";
+import { assertEquals } from "./test-deps.js";
+
+const bareOptions = {
+	getDefinitions: () => [],
+	getRecords: () => [],
+	executeUp() {},
+	executeDown() {},
+};
+
+Deno.test("defineMigration", async ({ step }) => {
+	await step("formats the options", () => {
+		const result = defineMigration({
+			up() {},
+			down() {},
+		});
+		assertEquals(result, {
+			up: result.up,
+			down: result.down,
+		});
+	});
+});
+
+Deno.test("Migrator", async ({ step }) => {
+	await step("_getTodo", async ({ step }) => {
+		await step("gets pending", async () => {
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+			});
+
+			const result = await migrator._getTodo("up", -1);
+			assertEquals(result, [{ name: "a" }, { name: "b" }, { name: "c" }]);
+		});
+		await step("gets executed", async () => {
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+				getRecords: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+			});
+
+			const result = await migrator._getTodo("down", -1);
+			assertEquals(result, [{ name: "c" }, { name: "b" }, { name: "a" }]);
+		});
+		await step("skips previous", async () => {
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+				getRecords: () => [{ name: "a" }],
+			});
+
+			const result = await migrator._getTodo("up", -1);
+			assertEquals(result, [{ name: "b" }, { name: "c" }]);
+		});
+		await step("limits up", async () => {
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+			});
+
+			const result = await migrator._getTodo("up", 1);
+			assertEquals(result, [{ name: "a" }]);
+		});
+		await step("limits down", async () => {
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+				getRecords: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+			});
+
+			const result = await migrator._getTodo("down", 1);
+			assertEquals(result, [{ name: "c" }]);
+		});
+	});
+
+	await step("up", async ({ step }) => {
+		await step("runs migrations", async () => {
+			const result = [];
+
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [
+					{ name: "a", up: () => result.push(1) },
+					{ name: "b", up: () => result.push(2) },
+					{ name: "c", up: () => result.push(3) },
+				],
+				executeUp: (_, fn) => fn(),
+			});
+
+			await migrator.up();
+
+			assertEquals(result, [1, 2, 3]);
+		});
+	});
+
+	await step("down", async ({ step }) => {
+		await step("runs migrations", async () => {
+			const result = [];
+
+			const migrator = new Migrator({
+				...bareOptions,
+				getDefinitions: () => [
+					{ name: "a", down: () => result.push(1) },
+					{ name: "b", down: () => result.push(2) },
+					{ name: "c", down: () => result.push(3) },
+				],
+				getRecords: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
+				executeDown: (_, fn) => fn(),
+			});
+
+			await migrator.down();
+
+			assertEquals(result, [3, 2, 1]);
+		});
+	});
+});

package/core/mod.js

@@ -0,0 +1,6 @@
+export * from "./configuration.js";
+export * from "./fetch-router.js";
+export * from "./http.js";
+export * from "./migrator.js";
+export * from "./postgres.js";
+export * from "./utilities.js";

package/core/postgres.js

@@ -0,0 +1,92 @@
+import { defineMigration } from "./migrator.js";
+
+/** @typedef {import("postgres").Sql} Sql */
+/** @typedef {import("./migrator.js").MigratorOptions} MigratorOptions */
+/** @typedef {import("./migrator.js").MigrationRecord} MigrationRecord */
+/** @typedef {import("./migrator.js").MigrationDefinition} MigrationDefinition */
+
+/**
+	@param {Sql} sql
+	@returns {Promise<MigrationRecord[]>}
+	*/
+export async function _getMigrationRecords(sql) {
+	try {
+		const rows = await sql`
+      SELECT name, created
+      FROM migrations
+    `;
+		return rows.map(({ name }) => ({ name }));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * @param {MigrationDefinition} def
+ * @param {"up" | "down"} direction
+ * @param {Sql} sql
+ */
+export function _execute(def, direction, sql) {
+	return sql.begin((sql) => {
+		console.log("migrate %s", direction, def.name);
+		if (direction === "up") return _executeUp(def, sql);
+		if (direction === "down") return _executeDown(def, sql);
+	});
+}
+
+/**
+ * @param {MigrationDefinition} def
+ * @param {Sql} sql
+ */
+export async function _executeUp(def, sql) {
+	await def.up(sql);
+
+	await sql`
+		INSERT INTO migrations (name) VALUES (${def.name})
+	`;
+}
+
+/**
+ * @param {MigrationDefinition} def
+ * @param {Sql} sql
+ */
+export async function _executeDown(def, sql) {
+	await def.down(sql);
+
+	if (def.down !== bootstrapMigration.down) {
+		await sql`DELETE FROM migrations WHERE name = ${def.name}`;
+	}
+}
+
+export const bootstrapMigration = defineMigration({
+	async up(sql) {
+		await sql`
+			CREATE TABLE "migrations" (
+				"name" varchar(255) PRIMARY KEY,
+				"created" timestamp DEFAULT CURRENT_TIMESTAMP NOT NULL
+			)
+		`;
+	},
+	async down(sql) {
+		await sql`
+			DROP TABLE "migrations"
+		`;
+	},
+});
+
+/**
+ * @typedef {object} PostgresMigratorOptions
+ * @property {Sql} sql
+ */
+
+/**
+ * @param {PostgresMigratorOptions} options
+ * @returns {MigratorOptions<Sql>}
+ */
+export function getPostgresMigratorOptions(options) {
+	return {
+		getRecords: () => _getMigrationRecords(options.sql),
+		execute: (def, direction) => _execute(def, direction, options.sql),
+		getDefinitions: () => [bootstrapMigration],
+	};
+}

package/core/test-deps.js

@@ -0,0 +1,2 @@
+export * from "https://deno.land/std@0.211.0/assert/mod.ts";
+export * as superstruct from "npm:superstruct@^1.0.3";

package/core/utilities.js

@@ -0,0 +1,47 @@
+/**
+ * @template T @param {T} fields
+ * @param {(keyof T)[]} columns
+ * @param {string} fallback
+ */
+export function formatMarkdownTable(fields, columns, fallback) {
+	const widths = columns.map((column) => {
+		let largest = column.length;
+		for (const field of fields) {
+			if (field[column] && field[column].length > largest) {
+				largest = field[column].length;
+			}
+		}
+		return largest;
+	});
+
+	const lines = [
+		// Header
+		"| " + columns.map((n, i) => n.padEnd(widths[i]), " ").join(" | ") + " |",
+
+		// Seperator
+		"| " + columns.map((_, i) => "=".padEnd(widths[i], "=")).join(" | ") + " |",
+
+		// Values
+		...fields.map(
+			(field) =>
+				"| " +
+				columns
+					.map((n, i) => (field[n] ?? fallback).padEnd(widths[i], " "))
+					.join(" | ") +
+				" |",
+		),
+	];
+	return lines.join("\n");
+}
+
+/**
+ * @template T @param {() => T} handler
+ */
+export function loader(handler) {
+	/** @type {T | null} */
+	let result = null;
+	return () => {
+		if (result === null) result = handler();
+		return result;
+	};
+}

package/core/utilities.test.js

@@ -0,0 +1,34 @@
+import { formatMarkdownTable } from "./utilities.js";
+import { assertEquals } from "./test-deps.js";
+
+const expected = `
+| name    | type   | argument   | variable | fallback              |
+| ======= | ====== | ========== | ======== | ===================== |
+| env     | string | ~          | NODE_ENV | development           |
+| selfUrl | url    | --self-url | ~        | http://localhost:3000 |
+`.trim();
+
+Deno.test("formatMarkdownTable", async ({ step }) => {
+	await step("returns a table", () => {
+		const result = formatMarkdownTable(
+			[
+				{
+					name: "env",
+					type: "string",
+					variable: "NODE_ENV",
+					fallback: "development",
+				},
+				{
+					name: "selfUrl",
+					type: "url",
+					argument: "--self-url",
+					variable: "~",
+					fallback: "http://localhost:3000",
+				},
+			],
+			["name", "type", "argument", "variable", "fallback"],
+			"~",
+		);
+		assertEquals(result, expected);
+	});
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "gruber",
+  "type": "module",
+  "dependencies": {
+    "superstruct": "^1.0.3",
+    "urlpattern-polyfill": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/koa": "^2.14.0",
+    "@types/node": "^20.10.8"
+  },
+  "exports": {
+    ".": {
+      "import": "./source/mod.js"
+    },
+    "./*.js": {
+      "import": "./source/*.js"
+    }
+  },
+  "version": "0.1.0"
+}

package/source/configuration.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import process from "node:process";
+import util from "node:util";
+
+import { Configuration } from "../core/configuration.js";
+
+export { Configuration };
+
+/**
+	@typedef {object} NodeConfigurationOptions
+	@property {import("superstruct")} superstruct
+*/
+
+/** @param {NodeConfigurationOptions} options */
+export function getNodeConfigOptions(options) {
+	const args = util.parseArgs({
+		args: process.args,
+		strict: false,
+	});
+	return {
+		superstruct: options.superstruct,
+		async readTextFile(url) {
+			try {
+				return await fs.promises.readFile(url);
+			} catch (error) {
+				return null;
+			}
+		},
+		getEnvironmentVariable(key) {
+			return process.env[key];
+		},
+		getCommandArgument(key) {
+			return args.values[key.replace(/^-+/, "")];
+		},
+		stringify(config) {
+			return JSON.stringify(config, null, 2);
+		},
+		parse(data) {
+			return JSON.parse(data);
+		},
+	};
+}
+
+/**
+ * This is a syntax sugar for `new Configuration(getNodeConfigOptions(options))`
+ * @param {NodeConfigurationOptions} options
+ */
+export function getNodeConfiguration(options) {
+	return new Configuration(getNodeConfigOptions(options));
+}

package/source/core.js

@@ -0,0 +1 @@
+export * from "../core/mod.js";

package/source/express-router.js

@@ -0,0 +1,55 @@
+import { Readable } from "node:stream";
+
+import { FetchRouter } from "../core/fetch-router.js";
+import { getFetchRequest } from "./node-router.js";
+
+/**
+	A HTTP router for Express applications
+
+	```js
+	const router = new ExpressRouter(...)
+
+	const app = express()
+		.use(...)
+		.use(router.middleware());
+		.use(...)
+	```
+*/
+export class ExpressRouter {
+	/** @param {NodeRouterOptions} options */
+	constructor(options = {}) {
+		this.router = new FetchRouter(options.routes ?? []);
+	}
+
+	/** @returns {import("express").RequestHandler} */
+	middleware() {
+		return async (req, res, next) => {
+			const request = getFetchRequest(req);
+			const response = await this.getResponse(request);
+			this.respond(res, response);
+			next();
+		};
+	}
+
+	/** @param {Request} request */
+	getResponse(request) {
+		return this.router.getResponse(request);
+	}
+
+	/**
+		@param {import("express").Response} res 
+		@param {Response} response 
+	 */
+	respond(res, response) {
+		res.statusCode = response.status;
+		res.statusMessage = response.statusMessage;
+
+		for (const [key, value] of response.headers) {
+			const values = value.split(",");
+			res.set(key, values.length === 1 ? value : values);
+		}
+
+		if (response.body) Readable.fromWeb(response.body).pipe(res);
+		else res.end();
+	}
+}