gruber 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 This file documents notable changes to the project
 
+## 0.4.0
+
+**new**
+
+- Added `config.number(...)` & `config.boolean(...)` types along with `Structure` equivolents.
+- Set a response body when creating a `HTTPError`, either via the constructor or the static methods.
+- Set headers when creating an `HTTPError` and mutate the headers on it too, to be passed to the Response.
+- Structure primatives' fallback is now optional. If a fallback isn't provided, validation will fail if with a "Missing value" if no value is provided.
+- Added an unstable/experimental `Structure.array` for validating an array of a single Structure, e.g. an array of strings.
+- Add number and boolean configurations (and their structures)
+
+**fixes**
+
+- Improve JSDoc types for Deno / Node clients
+- Fix Structure typings
+- Organise Config/Structure/Spec wording
+
+## 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**

package/README.md

@@ -235,17 +235,20 @@ 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() {
+export function getConfigStruct() {
 	return config.object({
-		env: config.string({
-			variable: "NODE_ENV",
-			fallback: "development",
+		env: config.string({ variable: "NODE_ENV", fallback: "development" }),
+
+		port: config.number({
+			variable: "APP_PORT",
+			flag: "--port",
+			fallback: 8000,
 		}),
 
 		selfUrl: config.url({
@@ -253,13 +256,13 @@ export function getSpecification() {
 			fallback: "http://localhost:3000",
 		}),
 
-		// Short hands?
 		meta: config.object({
 			name: config.string({ flag: "--app-name", fallback: pkg.name }),
 			version: config.string({ fallback: pkg.version }),
 		}),
 
 		database: config.object({
+			useSsl: config.boolean({ flag: "--database-ssl", fallback: true }),
 			url: config.url({
 				variable: "DATABASE_URL",
 				flag: "--database-url",
@@ -271,11 +274,11 @@ export function getSpecification() {
 
 // Load the configuration and parse it
 export function loadConfiguration(path) {
-	return config.load(path, getSpecification());
+	return config.load(path, getConfigStruct());
 }
 
 // TypeScript thought:
-// export type Configuration = Infer<ReturnType<typeof getSpecification>>
+// export type Configuration = Infer<ReturnType<typeof getConfigStruct>>
 
 // Expose the configutation for use in the application
 export const appConfig = await loadConfiguration(
@@ -284,7 +287,12 @@ export const appConfig = await loadConfiguration(
 
 // Export a method to generate usage documentation
 export function getConfigurationUsage() {
-	return config.getUsage(getSpecification());
+	return config.getUsage(getConfigStruct());
+}
+
+// Export a method to generate a JSON Schema for the configuration
+export function getConfigurationSchema() {
+	return config.getJSONSchema(getConfigStruct());
 }
 ```
 
@@ -357,7 +365,7 @@ this can be done like so:
 
 ```js
 export function loadConfiguration() {
-	const appConfig = config.loadJsonSync(path, getSpecification());
+	const appConfig = config.loadJsonSync(path, getConfigStruct());
 
 	// Only run these checks when running in production
 	if (appConfig.env === "production") {
@@ -672,7 +680,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
@@ -684,10 +691,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),
@@ -805,6 +811,8 @@ more can be added in the future as the need arrises.
 They directly map to HTTP error as codes documented on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
 
 ```js
+import { HTTPError } from "gruber";
+
 const teapot = new HTTPError(418, "I'm a teapot");
 ```
 
@@ -818,6 +826,55 @@ 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.
 
+**Request body**
+
+You can set the body to be returned when the HTTPError is thrown from the constructor or the factory methods:
+
+```ts
+import { HTTPError } from "gruber";
+
+const teapot = new HTTPError(418, "I'm a teapot", "model=teabot-5000");
+
+throw HTTPError.badRequest("no coffee provided");
+```
+
+The value of the body is the same as the `body` in the
+[Response constructor](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#body).
+
+**Headers**
+
+> _EXPERIMENTAL_
+
+If you really want, you can set headers on a HTTPError too:
+
+```ts
+import { HTTPError } from "gruber";
+
+const teapot = new HTTPError(
+	400,
+	"Bad Request",
+	JSON.stringify({ some: "thing" }),
+	{ "Content-Type": "application/json" },
+);
+
+// or via mutating the headers object
+teapot.headers.set("X-HOTEL-BAR", "Hotel Bar?");
+```
+
+If you want fine-grain control, you might be better off creating a subclass, e.g. `BadJSONRequest`:
+
+```ts
+class BadJSONRequest extends HTTPError {
+	constructor(body) {
+		super(400, "Bad Request", body, { "Content-type": "application/json" });
+		this.name = "BadJSONRequest";
+		Error.captureStackTrace(this, BadJSONRequest);
+	}
+}
+
+throw new BadJSONRequest({ message: "Something went wrong..." });
+```
+
 ### FetchRouter
 
 `FetchRouter` is a web-native router for routes defined with `defineRoute`.
@@ -870,7 +927,7 @@ You can use it and override parts of it to customise how the postgres migrator w
 
 ### Utilities
 
-### loader
+#### loader
 
 `loader` let's you memoize the result of a function to create a singleton from it.
 It works synchronously or with promises.
@@ -914,6 +971,89 @@ This will generate the table:
 | 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.
@@ -969,7 +1109,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:

package/core/configuration.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @template [T=any]
+ * @typedef {object} SpecOptions
+ * @property {string} [variable]
+ * @property {string} [flag]
+ * @property {T} fallback
+ */
+/**
+ * @template T
+ * @typedef {object} ConfigurationResult
+ * @property {'argument' | 'variable' | 'fallback'} source
+ * @property {string|T} value
+ */
+/**
+ * @typedef {object} ConfigurationDescription
+ * @property {unknown} fallback
+ * @property {Record<string,string>[]} fields
+ */
+/**
+ * @typedef {object} Specification
+ * @property {string} type
+ * @property {any} options
+ * @property {(name: string) => ConfigurationDescription} describe
+ */
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @returns {Specification}
+ */
+export function _getSpec(name: string, value: unknown): Specification;
+export class _ObjectSpec {
+    /** @param {Record<string, SpecOptions>} options  */
+    constructor(options: Record<string, SpecOptions>);
+    type: string;
+    options: Record<string, SpecOptions<any>>;
+    describe(name: any): {
+        fallback: {};
+        fields: Record<string, string>[];
+    };
+}
+export class _LiteralSpec {
+    /**
+     * @param {string} type
+     * @param {SpecOptions<any>} options
+     */
+    constructor(type: string, options: SpecOptions<any>);
+    type: string;
+    options: SpecOptions<any>;
+    describe(name: any): {
+        fallback: any;
+        fields: {
+            variable?: string;
+            flag?: string;
+            fallback: any;
+            name: any;
+            type: string;
+        }[];
+    };
+}
+/**
+ * @typedef {object} ConfigurationOptions
+ * @property {(url: URL) => Promise<string | null>} readTextFile
+ * @property {(key: string) => (string | undefined)} getEnvironmentVariable
+ * @property {(key: string) => (string | undefined)} getCommandArgument
+ * @property {(value: any) => (string | Promise<string>)} stringify
+ * @property {(value: string) => (any)} parse
+ */
+export class Configuration {
+    static spec: symbol;
+    /** @param {ConfigurationOptions} options */
+    constructor(options: ConfigurationOptions);
+    /** @type {ConfigurationOptions} */ options: ConfigurationOptions;
+    /**
+     * @template {Record<string, Structure<any>>} T
+     * @param {T} options
+     * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
+     */
+    object<T extends Record<string, Structure<any>>>(options: T): Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]>; }>;
+    /**
+     * @param {SpecOptions<string>} options
+     * @returns {Structure<string>}
+     */
+    string(options?: SpecOptions<string>): Structure<string>;
+    /**
+     * @param {SpecOptions<number>} options
+     * @returns {Structure<number>}
+     */
+    number(options: SpecOptions<number>): Structure<number>;
+    /**
+     * @param {SpecOptions<boolean>} options
+     * @returns {Structure<number>}
+     */
+    boolean(options: SpecOptions<boolean>): Structure<number>;
+    /**
+     * @param {SpecOptions<string|URL>} options
+     * @returns {Structure<URL>}
+     */
+    url(options: SpecOptions<string | URL>): Structure<URL>;
+    /**
+     * @template T
+     * @param {SpecOptions<T>} options
+     * @returns {ConfigurationResult<T>}
+     */
+    _getValue<T_1>(options: SpecOptions<T_1>): ConfigurationResult<T_1>;
+    /** @param {ConfigurationResult<number>} result */
+    _parseFloat(result: ConfigurationResult<number>): number;
+    /** @param {ConfigurationResult<boolean>} result */
+    _parseBoolean(result: ConfigurationResult<boolean>): any;
+    /**
+     * @template T
+     * @param {URL} url
+     * @param {Structure<T>} spec
+     * @returns {Promise<T>}
+     */
+    load<T_2>(url: URL, spec: Structure<T_2>): Promise<T_2>;
+    /** @param {unknown} value */
+    getUsage(value: unknown): string;
+    /**
+     * @param {unknown} struct
+     * @param {string} [prefix]
+     * @returns {{ config: any, fields: [string, string] }}
+     */
+    describe(value: any, prefix?: string): {
+        config: any;
+        fields: [string, string];
+    };
+    /** * @param {Structure<any>} struct */
+    getJSONSchema(struct: Structure<any>): {
+        $schema: string;
+    };
+}
+export type SpecOptions<T = any> = {
+    variable?: string;
+    flag?: string;
+    fallback: T;
+};
+export type ConfigurationResult<T> = {
+    source: 'argument' | 'variable' | 'fallback';
+    value: string | T;
+};
+export type ConfigurationDescription = {
+    fallback: unknown;
+    fields: Record<string, string>[];
+};
+export type Specification = {
+    type: string;
+    options: any;
+    describe: (name: string) => ConfigurationDescription;
+};
+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";