gruber 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 This file documents notable changes to the project
 
+## 0.4.1
+
+**fixes**
+
+- `getDenoConfigOptions`, `getDenoConfiguration`, `getNodeConfigOptions` and `getNodeConfiguration` all have a default options of `{}`
+- The Configuration markdown tables calculates the width properly when there are non-strings (URLs) in there
+- The `Structure.boolean` method correctly types the optional fallback argument.
+- Add experimental `Structure.literal` construct
+- `Structure.object` fails if there are additional fields or the value is an instance of a class
+
 ## 0.4.0
 
 **new**

package/core/configuration.d.ts

@@ -38,7 +38,7 @@ export class _ObjectSpec {
         fields: Record<string, string>[];
     };
 }
-export class _LiteralSpec {
+export class _PrimativeSpec {
     /**
      * @param {string} type
      * @param {SpecOptions<any>} options
@@ -49,11 +49,11 @@ export class _LiteralSpec {
     describe(name: any): {
         fallback: any;
         fields: {
-            variable?: string;
-            flag?: string;
-            fallback: any;
             name: any;
             type: string;
+            fallback: any;
+            variable?: string;
+            flag?: string;
         }[];
     };
 }

package/core/configuration.js

@@ -70,7 +70,11 @@ export class _ObjectSpec {
 	}
 }
 
-export class _LiteralSpec {
+//
+// NOTE: describe() calls should return the actual value in "fallback"
+//       and the string-value in fields
+//
+export class _PrimativeSpec {
 	/**
 	 * @param {string} type
 	 * @param {SpecOptions<any>} options
@@ -82,7 +86,14 @@ export class _LiteralSpec {
 	describe(name) {
 		return {
 			fallback: this.options.fallback,
-			fields: [{ name, type: this.type, ...this.options }],
+			fields: [
+				{
+					...this.options,
+					name,
+					type: this.type,
+					fallback: this.options.fallback?.toString(),
+				},
+			],
 		};
 	}
 }
@@ -150,7 +161,7 @@ export class Configuration {
 		}
 
 		const struct = Structure.string(this._getValue(options).value);
-		struct[Configuration.spec] = new _LiteralSpec("string", options);
+		struct[Configuration.spec] = new _PrimativeSpec("string", options);
 		return struct;
 	}
 
@@ -165,7 +176,7 @@ export class Configuration {
 
 		const fallback = this._parseFloat(this._getValue(options));
 		const struct = Structure.number(fallback);
-		struct[Configuration.spec] = new _LiteralSpec("number", options);
+		struct[Configuration.spec] = new _PrimativeSpec("number", options);
 		return struct;
 	}
 
@@ -180,7 +191,7 @@ export class Configuration {
 
 		const fallback = this._parseBoolean(this._getValue(options));
 		const struct = Structure.boolean(fallback);
-		struct[Configuration.spec] = new _LiteralSpec("boolean", options);
+		struct[Configuration.spec] = new _PrimativeSpec("boolean", options);
 		return struct;
 	}
 
@@ -196,7 +207,7 @@ export class Configuration {
 			throw new TypeError("options.fallback must be a string or URL");
 		}
 		const struct = Structure.url(this._getValue(options).value);
-		struct[Configuration.spec] = new _LiteralSpec("url", {
+		struct[Configuration.spec] = new _PrimativeSpec("url", {
 			...options,
 			fallback: new URL(options.fallback),
 		});

package/core/configuration.test.js

@@ -56,7 +56,7 @@ describe("Configuration", () => {
 						name: "person.age",
 						type: "number",
 						flag: "--age",
-						fallback: 42,
+						fallback: "42",
 					},
 				],
 			});
@@ -381,7 +381,7 @@ describe("Configuration", () => {
 			const config = new Configuration(bareOptions);
 			const result = config.describe(
 				config.url({
-					fallback: "https://example.com",
+					fallback: "https://example.com/",
 					variable: "SELF_URL",
 					flag: "--self-url",
 				}),
@@ -392,7 +392,7 @@ describe("Configuration", () => {
 				{
 					name: "selfUrl",
 					type: "url",
-					fallback: new URL("https://example.com"),
+					fallback: "https://example.com/",
 					variable: "SELF_URL",
 					flag: "--self-url",
 				},

package/core/structures.d.ts

@@ -18,17 +18,6 @@ export class StructError extends Error {
     /** @returns {Iterator<StructError>} */
     [Symbol.iterator](): Iterator<StructError>;
 }
-/**
- * @typedef {Record<string,unknown>} Schema
- */
-/**
- * @template T
- * @typedef {(input?: unknown, context?: StructContext) => T} StructExec
- */
-/**
- * @template T
- * @typedef {T extends Structure<infer U> ? U : never} Infer
- */
 /**
  * @template T
  */
@@ -44,10 +33,10 @@ export class Structure<T> {
      */
     static number(fallback?: number): Structure<number>;
     /**
-     * @param {boolean} fallback
+     * @param {boolean} [fallback]
      * @returns {Structure<boolean>}
      */
-    static boolean(fallback: boolean): Structure<boolean>;
+    static boolean(fallback?: boolean): Structure<boolean>;
     /**
      * @param {string | URL} [fallback]
      * @returns {Structure<URL>}
@@ -67,17 +56,28 @@ export class Structure<T> {
      * @returns {Structure<Array<Infer<U>>>}
      */
     static array<U_1 extends Structure<any>>(struct: U_1): Structure<Infer<U_1>[]>;
+    /**
+     * **UNSTABLE** use at your own risk
+     *
+     * @template {string|number|boolean} T
+     * @param {T} value
+     * @returns {Structure<T>}
+     */
+    static literal<T_1 extends string | number | boolean>(value: T_1): Structure<T_1>;
     /**
      * @param {Schema} schema
      * @param {StructExec<T>} process
      */
     constructor(schema: Schema, process: StructExec<T>);
-    schema: Schema;
+    schema: Record<string, unknown>;
     process: StructExec<T>;
     getSchema(): {
         $schema: string;
     };
 }
+export type Schema = Record<string, unknown>;
+export type StructExec<T> = (input?: unknown, context?: StructContext) => T;
+export type Infer<T> = T extends Structure<infer U> ? U : never;
 export type StructContext = {
     path: string[];
 };
@@ -86,6 +86,3 @@ export type StructOptions<Type, Schema> = {
     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 Infer<T> = T extends Structure<infer U> ? U : never;

package/core/structures.js

@@ -85,6 +85,11 @@ export class StructError extends Error {
  * @typedef {T extends Structure<infer U> ? U : never} Infer
  */
 
+function _additionalProperties(fields, input) {
+	const allowed = new Set(Object.keys(fields));
+	return Array.from(Object.keys(input)).filter((key) => !allowed.has(key));
+}
+
 /**
  * @template T
  */
@@ -148,7 +153,7 @@ export class Structure {
 	}
 
 	/**
-	 * @param {boolean} fallback
+	 * @param {boolean} [fallback]
 	 * @returns {Structure<boolean>}
 	 */
 	static boolean(fallback) {
@@ -206,6 +211,9 @@ export class Structure {
 			if (input && typeof input !== "object") {
 				throw new StructError("Expected an object", path);
 			}
+			if (Object.getPrototypeOf(input) !== Object.getPrototypeOf({})) {
+				throw new StructError("Should not have a prototype", path);
+			}
 			const output = {};
 			const errors = [];
 			for (const key in fields) {
@@ -216,6 +224,13 @@ export class Structure {
 					errors.push(StructError.chain(error, ctx));
 				}
 			}
+
+			for (const key of _additionalProperties(fields, input)) {
+				errors.push(
+					new StructError("Additional field not allowed", [...path, key]),
+				);
+			}
+
 			if (errors.length > 0) {
 				throw new StructError("Object does not match schema", path, errors);
 			}
@@ -257,4 +272,28 @@ export class Structure {
 			return output;
 		});
 	}
+
+	/**
+	 * **UNSTABLE** use at your own risk
+	 *
+	 * @template {string|number|boolean} T
+	 * @param {T} value
+	 * @returns {Structure<T>}
+	 */
+	static literal(value) {
+		const schema = { type: typeof value, const: value };
+
+		return new Structure(schema, (input, context = undefined) => {
+			if (input === undefined) {
+				throw new StructError("Missing value", context?.path);
+			}
+			if (input !== value) {
+				throw new StructError(
+					`Expected ${schema.type} literal: ${value}`,
+					context?.path,
+				);
+			}
+			return value;
+		});
+	}
 }

package/core/structures.test.js

@@ -425,6 +425,44 @@ describe("Structure", () => {
 			assertEquals(error.children[0].message, "Expected a string");
 			assertEquals(error.children[0].path, ["key"], "should capture context");
 		});
+		it("throws for unknown fields", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			const error = assertThrows(
+				() =>
+					struct.process(
+						{ key: "value", something: "else" },
+						{ path: ["some", "path"] },
+					),
+				StructError,
+			);
+
+			assertEquals(error.message, "Object does not match schema");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+
+			assertEquals(error.children[0].message, "Additional field not allowed");
+			assertEquals(
+				error.children[0].path,
+				["some", "path", "something"],
+				"should capture the context",
+			);
+		});
+		it("throws for non-null prototypes", () => {
+			const struct = Structure.object({
+				key: Structure.string("fallback"),
+			});
+			class Injector {
+				key = "value";
+			}
+			const error = assertThrows(
+				() => struct.process(new Injector(), { path: ["some", "path"] }),
+				StructError,
+			);
+
+			assertEquals(error.message, "Should not have a prototype");
+			assertEquals(error.path, ["some", "path"], "should capture the context");
+		});
 	});
 
 	describe("array", () => {
@@ -471,4 +509,54 @@ describe("Structure", () => {
 			assertEquals(error.children[0].path, ["1"], "should capture context");
 		});
 	});
+
+	describe("literal", () => {
+		it("creates a structure", () => {
+			const struct = Structure.literal(42);
+			assertInstanceOf(struct, Structure);
+		});
+		it("allows that value", () => {
+			const struct = Structure.literal(42);
+			assertEquals(struct.process(42), 42, "should pass the value through");
+		});
+		it("throws for different values", () => {
+			const struct = Structure.literal(42);
+
+			const error = assertThrows(
+				() => struct.process(69, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(
+				error,
+				new StructError("Expected number literal: 42", ["some", "path"]),
+				"should throw a StructError and capture the context",
+			);
+		});
+		it("throws for different types", () => {
+			const struct = Structure.literal(42);
+
+			const error = assertThrows(
+				() => struct.process("nice", { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(
+				error,
+				new StructError("Expected number literal: 42", ["some", "path"]),
+				"should throw a StructError and capture the context",
+			);
+		});
+		it("throws for missing values", () => {
+			const struct = Structure.literal(42);
+
+			const error = assertThrows(
+				() => struct.process(undefined, { path: ["some", "path"] }),
+				StructError,
+			);
+			assertEquals(
+				error,
+				new StructError("Missing value", ["some", "path"]),
+				"should throw a StructError and capture the context",
+			);
+		});
+	});
 });

package/package.json

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

package/source/configuration.d.ts

@@ -2,7 +2,7 @@
     @typedef {object} NodeConfigurationOptions
 */
 /** @param {NodeConfigurationOptions} options */
-export function getNodeConfigOptions(options: NodeConfigurationOptions): {
+export function getNodeConfigOptions(options?: NodeConfigurationOptions): {
     readTextFile(url: any): Promise<Buffer>;
     getEnvironmentVariable(key: any): string;
     getCommandArgument(key: any): string | boolean;
@@ -13,7 +13,7 @@ export function getNodeConfigOptions(options: NodeConfigurationOptions): {
  * This is a syntax sugar for `new Configuration(getNodeConfigOptions(options))`
  * @param {NodeConfigurationOptions} options
  */
-export function getNodeConfiguration(options: NodeConfigurationOptions): Configuration;
+export function getNodeConfiguration(options?: NodeConfigurationOptions): Configuration;
 export { Configuration };
 export type NodeConfigurationOptions = object;
 import { Configuration } from "../core/configuration.js";

package/source/configuration.js

@@ -11,7 +11,7 @@ export { Configuration };
 */
 
 /** @param {NodeConfigurationOptions} options */
-export function getNodeConfigOptions(options) {
+export function getNodeConfigOptions(options = {}) {
 	const args = util.parseArgs({
 		args: process.args,
 		strict: false,
@@ -43,6 +43,6 @@ export function getNodeConfigOptions(options) {
  * This is a syntax sugar for `new Configuration(getNodeConfigOptions(options))`
  * @param {NodeConfigurationOptions} options
  */
-export function getNodeConfiguration(options) {
+export function getNodeConfiguration(options = {}) {
 	return new Configuration(getNodeConfigOptions(options));
 }