gruber 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 This file documents notable changes to the project
 
+## 0.3.0
+
+**new**
+
+- Removed use of superstruct in favour of new `structures.js` implementation
+- Added `getJSONSchema` method to `Configuration`
+
+**fixed**
+
+- Node.js types should work now
+- Node.js types includes a url-pattern polyfil
+
+## 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:
@@ -214,11 +235,11 @@ Building on the [HTTP server](#http-server) above, we'll setup configuration. St
 **config.js**
 
 ```js
-import superstruct from "superstruct";
+import fs from "node:fs";
 import { getNodeConfiguration } from "gruber";
 
 const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"));
-const config = getNodeConfiguration({ superstruct });
+const config = getNodeConfiguration();
 
 export function getSpecification() {
 	return config.object({
@@ -265,6 +286,11 @@ export const appConfig = await loadConfiguration(
 export function getConfigurationUsage() {
 	return config.getUsage(getSpecification());
 }
+
+// Export a method to generate a JSON Schema for the configuration
+export function getConfigurationSchema() {
+	return config.getJSONSchema(getSpecification());
+}
 ```
 
 ### Usage info
@@ -306,11 +332,11 @@ You can provide a configuration file like **config.json** to load through the co
 	"selfUrl": "http://localhost:3000",
 	"meta": {
 		"name": "gruber-app",
-		"version": "1.2.3",
+		"version": "1.2.3"
 	},
 	"database": {
-		"url": "postgres://user:secret@localhost:5432/database",
-	},
+		"url": "postgres://user:secret@localhost:5432/database"
+	}
 }
 ```
 
@@ -651,7 +677,6 @@ To see how it works, look at the [Node](./node/source/configuration.js) and [Den
 You can use the static `getOptions` method both subclasses provide and override the parts you want.
 These are the options:
 
-- `superstruct` — Configuration is based on [superstruct](https://docs.superstructjs.org/), you can pass your own instance if you like.
 - `readTextFile(url)` — How to load a text file from the file system
 - `getEnvironmentVariable(key)` — Return a matching environment "variable" for a key
 - `getCommandArgument(key)` — Get the corresponding "flag" from a CLI argument
@@ -663,10 +688,9 @@ For example, to override in Node:
 ```js
 import { Configuration, getNodeConfigOptions } from "gruber";
 import Yaml from "yaml";
-import superstruct from "superstruct";
 
 const config = new Configuration({
-	...getNodeConfigOptions({ superstruct }),
+	...getNodeConfigOptions(),
 	getEnvionmentVariable: () => undefined,
 	stringify: (v) => Yaml.stringify(v),
 	parse: (v) => Yaml.parse(v),
@@ -797,6 +821,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 +871,135 @@ 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   | ~   |
+```
+
+#### Structure
+
+This is an internal primative for validating objects, strings, numbers and URLs for use in [Configuration](#configuration).
+It is based on a very specific use of [superstruct](https://github.com/ianstormtaylor/superstruct) which it made sense to internalise to make the code base more portable.
+A `Structure` is a type that validates a value is correct by throwing an error if validation fails, i.e. the wrong type is passed.
+Every struct has an intrinsic `fallback` so that if no value (`undefined`) is passed, that is used instead.
+
+```js
+import { Structure } from "gruber/structures.js";
+
+// A string primative, or use "Geoff Testington" if no value is passed.
+const name = Structure.string("Geoff Testington");
+
+// A URL instance or a string that contains a valid URL, always converting to a URL
+const website = Structure.url("https://example.com");
+
+// A number primative, falling back to 42
+const age = Structure.number(42);
+
+// An object with all of the fields above and nothing else
+// defaulting to create { name: "Geoff..", age: 42, website: "https..." } with the same fallback values
+const person = Structure.object({ name, age, website });
+
+// Process the Structure and get a value out. The returned value is strongly typed!
+// This will throw if the value passed does not match the schema.
+const value = person.process(/* ... */);
+```
+
+Those static Structure methods return a `Structure` instance. You can also create your own types with the constructor. This example shows how to do that, and also starts to unveil how the internals work a bit with [StructError](#structerror).
+
+```js
+import { Structure, StructError } from "gruber/structures.js";
+
+// Create a new boolean structure (this should probably be included as Structure.boolean tbh)
+const boolean = new Structure(
+	{ type: "boolean", default: false },
+	(input, context) => {
+		if (input === undefined) return false;
+		if (typeof input !== "boolean") {
+			throw new StructError("Expected a boolean", context?.path);
+		}
+		return input;
+	},
+);
+```
+
+To create a custom Structure, you give it a [JSON schema](https://json-schema.org/) and a "process" function.
+The function is called to validate a value against the structure. It should return the processed value or throw a `StructError`.
+
+The `context` object might not be set and this means the struct is at the root level. If it is nested in an `object` then the context contains the path that the struct is located at, all the way from the root object. That path is expressed as an array of strings. That path is used to generate friendlier error messages to explain which nested field failed.
+
+With a Structure, you can generate a JSON Schema:
+
+```js
+import { Structure } from "gruber/structures.js";
+
+const person = Structure.object({
+	name: Structure.string("Geoff Testington"),
+	age: Structure.number(42),
+	website: Structure.url("https://example.com"),
+});
+
+console.log(JSON.stringify(person.getSchema(), null, 2));
+```
+
+This is a bit WIP, but you could use this to generate a JSON schema to lint configurations in your IDE.
+
+#### StructError
+
+This Error subclass contains extra information about why parsing a `Structure` failed.
+
+- The `message` field is a description of what went wrong, in the context of the structure.
+- An extra `path` field exists to describe the path from the root object to get to this failed structure
+- `children` is also available to let a structure have multiple child errors, i.e. for an object to have failures for each of the fields that have failed.
+
+On the error, there are also methods to help use it:
+
+- `toFriendlyString` goes through all nested failures and outputs a single message to describe everything that went wrong.
+- `getOneLiner` converts the error to a succint one-line error message, concatentating the path and message
+- `[Symbol.iterator]` is also available if you want to loop through all children nodes, only those that do not have children themselves.
+
+There is also the static method `StructError.chain(error, context)` which is useful for catching errors and applying a context to them (if they are not already a StructError).
+
 ## Node.js library
 
 There are some specific helpers to help use Gruber in Node.js apps.
@@ -859,7 +1055,7 @@ For older version of Node.js that don't support the latest web-standards,
 there is a polyfil import you can use to add support for them to your runtime.
 
 ```js
-import "gruber/polyfil";
+import "gruber/polyfill.js";
 ```
 
 This currently polyfils these APIs:
@@ -913,6 +1109,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 +1197,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.d.ts

@@ -0,0 +1,59 @@
+export class Configuration {
+    static spec: symbol;
+    /** @param {ConfigurationOptions} options */
+    constructor(options: ConfigurationOptions);
+    /** @type {ConfigurationOptions} */ options: ConfigurationOptions;
+    /**
+     * @template {Record<string, Structure<any>>} T
+     * @param {T} spec
+     * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
+     */
+    object<T extends Record<string, Structure<any>>>(spec: T): Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]>; }>;
+    /**
+     * @template {SpecOptions} Spec @param {Spec} spec
+     * @returns {Structure<string>}
+     */
+    string<Spec extends SpecOptions>(spec?: Spec): Structure<string>;
+    /**
+     * @template {SpecOptions} Spec @param {Spec} spec
+     * @returns {Structure<URL>}
+     */
+    url<Spec_1 extends SpecOptions>(spec: Spec_1): Structure<URL>;
+    /** @param {SpecOptions} spec */
+    _getValue(spec: SpecOptions): string;
+    /**
+     * @template T
+     * @param {URL} url
+     * @param {Structure<T>} spec
+     * @returns {Promise<T>}
+     */
+    load<T_1>(url: URL, spec: Structure<T_1>): Promise<T_1>;
+    /** @template T @param {T} config */
+    getUsage<T_2>(spec: any): string;
+    /**
+     * @template T @param {T} config
+     * @param {string} [prefix]
+     * @returns {{ config: any, fields: [string, string] }}
+     */
+    describeSpecification<T_3>(spec: any, prefix?: string): {
+        config: any;
+        fields: [string, string];
+    };
+    /** @param {Structure<any>} spec */
+    getJSONSchema(spec: Structure<any>): {
+        $schema: string;
+    };
+}
+export type SpecOptions = {
+    variable?: string;
+    flag?: string;
+    fallback: string;
+};
+export type ConfigurationOptions = {
+    readTextFile: (url: URL) => Promise<string | null>;
+    getEnvironmentVariable: (key: string) => (string | undefined);
+    getCommandArgument: (key: string) => (string | undefined);
+    stringify: (value: any) => (string | Promise<string>);
+    parse: (value: string) => (any);
+};
+import { Structure } from "./structures.js";

package/core/configuration.js

@@ -1,4 +1,9 @@
 import { formatMarkdownTable } from "./utilities.js";
+import { Structure, StructError } from "./structures.js";
+
+// NOTE: it would be nice to reverse the object/string/url methods around so they return the "spec" value, then the "struct" is stored under a string. This could mean the underlying architecture could change in the future. I'm not sure if that is possible with the structure nesting in play.
+
+// NOTE: the schema generation will include whatever value is passed to the structure, in the context of configuration it will be whatever is configured and may be something secret
 
 /**
  * @typedef {object} SpecOptions
@@ -9,7 +14,6 @@ import { formatMarkdownTable } from "./utilities.js";
 
 /**
  * @typedef {object} ConfigurationOptions
- * @property {import("superstruct")} superstruct
  * @property {(url: URL) => Promise<string | null>} readTextFile
  * @property {(key: string) => (string | undefined)} getEnvironmentVariable
  * @property {(key: string) => (string | undefined)} getCommandArgument
@@ -18,7 +22,6 @@ import { formatMarkdownTable } from "./utilities.js";
  */
 
 const _requiredOptions = [
-	"superstruct",
 	"readTextFile",
 	"getEnvironmentVariable",
 	"getCommandArgument",
@@ -29,7 +32,7 @@ const _requiredOptions = [
 export class Configuration {
 	static spec = Symbol("Configuration.spec");
 
-	options /** @type {ConfigurationOptions} */;
+	/** @type {ConfigurationOptions} */ options;
 
 	/** @param {ConfigurationOptions} options */
 	constructor(options) {
@@ -39,51 +42,41 @@ export class Configuration {
 		this.options = options;
 	}
 
-	/** @template T @param {T} spec */
+	/**
+	 * @template {Record<string, Structure<any>>} T
+	 * @param {T} spec
+	 * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
+	 */
 	object(spec) {
-		return Object.assign(
-			this.options.superstruct.defaulted(
-				this.options.superstruct.object(spec),
-				{},
-			),
-			{ [Configuration.spec]: { type: "object", value: spec } },
-		);
+		const struct = Structure.object(spec);
+		struct[Configuration.spec] = { type: "object", value: spec };
+		return struct;
 	}
 
 	/**
 	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @returns {Structure<string>}
 	 */
 	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 = Structure.string(this._getValue(spec));
+		struct[Configuration.spec] = { type: "string", value: spec };
+		return struct;
 	}
 
 	/**
 	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @returns {Structure<URL>}
 	 */
 	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),
-			),
-			{ [Configuration.spec]: { type: "url", value: spec } },
-		);
+		const struct = Structure.url(this._getValue(spec));
+		struct[Configuration.spec] = { type: "url", value: spec };
+		return struct;
 	}
 
 	/** @param {SpecOptions} spec */
@@ -102,22 +95,27 @@ export class Configuration {
 	/**
 	 * @template T
 	 * @param {URL} url
-	 * @param {import("superstruct").Struct<T>} spec
+	 * @param {Structure<T>} spec
+	 * @returns {Promise<T>}
 	 */
 	async load(url, spec) {
 		const file = await this.options.readTextFile(url);
 
 		// Catch missing files and create a default configuration
 		if (!file) {
-			return this.options.superstruct.create({}, spec);
+			return spec.process({});
 		}
 
 		// Fail outside the try-catch to surface structure errors
-		return this.options.superstruct.create(
-			await this.options.parse(file),
-			spec,
-			"Configuration failed to parse",
-		);
+		try {
+			return spec.process(await this.options.parse(file));
+		} catch (error) {
+			console.error("Configuration failed to parse");
+			if (error instanceof StructError) {
+				error.message = error.toFriendlyString();
+			}
+			throw error;
+		}
 	}
 
 	/** @template T @param {T} config */
@@ -179,4 +177,9 @@ export class Configuration {
 		}
 		throw new TypeError("Invalid [Configuration.spec].type '" + type + "'");
 	}
+
+	/** @param {Structure<any>} spec */
+	getJSONSchema(spec) {
+		return spec.getSchema();
+	}
 }

package/core/configuration.test.d.ts

@@ -0,0 +1 @@
+export {};