gruber 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 This file documents notable changes to the project
 
+## 0.2.0
+
+**new**
+
+- Added and documented `FetchRouter`
+- Generate typings for Node.js
+- Unhandled route errors are logged to the console
+
+**fixes**
+
+- Configuration is better typed to be able to infer the final structure
+- Add missing NPM package information
+
+**docs**
+
+- Add a section on installation
+- Add a section on the releaes process
+- Add information about `loader` and `formatMarkdownTable`
+
 ## 0.1.0
 
 🎉 Everything is new!

package/README.md

@@ -77,6 +77,27 @@ A Gruber app should be run behind a reverse proxy and that can do those things f
 - Minimal — start small, carefully add features and consider removing them
 - No magic — it's confusing when you don't know whats going on
 
+## Install
+
+**Node.js**
+
+Gruber is available on NPM as [gruber](https://www.npmjs.com/package/gruber).
+
+```bash
+# cd to/your/project
+npm install gruber
+```
+
+**Deno**
+
+> WORK IN PROGRESS
+
+Gruber is available at [esm.r0b.io/gruber@0.1.0/mod.ts](https://esm.r0b.io/gruber@0.1.0/mod.ts).
+
+```js
+import { defineRoute } from "https://esm.r0b.io/gruber@0.1.0/mod.ts";
+```
+
 ## HTTP server
 
 First a HTTP route to do something:
@@ -797,6 +818,49 @@ teapot.toResponse();
 Currently, you can't set the body of the generated Response objects.
 This would be nice to have in the future, but the API should be thoughtfully designed first.
 
+### FetchRouter
+
+`FetchRouter` is a web-native router for routes defined with `defineRoute`.
+
+```js
+import { FetchRouter, defineRoute } from "gruber";
+
+const routes = [defineRoute("..."), defineRoute("..."), defineRoute("...")];
+
+const router = new FetchRouter({
+	routes,
+	errorHandler(error, request) {
+		console.log("Route error", error);
+	},
+});
+```
+
+All options to the `FetchRouter` constructor are optional and you can create a router without any options if you want.
+
+`routes` are the route definitions you want the router to processes, the router will handle a request based on the first route that matches.
+So order is important.
+
+`errorHandler` is called if a non-`HTTPError` or a 5xx `HTTPError` is thrown.
+It is called with the offending error and the request it is associated with.
+
+> NOTE: The `errorHandler` could do more in the future, like create it's own Response or mutate the existing response.
+> This has not been design and is left open to future development if it becomes important.
+
+**getResponse**
+
+`getResponse` is the main method on a router.
+Use it to get a `Response` from the provided request, based on the router's route definitions.
+
+```js
+const response = await router.getResponse(new Request("http://localhost"));
+```
+
+There are some unstable internal methods too:
+
+- `findMatchingRoutes(request)` is a generator function to get the first route definition that matches the supplied request. It's a generator so as few routes are matched as possible and execution can be stopped if you like.
+- `processMatches(request, matches)` attempts to get a `Response` from a request and an Iterator of route definitions.
+- `handleError(error, request)` converts a error into a Response and triggers the `errorHandler`
+
 ### Postgres
 
 #### getPostgresMigratorOptions
@@ -804,6 +868,52 @@ This would be nice to have in the future, but the API should be thoughtfully des
 `getPostgresMigratorOptions` generates the default options for a `PostgresMigrator`.
 You can use it and override parts of it to customise how the postgres migrator works.
 
+### Utilities
+
+### loader
+
+`loader` let's you memoize the result of a function to create a singleton from it.
+It works synchronously or with promises.
+
+```js
+import { loader } from "gruber";
+
+const useRedis = loader(async () => {
+	return "connect to the database somehow...";
+});
+
+// Then elsewhere
+const redis = await useRedis();
+```
+
+#### formatMarkdownTable
+
+`formatMarkdownTable` generates a pretty markdown table based on an array of rows and the desired column names.
+
+```js
+import { formatMarkdownTable } from "gruber";
+
+const table = formatMarkdownTable(
+	[
+		{ name: "Geoff Testington", age: 42 },
+		{ name: "Jess Smith", age: 32 },
+		{ name: "Tyler Rockwell" },
+	],
+	["name", "age"],
+	"~",
+);
+```
+
+This will generate the table:
+
+```
+| name             | age |
+| ================ | === |
+| Geoff Testington | 42  |
+| Jess Smith       | 32  |
+| Tyler Rockwell   | ~   |
+```
+
 ## Node.js library
 
 There are some specific helpers to help use Gruber in Node.js apps.
@@ -913,6 +1023,15 @@ const server = http.createServer((req) => {
 });
 ```
 
+## Release process
+
+1. Generate a new version at the root with `npm version <version>`
+2. Run the bundle `./bundle.js`
+3. Publish the node module
+   1. `cd bundle/node`
+   2. `npm publish`
+4. Copy the deno source to the S3 bucket — `bundle/deno` → `esm.r0b.io/gruber@VERSION/`
+
 ---
 
 <!-- -->
@@ -992,7 +1111,6 @@ retryWithBackoff({
 
 ## Rob's notes
 
-- should exposing `appConfig` be a best practice?
 - `core` tests are deno because it's hard to do both and Deno is more web-standards based
 - json schema for configuration specs?
 - note or info about loading dot-env files

package/core/configuration.js

@@ -26,6 +26,8 @@ const _requiredOptions = [
 	"parse",
 ];
 
+/** @typedef {Record<string, import("superstruct").Struct<any, any>>} ObjectSchema */
+
 export class Configuration {
 	static spec = Symbol("Configuration.spec");
 
@@ -39,51 +41,53 @@ export class Configuration {
 		this.options = options;
 	}
 
-	/** @template T @param {T} spec */
+	/**
+	 * @template {ObjectSchema} T
+	 * @param {T} spec
+	 */
 	object(spec) {
-		return Object.assign(
-			this.options.superstruct.defaulted(
-				this.options.superstruct.object(spec),
-				{},
-			),
-			{ [Configuration.spec]: { type: "object", value: spec } },
-		);
+		const struct = this.options.superstruct.defaulted(
+			this.options.superstruct.object(spec),
+			{},
+		)
+		struct[Configuration.spec]= { type: "object", value: spec }
+		return struct
 	}
 
 	/**
 	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @returns {import("superstruct").Struct<string, null>}
 	 */
 	string(spec = {}) {
 		if (typeof spec.fallback !== "string") {
 			throw new TypeError("spec.fallback must be a string: " + spec.fallback);
 		}
-		return Object.assign(
-			this.options.superstruct.defaulted(
-				this.options.superstruct.string(),
-				this._getValue(spec),
-			),
-			{ [Configuration.spec]: { type: "string", value: spec } },
-		);
+		const struct = this.options.superstruct.defaulted(
+			this.options.superstruct.string(),
+			this._getValue(spec),
+		)
+		struct[Configuration.spec] = { type: "string", value: spec }
+		return struct
 	}
 
 	/**
 	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @returns {import("superstruct").Struct<URL, null>}
 	 */
 	url(spec) {
 		if (typeof spec.fallback !== "string") {
 			throw new TypeError("spec.fallback must be a string");
 		}
-		return Object.assign(
-			this.options.superstruct.defaulted(
-				this.options.superstruct.coerce(
-					this.options.superstruct.instance(URL),
-					this.options.superstruct.string(),
-					(value) => new URL(value),
-				),
-				this._getValue(spec),
+		const struct = this.options.superstruct.defaulted(
+			this.options.superstruct.coerce(
+				this.options.superstruct.instance(URL),
+				this.options.superstruct.string(),
+				(value) => new URL(value),
 			),
-			{ [Configuration.spec]: { type: "url", value: spec } },
-		);
+			this._getValue(spec),
+		)
+		struct[Configuration.spec]= { type: "url", value: spec }
+		return struct
 	}
 
 	/** @param {SpecOptions} spec */
@@ -103,6 +107,7 @@ export class Configuration {
 	 * @template T
 	 * @param {URL} url
 	 * @param {import("superstruct").Struct<T>} spec
+	 * @returns {Promise<T>}
 	 */
 	async load(url, spec) {
 		const file = await this.options.readTextFile(url);

package/core/fetch-router.js

@@ -1,6 +1,8 @@
-/**
- * @typedef {import("./http.js").RouteDefinition} RouteDefinition
- */
+import { HTTPError } from "./http.js";
+
+/** @typedef {import("./types.ts").RouteDefinition<any>} RouteDefinition */
+
+/** @typedef {(error: unknown, request: Request) => unknown} RouteErrorHandler */
 
 /**
  * @typedef {object} MatchedRoute
@@ -9,32 +11,40 @@
  * @property {URLPatternResult} result
  */
 
-import { HTTPError } from "./http.js";
+/**
+ * @typedef {object} FetchRouterOptions
+ * @property {RouteDefinition[]} [routes]
+ * @property {RouteErrorHandler} [errorHandler]
+ */
 
-/** A rudimentary HTTP router using fetch Request & Responses with RouteDefinions based on URLPattern */
+/** A rudimentary HTTP router using fetch Request & Responses with RouteDefinitions based on URLPattern */
 export class FetchRouter {
-	routes /** @type {RouteDefinition} */;
+	/** @type {RouteDefinition} */ routes;
+	/** @type {RouteErrorHandler | null} */ errorHandler;
 
-	/** @param {RouteDefinition[]} routes */
-	constructor(routes) {
-		this.routes = routes;
+	/** @param {FetchRouterOptions} [options] */
+	constructor(options = {}) {
+		this.routes = options.routes ?? [];
+		this.errorHandler = options.errorHandler ?? null;
 	}
 
 	/**
 	 * Finds routes that match the request method and URLPattern
 	 * and get's the matched parameters and parsed URL
 	 * @param {Request} request
-	 * @returns {MatchedRoute[]}
+	 * @returns {Iterator<MatchedRoute>}
 	 */
-	findMatchingRoutes(request) {
-		return this.routes
-			.filter((route) => route.method === request.method)
-			.map((route) => {
-				const url = new URL(request.url);
-				const result = route.pattern.exec(request.url);
-				return { result, route, url };
-			})
-			.filter((item) => item.result);
+	*findMatchingRoutes(request) {
+		const url = new URL(request.url);
+
+		for (const route of this.routes) {
+			if (request.method !== route.method) continue;
+
+			const result = route.pattern.exec(url);
+			if (!result) continue;
+
+			yield { result, route, url };
+		}
 	}
 
 	/**
@@ -57,13 +67,16 @@ export class FetchRouter {
 		throw HTTPError.notFound();
 	}
 
-	handleError(error) {
+	/**
+	 * @param {Request} request
+	 * @param {unknown} error
+	 */
+	handleError(request, error) {
 		// Get or create a HTTP error based on the one thrown
 		const httpError =
 			error instanceof HTTPError ? error : HTTPError.internalServerError();
 
-		// NOTE: could emit the error
-		// if (httpError.status >= 500) console.error("FetchRouter error:", error);
+		if (httpError.status >= 500) this.errorHandler?.(error, request);
 
 		return httpError.toResponse();
 	}
@@ -76,7 +89,7 @@ export class FetchRouter {
 				this.findMatchingRoutes(request),
 			);
 		} catch (error) {
-			return this.handleError(error);
+			return this.handleError(request, error);
 		}
 	}
 }

package/core/fetch-router.test.js

@@ -4,17 +4,19 @@ import { assertEquals, assertInstanceOf } from "./test-deps.js";
 
 Deno.test("FetchRouter", async (t) => {
 	await t.step("constructor", () => {
-		const route = defineRoute({
-			method: "GET",
-			pathname: "/",
-			handler: () => new Response("OK"),
-		});
-		const result = new FetchRouter([route]);
-		assertEquals(result.routes, [route], "should store the routes");
+		const routes = [
+			defineRoute({
+				method: "GET",
+				pathname: "/",
+				handler: () => new Response("OK"),
+			}),
+		];
+		const result = new FetchRouter({ routes });
+		assertEquals(result.routes, routes, "should store the routes");
 	});
 
 	await t.step("findMatchingRoutes", async (t) => {
-		const router = new FetchRouter([
+		const routes = [
 			defineRoute({
 				method: "GET",
 				pathname: "/",
@@ -25,27 +27,30 @@ Deno.test("FetchRouter", async (t) => {
 				pathname: "/hello/:name",
 				handler: () => new Response("OK"),
 			}),
-		]);
+		];
+		const router = new FetchRouter({ routes });
 
 		await t.step("returns the match", () => {
-			const result = router.findMatchingRoutes(
-				new Request("http://localhost/"),
-			);
+			const result = [
+				...router.findMatchingRoutes(new Request("http://localhost/")),
+			];
 
 			assertEquals(result.length, 1, "should match 1 route");
 		});
 		await t.step("parses the URL", () => {
-			const result = router.findMatchingRoutes(
-				new Request("http://localhost/"),
-			);
+			const result = [
+				...router.findMatchingRoutes(new Request("http://localhost/")),
+			];
 
 			assertEquals(result.length, 1, "should match 1 route");
 			assertInstanceOf(result[0].url, URL);
 		});
 		await t.step("parse params", () => {
-			const result = router.findMatchingRoutes(
-				new Request("http://localhost/hello/Geoff", { method: "POST" }),
-			);
+			const result = [
+				...router.findMatchingRoutes(
+					new Request("http://localhost/hello/Geoff", { method: "POST" }),
+				),
+			];
 
 			assertEquals(result.length, 1, "should match 1 route");
 			assertEquals(
@@ -97,26 +102,49 @@ Deno.test("FetchRouter", async (t) => {
 		const router = new FetchRouter();
 
 		await t.step("converts to HTTPError", () => {
-			const result = router.handleError(new Error());
+			const result = router.handleError(
+				new Request("http://localhost"),
+				new Error(),
+			);
 			assertInstanceOf(result, Response);
 			assertEquals(result.status, 500);
 		});
 
 		await t.step("uses the HTTPError", () => {
-			const result = router.handleError(new HTTPError(400, "Bad Request"));
+			const result = router.handleError(
+				new Request("http://localhost"),
+				new HTTPError(400, "Bad Request"),
+			);
 			assertInstanceOf(result, Response);
 			assertEquals(result.status, 400);
 		});
+
+		await t.step("calls the callback", () => {
+			let args = [];
+			const router = new FetchRouter({
+				errorHandler(...result) {
+					args = result;
+				},
+			});
+			router.handleError(
+				new Request("http://localhost"),
+				new HTTPError(500, "Internal Server Error"),
+			);
+			assertInstanceOf(args[0], HTTPError);
+			assertEquals(args[0].status, 500);
+			assertInstanceOf(args[1], Request);
+		});
 	});
 
 	await t.step("getResponse", async () => {
-		const router = new FetchRouter([
+		const routes = [
 			defineRoute({
 				method: "PATCH",
 				pathname: "/hello/:name",
 				handler: ({ params }) => new Response(`Hello ${params.name}!`),
 			}),
-		]);
+		];
+		const router = new FetchRouter({ routes });
 
 		const result = await router.getResponse(
 			new Request("http://localhost/hello/Geoff", { method: "PATCH" }),

package/core/http.js

@@ -1,41 +1,40 @@
+/** @typedef {import("./types.ts").HTTPMethod} HTTPMethod */
+/** @typedef {import("./types.ts").RouteResult} RouteResult */
+
 /**
- * @typedef {"GET"|"HEAD"|"POST"|"PUT"|"PATCH"|"DELETE"|"CONNECT"} HTTPMethod
- */
+ * @template {string} T
+ * @typedef {import("./types.ts").ExtractRouteParams<T>} ExtractRouteParams */
 
 /**
- * @typedef {object} RouteContext
- * @property {Request} request
- * @property {URL} url
- * @property {Record<string, string>} params
+ * @template T
+ * @typedef {import("./types.ts").RouteContext<T>} RouteContext
  */
 
 /**
- * @typedef {(context: RouteContext) => Response | Promise<Response>} RouteHandler
+ * @template T
+ * @typedef {import("./types.ts").RouteHandler<T>} RouteHandler
  */
 
 /**
- * @typedef {object} RouteOptions
- * @property {HTTPMethod} method
- * @property {pathname} pathname
- * @property {RouteHandler} handler
+ * @template {string} T
+ * @typedef {import("./types.ts").RouteOptions<T>} RouteOptions
  */
 
 /**
- * @typedef {object} RouteDefinition
- * @property {HTTPMethod} method
- * @property {URLPattern} pattern
- * @property {RouteHandler} handler
+ * @template [T]
+ * @typedef {import("./types.ts").RouteDefinition<T>} RouteDefinition
  */
 
 /**
- * @param {RouteOptions} options
- * @returns {RouteDefinition}
+ * @template {string} T
+ * @param {RouteOptions<T>} init
+ * @returns {RouteDefinition<T>}
  */
-export function defineRoute(options) {
+export function defineRoute(init) {
 	return {
-		method: options.method,
-		pattern: new URLPattern({ pathname: options.pathname }),
-		handler: options.handler,
+		method: init.method,
+		pattern: new URLPattern({ pathname: init.pathname }),
+		handler: init.handler,
 	};
 }
 

package/core/migrator.test.js

@@ -4,8 +4,7 @@ import { assertEquals } from "./test-deps.js";
 const bareOptions = {
 	getDefinitions: () => [],
 	getRecords: () => [],
-	executeUp() {},
-	executeDown() {},
+	execute() {},
 };
 
 Deno.test("defineMigration", async ({ step }) => {
@@ -84,7 +83,7 @@ Deno.test("Migrator", async ({ step }) => {
 					{ name: "b", up: () => result.push(2) },
 					{ name: "c", up: () => result.push(3) },
 				],
-				executeUp: (_, fn) => fn(),
+				execute: (def, dir) => def[dir](),
 			});
 
 			await migrator.up();
@@ -105,7 +104,7 @@ Deno.test("Migrator", async ({ step }) => {
 					{ name: "c", down: () => result.push(3) },
 				],
 				getRecords: () => [{ name: "a" }, { name: "b" }, { name: "c" }],
-				executeDown: (_, fn) => fn(),
+				execute: (def, dir) => def[dir](),
 			});
 
 			await migrator.down();

package/core/types.ts

@@ -0,0 +1,41 @@
+/// <reference types="urlpattern-polyfill" />
+
+export type HTTPMethod =
+	| "GET"
+	| "HEAD"
+	| "POST"
+	| "PUT"
+	| "PATCH"
+	| "DELETE"
+	| "CONNECT";
+
+export type RouteResult = Promise<Response | undefined> | Response | undefined;
+
+export type ExtractRouteParams<T extends string> =
+	T extends `${string}:${infer Param}/${infer Rest}`
+		? Param | ExtractRouteParams<Rest>
+		: T extends `${string}:${infer Param}`
+			? Param
+			: never;
+
+export interface RouteContext<T> {
+	request: Request;
+	params: T;
+	url: URL;
+}
+
+export interface RouteHandler<T> {
+	(context: RouteContext<T>): RouteResult;
+}
+
+export interface RouteOptions<T extends string> {
+	method: HTTPMethod;
+	pathname: T;
+	handler: RouteHandler<Record<ExtractRouteParams<T>, string>>;
+}
+
+export interface RouteDefinition<T> {
+	method: HTTPMethod;
+	pattern: URLPattern;
+	handler: RouteHandler<T>;
+}

package/core/utilities.js

@@ -16,7 +16,9 @@ export function formatMarkdownTable(fields, columns, fallback) {
 
 	const lines = [
 		// Header
-		"| " + columns.map((n, i) => n.padEnd(widths[i]), " ").join(" | ") + " |",
+		"| " +
+			columns.map((n, i) => n.toString().padEnd(widths[i]), " ").join(" | ") +
+			" |",
 
 		// Seperator
 		"| " + columns.map((_, i) => "=".padEnd(widths[i], "=")).join(" | ") + " |",
@@ -26,7 +28,9 @@ export function formatMarkdownTable(fields, columns, fallback) {
 			(field) =>
 				"| " +
 				columns
-					.map((n, i) => (field[n] ?? fallback).padEnd(widths[i], " "))
+					.map((n, i) =>
+						(field[n] ?? fallback).toString().padEnd(widths[i], " "),
+					)
 					.join(" | ") +
 				" |",
 		),
@@ -35,10 +39,12 @@ export function formatMarkdownTable(fields, columns, fallback) {
 }
 
 /**
- * @template T @param {() => T} handler
+ * @template {() => any} T
+ * @param {T} handler
+ * @returns {T}
  */
 export function loader(handler) {
-	/** @type {T | null} */
+	/** @type {ReturnType<T> | null} */
 	let result = null;
 	return () => {
 		if (result === null) result = handler();