gruber 0.3.0 → 0.4.0

package/core/structures.js

@@ -77,7 +77,7 @@ export class StructError extends Error {
 
 /**
  * @template T
- * @typedef {(input?: unknown, context: StructContext) => T} StructExec
+ * @typedef {(input?: unknown, context?: StructContext) => T} StructExec
  */
 
 /**
@@ -100,22 +100,23 @@ export class Structure {
 
 	getSchema() {
 		return {
-			$schema: "https://json-schema.org/draft/2019-09/schema",
+			$schema: "https://json-schema.org/draft/2020-12/schema",
 			...this.schema,
 		};
 	}
 
 	/**
-	 * @param {string} fallback
+	 * @param {string} [fallback]
 	 * @returns {Structure<string>}
 	 */
-	static string(fallback) {
-		const schema = {
-			type: "string",
-			default: fallback,
-		};
-		return new Structure(schema, (input, context) => {
-			if (input === undefined) return fallback;
+	static string(fallback = undefined) {
+		const schema = { type: "string" };
+		if (fallback !== undefined) schema.default = fallback;
+
+		return new Structure(schema, (input = fallback, context = undefined) => {
+			if (input === undefined) {
+				throw new StructError("Missing value", context?.path);
+			}
 			if (typeof input !== "string") {
 				throw new StructError("Expected a string", context?.path);
 			}
@@ -124,36 +125,59 @@ export class Structure {
 	}
 
 	/**
-	 * @param {number} fallback
+	 * @param {number} [fallback]
 	 * @returns {Structure<number>}
 	 */
 	static number(fallback) {
-		const schema = {
-			type: "number",
-			default: fallback,
-		};
+		const schema = { type: "number" };
+		if (fallback !== undefined) schema.default = fallback;
+
+		return new Structure(schema, (input = fallback, context = undefined) => {
+			if (input === undefined) {
+				throw new StructError("Missing value", context?.path);
+			}
+			// if (typeof input === "string") {
+			// 	const parsed = Number.parseFloat(input);
+			// 	if (!Number.isNaN(parsed)) return parsed;
+			// }
+			if (typeof input !== "number") {
+				throw new StructError("Expected a number", context?.path);
+			}
+			return input;
+		});
+	}
+
+	/**
+	 * @param {boolean} fallback
+	 * @returns {Structure<boolean>}
+	 */
+	static boolean(fallback) {
+		const schema = { type: "boolean" };
+		if (fallback !== undefined) schema.default = fallback;
+
 		return new Structure(schema, (input, context) => {
 			if (input === undefined) return fallback;
-			if (typeof input !== "number") {
-				throw new StructError("Not a number", context?.path);
+			if (typeof input !== "boolean") {
+				throw new StructError("Not a boolean", context?.path);
 			}
 			return input;
 		});
 	}
 
 	/**
-	 * @param {string | URL} fallback
+	 * @param {string | URL} [fallback]
 	 * @returns {Structure<URL>}
 	 */
 	static url(fallback) {
-		const schema = {
-			type: "string",
-			format: "uri",
-			default: fallback,
-		};
-		const fallbackUrl = new URL(fallback); // ~ make sure the fallback is valid ~
-		return new Structure(schema, (input, context) => {
-			if (input === undefined) return fallbackUrl;
+		const schema = { type: "string", format: "uri" };
+		if (fallback !== undefined) schema.default = fallback.toString();
+
+		// ~ make sure the fallback is valid ~
+		const url = fallback ? new URL(fallback) : undefined;
+		return new Structure(schema, (input = url, context = undefined) => {
+			if (input === undefined) {
+				throw new StructError("Missing value", context?.path);
+			}
 			if (input instanceof URL) return input;
 			if (typeof input !== "string") {
 				throw new StructError("Not a string or URL", context?.path);
@@ -177,12 +201,11 @@ export class Structure {
 		for (const [key, struct] of Object.entries(fields)) {
 			schema.properties[key] = struct.schema;
 		}
-		return new Structure(schema, (input, context) => {
+		return new Structure(schema, (input = {}, context = undefined) => {
 			const path = context?.path ?? [];
 			if (input && typeof input !== "object") {
-				throw new StructError("Not an object", path);
+				throw new StructError("Expected an object", path);
 			}
-			input = input ?? {};
 			const output = {};
 			const errors = [];
 			for (const key in fields) {
@@ -199,4 +222,39 @@ export class Structure {
 			return output;
 		});
 	}
+
+	/**
+	 * **UNSTABLE** use at your own risk
+	 *
+	 * @template {Structure<any>} U
+	 * @param {U} struct
+	 * @returns {Structure<Array<Infer<U>>>}
+	 */
+	static array(struct) {
+		const schema = {
+			type: "array",
+			items: struct.schema,
+			default: [],
+		};
+		return new Structure(schema, (input = [], context = undefined) => {
+			const path = context?.path ?? [];
+			if (!Array.isArray(input)) {
+				throw new StructError("Expected an array", path);
+			}
+			const output = [];
+			const errors = [];
+			for (let i = 0; i < input.length; i++) {
+				const ctx = { path: [...path, `${i}`] };
+				try {
+					output.push(struct.process(input[i], ctx));
+				} catch (error) {
+					errors.push(StructError.chain(error, ctx));
+				}
+			}
+			if (errors.length > 0) {
+				throw new StructError("Array item does not match schema", path, errors);
+			}
+			return output;
+		});
+	}
 }

package/core/structures.test.js

@@ -1,6 +1,11 @@
-import { assertInstanceOf } from "../bundle/deno/core/test-deps.js";
 import { StructError, Structure } from "./structures.js";
-import { assertEquals, assertThrows, describe, it } from "./test-deps.js";
+import {
+	assertEquals,
+	assertThrows,
+	describe,
+	it,
+	assertInstanceOf,
+} from "./test-deps.js";
 
 describe("StructError", () => {
 	describe("constructor", () => {
@@ -139,7 +144,7 @@ describe("Structure", () => {
 			assertEquals(
 				struct.getSchema(),
 				{
-					$schema: "https://json-schema.org/draft/2019-09/schema",
+					$schema: "https://json-schema.org/draft/2020-12/schema",
 					type: "string",
 					default: "fallback",
 				},
@@ -169,18 +174,25 @@ describe("Structure", () => {
 				"should fall back to the default if undefined is passed",
 			);
 		});
-		it("throws for non-strings", () => {
+		it("validates strings", () => {
 			const struct = Structure.string("fallback");
 
 			const error = assertThrows(
 				() => struct.process(42, { path: ["some", "path"] }),
 				StructError,
 			);
-			assertEquals(
-				error,
-				new StructError("Expected a string", ["some", "path"]),
-				"should throw a StructError and capture the context",
+			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");
@@ -209,22 +221,79 @@ describe("Structure", () => {
 				"should fall back to the default if undefined is passed",
 			);
 		});
-		it("throws for non-numbers", () => {
+		// 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 number", ["some", "path"]),
+				new StructError("Expected a boolean", ["some", "path"]),
 				"should throw a StructError and capture the context",
 			);
 		});
 		it("generates JSON schema", () => {
-			const struct = Structure.number(42);
-			assertEquals(struct.schema, { type: "number", default: 42 });
+			const struct = Structure.boolean(false);
+			assertEquals(struct.schema, { type: "boolean", default: false });
 		});
 	});
 
@@ -260,18 +329,26 @@ describe("Structure", () => {
 				"should fall back to the default if undefined is passed",
 			);
 		});
-		it("throws for non-strings", () => {
+		it("validates non-strings", () => {
 			const struct = Structure.url("https://fallback.example.com");
 
 			const error = assertThrows(
 				() => struct.process(42, { path: ["some", "path"] }),
 				StructError,
 			);
-			assertEquals(
-				error,
-				new StructError("Not a string or URL", ["some", "path"]),
-				"should throw a StructError and capture the context",
+
+			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");
@@ -281,6 +358,14 @@ describe("Structure", () => {
 				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", () => {
@@ -314,20 +399,18 @@ describe("Structure", () => {
 				() => struct.process("not an object", { path: ["some", "path"] }),
 				StructError,
 			);
-			assertEquals(
-				error,
-				new StructError("Not an object", ["some", "path"]),
-				"should throw a StructError and capture the context",
-			);
+
+			assertEquals(error.message, "Expected an object");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
 		});
-		it("validates nested values", () => {
+		it("allows objects", () => {
 			const struct = Structure.object({
 				key: Structure.string("fallback"),
 			});
 			const result = struct.process({ key: "value" });
 			assertEquals(result, { key: "value" });
 		});
-		it("fails on nested values", () => {
+		it("validates nested values", () => {
 			const struct = Structure.object({
 				key: Structure.string("fallback"),
 			});
@@ -335,15 +418,57 @@ describe("Structure", () => {
 				() => struct.process({ key: 42 }),
 				StructError,
 			);
-			assertEquals(
-				error,
-				new StructError(
-					"Object does not match schema",
-					[],
-					[new StructError("Not a string", ["key"])],
-				),
-				"should validate properties against their schema",
+
+			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/package.json

@@ -28,5 +28,5 @@
       "import": "./source/*.js"
     }
   },
-  "version": "0.3.0"
+  "version": "0.4.0"
 }