gruber 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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**

package/README.md

@@ -241,11 +241,14 @@ import { getNodeConfiguration } from "gruber";
 const pkg = JSON.parse(fs.readFileSync("./package.json", "utf8"));
 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,12 +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(getSpecification());
+	return config.getJSONSchema(getConfigStruct());
 }
 ```
 
@@ -332,11 +335,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",
+	},
 }
 ```
 
@@ -362,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") {
@@ -808,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");
 ```
 
@@ -821,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`.

package/core/configuration.d.ts

@@ -1,3 +1,70 @@
+/**
+ * @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 */
@@ -5,49 +72,80 @@ export class Configuration {
     /** @type {ConfigurationOptions} */ options: ConfigurationOptions;
     /**
      * @template {Record<string, Structure<any>>} T
-     * @param {T} spec
+     * @param {T} options
      * @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]>; }>;
+    object<T extends Record<string, Structure<any>>>(options: T): Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]>; }>;
     /**
-     * @template {SpecOptions} Spec @param {Spec} spec
+     * @param {SpecOptions<string>} options
      * @returns {Structure<string>}
      */
-    string<Spec extends SpecOptions>(spec?: Spec): Structure<string>;
+    string(options?: SpecOptions<string>): Structure<string>;
+    /**
+     * @param {SpecOptions<number>} options
+     * @returns {Structure<number>}
+     */
+    number(options: SpecOptions<number>): Structure<number>;
     /**
-     * @template {SpecOptions} Spec @param {Spec} spec
+     * @param {SpecOptions<boolean>} options
+     * @returns {Structure<number>}
+     */
+    boolean(options: SpecOptions<boolean>): Structure<number>;
+    /**
+     * @param {SpecOptions<string|URL>} options
      * @returns {Structure<URL>}
      */
-    url<Spec_1 extends SpecOptions>(spec: Spec_1): Structure<URL>;
-    /** @param {SpecOptions} spec */
-    _getValue(spec: SpecOptions): string;
+    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_1>(url: URL, spec: Structure<T_1>): Promise<T_1>;
-    /** @template T @param {T} config */
-    getUsage<T_2>(spec: any): string;
+    load<T_2>(url: URL, spec: Structure<T_2>): Promise<T_2>;
+    /** @param {unknown} value */
+    getUsage(value: unknown): string;
     /**
-     * @template T @param {T} config
+     * @param {unknown} struct
      * @param {string} [prefix]
      * @returns {{ config: any, fields: [string, string] }}
      */
-    describeSpecification<T_3>(spec: any, prefix?: string): {
+    describe(value: any, prefix?: string): {
         config: any;
         fields: [string, string];
     };
-    /** @param {Structure<any>} spec */
-    getJSONSchema(spec: Structure<any>): {
+    /** * @param {Structure<any>} struct */
+    getJSONSchema(struct: Structure<any>): {
         $schema: string;
     };
 }
-export type SpecOptions = {
+export type SpecOptions<T = any> = {
     variable?: string;
     flag?: string;
-    fallback: 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>;

package/core/configuration.js

@@ -6,21 +6,87 @@ import { Structure, StructError } from "./structures.js";
 // 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
 
 /**
+ * @template [T=any]
  * @typedef {object} SpecOptions
  * @property {string} [variable]
  * @property {string} [flag]
- * @property {string} fallback
+ * @property {T} fallback
  */
 
 /**
- * @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
+ * @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, value) {
+	if (
+		typeof value[Configuration.spec] !== "object" ||
+		typeof value[Configuration.spec].type !== "string" ||
+		typeof value[Configuration.spec].options !== "object" ||
+		typeof value[Configuration.spec].describe !== "function"
+	) {
+		throw new TypeError(`Invalid [Configuration.spec] for '${name}'`);
+	}
+	return value[Configuration.spec];
+}
+
+export class _ObjectSpec {
+	/** @param {Record<string, SpecOptions>} options  */
+	constructor(options) {
+		this.type = "object";
+		this.options = options;
+	}
+	describe(name) {
+		const fallback = {};
+		const fields = [];
+		for (const [key, childOptions] of Object.entries(this.options)) {
+			const childName = (name ? name + "." : "") + key;
+			const childSpec = _getSpec(childName, childOptions).describe(childName);
+
+			fallback[key] = childSpec.fallback;
+			fields.push(...childSpec.fields);
+		}
+		return { fallback, fields };
+	}
+}
+
+export class _LiteralSpec {
+	/**
+	 * @param {string} type
+	 * @param {SpecOptions<any>} options
+	 */
+	constructor(type, options) {
+		this.type = type;
+		this.options = options;
+	}
+	describe(name) {
+		return {
+			fallback: this.options.fallback,
+			fields: [{ name, type: this.type, ...this.options }],
+		};
+	}
+}
+
 const _requiredOptions = [
 	"readTextFile",
 	"getEnvironmentVariable",
@@ -29,6 +95,22 @@ const _requiredOptions = [
 	"parse",
 ];
 
+const _booleans = {
+	1: true,
+	true: true,
+	0: false,
+	false: false,
+};
+
+/**
+ * @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("Configuration.spec");
 
@@ -44,52 +126,128 @@ export class Configuration {
 
 	/**
 	 * @template {Record<string, Structure<any>>} T
-	 * @param {T} spec
+	 * @param {T} options
 	 * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
 	 */
-	object(spec) {
-		const struct = Structure.object(spec);
-		struct[Configuration.spec] = { type: "object", value: spec };
+	object(options) {
+		if (typeof options !== "object" || options === null) {
+			throw new TypeError("options must be a non-null object");
+		}
+		const struct = Structure.object(options);
+		struct[Configuration.spec] = new _ObjectSpec(options);
 		return struct;
 	}
 
 	/**
-	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @param {SpecOptions<string>} options
 	 * @returns {Structure<string>}
 	 */
-	string(spec = {}) {
-		if (typeof spec.fallback !== "string") {
-			throw new TypeError("spec.fallback must be a string: " + spec.fallback);
+	string(options = {}) {
+		if (typeof options.fallback !== "string") {
+			throw new TypeError(
+				"options.fallback must be a string: " + options.fallback,
+			);
+		}
+
+		const struct = Structure.string(this._getValue(options).value);
+		struct[Configuration.spec] = new _LiteralSpec("string", options);
+		return struct;
+	}
+
+	/**
+	 * @param {SpecOptions<number>} options
+	 * @returns {Structure<number>}
+	 */
+	number(options) {
+		if (typeof options.fallback !== "number") {
+			throw new TypeError("options.fallback must be a number");
+		}
+
+		const fallback = this._parseFloat(this._getValue(options));
+		const struct = Structure.number(fallback);
+		struct[Configuration.spec] = new _LiteralSpec("number", options);
+		return struct;
+	}
+
+	/**
+	 * @param {SpecOptions<boolean>} options
+	 * @returns {Structure<number>}
+	 */
+	boolean(options) {
+		if (typeof options.fallback !== "boolean") {
+			throw new TypeError("options.fallback must be a boolean");
 		}
-		const struct = Structure.string(this._getValue(spec));
-		struct[Configuration.spec] = { type: "string", value: spec };
+
+		const fallback = this._parseBoolean(this._getValue(options));
+		const struct = Structure.boolean(fallback);
+		struct[Configuration.spec] = new _LiteralSpec("boolean", options);
 		return struct;
 	}
 
 	/**
-	 * @template {SpecOptions} Spec @param {Spec} spec
+	 * @param {SpecOptions<string|URL>} options
 	 * @returns {Structure<URL>}
 	 */
-	url(spec) {
-		if (typeof spec.fallback !== "string") {
-			throw new TypeError("spec.fallback must be a string");
+	url(options) {
+		if (
+			typeof options.fallback !== "string" &&
+			!(options.fallback instanceof URL)
+		) {
+			throw new TypeError("options.fallback must be a string or URL");
 		}
-		const struct = Structure.url(this._getValue(spec));
-		struct[Configuration.spec] = { type: "url", value: spec };
+		const struct = Structure.url(this._getValue(options).value);
+		struct[Configuration.spec] = new _LiteralSpec("url", {
+			...options,
+			fallback: new URL(options.fallback),
+		});
 		return struct;
 	}
 
-	/** @param {SpecOptions} spec */
-	_getValue(spec) {
-		const argument = spec.flag
-			? this.options.getCommandArgument(spec.flag)
+	/**
+	 * @template T
+	 * @param {SpecOptions<T>} options
+	 * @returns {ConfigurationResult<T>}
+	 */
+	_getValue(options) {
+		const argument = options.flag
+			? this.options.getCommandArgument(options.flag)
 			: null;
+		if (argument) return { source: "argument", value: argument };
 
-		const variable = spec.variable
-			? this.options.getEnvironmentVariable(spec.variable)
+		const variable = options.variable
+			? this.options.getEnvironmentVariable(options.variable)
 			: null;
+		if (variable) return { source: "variable", value: variable };
+
+		return { source: "fallback", value: options.fallback };
+	}
 
-		return argument ?? variable ?? spec.fallback;
+	/** @param {ConfigurationResult<number>} result */
+	_parseFloat(result) {
+		if (typeof result.value === "string") {
+			const parsed = Number.parseFloat(result.value);
+			if (Number.isNaN(parsed)) {
+				throw TypeError(`Invalid number: ${result.value}`);
+			}
+			return parsed;
+		}
+		if (typeof result.value === "number") {
+			return result.value;
+		}
+		throw new TypeError("Unknown result");
+	}
+
+	/** @param {ConfigurationResult<boolean>} result */
+	_parseBoolean(result) {
+		if (typeof result.value === "boolean") return result.value;
+
+		if (typeof _booleans[result.value] === "boolean") {
+			return _booleans[result.value];
+		}
+		if (result.source === "argument" && result.value === "") {
+			return true;
+		}
+		throw new TypeError("Unknown result");
 	}
 
 	/**
@@ -118,9 +276,9 @@ export class Configuration {
 		}
 	}
 
-	/** @template T @param {T} config */
-	getUsage(spec) {
-		const { fallback, fields } = this.describeSpecification(spec);
+	/** @param {unknown} value */
+	getUsage(value) {
+		const { fallback, fields } = this.describe(value);
 
 		const lines = [
 			"Usage:",
@@ -140,46 +298,16 @@ export class Configuration {
 	}
 
 	/**
-	 * @template T @param {T} config
+	 * @param {unknown} struct
 	 * @param {string} [prefix]
 	 * @returns {{ config: any, fields: [string, string] }}
 	 */
-	describeSpecification(spec, prefix = "") {
-		if (!spec[Configuration.spec]) {
-			throw new TypeError("Invalid [Configuration.spec]");
-		}
-		const { type, value } = spec[Configuration.spec];
-
-		if (type === "object") {
-			const fallback = {};
-			const fields = [];
-			for (const [key, value2] of Object.entries(value)) {
-				const child = this.describeSpecification(
-					value2,
-					(prefix ? prefix + "." : "") + key,
-				);
-				fallback[key] = child.fallback;
-				fields.push(...child.fields);
-			}
-			return { fallback, fields };
-		}
-		if (type === "string") {
-			return {
-				fallback: value.fallback,
-				fields: [{ name: prefix, type, ...value }],
-			};
-		}
-		if (type === "url") {
-			return {
-				fallback: new URL(value.fallback),
-				fields: [{ name: prefix, type, ...value }],
-			};
-		}
-		throw new TypeError("Invalid [Configuration.spec].type '" + type + "'");
+	describe(value, prefix = "") {
+		return _getSpec(prefix || ".", value).describe(prefix);
 	}
 
-	/** @param {Structure<any>} spec */
-	getJSONSchema(spec) {
-		return spec.getSchema();
+	/** * @param {Structure<any>} struct */
+	getJSONSchema(struct) {
+		return struct.getSchema();
 	}
 }