gruber 0.2.0 → 0.3.0

package/CHANGELOG.md

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

package/README.md

@@ -235,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({
@@ -286,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
@@ -327,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"
+	}
 }
 ```
 
@@ -672,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
@@ -684,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),
@@ -870,7 +873,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 +917,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 +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:

package/{types/core → core}/configuration.d.ts

@@ -1,33 +1,33 @@
-/** @typedef {Record<string, import("superstruct").Struct<any, any>>} ObjectSchema */
 export class Configuration {
     static spec: symbol;
     /** @param {ConfigurationOptions} options */
     constructor(options: ConfigurationOptions);
-    options: ConfigurationOptions;
+    /** @type {ConfigurationOptions} */ options: ConfigurationOptions;
     /**
-     * @template {ObjectSchema} T
+     * @template {Record<string, Structure<any>>} T
      * @param {T} spec
+     * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
      */
-    object<T extends ObjectSchema>(spec: T): any;
+    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 {import("superstruct").Struct<string, null>}
+     * @returns {Structure<string>}
      */
-    string<Spec extends SpecOptions>(spec?: Spec): any;
+    string<Spec extends SpecOptions>(spec?: Spec): Structure<string>;
     /**
      * @template {SpecOptions} Spec @param {Spec} spec
-     * @returns {import("superstruct").Struct<URL, null>}
+     * @returns {Structure<URL>}
      */
-    url<Spec_1 extends SpecOptions>(spec: Spec_1): any;
+    url<Spec_1 extends SpecOptions>(spec: Spec_1): Structure<URL>;
     /** @param {SpecOptions} spec */
     _getValue(spec: SpecOptions): string;
     /**
      * @template T
      * @param {URL} url
-     * @param {import("superstruct").Struct<T>} spec
+     * @param {Structure<T>} spec
      * @returns {Promise<T>}
      */
-    load<T_1>(url: URL, spec: any): Promise<T_1>;
+    load<T_1>(url: URL, spec: Structure<T_1>): Promise<T_1>;
     /** @template T @param {T} config */
     getUsage<T_2>(spec: any): string;
     /**
@@ -39,6 +39,10 @@ export class Configuration {
         config: any;
         fields: [string, string];
     };
+    /** @param {Structure<any>} spec */
+    getJSONSchema(spec: Structure<any>): {
+        $schema: string;
+    };
 }
 export type SpecOptions = {
     variable?: string;
@@ -46,12 +50,10 @@ export type SpecOptions = {
     fallback: string;
 };
 export type ConfigurationOptions = {
-    superstruct: typeof import("superstruct");
     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);
 };
-export type ObjectSchema = Record<string, import("superstruct").Struct<any, any>>;
-//# sourceMappingURL=configuration.d.ts.map
+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",
@@ -26,12 +29,10 @@ const _requiredOptions = [
 	"parse",
 ];
 
-/** @typedef {Record<string, import("superstruct").Struct<any, any>>} ObjectSchema */
-
 export class Configuration {
 	static spec = Symbol("Configuration.spec");
 
-	options /** @type {ConfigurationOptions} */;
+	/** @type {ConfigurationOptions} */ options;
 
 	/** @param {ConfigurationOptions} options */
 	constructor(options) {
@@ -42,52 +43,40 @@ export class Configuration {
 	}
 
 	/**
-	 * @template {ObjectSchema} T
+	 * @template {Record<string, Structure<any>>} T
 	 * @param {T} spec
+	 * @returns {Structure<{ [K in keyof T]: import("./structures.js").Infer<T[K]> }>}
 	 */
 	object(spec) {
-		const struct = this.options.superstruct.defaulted(
-			this.options.superstruct.object(spec),
-			{},
-		)
-		struct[Configuration.spec]= { type: "object", value: spec }
-		return struct
+		const struct = Structure.object(spec);
+		struct[Configuration.spec] = { type: "object", value: spec };
+		return struct;
 	}
 
 	/**
 	 * @template {SpecOptions} Spec @param {Spec} spec
-	 * @returns {import("superstruct").Struct<string, null>}
+	 * @returns {Structure<string>}
 	 */
 	string(spec = {}) {
 		if (typeof spec.fallback !== "string") {
 			throw new TypeError("spec.fallback must be a string: " + spec.fallback);
 		}
-		const struct = this.options.superstruct.defaulted(
-			this.options.superstruct.string(),
-			this._getValue(spec),
-		)
-		struct[Configuration.spec] = { type: "string", value: spec }
-		return struct
+		const struct = Structure.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>}
+	 * @returns {Structure<URL>}
 	 */
 	url(spec) {
 		if (typeof spec.fallback !== "string") {
 			throw new TypeError("spec.fallback must be a string");
 		}
-		const struct = this.options.superstruct.defaulted(
-			this.options.superstruct.coerce(
-				this.options.superstruct.instance(URL),
-				this.options.superstruct.string(),
-				(value) => new URL(value),
-			),
-			this._getValue(spec),
-		)
-		struct[Configuration.spec]= { type: "url", value: spec }
-		return struct
+		const struct = Structure.url(this._getValue(spec));
+		struct[Configuration.spec] = { type: "url", value: spec };
+		return struct;
 	}
 
 	/** @param {SpecOptions} spec */
@@ -106,7 +95,7 @@ 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) {
@@ -114,15 +103,19 @@ export class Configuration {
 
 		// 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 */
@@ -184,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 {};

package/core/configuration.test.js

@@ -1,10 +1,8 @@
 import { Configuration } from "./configuration.js";
-import { assertEquals, assertThrows } from "./test-deps.js";
-import { superstruct } from "./test-deps.js";
+import { assertEquals, assertThrows, describe, it } from "./test-deps.js";
 
 /** @type {import("./configuration.js").ConfigurationOptions} */
 const bareOptions = {
-	superstruct,
 	readTextFile() {},
 	getEnvironmentVariable(_key) {},
 	getCommandArgument(_key) {},
@@ -12,11 +10,10 @@ const bareOptions = {
 	parse(_value) {},
 };
 
-Deno.test("Configuration", async ({ step }) => {
-	await step("constructor", async ({ step }) => {
-		await step("validates options", () => {
+describe("Configuration", () => {
+	describe("constructor", () => {
+		it("validates options", () => {
 			new Configuration({
-				superstruct,
 				readTextFile() {},
 				getEnvironmentVariable(_key) {},
 				getCommandArgument(_key) {},
@@ -26,30 +23,28 @@ Deno.test("Configuration", async ({ step }) => {
 		});
 	});
 
-	await step("object", async ({ step }) => {
+	describe("object", () => {
 		const config = new Configuration(bareOptions);
 
-		await step("stores spec", () => {
+		it("stores the spec", () => {
 			const result = config.object({});
 			assertEquals(result[Configuration.spec].type, "object");
 			assertEquals(result[Configuration.spec].value, {});
 		});
 	});
 
-	await step("string", async ({ step }) => {
+	describe("string", () => {
 		const config = new Configuration(bareOptions);
 
-		await step("requires a fallback", () => {
+		it("requires a fallback", () => {
 			assertThrows(() => config.string({}), TypeError);
 		});
-
-		await step("uses the fallback", () => {
+		it("uses the fallback", () => {
 			const struct = config.string({ fallback: "Geoff Testington" });
-			const result = superstruct.create(undefined, struct);
+			const result = struct.process(undefined);
 			assertEquals(result, "Geoff Testington");
 		});
-
-		await step("stores spec", () => {
+		it("stores the spec", () => {
 			const result = config.string({
 				variable: "SOME_VAR",
 				fallback: "value",
@@ -62,26 +57,23 @@ Deno.test("Configuration", async ({ step }) => {
 		});
 	});
 
-	await step("url", async ({ step }) => {
+	describe("url", () => {
 		const config = new Configuration(bareOptions);
 
-		await step("requires a fallback", () => {
+		it("requires a fallback", () => {
 			assertThrows(() => config.url({}), TypeError);
 		});
-
-		await step("converts to URL", () => {
-			const struct = config.url({ fallback: "" });
-			const result = superstruct.create("https://example.com", struct);
+		it("converts to URL", () => {
+			const struct = config.url({ fallback: "https://fallback.example.com" });
+			const result = struct.process("https://example.com");
 			assertEquals(result, new URL("https://example.com"));
 		});
-
-		await step("uses the fallback", () => {
-			const struct = config.url({ fallback: "https://example.com" });
-			const result = superstruct.create(undefined, struct);
-			assertEquals(result, new URL("https://example.com"));
+		it("uses the fallback", () => {
+			const struct = config.url({ fallback: "https://fallback.example.com" });
+			const result = struct.process(undefined);
+			assertEquals(result, new URL("https://fallback.example.com"));
 		});
-
-		await step("stores spec", () => {
+		it("stores the spec", () => {
 			const result = config.url({
 				variable: "SOME_VAR",
 				fallback: "https://example.com",
@@ -94,8 +86,8 @@ Deno.test("Configuration", async ({ step }) => {
 		});
 	});
 
-	await step("_getValue", async ({ step }) => {
-		await step("uses arguments", () => {
+	describe("_getValue", () => {
+		it("uses arguments", () => {
 			const args = { "--option": "value-from-arg" };
 			const config = new Configuration({
 				...bareOptions,
@@ -106,8 +98,7 @@ Deno.test("Configuration", async ({ step }) => {
 			});
 			assertEquals(result, "value-from-arg");
 		});
-
-		await step("uses environment variables", () => {
+		it("uses environment variables", () => {
 			const env = { MY_VAR: "value-from-env" };
 			const config = new Configuration({
 				...bareOptions,
@@ -118,15 +109,14 @@ Deno.test("Configuration", async ({ step }) => {
 			});
 			assertEquals(result, "value-from-env");
 		});
-
-		await step("uses the fallback", () => {
+		it("uses the fallback", () => {
 			const config = new Configuration(bareOptions);
 			const result = config._getValue({ fallback: "value-from-fallback" });
 			assertEquals(result, "value-from-fallback");
 		});
 	});
 
-	await step("load", async ({ step }) => {
+	describe("load", () => {
 		const files = {
 			"config.json":
 				'{"env":"production","meta":{"version":"1.2.3"},"selfUrl":"https://example.com"}',
@@ -146,7 +136,7 @@ Deno.test("Configuration", async ({ step }) => {
 			selfUrl: config.url({ fallback: "http://localhost" }),
 		});
 
-		await step("loads config", async () => {
+		it("loads config", async () => {
 			const result = await config.load("config.json", spec);
 			assertEquals(result, {
 				env: "production",
@@ -155,7 +145,7 @@ Deno.test("Configuration", async ({ step }) => {
 			});
 		});
 
-		await step("uses the fallback", async () => {
+		it("uses the fallback", async () => {
 			const result = await config.load("missing-config.json", spec);
 			assertEquals(result, {
 				env: "development",
@@ -165,8 +155,8 @@ Deno.test("Configuration", async ({ step }) => {
 		});
 	});
 
-	await step("describeSpecification", async ({ step }) => {
-		await step("processes strings", () => {
+	describe("describeSpecification", () => {
+		it("processes strings", () => {
 			const config = new Configuration(bareOptions);
 			const result = config.describeSpecification(
 				config.string({
@@ -188,7 +178,7 @@ Deno.test("Configuration", async ({ step }) => {
 			]);
 		});
 
-		await step("processes urls", () => {
+		it("processes urls", () => {
 			const config = new Configuration(bareOptions);
 			const result = config.describeSpecification(
 				config.url({
@@ -210,7 +200,7 @@ Deno.test("Configuration", async ({ step }) => {
 			]);
 		});
 
-		await step("processes objects", () => {
+		it("processes objects", () => {
 			const config = new Configuration(bareOptions);
 			const result = config.describeSpecification(
 				config.object({

package/{types/core → core}/fetch-router.d.ts

@@ -49,4 +49,3 @@ export type FetchRouterOptions = {
     routes?: import("./types.ts").RouteDefinition<any>[];
     errorHandler?: RouteErrorHandler;
 };
-//# sourceMappingURL=fetch-router.d.ts.map

package/core/fetch-router.test.d.ts

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

package/{types/core → core}/http.d.ts

@@ -52,4 +52,3 @@ export type RouteContext<T> = import("./types.ts").RouteContext<T>;
 export type RouteHandler<T> = import("./types.ts").RouteHandler<T>;
 export type RouteOptions<T extends string> = import("./types.ts").RouteOptions<T>;
 export type RouteDefinition<T = any> = import("./types.ts").RouteDefinition<T>;
-//# sourceMappingURL=http.d.ts.map

package/core/http.test.d.ts

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

package/{types/core → core}/migrator.d.ts

@@ -53,4 +53,3 @@ export type MigratorOptions<T> = {
     getRecords: () => Promise<MigrationRecord[]>;
     execute: (def: MigrationDefinition<T>, direction: "up" | "down") => void | Promise<void>;
 };
-//# sourceMappingURL=migrator.d.ts.map

package/core/migrator.test.d.ts

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

package/{types/core → core}/mod.d.ts

@@ -4,4 +4,3 @@ export * from "./http.js";
 export * from "./migrator.js";
 export * from "./postgres.js";
 export * from "./utilities.js";
-//# sourceMappingURL=mod.d.ts.map

package/{types/core → core}/postgres.d.ts

@@ -40,4 +40,3 @@ export type MigrationDefinition = import("./migrator.js").MigrationDefinition;
 export type PostgresMigratorOptions = {
     sql: Sql;
 };
-//# sourceMappingURL=postgres.d.ts.map