gruber 0.9.0-beta.2 → 0.9.0

package/CHANGELOG.md

@@ -24,7 +24,12 @@ This file documents notable changes to the project
 - `assertRequestBody` can return a Promise if you pass a request,
   where it will use `getRequestBody` to get the body then validate it
 - Add `createStoppable` to Node.js module and apply it to `serveHTTP`
-- Add `testing` module with utilities, stubs, fakes and a testing router
+- Add experimental `testing` module with utilities, stubs, fakes and a testing router
+- Add `preventExtraction` and `dangerouslyExpose` to core module
+- (WIP) Attempting to `JSON.stringify` any values from configuration value now throws a TypeError
+- Add experimental wildcard HTTP methods
+- Add HTTP OPTIONS requests when enabling cors
+- Add experimental `terminator.waitForSignals()` async method
 
 **improved**
 
@@ -35,12 +40,19 @@ This file documents notable changes to the project
 - Simplified `Structure` and `config` generics with nested structures
 - Update `urlpattern-polyfill` to 10.1.0
 - Move to erasable TypeScript code
+- Store conforms to AsyncDisposable
+- FetchRouter — log HTTP errors when `options.log` is set and `errorHandler` is not
+- FetchRouter — Attempt to apply internal middleware during error handling too
 
 **fixes**
 
 - `AbstractAuthorizationService` includes assert's `options` parameter
 - Configuration correctly follows `flags > env > json > fallback`
 - `Structure.object` sets required fields in schema
+- Internaly use `verbatimModuleSyntax` to be more JavaScript agnostic
+- Remove use of conditional imports in the node polyfil
+- `FetchRouter` internally applies middleware during error handling too
+- node - terminate the stream if the ServerResponse is cancelled
 
 **deprecations**
 

package/README.md

@@ -11,61 +11,100 @@ An isomorphic JavaScript library for creating web apps.
 
 ## Contents
 
-- [Quick tour](/quick-tour/) — a whistle-stop tour of all of Gruber
-- [Core](/core/) — essential primitives that use or build on web-standards
-- [HTTP](/http/) — quickly define server endpoints
-- [Configuration](/config/) — specify exactly how to configure your application
-- [Migrations](/core#migrations) — curate how to migrate your state
-- [Testing](/testing/) — ensure your code does what you thought it does
-- [Node](/node/) — easily use Gruber in Node.js
-- [Deno](/deno/) — easily use Gruber in Deno
-- [Examples](/examples/) — more in-depth use cases and patterns
+- [Install](#install)
+- [Quick tour](/quick-tour/) — a whistle-stop tour of everything
+- [Core](/core/) — essentials that use or build on web-standards
+- [HTTP](/http/) — quickly create server endpoints
+- [Configuration](/config/) — declaratively configure your application
+- [Migrations](/core#migrations) — specify transitions between application state
+- [Testing](/testing/) — ensure your code does what you expected
 
 ## About
 
-Gruber is a collection of modules for creating isomorphic JavaScript applications, that means web-standards JavaScript on the front- and back-end. It's a bet that web-standards aren't going to change, so our apps don't break in the future. There's also a hope that [WinterTG](https://wintertc.org/work) works some stuff out. (Previously WinterCG, which is a good step!)
+Gruber is a collection of modules for creating isomorphic JavaScript applications.
+That means using the same web standards developed for the browser in backend runtimes.
+Web-standards aren't going to change, so apps based on them are less likely break in the future.
+There's also a hope that [WinterTG](https://wintertc.org/work) works some stuff out.
 
 Gruber acknowledges that web-standards don't do everything we want (at least yet!) and that they aren't implemented properly everywhere either.
-For this reason, the core of Gruber is agnostic and attempts to make sensible building blocks on top of them. Then there are **helpers** for using specific runtimes and **modules** that build around those common primitives.
+For this reason, Gruber tries to be as agnostic as possible and makes building blocks on top of them.
+There are **integrations** with specific runtimes & libraries and **modules** that build around those common primitives.
 
-Gruber itself is a library and can be used however you like. The rest are **patterns** which you can apply if you like.
+Gruber itself is a library and can be used however you like.
+There are also **patterns** which you can apply if you like.
 Patterns are ways of structuring your code if you don't already have opinions on the matter.
 They also help to explain why Gruber is made in the way it is.
 
 There is a lot not in Gruber too. By design it tries to be as minimal as possible.
-For examples, there is a development CORs implementation but a production app should be run behind a reverse proxy and that can do those things for you.
 
-## Why does this exist
+## Terms
 
-I've spent the past few years working on JavaScript backends and nothing has really stuck with me.
-There have been lots of nice ideas along the way but no one solution ever felt like home.
-It always felt like starting from scratch for each project.
+These are a few words that pop-up in the documentation, often in bold,
+here is what they mean in the context of Gruber:
 
-Some of the apps I've made:
+- **standards** — well-known, non-proprietary, formal and agreed specifications
+- **modules** — code built around web-standards and the common core
+- **integrations** — a module integrating with a specific JavaScript runtime or library
+- **patterns** — optional but recommended best-practices you can adopt
+- **isomorphic** — running the same JavaScript on the front and backend
 
-- [Open Lab Hub](https://github.com/digitalinteraction/hub.openlab.dev) — Deno + Oak + vue3 + vite
-- [BeanCounter](https://github.com/digitalinteraction/beancounter) — Node.js + Koa + vanilla js + parcel
-- [MozFest Plaza](https://github.com/digitalinteraction/mozfest) — Node.js + Koa + vue2 + webpack
-- [Sticker Stories](https://github.com/digitalinteraction/sticker-stories) — Node.js + Koa + vue3 + vite
-- [Data Diaries](https://github.com/digitalinteraction/data-diaries) — Node.js + Koa + vue3 + vite
-- [DataOfficer](https://github.com/digitalinteraction/data-officer) — Deno + Acorn
-- [IrisMsg](https://github.com/digitalinteraction/iris-msg/tree/master) — Node.js + Express + native app
-- [Poster Vote](https://github.com/digitalinteraction/poster-vote) — Node.js + Express + vue + webpack
+## Background
+
+I've spent several years working on JavaScript backends and nothing has really stuck with me.
+There have been lots of nice ideas along the way but no one solution ever felt like home.
+It always felt like starting from scratch for each project.
 
 Many frameworks expect you to be making the next big platform with millions of users,
 I don't expect this to be true and would prefer to keep things as simple as possible for the projects I am working on.
 
-I'm also quite wary of going all-in on a big tech company's library or framework,
-having explored lots of them on smaller projects.
-The fatigue from breaking changes or deprecations is real,
-"move fast and break things" sounds great but it creates a lot of maintenance when you work of lots of small projects in small teams.
+I'm also quite wary of going all-in on a big tech company's library or framework.
+Having explored lots of them, the fatigue from breaking changes or deprecations is real.
+"Move fast and break things" sounds great but it creates a lot of maintenance,
+especially for small projects and teams.
+
+I'd prefer a style of **move slow and deliberate**.
+So I use Gruber in a project and develop features within that project.
+Then if I find myself copy-pasting those modules between projects,
+I'll look into ways of contributing them back to the library.
 
 ## Principles
 
-- Composability — logic should be composed together rather than messily intertwined
-- Standards based — where available existing standards should be applied or migrated towards
-- Agnostic — a frontend framework or backend runtime shouldn't be forced upon you
-- Patterns — how you _could_ use modules rather than enforce an implementation
-- Minimal — start small, carefully add features and consider removing them
-- Holistic — by owning the tech-stack it creates unique opportunities for integration
-- No magic — it's confusing when you don't know whats going on
+- **Standardised & Compatible** — use existing standards, migrate towards them and try not to break things
+- **Agnostic** — libraries, frameworks or runtimes shouldn't be forced upon you
+- **Patterns** — optional best-practises for how to use modules
+- **Composability** — logic should be composed together rather than messily intertwined
+- **Minimal & Deliberate** — carefully add only what's is necessary
+- **Holistic** — complete ownership and careful abstractions creates unique opportunities for integration
+- **No magic** — it's confusing when you don't know what's going on
+
+## Standards
+
+Here is a non-exclusive list of standards that Gruber uses or is interested in.
+
+- [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) — used extensively in the HTTP module
+- [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) — is used within `FetchRouter`
+- [StandardSchema V1](https://standardschema.dev/) — is supported by `Structure` and `assertRequestBody`
+- [JSONSchema](https://json-schema.org/) — is used inside `Structure` and can be generated.
+
+Maybe
+
+- [OpenAPI](https://swagger.io/specification/)
+- Open CLI?
+
+## Direction
+
+Here are places I want to explore next.
+
+- [CLI](https://github.com/robb-j/gruber/issues/54) — declaratively define command line interfaces
+- Frontend configuration — using the `config` module on the front-end
+- SQL — an abstraction over database communication
+- Open API, HTTP documentation & JS client generation
+- Dependencies — a system for defining interdependent modules and controlling their lifecycle
+- Events — ways of broadcasting and consuming them with different topologies
+- [Even more →](https://github.com/robb-j/gruber/issues)
+
+## Get Started
+
+- [Take the tour →](/tour/)
+- [Get started with Node.js →](/node/)
+- [Get started with Deno →](/deno/)

package/config/configuration.d.ts

@@ -2,13 +2,50 @@ import { Structure } from "./structure.ts";
 import { type ConfigurationDescription, type PrimativeOptions } from "./specifications.ts";
 import { type ConfigurationResult } from "./parsers.ts";
 import { type StructContext } from "./struct-context.ts";
+/**
+ * @group Configuration
+ *
+ * Options for creating a platform-sepcific {@link Configuration} object,
+ * different methods provide abstractions over the filesystem & parsing capabilities of the Configuration.
+ *
+ * For instance, you could create one that loads remote files over S3 and parses them as YAML,
+ * or just a simple one that loads JSON files from the filesystem
+ */
 export interface ConfigurationOptions {
+    /** Read in a file and decode it as text, or return null if it doesn't exist */
     readTextFile(url: URL | string): Promise<string | null>;
+    /** Get a specific environment variable, or undefined if it is not set */
     getEnvironmentVariable(key: string): string | undefined;
+    /** Get a specific CLI option, like `--some-thing`, or undefined if it is not set */
     getCommandArgument(key: string): string | undefined;
+    /** Convert an in-memory value to a string for displaying to the user */
     stringify(value: any): string | Promise<string>;
+    /** Parse a text file into in-memory values */
     parse(value: string): any;
 }
+/**
+ * @group Configuration
+ *
+ * **Configuration** is both an abstraction around processing config files,
+ * environment variables & CLI flags from the platform
+ * and also a tool for users to declaratively define how their configuration is.
+ *
+ * Each platform specifies a default `options` to load JSON files,
+ * but you can also construct your own if you want to customise how it works.
+ *
+ * With an instance, you can then define how an app's config can be specified as either configuration files,
+ * CLI flag, environment variables or a combination of any of them.
+ *
+ * ```js
+ * const config = new Configuration({
+ * 	readTextFile(url) {},
+ * 	getEnvironmentVariable(key) {},
+ * 	getCommandArgument() {},
+ * 	stringify(value) {},
+ * 	parse(value) {},
+ * })
+ * ```
+ */
 export declare class Configuration {
     static readonly spec: unique symbol;
     options: ConfigurationOptions;
@@ -16,18 +53,152 @@ export declare class Configuration {
     _loadValue<T>(path: string | URL, structure: Structure<T>, context: StructContext): Promise<T | null>;
     /** Wrap a primativ Structure with configuration logic */
     _primative<T>(struct: Structure<T>, options: PrimativeOptions<T>, deconfigure: (result: ConfigurationResult) => unknown): Structure<T>;
+    /**
+     * Group or nest configuration in an object.
+     *
+     * ```js
+     * config.object({
+     * 	name: config.string({ fallback: "Geoff Testington" }),
+     * 	age: config.number({ fallback: 42 }),
+     * })
+     * ```
+     */
     object<T extends Record<string, unknown>>(fields: {
         [K in keyof T]: Structure<T[K]>;
     }): Structure<T>;
+    /**
+     * @unstable
+     *
+     * Create an ordered list of another type
+     *
+     * ```js
+     * config.array(
+     * 	Structure.string()
+     * )
+     * ```
+     */
     array<T extends unknown>(item: Structure<T>): Structure<T[]>;
+    /**
+     * @unstable
+     *
+     * Load another configuration file or use value in the original configuration
+     *
+     * ```js
+     * config.external(
+     * 	new URL("./api-keys.json", import.meta.url),
+     * 	config.object({
+     * 		keys: Structure.array(Structure.string())
+     * 	})
+     * )
+     * ```
+     *
+     * Which will attempt to load "api-keys.json" and parse that,
+     * and if that doesn't exist it will also try the value in the original configuration.
+     */
     external<T extends Record<string, unknown> | Array<unknown>>(path: string | URL, struct: Structure<T>): Structure<T>;
+    /**
+     * Define a string-based value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * ```js
+     * config.string({
+     * 	variable: "HOSTNAME",
+     * 	flag: "--host",
+     * 	fallback: "localhost"
+     * })
+     * ```
+     */
     string(options: PrimativeOptions<string>): Structure<string>;
+    /**
+     * Define a numeric value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * It will also coerce floating point numbers from strings
+     *
+     * ```js
+     * config.number({
+     * 	variable: "PORT",
+     * 	flag: "--port",
+     * 	fallback: "1234"
+     * })
+     * ```
+     */
     number(options: PrimativeOptions<number>): Structure<number>;
+    /**
+     * Define a boolean value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * There are extra coercions for boolean-like strings
+     *
+     * - `1`, `true` & `yes` coerce to true
+     * - `0`, `false` & `no` coerce to false
+     *
+     * ```js
+     * config.boolean({
+     * 	variable: "USE_SSL",
+     * 	flag: "--ssl",
+     * 	fallback: false
+     * })
+     * ```
+     */
     boolean(options: PrimativeOptions<boolean>): Structure<boolean>;
+    /**
+     * Define a URL based value, the value is validated and converted into a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
+     *
+     * ```js
+     * config.url({
+     * 	variable: "SELF_URL",
+     * 	flag: "--url",
+     * 	fallback: "http://localhost:1234"
+     * })
+     * ```
+     */
     url(options: PrimativeOptions<string | URL>): Structure<URL>;
+    /**
+     * Load configuration with a base file, also pulling in environment variables and CLI flags using {@link ConfigurationOptions}
+     *
+     * ```js
+     * const struct = config.object({
+     * 	env: config.string({ variable: "NODE_ENV", fallback: "development" })
+     * })
+     *
+     * config.load(
+     * 	new URL("./app-config.json", import.meta.url),
+     * 	struct
+     * )
+     * ```
+     *
+     * It will asynchronously load the configuration, validate it and return the coerced value.
+     * If it fails it will output a friendly string listing what is wrong and throw the Structure.Error
+     */
     load<T>(url: URL | string, struct: Structure<T>): Promise<T>;
+    /**
+     * Given a structure defined using Configuration, generate human-readable usage information.
+     * The usage includes a table of all configuration options and what the default value would be if no other soruces are used.
+     *
+     * Optionally, output the current value of the configuration too.
+     */
     getUsage(struct: unknown, currentValue?: unknown): string;
+    /**
+     * @ignore
+     *
+     * Given a structure defined using configuration, get meta-information about it
+     */
     describe(value: unknown, prefix?: string): ConfigurationDescription;
+    /**
+     * @unstable
+     *
+     * Given a structure defined using configuration, generate a JSON Schema to validate it. This could be useful to write to a file then use a IDE-based validator using something like
+     *
+     * ```json
+     * {
+     * 	"$schema": "./app-config.schema.json",
+     * }
+     * ```
+     */
     getJSONSchema(struct: Structure<any>): import("./structure.ts").Schema;
 }
 //# sourceMappingURL=configuration.d.ts.map

package/config/configuration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAEN,KAAK,wBAAwB,EAG7B,KAAK,gBAAgB,EAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKN,KAAK,mBAAmB,EACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACpC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxD,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpD,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;CAC1B;AAED,qBAAa,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgC;IAEpD,OAAO,EAAE,oBAAoB,CAAC;gBAElB,OAAO,EAAE,oBAAoB;IAOnC,UAAU,CAAC,CAAC,EACjB,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgBpB,yDAAyD;IACzD,UAAU,CAAC,CAAC,EACX,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,WAAW,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,OAAO;IActD,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;SAChD,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC/B,GAAG,SAAS,CAAC,CAAC,CAAC;IAgBhB,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC;IAW5D,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAC1D,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAClB,SAAS,CAAC,CAAC,CAAC;IAgCf,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IAkB5D,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IAgB5D,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC;IAgB/D,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;IAyBtD,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBlE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO;IAwBhD,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,wBAAwB;IAM/D,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC;CAGpC"}
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["configuration.ts"],"names":[],"mappings":"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"}

package/config/configuration.js

@@ -1,8 +1,31 @@
 import { Structure } from "./structure.js";
-import { formatMarkdownTable, PromiseList } from "../core/mod.js";
-import { arraySpec, getSpecification, objectSpec, primativeSpec, } from "./specifications.js";
+import { dangerouslyExpose, formatMarkdownTable, PromiseList, } from "../core/mod.js";
+import { _arraySpec, getSpecification, _objectSpec, _primativeSpec, } from "./specifications.js";
 import { _parseBoolean, _parseFloat, _parsePrimative, _parseURL, } from "./parsers.js";
 import {} from "./struct-context.js";
+/**
+ * @group Configuration
+ *
+ * **Configuration** is both an abstraction around processing config files,
+ * environment variables & CLI flags from the platform
+ * and also a tool for users to declaratively define how their configuration is.
+ *
+ * Each platform specifies a default `options` to load JSON files,
+ * but you can also construct your own if you want to customise how it works.
+ *
+ * With an instance, you can then define how an app's config can be specified as either configuration files,
+ * CLI flag, environment variables or a combination of any of them.
+ *
+ * ```js
+ * const config = new Configuration({
+ * 	readTextFile(url) {},
+ * 	getEnvironmentVariable(key) {},
+ * 	getCommandArgument() {},
+ * 	stringify(value) {},
+ * 	parse(value) {},
+ * })
+ * ```
+ */
 export class Configuration {
     static spec = Symbol("configuration.spec");
     options;
@@ -33,6 +56,16 @@ export class Configuration {
     //
     // Types
     //
+    /**
+     * Group or nest configuration in an object.
+     *
+     * ```js
+     * config.object({
+     * 	name: config.string({ fallback: "Geoff Testington" }),
+     * 	age: config.number({ fallback: 42 }),
+     * })
+     * ```
+     */
     object(fields) {
         if (typeof fields !== "object" || fields === null) {
             throw new TypeError("options must be a non-null object");
@@ -44,20 +77,48 @@ export class Configuration {
         }
         const struct = Structure.object(fields);
         Object.defineProperty(struct, Configuration.spec, {
-            value: objectSpec(fields),
+            value: _objectSpec(fields),
         });
         return struct;
     }
+    /**
+     * @unstable
+     *
+     * Create an ordered list of another type
+     *
+     * ```js
+     * config.array(
+     * 	Structure.string()
+     * )
+     * ```
+     */
     array(item) {
         if (!(item instanceof Structure)) {
             throw new TypeError("options is not a Structure");
         }
         const struct = Structure.array(item);
         Object.defineProperty(struct, Configuration.spec, {
-            value: arraySpec(item),
+            value: _arraySpec(item),
         });
         return struct;
     }
+    /**
+     * @unstable
+     *
+     * Load another configuration file or use value in the original configuration
+     *
+     * ```js
+     * config.external(
+     * 	new URL("./api-keys.json", import.meta.url),
+     * 	config.object({
+     * 		keys: Structure.array(Structure.string())
+     * 	})
+     * )
+     * ```
+     *
+     * Which will attempt to load "api-keys.json" and parse that,
+     * and if that doesn't exist it will also try the value in the original configuration.
+     */
     external(path, struct) {
         return new Structure(struct.schema, (value, context) => {
             if (context.type !== "async") {
@@ -85,36 +146,93 @@ export class Configuration {
             return internal;
         });
     }
+    /**
+     * Define a string-based value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * ```js
+     * config.string({
+     * 	variable: "HOSTNAME",
+     * 	flag: "--host",
+     * 	fallback: "localhost"
+     * })
+     * ```
+     */
     string(options) {
         if (typeof options.fallback !== "string") {
             throw new TypeError("options.fallback must be a string");
         }
         const struct = this._primative(Structure.string(), options, (result) => result.value);
         Object.defineProperty(struct, Configuration.spec, {
-            value: primativeSpec("string", options),
+            value: _primativeSpec("string", options),
         });
         return struct;
     }
+    /**
+     * Define a numeric value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * It will also coerce floating point numbers from strings
+     *
+     * ```js
+     * config.number({
+     * 	variable: "PORT",
+     * 	flag: "--port",
+     * 	fallback: "1234"
+     * })
+     * ```
+     */
     number(options) {
         if (typeof options.fallback !== "number") {
             throw new TypeError("options.fallback must be a number");
         }
         const struct = this._primative(Structure.number(), options, (result) => _parseFloat(result));
         Object.defineProperty(struct, Configuration.spec, {
-            value: primativeSpec("number", options),
+            value: _primativeSpec("number", options),
         });
         return struct;
     }
+    /**
+     * Define a boolean value with options to load from the config-file,
+     * an environment variable or a CLI flag.
+     * The only required field is **fallback**
+     *
+     * There are extra coercions for boolean-like strings
+     *
+     * - `1`, `true` & `yes` coerce to true
+     * - `0`, `false` & `no` coerce to false
+     *
+     * ```js
+     * config.boolean({
+     * 	variable: "USE_SSL",
+     * 	flag: "--ssl",
+     * 	fallback: false
+     * })
+     * ```
+     */
     boolean(options) {
         if (typeof options?.fallback !== "boolean") {
             throw new TypeError("options.fallback must be a boolean");
         }
         const struct = this._primative(Structure.boolean(), options, (result) => _parseBoolean(result));
         Object.defineProperty(struct, Configuration.spec, {
-            value: primativeSpec("boolean", options),
+            value: _primativeSpec("boolean", options),
         });
         return struct;
     }
+    /**
+     * Define a URL based value, the value is validated and converted into a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
+     *
+     * ```js
+     * config.url({
+     * 	variable: "SELF_URL",
+     * 	flag: "--url",
+     * 	fallback: "http://localhost:1234"
+     * })
+     * ```
+     */
     url(options) {
         if (typeof options.fallback !== "string" &&
             !(options.fallback instanceof URL)) {
@@ -123,13 +241,30 @@ export class Configuration {
         const opts2 = { ...options, fallback: new URL(options.fallback) };
         const struct = this._primative(Structure.url(), opts2, (result) => _parseURL(result));
         Object.defineProperty(struct, Configuration.spec, {
-            value: primativeSpec("url", opts2),
+            value: _primativeSpec("url", opts2),
         });
         return struct;
     }
     //
     // Methods
     //
+    /**
+     * Load configuration with a base file, also pulling in environment variables and CLI flags using {@link ConfigurationOptions}
+     *
+     * ```js
+     * const struct = config.object({
+     * 	env: config.string({ variable: "NODE_ENV", fallback: "development" })
+     * })
+     *
+     * config.load(
+     * 	new URL("./app-config.json", import.meta.url),
+     * 	struct
+     * )
+     * ```
+     *
+     * It will asynchronously load the configuration, validate it and return the coerced value.
+     * If it fails it will output a friendly string listing what is wrong and throw the Structure.Error
+     */
     async load(url, struct) {
         const context = {
             type: "async",
@@ -154,6 +289,12 @@ export class Configuration {
             throw error;
         }
     }
+    /**
+     * Given a structure defined using Configuration, generate human-readable usage information.
+     * The usage includes a table of all configuration options and what the default value would be if no other soruces are used.
+     *
+     * Optionally, output the current value of the configuration too.
+     */
     getUsage(struct, currentValue) {
         const { fallback, fields } = this.describe(struct);
         const lines = [
@@ -166,17 +307,33 @@ export class Configuration {
             this.options.stringify(fallback),
         ];
         if (currentValue) {
-            lines.push("", "", "Current:", JSON.stringify(currentValue, null, 2));
+            lines.push("", "", "Current:", JSON.stringify(dangerouslyExpose(currentValue), null, 2));
         }
         return lines.join("\n");
     }
+    /**
+     * @ignore
+     *
+     * Given a structure defined using configuration, get meta-information about it
+     */
     describe(value, prefix = "") {
         const spec = getSpecification(value);
         if (!spec)
             return { fallback: undefined, fields: [] };
         return spec(prefix);
     }
+    /**
+     * @unstable
+     *
+     * Given a structure defined using configuration, generate a JSON Schema to validate it. This could be useful to write to a file then use a IDE-based validator using something like
+     *
+     * ```json
+     * {
+     * 	"$schema": "./app-config.schema.json",
+     * }
+     * ```
+     */
     getJSONSchema(struct) {
-        return struct.getSchema();
+        return struct.getFullSchema();
     }
 }