gruber 0.3.0 → 0.4.0

package/core/configuration.test.js

@@ -26,10 +26,40 @@ describe("Configuration", () => {
 	describe("object", () => {
 		const config = new Configuration(bareOptions);
 
-		it("stores the spec", () => {
-			const result = config.object({});
+		it("stores the options", () => {
+			const result = config.object({ key: "value" });
+
 			assertEquals(result[Configuration.spec].type, "object");
-			assertEquals(result[Configuration.spec].value, {});
+			assertEquals(result[Configuration.spec].options, { key: "value" });
+		});
+		it("describes itself", () => {
+			const spec = config.object({
+				fullName: config.string({ variable: "FULL_NAME", fallback: "Geoff T" }),
+				age: config.number({ flag: "--age", fallback: 42 }),
+			});
+			//
+			const result = spec[Configuration.spec].describe(
+				"person",
+				(options, name) => ({ name, ...options }),
+			);
+
+			assertEquals(result, {
+				fallback: { fullName: "Geoff T", age: 42 },
+				fields: [
+					{
+						name: "person.fullName",
+						type: "string",
+						variable: "FULL_NAME",
+						fallback: "Geoff T",
+					},
+					{
+						name: "person.age",
+						type: "number",
+						flag: "--age",
+						fallback: 42,
+					},
+				],
+			});
 		});
 	});
 
@@ -44,16 +74,118 @@ describe("Configuration", () => {
 			const result = struct.process(undefined);
 			assertEquals(result, "Geoff Testington");
 		});
-		it("stores the spec", () => {
+		it("stores the options", () => {
 			const result = config.string({
 				variable: "SOME_VAR",
+				flag: "--some-flag",
 				fallback: "value",
 			});
 			assertEquals(result[Configuration.spec].type, "string");
-			assertEquals(result[Configuration.spec].value, {
+			assertEquals(result[Configuration.spec].options, {
+				variable: "SOME_VAR",
+				flag: "--some-flag",
+				fallback: "value",
+			});
+		});
+		it("describes itself", () => {
+			const spec = config.string({
 				variable: "SOME_VAR",
+				flag: "--some-flag",
 				fallback: "value",
 			});
+			const result = spec[Configuration.spec].describe("fullName");
+			assertEquals(result, {
+				fallback: "value",
+				fields: [
+					{
+						name: "fullName",
+						type: "string",
+						variable: "SOME_VAR",
+						flag: "--some-flag",
+						fallback: "value",
+					},
+				],
+			});
+		});
+	});
+
+	describe("number", () => {
+		const config = new Configuration(bareOptions);
+
+		it("requires a fallback", () => {
+			assertThrows(() => config.number({}), TypeError);
+		});
+		it("uses the fallback", () => {
+			const struct = config.number({ fallback: 42 });
+			const result = struct.process(undefined);
+			assertEquals(result, 42);
+		});
+		it("stores the options", () => {
+			const result = config.number({
+				variable: "SOME_VAR",
+				flag: "--some-flag",
+				fallback: 42,
+			});
+			assertEquals(result[Configuration.spec].type, "number");
+			assertEquals(result[Configuration.spec].options, {
+				variable: "SOME_VAR",
+				flag: "--some-flag",
+				fallback: 42,
+			});
+		});
+		it("parses strings", () => {
+			const vars = { SOME_VAR: "12.34" };
+			const config = new Configuration({
+				...bareOptions,
+				getEnvironmentVariable: (key) => vars[key],
+			});
+
+			const result = config.number({
+				variable: "SOME_VAR",
+				fallback: 42,
+			});
+
+			assertEquals(result.process(undefined), 12.34);
+		});
+	});
+
+	describe("boolean", () => {
+		const config = new Configuration(bareOptions);
+
+		it("requires a fallback", () => {
+			assertThrows(() => config.boolean({}), TypeError);
+		});
+		it("uses the fallback", () => {
+			const struct = config.boolean({ fallback: false });
+			const result = struct.process(undefined);
+			assertEquals(result, false);
+		});
+		it("stores the options", () => {
+			const result = config.boolean({
+				variable: "SOME_VAR",
+				flag: "--some-flag",
+				fallback: false,
+			});
+			assertEquals(result[Configuration.spec].type, "boolean");
+			assertEquals(result[Configuration.spec].options, {
+				variable: "SOME_VAR",
+				flag: "--some-flag",
+				fallback: false,
+			});
+		});
+		it("parses strings", () => {
+			const vars = { SOME_VAR: "true" };
+			const config = new Configuration({
+				...bareOptions,
+				getEnvironmentVariable: (key) => vars[key],
+			});
+
+			const result = config.boolean({
+				variable: "SOME_VAR",
+				fallback: false,
+			});
+
+			assertEquals(result.process(undefined), true);
 		});
 	});
 
@@ -73,15 +205,17 @@ describe("Configuration", () => {
 			const result = struct.process(undefined);
 			assertEquals(result, new URL("https://fallback.example.com"));
 		});
-		it("stores the spec", () => {
+		it("stores the options", () => {
 			const result = config.url({
 				variable: "SOME_VAR",
+				flag: "--some-flag",
 				fallback: "https://example.com",
 			});
 			assertEquals(result[Configuration.spec].type, "url");
-			assertEquals(result[Configuration.spec].value, {
+			assertEquals(result[Configuration.spec].options, {
 				variable: "SOME_VAR",
-				fallback: "https://example.com",
+				flag: "--some-flag",
+				fallback: new URL("https://example.com"),
 			});
 		});
 	});
@@ -96,7 +230,10 @@ describe("Configuration", () => {
 			const result = config._getValue({
 				flag: "--option",
 			});
-			assertEquals(result, "value-from-arg");
+			assertEquals(result, {
+				source: "argument",
+				value: "value-from-arg",
+			});
 		});
 		it("uses environment variables", () => {
 			const env = { MY_VAR: "value-from-env" };
@@ -107,12 +244,74 @@ describe("Configuration", () => {
 			const result = config._getValue({
 				variable: "MY_VAR",
 			});
-			assertEquals(result, "value-from-env");
+			assertEquals(result, {
+				source: "variable",
+				value: "value-from-env",
+			});
 		});
 		it("uses the fallback", () => {
 			const config = new Configuration(bareOptions);
 			const result = config._getValue({ fallback: "value-from-fallback" });
-			assertEquals(result, "value-from-fallback");
+			assertEquals(result, {
+				source: "fallback",
+				value: "value-from-fallback",
+			});
+		});
+	});
+
+	describe("_parseFloat", () => {
+		it("parses strings", () => {
+			const config = new Configuration(bareOptions);
+			assertEquals(
+				config._parseFloat({ source: "argument", value: "12.34" }),
+				12.34,
+				"should parse the float from the result",
+			);
+		});
+		it("passes numbers through", () => {
+			const config = new Configuration(bareOptions);
+			assertEquals(
+				config._parseFloat({ source: "fallback", value: 98.76 }),
+				98.76,
+				"should preserve number literals",
+			);
+		});
+	});
+
+	describe("_parseBoolean", () => {
+		it("parses strings", () => {
+			const config = new Configuration(bareOptions);
+			assertEquals(
+				config._parseBoolean({ source: "argument", value: "1" }),
+				true,
+			);
+			assertEquals(
+				config._parseBoolean({ source: "argument", value: "true" }),
+				true,
+			);
+			assertEquals(
+				config._parseBoolean({ source: "argument", value: "0" }),
+				false,
+			);
+			assertEquals(
+				config._parseBoolean({ source: "argument", value: "false" }),
+				false,
+			);
+		});
+		it("passes booleans through", () => {
+			const config = new Configuration(bareOptions);
+			assertEquals(
+				config._parseBoolean({ source: "fallback", value: true }),
+				true,
+				"should preserve boolean literals",
+			);
+		});
+		it("allows empty-string for arguments", () => {
+			const config = new Configuration(bareOptions);
+			assertEquals(
+				config._parseBoolean({ source: "argument", value: "" }),
+				true,
+			);
 		});
 	});
 
@@ -155,10 +354,10 @@ describe("Configuration", () => {
 		});
 	});
 
-	describe("describeSpecification", () => {
+	describe("describe", () => {
 		it("processes strings", () => {
 			const config = new Configuration(bareOptions);
-			const result = config.describeSpecification(
+			const result = config.describe(
 				config.string({
 					fallback: "test-app",
 					variable: "APP_NAME",
@@ -180,7 +379,7 @@ describe("Configuration", () => {
 
 		it("processes urls", () => {
 			const config = new Configuration(bareOptions);
-			const result = config.describeSpecification(
+			const result = config.describe(
 				config.url({
 					fallback: "https://example.com",
 					variable: "SELF_URL",
@@ -193,7 +392,7 @@ describe("Configuration", () => {
 				{
 					name: "selfUrl",
 					type: "url",
-					fallback: "https://example.com",
+					fallback: new URL("https://example.com"),
 					variable: "SELF_URL",
 					flag: "--self-url",
 				},
@@ -202,7 +401,7 @@ describe("Configuration", () => {
 
 		it("processes objects", () => {
 			const config = new Configuration(bareOptions);
-			const result = config.describeSpecification(
+			const result = config.describe(
 				config.object({
 					name: config.string({
 						fallback: "testing-app",

package/core/http.d.ts

@@ -26,23 +26,42 @@
  */
 export function defineRoute<T extends string>(init: import("./types.ts").RouteOptions<T>): import("./types.ts").RouteDefinition<T>;
 export class HTTPError extends Error {
-    /** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 */
-    static badRequest(): HTTPError;
-    /** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 */
-    static unauthorized(): HTTPError;
-    /** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 */
-    static notFound(): HTTPError;
-    /** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 */
-    static internalServerError(): HTTPError;
-    /** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501 */
-    static notImplemented(): HTTPError;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
+     * @param {BodyInit} [body]
+     */
+    static badRequest(body?: BodyInit): HTTPError;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
+     * @param {BodyInit} [body]
+     */
+    static unauthorized(body?: BodyInit): HTTPError;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
+     * @param {BodyInit} [body]
+     */
+    static notFound(body?: BodyInit): HTTPError;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
+     * @param {BodyInit} [body]
+     */
+    static internalServerError(body?: BodyInit): HTTPError;
+    /**
+     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501
+     * @param {BodyInit} [body]
+     */
+    static notImplemented(body?: BodyInit): HTTPError;
     /**
      * @param {number} status
      * @param {string} statusText
+     * @param {BodyInit|null|undefined} [body=null]
+     * @param {HeadersInit} [headers=undefined]
      */
-    constructor(status?: number, statusText?: string);
+    constructor(status?: number, statusText?: string, body?: BodyInit | null | undefined, headers?: HeadersInit);
     /** @type {number} */ status: number;
     /** @type {string}*/ statusText: string;
+    body: BodyInit;
+    headers: Headers;
     toResponse(): Response;
 }
 export type HTTPMethod = import("./types.ts").HTTPMethod;

package/core/http.js

@@ -41,29 +41,44 @@ export function defineRoute(init) {
 // NOTE: add more error codes as needed
 // NOTE: design an API for setting the body on static errors
 export class HTTPError extends Error {
-	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 */
-	static badRequest() {
-		return new HTTPError(400, "Bad Request");
+	/**
+	 * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
+	 * @param {BodyInit} [body]
+	 */
+	static badRequest(body = undefined) {
+		return new HTTPError(400, "Bad Request", body);
 	}
 
-	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 */
-	static unauthorized() {
-		return new HTTPError(401, "Unauthorized");
+	/**
+	 * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
+	 * @param {BodyInit} [body]
+	 */
+	static unauthorized(body = undefined) {
+		return new HTTPError(401, "Unauthorized", body);
 	}
 
-	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 */
-	static notFound() {
-		return new HTTPError(404, "Not Found");
+	/**
+	 * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
+	 * @param {BodyInit} [body]
+	 */
+	static notFound(body = undefined) {
+		return new HTTPError(404, "Not Found", body);
 	}
 
-	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 */
-	static internalServerError() {
-		return new HTTPError(500, "Internal Server Error");
+	/**
+	 * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
+	 * @param {BodyInit} [body]
+	 */
+	static internalServerError(body = undefined) {
+		return new HTTPError(500, "Internal Server Error", body);
 	}
 
-	/** https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501 */
-	static notImplemented() {
-		return new HTTPError(501, "Not Implemented");
+	/**
+	 * https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501
+	 * @param {BodyInit} [body]
+	 */
+	static notImplemented(body = undefined) {
+		return new HTTPError(501, "Not Implemented", body);
 	}
 
 	/** @type {number} */ status;
@@ -72,19 +87,29 @@ export class HTTPError extends Error {
 	/**
 	 * @param {number} status
 	 * @param {string} statusText
+	 * @param {BodyInit|null|undefined} [body=null]
+	 * @param {HeadersInit} [headers=undefined]
 	 */
-	constructor(status = 200, statusText = "OK") {
+	constructor(
+		status = 200,
+		statusText = "OK",
+		body = null,
+		headers = undefined,
+	) {
 		super(statusText);
 		this.status = status;
 		this.statusText = statusText;
+		this.body = body;
 		this.name = "HTTPError";
+		this.headers = new Headers(headers);
 		Error.captureStackTrace(this, HTTPError);
 	}
 
 	toResponse() {
-		return new Response(null, {
+		return new Response(this.body, {
 			status: this.status,
 			statusText: this.statusText,
+			headers: this.headers,
 		});
 	}
 }

package/core/http.test.js

@@ -1,8 +1,8 @@
-import { assertInstanceOf, assertEquals } from "./test-deps.js";
+import { assertInstanceOf, assertEquals, describe, it } from "./test-deps.js";
 import { defineRoute, HTTPError } from "./http.js";
 
-Deno.test("defineRoute", async (t) => {
-	await t.step("sets the method", () => {
+describe("defineRoute", () => {
+	it("sets the method", () => {
 		const result = defineRoute({
 			method: "GET",
 			pathname: "/",
@@ -11,7 +11,7 @@ Deno.test("defineRoute", async (t) => {
 		assertEquals(result.method, "GET");
 	});
 
-	await t.step("creates a URLPattern", () => {
+	it("creates a URLPattern", () => {
 		const result = defineRoute({
 			method: "GET",
 			pathname: "/hello/:name",
@@ -22,47 +22,69 @@ Deno.test("defineRoute", async (t) => {
 	});
 });
 
-Deno.test("HTTPError", async (t) => {
-	await t.step("constructor", () => {
-		const result = new HTTPError(418, "I'm a teapot");
-		assertEquals(result.status, 418);
-		assertEquals(result.statusText, "I'm a teapot");
-		assertEquals(result.name, "HTTPError");
+describe("HTTPError", () => {
+	describe("constructor", () => {
+		it("creates the error", () => {
+			const result = new HTTPError(418, "I'm a teapot");
+			assertEquals(result.status, 418);
+			assertEquals(result.statusText, "I'm a teapot");
+			assertEquals(result.name, "HTTPError");
+		});
 	});
 
-	await t.step("toResponse", () => {
-		const result = new HTTPError(200, "OK").toResponse();
-		assertEquals(result.status, 200);
-		assertEquals(result.statusText, "OK");
-	});
+	describe("toResponse", () => {
+		it("creates the error", () => {
+			const result = new HTTPError(200, "OK").toResponse();
+			assertEquals(result.status, 200);
+			assertEquals(result.statusText, "OK");
+		});
+		it("sets headers", () => {
+			const error = new HTTPError(200, "OK", null, {
+				"X-HOTEL-BAR": "Hotel Bar?",
+			});
 
-	await t.step("badRequest", () => {
-		const result = HTTPError.badRequest("body");
-		assertEquals(result.status, 400);
-		assertEquals(result.statusText, "Bad Request");
+			const result = error.toResponse();
+			assertEquals(result.headers.get("X-HOTEL-BAR"), "Hotel Bar?");
+		});
 	});
 
-	await t.step("unauthorized", () => {
-		const result = HTTPError.unauthorized();
-		assertEquals(result.status, 401);
-		assertEquals(result.statusText, "Unauthorized");
+	describe("badRequest", () => {
+		it("creates the error", () => {
+			const result = HTTPError.badRequest("body");
+			assertEquals(result.status, 400);
+			assertEquals(result.statusText, "Bad Request");
+		});
 	});
 
-	await t.step("notFound", () => {
-		const result = HTTPError.notFound();
-		assertEquals(result.status, 404);
-		assertEquals(result.statusText, "Not Found");
+	describe("unauthorized", () => {
+		it("creates the error", () => {
+			const result = HTTPError.unauthorized();
+			assertEquals(result.status, 401);
+			assertEquals(result.statusText, "Unauthorized");
+		});
 	});
 
-	await t.step("internalServerError", () => {
-		const result = HTTPError.internalServerError();
-		assertEquals(result.status, 500);
-		assertEquals(result.statusText, "Internal Server Error");
+	describe("notFound", () => {
+		it("creates the error", () => {
+			const result = HTTPError.notFound();
+			assertEquals(result.status, 404);
+			assertEquals(result.statusText, "Not Found");
+		});
 	});
 
-	await t.step("notImplemented", () => {
-		const result = HTTPError.notImplemented();
-		assertEquals(result.status, 501);
-		assertEquals(result.statusText, "Not Implemented");
+	describe("internalServerError", () => {
+		it("creates the error", () => {
+			const result = HTTPError.internalServerError();
+			assertEquals(result.status, 500);
+			assertEquals(result.statusText, "Internal Server Error");
+		});
+
+		describe("notImplemented", () => {
+			it("creates the error", () => {
+				const result = HTTPError.notImplemented();
+				assertEquals(result.status, 501);
+				assertEquals(result.statusText, "Not Implemented");
+			});
+		});
 	});
 });

package/core/mod.d.ts

@@ -3,4 +3,5 @@ export * from "./fetch-router.js";
 export * from "./http.js";
 export * from "./migrator.js";
 export * from "./postgres.js";
+export * from "./structures.js";
 export * from "./utilities.js";

package/core/mod.js

@@ -3,4 +3,5 @@ export * from "./fetch-router.js";
 export * from "./http.js";
 export * from "./migrator.js";
 export * from "./postgres.js";
+export * from "./structures.js";
 export * from "./utilities.js";

package/core/structures.d.ts

@@ -23,7 +23,7 @@ export class StructError extends Error {
  */
 /**
  * @template T
- * @typedef {(input?: unknown, context: StructContext) => T} StructExec
+ * @typedef {(input?: unknown, context?: StructContext) => T} StructExec
  */
 /**
  * @template T
@@ -34,26 +34,39 @@ export class StructError extends Error {
  */
 export class Structure<T> {
     /**
-     * @param {string} fallback
+     * @param {string} [fallback]
      * @returns {Structure<string>}
      */
-    static string(fallback: string): Structure<string>;
+    static string(fallback?: string): Structure<string>;
     /**
-     * @param {number} fallback
+     * @param {number} [fallback]
      * @returns {Structure<number>}
      */
-    static number(fallback: number): Structure<number>;
+    static number(fallback?: number): Structure<number>;
     /**
-     * @param {string | URL} fallback
+     * @param {boolean} fallback
+     * @returns {Structure<boolean>}
+     */
+    static boolean(fallback: boolean): Structure<boolean>;
+    /**
+     * @param {string | URL} [fallback]
      * @returns {Structure<URL>}
      */
-    static url(fallback: string | URL): Structure<URL>;
+    static url(fallback?: string | URL): Structure<URL>;
     /**
      * @template {Record<string, Structure<any>>} U
      * @param {U} fields
      * @returns {Structure<{ [K in keyof U]: Infer<U[K]> }>}
      */
     static object<U extends Record<string, Structure<any>>>(fields: U): Structure<{ [K in keyof U]: Infer<U[K]>; }>;
+    /**
+     * **UNSTABLE** use at your own risk
+     *
+     * @template {Structure<any>} U
+     * @param {U} struct
+     * @returns {Structure<Array<Infer<U>>>}
+     */
+    static array<U_1 extends Structure<any>>(struct: U_1): Structure<Infer<U_1>[]>;
     /**
      * @param {Schema} schema
      * @param {StructExec<T>} process
@@ -68,11 +81,11 @@ export class Structure<T> {
 export type StructContext = {
     path: string[];
 };
-export type StructOptions<Type, Schema_1> = {
+export type StructOptions<Type, Schema> = {
     type: 'object' | 'string' | 'url';
     schema: Schema;
     fn: (value: unknown, ctx: StructContext) => Type;
 };
 export type Schema = Record<string, unknown>;
-export type StructExec<T> = (input?: unknown, context: StructContext) => T;
+export type StructExec<T> = (input?: unknown, context?: StructContext) => T;
 export type Infer<T> = T extends Structure<infer U> ? U : never;