gruber 0.2.0 → 0.4.0

package/core/structures.test.js

@@ -0,0 +1,474 @@
+import { StructError, Structure } from "./structures.js";
+import {
+	assertEquals,
+	assertThrows,
+	describe,
+	it,
+	assertInstanceOf,
+} from "./test-deps.js";
+
+describe("StructError", () => {
+	describe("constructor", () => {
+		it("stores values", () => {
+			const err = new StructError("error message", "some.path");
+			assertEquals(err.path, "some.path");
+			assertEquals(err.message, "error message");
+			assertEquals(err.name, "StructError");
+		});
+		it("stores children", () => {
+			const child = new StructError("child message", "path");
+			const parent = new StructError("parent message", "path", [child]);
+			assertEquals(parent.children, [child]);
+		});
+	});
+
+	describe("chain", () => {
+		it("returns StructErrors", () => {
+			const ctx = { path: ["some", "path"] };
+			const result = StructError.chain(
+				new StructError("error message", ["another", "path"]),
+				ctx,
+			);
+			assertEquals(
+				result,
+				new StructError("error message", ["another", "path"]),
+				"returns the StructError without modifying the path",
+			);
+		});
+		it("wraps Errors", () => {
+			const ctx = { path: ["some", "path"] };
+			const result = StructError.chain(new Error("error message"), ctx);
+			assertEquals(
+				result,
+				new StructError("error message", ["some", "path"]),
+				"creates a StructError and sets the path from the context",
+			);
+		});
+		it("wraps non-Errors", () => {
+			const ctx = { path: ["some", "path"] };
+			const result = StructError.chain("unknown", ctx);
+			assertEquals(
+				result,
+				new StructError("Unknown error", ["some", "path"]),
+				"creates a generic StructError",
+			);
+		});
+	});
+
+	describe("getOneLiner", () => {
+		it("formats the error", () => {
+			const error = new StructError("error message", ["some", "path"]);
+			assertEquals(error.getOneLiner(), "some.path — error message");
+		});
+	});
+
+	describe("[Symbol.iterator]", () => {
+		it("yields children", () => {
+			const error = new StructError(
+				"error message",
+				["some", "path"],
+				[
+					new StructError("child a"),
+					new StructError("child b"),
+					new StructError("child c"),
+				],
+			);
+			assertEquals(
+				Array.from(error, (i) => i.message),
+				["child a", "child b", "child c"],
+				"should yield each child",
+			);
+		});
+		it("yields nested children", () => {
+			const error = new StructError(
+				"parent a",
+				["some"],
+				[
+					new StructError(
+						"parent b",
+						["path"],
+						[
+							new StructError("child a"),
+							new StructError("child b"),
+							new StructError("child c"),
+						],
+					),
+				],
+			);
+			assertEquals(
+				Array.from(error, (i) => i.message),
+				["child a", "child b", "child c"],
+				"should yield all nested children which have no children of their own",
+			);
+		});
+	});
+
+	describe("toFriendlyString", () => {
+		it("formats a message", () => {
+			const error = new StructError(
+				"parent message",
+				["some", "path"],
+				[
+					new StructError("child a", ["some", "path", "a"]),
+					new StructError("child b", ["some", "path", "b"]),
+					new StructError("child c", ["some", "path", "c"]),
+				],
+			);
+
+			assertEquals(
+				error.toFriendlyString(),
+				[
+					"parent message",
+					"  some.path.a — child a",
+					"  some.path.b — child b",
+					"  some.path.c — child c",
+				].join("\n"),
+			);
+		});
+	});
+});
+
+describe("Structure", () => {
+	describe("constructor", () => {
+		it("stores fields", () => {
+			const result = new Structure("schema", "process");
+			assertEquals(result.schema, "schema");
+			assertEquals(result.process, "process");
+		});
+	});
+
+	describe("getSchema", () => {
+		it("injects $schema", () => {
+			const schema = { type: "string", default: "fallback" };
+			const struct = new Structure(schema, () => {});
+			assertEquals(
+				struct.getSchema(),
+				{
+					$schema: "https://json-schema.org/draft/2020-12/schema",
+					type: "string",
+					default: "fallback",
+				},
+				"should add the $schema variable to make it a valid JSON schema",
+			);
+		});
+	});
+
+	describe("string", () => {
+		it("creates a structure", () => {
+			const struct = Structure.string("fallback");
+			assertInstanceOf(struct, Structure);
+		});
+		it("allows strings", () => {
+			const struct = Structure.string("fallback");
+			assertEquals(
+				struct.process("value"),
+				"value",
+				"should allow string values through",
+			);
+		});
+		it("uses the fallback", () => {
+			const struct = Structure.string("fallback");
+			assertEquals(
+				struct.process(undefined),
+				"fallback",
+				"should fall back to the default if undefined is passed",
+			);
+		});
+		it("validates strings", () => {
+			const struct = Structure.string("fallback");
+
+			const error = assertThrows(
+				() => struct.process(42, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(error.message, "Expected a string");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("validates missing values", () => {
+			const struct = Structure.string();
+
+			const error = assertThrows(
+				() => struct.process(undefined, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(error.message, "Missing value");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.string("fallback");
+			assertEquals(struct.schema, { type: "string", default: "fallback" });
+		});
+	});
+
+	describe("number", () => {
+		it("creates a structure", () => {
+			const struct = Structure.number(42);
+			assertInstanceOf(struct, Structure);
+		});
+		it("allows numbers", () => {
+			const struct = Structure.number(42);
+			assertEquals(
+				struct.process(33),
+				33,
+				"should allow number values through",
+			);
+		});
+		it("uses the fallback", () => {
+			const struct = Structure.number(42);
+			assertEquals(
+				struct.process(undefined),
+				42,
+				"should fall back to the default if undefined is passed",
+			);
+		});
+		// TODO: I'm not sure if this should be on Structure or Configuration
+		it.skip("parses string integers", () => {
+			const struct = Structure.number(42);
+			assertEquals(
+				struct.process("33"),
+				33,
+				"should parse the integer out of the string",
+			);
+		});
+		it.skip("throws for non-numbers", () => {
+			const struct = Structure.number(42);
+
+			const error = assertThrows(
+				() => struct.process("a string", { path: ["some", "path"] }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Expected a number");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("validates missing values", () => {
+			const struct = Structure.number();
+
+			const error = assertThrows(
+				() => struct.process(undefined, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(error.message, "Missing value");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.number(42);
+			assertEquals(struct.schema, { type: "number", default: 42 });
+		});
+	});
+
+	describe("boolean", () => {
+		it("creates a structure", () => {
+			const struct = Structure.boolean(false);
+			assertInstanceOf(struct, Structure);
+		});
+		it("allows booleans", () => {
+			const struct = Structure.boolean(false);
+			assertEquals(
+				struct.process(true),
+				true,
+				"should allow boolean values through",
+			);
+		});
+		it("uses the fallback", () => {
+			const struct = Structure.boolean(false);
+			assertEquals(
+				struct.process(undefined),
+				false,
+				"should fall back to the default if undefined is passed",
+			);
+		});
+		it("throws for non-booleans", () => {
+			const struct = Structure.boolean(false);
+
+			const error = assertThrows(
+				() => struct.process("a string", { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(
+				error,
+				new StructError("Expected a boolean", ["some", "path"]),
+				"should throw a StructError and capture the context",
+			);
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.boolean(false);
+			assertEquals(struct.schema, { type: "boolean", default: false });
+		});
+	});
+
+	describe("url", () => {
+		it("creates a structure", () => {
+			const struct = Structure.url("https://fallback.example.com");
+			assertInstanceOf(struct, Structure);
+		});
+		it("fail for invalid fallbacks", () => {
+			assertThrows(() => Structure.url("not a URL"));
+		});
+		it("allows strings", () => {
+			const struct = Structure.url("https://fallback.example.com");
+			assertEquals(
+				struct.process("https://example.com"),
+				new URL("https://example.com"),
+				"should allow strings and convert them to a URL",
+			);
+		});
+		it("allows URLs", () => {
+			const struct = Structure.url("https://fallback.example.com");
+			assertEquals(
+				struct.process(new URL("https://example.com")),
+				new URL("https://example.com"),
+				"should allow strings and convert them to a URL",
+			);
+		});
+		it("uses the fallback", () => {
+			const struct = Structure.url("https://fallback.example.com");
+			assertEquals(
+				struct.process(undefined),
+				new URL("https://fallback.example.com"),
+				"should fall back to the default if undefined is passed",
+			);
+		});
+		it("validates non-strings", () => {
+			const struct = Structure.url("https://fallback.example.com");
+
+			const error = assertThrows(
+				() => struct.process(42, { path: ["some", "path"] }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Not a string or URL");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("validates missing values", () => {
+			const struct = Structure.url();
+
+			const error = assertThrows(
+				() => struct.process(undefined, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(error.message, "Missing value");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.url("https://fallback.example.com");
+			assertEquals(struct.schema, {
+				type: "string",
+				format: "uri",
+				default: "https://fallback.example.com",
+			});
+		});
+		it("stringifies URLs for JSON schema", () => {
+			const struct = Structure.url(new URL("https://fallback.example.com"));
+			assertEquals(struct.schema, {
+				type: "string",
+				format: "uri",
+				default: "https://fallback.example.com/",
+			});
+		});
+	});
+
+	describe("object", () => {
+		it("creates a structure", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			assertInstanceOf(struct, Structure);
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			assertEquals(struct.schema, {
+				type: "object",
+				properties: {
+					key: {
+						type: "string",
+						default: "fallback",
+					},
+				},
+				default: {},
+				additionalProperties: false,
+			});
+		});
+		it("throws for non-objects", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			const error = assertThrows(
+				() => struct.process("not an object", { path: ["some", "path"] }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Expected an object");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("allows objects", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			const result = struct.process({ key: "value" });
+			assertEquals(result, { key: "value" });
+		});
+		it("validates nested values", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			const error = assertThrows(
+				() => struct.process({ key: 42 }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Object does not match schema");
+			assertEquals(error.path, []);
+			assertEquals(error.children.length, 1, "should have one nested error");
+			assertEquals(error.children[0].message, "Expected a string");
+			assertEquals(error.children[0].path, ["key"], "should capture context");
+		});
+	});
+
+	describe("array", () => {
+		it("creates a structure", () => {
+			const struct = Structure.array(Structure.string());
+			assertInstanceOf(struct, Structure);
+		});
+		it("generates JSON schema", () => {
+			const struct = Structure.array(Structure.string());
+			assertEquals(struct.schema, {
+				type: "array",
+				items: {
+					type: "string",
+				},
+				default: [],
+			});
+		});
+		it("throws for non-arrays", () => {
+			const struct = Structure.array(Structure.string());
+			const error = assertThrows(
+				() => struct.process("not an object", { path: ["some", "path"] }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Expected an array");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
+		it("allows arrays", () => {
+			const struct = Structure.array(Structure.string());
+			const result = struct.process(["a", "b", "c"]);
+			assertEquals(result, ["a", "b", "c"]);
+		});
+		it("validates array items", () => {
+			const struct = Structure.array(Structure.string());
+			const error = assertThrows(
+				() => struct.process(["a", 2, "c"]),
+				StructError,
+			);
+
+			assertEquals(error.message, "Array item does not match schema");
+			assertEquals(error.path, []);
+			assertEquals(error.children.length, 1, "should have one nested error");
+			assertEquals(error.children[0].message, "Expected a string");
+			assertEquals(error.children[0].path, ["1"], "should capture context");
+		});
+	});
+});

package/core/test-deps.d.ts

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

package/core/test-deps.js

@@ -1,2 +1,2 @@
 export * from "https://deno.land/std@0.211.0/assert/mod.ts";
-export * as superstruct from "npm:superstruct@^1.0.3";
+export * from "https://deno.land/std@0.211.0/testing/bdd.ts";

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

@@ -20,4 +20,3 @@ export interface RouteDefinition<T> {
     pattern: URLPattern;
     handler: RouteHandler<T>;
 }
-//# sourceMappingURL=types.d.ts.map

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

@@ -10,4 +10,3 @@ export function formatMarkdownTable<T>(fields: T, columns: (keyof T)[], fallback
  * @returns {T}
  */
 export function loader<T extends () => any>(handler: T): T;
-//# sourceMappingURL=utilities.d.ts.map

package/core/utilities.test.d.ts

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

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "gruber",
   "type": "module",
-  "license": "MIT",
   "repository": "robb-j/gruber",
   "author": {
     "name": "Rob Anderson",
@@ -11,7 +10,6 @@
     "node": ">=20"
   },
   "dependencies": {
-    "superstruct": "^1.0.3",
     "urlpattern-polyfill": "^9.0.0"
   },
   "devDependencies": {
@@ -21,13 +19,14 @@
   },
   "exports": {
     ".": {
-      "types": "./types/mod.d.ts",
       "import": "./source/mod.js"
     },
+    "./core/*.js": {
+      "import": "./core/*.js"
+    },
     "./*.js": {
-      "types": "./types/*.d.ts",
       "import": "./source/*.js"
     }
   },
-  "version": "0.2.0"
+  "version": "0.4.0"
 }

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

@@ -1,13 +1,11 @@
 /**
     @typedef {object} NodeConfigurationOptions
-    @property {import("superstruct")} superstruct
 */
 /** @param {NodeConfigurationOptions} options */
 export function getNodeConfigOptions(options: NodeConfigurationOptions): {
-    superstruct: typeof import("superstruct");
-    readTextFile(url: any): Promise<any>;
-    getEnvironmentVariable(key: any): any;
-    getCommandArgument(key: any): any;
+    readTextFile(url: any): Promise<Buffer>;
+    getEnvironmentVariable(key: any): string;
+    getCommandArgument(key: any): string | boolean;
     stringify(config: any): string;
     parse(data: any): any;
 };
@@ -17,8 +15,5 @@ export function getNodeConfigOptions(options: NodeConfigurationOptions): {
  */
 export function getNodeConfiguration(options: NodeConfigurationOptions): Configuration;
 export { Configuration };
-export type NodeConfigurationOptions = {
-    superstruct: typeof import("superstruct");
-};
+export type NodeConfigurationOptions = object;
 import { Configuration } from "../core/configuration.js";
-//# sourceMappingURL=configuration.d.ts.map

package/source/configuration.js

@@ -8,7 +8,6 @@ export { Configuration };
 
 /**
 	@typedef {object} NodeConfigurationOptions
-	@property {import("superstruct")} superstruct
 */
 
 /** @param {NodeConfigurationOptions} options */
@@ -18,7 +17,6 @@ export function getNodeConfigOptions(options) {
 		strict: false,
 	});
 	return {
-		superstruct: options.superstruct,
 		async readTextFile(url) {
 			try {
 				return await fs.promises.readFile(url);

package/source/core.d.ts

@@ -0,0 +1 @@
+export * from "../core/mod.js";

package/{types/source → source}/express-router.d.ts

@@ -11,8 +11,8 @@
     ```
 */
 export class ExpressRouter {
-    /** @param {NodeRouterOptions} options */
-    constructor(options?: NodeRouterOptions);
+    /** @param {import("./node-router.js").NodeRouterOptions} options */
+    constructor(options?: import("./node-router.js").NodeRouterOptions);
     router: FetchRouter;
     /** @returns {import("express").RequestHandler} */
     middleware(): any;
@@ -25,4 +25,3 @@ export class ExpressRouter {
     respond(res: any, response: Response): void;
 }
 import { FetchRouter } from "../core/fetch-router.js";
-//# sourceMappingURL=express-router.d.ts.map

package/source/express-router.js

@@ -16,7 +16,7 @@ import { getFetchRequest } from "./node-router.js";
 	```
 */
 export class ExpressRouter {
-	/** @param {NodeRouterOptions} options */
+	/** @param {import("./node-router.js").NodeRouterOptions} options */
 	constructor(options = {}) {
 		this.router = new FetchRouter(options.routes ?? []);
 	}

package/{types/source → source}/koa-router.d.ts

@@ -30,4 +30,3 @@ export class KoaRouter {
 export type Context = any;
 export type NodeRouterOptions = import("./node-router.js").NodeRouterOptions;
 import { FetchRouter } from "../core/fetch-router.js";
-//# sourceMappingURL=koa-router.d.ts.map

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

@@ -1,7 +1,4 @@
 export * from "./configuration.js";
 export * from "./core.js";
-export * from "./express-router.js";
-export * from "./koa-router.js";
 export * from "./node-router.js";
 export * from "./postgres.js";
-//# sourceMappingURL=mod.d.ts.map

package/source/mod.js

@@ -1,6 +1,6 @@
 export * from "./configuration.js";
 export * from "./core.js";
-export * from "./express-router.js";
-export * from "./koa-router.js";
+// export * from "./express-router.js";
+// export * from "./koa-router.js";
 export * from "./node-router.js";
 export * from "./postgres.js";

package/{types/source → source}/node-router.d.ts

@@ -1,10 +1,11 @@
+/// <reference types="node" resolution-mode="require"/>
 /** @param {import("node:http").IncomingMessage} req */
-export function getFetchRequest(req: any): Request;
+export function getFetchRequest(req: import("node:http").IncomingMessage): Request;
 /** @param {import("node:http").IncomingHttpHeaders} input */
-export function getFetchHeaders(input: any): Headers;
+export function getFetchHeaders(input: import("node:http").IncomingHttpHeaders): Headers;
 /** @param {import("node:http").IncomingMessage} req */
-export function getIncomingMessageBody(req: any): any;
-/** @typedef {import("../../core/mod.js").RouteDefinition} RouteDefinition */
+export function getIncomingMessageBody(req: import("node:http").IncomingMessage): import("stream/web").ReadableStream<any>;
+/** @typedef {import("../core/mod.js").RouteDefinition} RouteDefinition */
 /**
     @typedef {object} NodeRouterOptions
     @property {RouteDefinition []} routes
@@ -32,11 +33,10 @@ export class NodeRouter {
         @param {import("node:http").ServerResponse} res
         @param {Response} response
     */
-    respond(res: any, response: Response): void;
+    respond(res: import("node:http").ServerResponse, response: Response): void;
 }
-export type RouteDefinition = any;
+export type RouteDefinition = import("../core/mod.js").RouteDefinition;
 export type NodeRouterOptions = {
-    routes: RouteDefinition[];
+    routes: import("../core/types.js").RouteDefinition<any>[];
 };
 import { FetchRouter } from "../core/fetch-router.js";
-//# sourceMappingURL=node-router.d.ts.map

package/source/node-router.js

@@ -1,7 +1,7 @@
 import { Readable } from "node:stream";
 import { FetchRouter } from "../core/fetch-router.js";
 
-/** @typedef {import("../../core/mod.js").RouteDefinition} RouteDefinition */
+/** @typedef {import("../core/mod.js").RouteDefinition} RouteDefinition */
 
 /**
 	@typedef {object} NodeRouterOptions