@oscarpalmer/jhunal 0.19.0 → 0.20.0

package/dist/index.mjs

@@ -2,6 +2,10 @@ import { isConstructor, isPlainObject } from "@oscarpalmer/atoms/is";
 import { join } from "@oscarpalmer/atoms/string";
 import { error } from "@oscarpalmer/atoms/result/misc";
 //#region src/constants.ts
+const CONJUNCTION_OR = " or ";
+const CONJUNCTION_OR_COMMA = ", or ";
+const CONJUNCTION_AND = " and ";
+const CONJUNCTION_AND_COMMA = ", and ";
 const MESSAGE_CONSTRUCTOR = "Expected a constructor function";
 const NAME_SCHEMATIC = "Schematic";
 const NAME_ERROR_SCHEMATIC = "SchematicError";
@@ -15,6 +19,7 @@ const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required property '
 const VALIDATION_MESSAGE_INVALID_TYPE = "Expected <> for '<>' but received <>";
 const VALIDATION_MESSAGE_INVALID_VALUE = "Value does not satisfy validator for '<>' and type '<>'";
 const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = " at index <>";
+const VALIDATION_MESSAGE_UNKNOWN_KEYS = "Found keys that are not defined in the schema: <>";
 const REPORTING_FIRST = "first";
 const REPORTING_NONE = "none";
 const REPORTING_THROW = "throw";
@@ -75,6 +80,21 @@ function getInvalidValidatorMessage(property, type, index, length) {
 	if (length > 1) message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace("<>", String(index));
 	return message;
 }
+function getOptions(input) {
+	if (typeof input === "boolean") return {
+		reporting: getReporting(REPORTING_NONE),
+		strict: input
+	};
+	if (REPORTING_TYPES.has(input)) return {
+		reporting: getReporting(input),
+		strict: false
+	};
+	const options = isPlainObject(input) ? input : {};
+	return {
+		reporting: getReporting(options.errors),
+		strict: typeof options.strict === "boolean" ? options.strict : false
+	};
+}
 function getPropertyType(original) {
 	if (typeof original === "function") return "a validated value";
 	if (Array.isArray(original)) return `'${TYPE_OBJECT}'`;
@@ -84,12 +104,16 @@ function getPropertyType(original) {
 function getReporting(value) {
 	const type = REPORTING_TYPES.has(value) ? value : REPORTING_NONE;
 	return {
+		type,
 		["all"]: type === "all",
 		[REPORTING_FIRST]: type === REPORTING_FIRST,
 		[REPORTING_NONE]: type === REPORTING_NONE,
 		[REPORTING_THROW]: type === REPORTING_THROW
 	};
 }
+function getUnknownKeysMessage(keys) {
+	return VALIDATION_MESSAGE_UNKNOWN_KEYS.replace("<>", renderKeys(keys));
+}
 function getValueType(value) {
 	const valueType = typeof value;
 	switch (true) {
@@ -122,6 +146,20 @@ function instanceOf(constructor) {
 function isSchematic(value) {
 	return typeof value === "object" && value !== null && "$schematic" in value && value["$schematic"] === true;
 }
+function renderKeys(keys) {
+	return renderParts(keys.map((key) => `'${key}'`), CONJUNCTION_AND, CONJUNCTION_AND_COMMA);
+}
+function renderParts(parts, delimiterShort, delimiterLong) {
+	const { length } = parts;
+	if (length === 1) return parts[0];
+	let rendered = "";
+	for (let index = 0; index < length; index += 1) {
+		rendered += parts[index];
+		if (index < length - 2) rendered += ", ";
+		else if (index === length - 2) rendered += parts.length > 2 ? delimiterLong : delimiterShort;
+	}
+	return rendered;
+}
 function renderTypes(types) {
 	const unique = /* @__PURE__ */ new Set();
 	const parts = [];
@@ -131,19 +169,12 @@ function renderTypes(types) {
 		unique.add(rendered);
 		parts.push(rendered);
 	}
-	const { length } = parts;
-	let rendered = "";
-	for (let index = 0; index < length; index += 1) {
-		rendered += parts[index];
-		if (index < length - 2) rendered += ", ";
-		else if (index === length - 2) rendered += parts.length > 2 ? ", or " : " or ";
-	}
-	return rendered;
+	return renderParts(parts, CONJUNCTION_OR, CONJUNCTION_OR_COMMA);
 }
 //#endregion
 //#region src/models/validation.model.ts
 /**
-* A custom error class for schematic validation failures
+* Thrown when a schema definition is invalid
 */
 var SchematicError = class extends Error {
 	constructor(message) {
@@ -151,6 +182,9 @@ var SchematicError = class extends Error {
 		this.name = NAME_ERROR_SCHEMATIC;
 	}
 };
+/**
+* Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
+*/
 var ValidationError = class extends Error {
 	constructor(information) {
 		super(join(information.map((item) => item.message), "; "));
@@ -269,23 +303,53 @@ function validateNamed(property, name, value, validation) {
 	}
 	return true;
 }
-function validateObject(obj, properties, reporting, property, validation) {
+function validateObject(obj, properties, options, origin, validation) {
 	if (!isPlainObject(obj)) {
+		const key = origin == null ? {
+			full: "",
+			short: ""
+		} : { ...origin.key };
 		const information = {
-			key: {
-				full: "",
-				short: ""
-			},
-			message: property == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage(property, obj),
+			key,
+			message: origin == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage({
+				...origin,
+				key
+			}, obj),
 			value: obj
 		};
-		if (reporting.throw) throw new ValidationError([information]);
-		return reporting.none ? false : [information];
+		if (options.reporting.throw) throw new ValidationError([information]);
+		validation?.push(information);
+		return options.reporting.none ? false : [information];
+	}
+	if (options.strict) {
+		const objKeys = Object.keys(obj);
+		const propertiesKeys = new Set(properties.map((property) => property.key.short));
+		const unknownKeys = objKeys.filter((key) => !propertiesKeys.has(key));
+		if (unknownKeys.length > 0) {
+			const information = {
+				key: origin == null ? {
+					full: "",
+					short: ""
+				} : { ...origin.key },
+				message: getUnknownKeysMessage(unknownKeys.map((key) => join([origin?.key.full, key], "."))),
+				value: obj
+			};
+			if (options.reporting.throw) throw new ValidationError([information]);
+			validation?.push(information);
+			return options.reporting.none ? false : [information];
+		}
 	}
 	const allInformation = [];
 	const propertiesLength = properties.length;
 	outer: for (let propertyIndex = 0; propertyIndex < propertiesLength; propertyIndex += 1) {
-		const property = properties[propertyIndex];
+		let property = properties[propertyIndex];
+		property = {
+			...property,
+			key: {
+				full: join([origin?.key.full, property.key.short], "."),
+				short: property.key.short
+			}
+		};
 		const { key, required, types } = property;
 		const value = obj[key.short];
 		if (value === void 0 && required) {
@@ -294,43 +358,47 @@ function validateObject(obj, properties, reporting, property, validation) {
 				key: { ...key },
 				message: getInvalidMissingMessage(property)
 			};
-			if (reporting.throw && validation == null) throw new ValidationError([information]);
+			if (options.reporting.throw && validation == null) throw new ValidationError([information]);
 			if (validation != null) validation.push(information);
-			if (reporting.all) {
+			if (options.reporting.all) {
 				allInformation.push(information);
 				continue;
 			}
-			return reporting.none ? false : [information];
+			return options.reporting.none ? false : [information];
 		}
 		const typesLength = types.length;
 		const information = [];
 		for (let typeIndex = 0; typeIndex < typesLength; typeIndex += 1) {
 			const type = types[typeIndex];
-			if (validateValue(type, property, value, reporting, information)) continue outer;
+			if (validateValue(type, property, value, options, information)) continue outer;
 		}
 		if (information.length === 0) information.push({
 			value,
 			key: { ...key },
 			message: getInvalidTypeMessage(property, value)
 		});
-		if (reporting.throw && validation == null) throw new ValidationError(information);
+		if (options.reporting.throw && validation == null) throw new ValidationError(information);
 		validation?.push(...information);
-		if (reporting.all) {
+		if (options.reporting.all) {
 			allInformation.push(...information);
 			continue;
 		}
-		return reporting.none ? false : information;
+		return options.reporting.none ? false : information;
 	}
-	return reporting.none ? true : allInformation.length === 0 ? true : allInformation;
+	return options.reporting.none || allInformation.length === 0 ? true : allInformation;
 }
-function validateValue(type, property, value, reporting, validation) {
+function validateSchematic(property, schematic, value, options, validation) {
+	const result = validateObject(value, schematicProperties.get(schematic), options, property, validation);
+	return typeof result === "boolean" ? result : result.length === 0;
+}
+function validateValue(type, property, value, options, validation) {
 	switch (true) {
 		case typeof type === "function": return type(value);
 		case Array.isArray(type): {
-			const nested = validateObject(value, type, reporting, property, validation);
-			return typeof nested !== "boolean" ? false : nested;
+			const validated = validateObject(value, type, options, property, validation);
+			return typeof validated === "boolean" ? validated : false;
 		}
-		case isSchematic(type): return type.is(value, reporting);
+		case isSchematic(type): return validateSchematic(property, type, value, options, validation);
 		default: return validateNamed(property, type, value, validation);
 	}
 }
@@ -357,10 +425,14 @@ var Schematic = class {
 	constructor(properties) {
 		Object.defineProperty(this, PROPERTY_SCHEMATIC, { value: true });
 		this.#properties = properties;
+		schematicProperties.set(this, properties);
 	}
-	is(value, errors) {
-		const reporting = getReporting(errors);
-		const result = validateObject(value, this.#properties, reporting);
+	is(value, options) {
+		const { reporting, strict } = getOptions(options);
+		const result = validateObject(value, this.#properties, {
+			reporting,
+			strict
+		});
 		if (typeof result === "boolean") return result;
 		return error(reporting.all ? result : result[0]);
 	}
@@ -370,5 +442,6 @@ function schematic(schema) {
 	if (!isPlainObject(schema)) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE);
 	return new Schematic(getProperties(schema));
 }
+const schematicProperties = /* @__PURE__ */ new WeakMap();
 //#endregion
 export { SchematicError, ValidationError, instanceOf, isSchematic, schematic };

package/dist/models/infer.model.d.mts

@@ -7,7 +7,7 @@ import { Constructor, Simplify } from "@oscarpalmer/atoms/models";
 /**
  * Infers the TypeScript type from a {@link Schema} definition
  *
- * @template Model - Schema to infer types from
+ * @template Model Schema to infer types from
  *
  * @example
  * ```ts
@@ -29,37 +29,37 @@ type Infer<Model extends Schema> = Simplify<{ [Key in InferRequiredKeys<Model>]:
  */
 type InferOptionalKeys<Model extends Schema> = keyof { [Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? Key : never]: never };
 /**
- * Infers the TypeScript type of a {@link SchemaProperty}'s `$type` field, unwrapping arrays to infer their item type
+ * Infers the TypeScript type from a {@link SchemaProperty}'s `$type` field
  *
- * @template Value - `$type` value _(single or array)_
+ * @template Value `$type` value _(single or array)_
  */
 type InferPropertyType<Value> = Value extends (infer Item)[] ? InferPropertyValue<Item> : InferPropertyValue<Value>;
 /**
- * Maps a single type definition to its TypeScript equivalent
+ * Maps a single `$type` definition to its TypeScript equivalent
  *
- * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link ValueName} strings, and nested {@link Schema} objects
+ * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link ValueName} strings, and nested {@link PlainSchema} objects
  *
- * @template Value - single type definition
+ * @template Value single type definition
  */
 type InferPropertyValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schematic<infer Model> ? Model : Value extends ValueName ? Values[Value & ValueName] : Value extends Schema ? Infer<Value> : never;
 /**
  * Extracts keys from a {@link Schema} whose entries are required _(i.e., `$required` is not `false`)_
  *
- * @template Model - Schema to extract required keys from
+ * @template Model Schema to extract required keys from
  */
 type InferRequiredKeys<Model extends Schema> = keyof { [Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? never : Key]: never };
 /**
- * Infers the type for a top-level {@link Schema} entry, unwrapping arrays to infer their item type
+ * Infers the TypeScript type from a top-level {@link Schema} entry
  *
- * @template Value - Schema entry value _(single or array)_
+ * @template Value Schema entry value _(single or array)_
  */
 type InferSchemaEntry<Value> = Value extends (infer Item)[] ? InferSchemaEntryValue<Item> : InferSchemaEntryValue<Value>;
 /**
- * Resolves a single schema entry to its TypeScript type
+ * Maps a single top-level schema entry to its TypeScript type
  *
- * Handles, in order: {@link Constructor} instances, {@link Schematic} models, {@link SchemaProperty} objects, {@link NestedSchema} objects, {@link ValueName} strings, and plain {@link Schema} objects
+ * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link SchemaProperty} objects, {@link PlainSchema} objects, and {@link ValueName} strings
  *
- * @template Value - single schema entry
+ * @template Value single schema entry
  */
 type InferSchemaEntryValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schematic<infer Model> ? Model : Value extends SchemaProperty ? InferPropertyType<Value['$type']> : Value extends PlainSchema ? Infer<Value & Schema> : Value extends ValueName ? Values[Value & ValueName] : Value extends Schema ? Infer<Value> : never;
 //#endregion

package/dist/models/misc.model.d.mts

@@ -4,8 +4,8 @@ import { SchemaProperty } from "./schema.plain.model.mjs";
 /**
  * Removes duplicate types from a tuple, preserving first occurrence order
  *
- * @template Value - Tuple to deduplicate
- * @template Seen - Accumulator for already-seen types _(internal)_
+ * @template Value Tuple to deduplicate
+ * @template Seen Accumulator for already-seen types _(internal)_
  *
  * @example
  * ```ts
@@ -17,7 +17,7 @@ type DeduplicateTuple<Value extends unknown[], Seen extends unknown[] = []> = Va
 /**
  * Recursively extracts {@link ValueName} strings from a type, unwrapping arrays and readonly arrays
  *
- * @template Value - Type to extract value names from
+ * @template Value Type to extract value names from
  *
  * @example
  * ```ts
@@ -29,27 +29,27 @@ type ExtractValueNames<Value> = Value extends ValueName ? Value : Value extends
 /**
  * Determines whether a schema entry is optional
  *
- * Returns `true` if the entry is a {@link SchemaProperty} or {@link NestedSchema} with `$required` set to `false`; otherwise returns `false`
+ * Returns `true` if the entry is a {@link SchemaProperty} with `$required` set to `false`; otherwise returns `false`
  *
- * @template Value - Schema entry to check
+ * @template Value Schema entry to check
  */
 type IsOptionalProperty<Value> = Value extends SchemaProperty ? Value['$required'] extends false ? true : false : false;
 /**
- * Extracts the last member from a union type by leveraging intersection of function return types
+ * Extracts the last member from a union type by leveraging contravariance of function parameter types
  *
- * @template Value - Union type
+ * @template Value Union type
  */
 type LastOfUnion<Value> = UnionToIntersection<Value extends unknown ? () => Value : never> extends (() => infer Item) ? Item : never;
 /**
  * Extracts keys from an object type that are optional
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 type OptionalKeys<Value> = { [Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never }[keyof Value];
 /**
  * Extracts keys from an object type that are required _(i.e., not optional)_
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
 /**
@@ -57,8 +57,8 @@ type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
  *
  * Used by {@link UnwrapSingle} to allow schema types in any order for small tuples _(length ≤ 5)_
  *
- * @template Tuple - Tuple to permute
- * @template Elput - Accumulator for the current permutation _(internal; name is Tuple backwards)_
+ * @template Tuple Tuple to permute
+ * @template Elput Accumulator for the current permutation _(internal; name is Tuple backwards)_
  *
  * @example
  * ```ts
@@ -72,9 +72,9 @@ type TuplePermutations<Tuple extends unknown[], Elput extends unknown[] = []> =
  *
  * Used internally by {@link TuplePermutations}
  *
- * @template Items - Tuple to remove from
- * @template Item - Stringified index to remove
- * @template Prefix - Accumulator for elements before the target _(internal)_
+ * @template Items Tuple to remove from
+ * @template Item Index as a string literal
+ * @template Prefix Accumulator for elements before the target _(internal)_
  */
 type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends unknown[] = []> = Items extends [infer Head, ...infer Tail] ? `${Prefix['length']}` extends Item ? [...Prefix, ...Tail] : TupleRemoveAt<Tail, Item, [...Prefix, Head]> : Prefix;
 /**
@@ -82,7 +82,7 @@ type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends
  *
  * Uses the contravariance of function parameter types to collapse a union into an intersection
  *
- * @template Value - Union type to convert
+ * @template Value Union type to convert
  *
  * @example
  * ```ts
@@ -96,8 +96,8 @@ type UnionToIntersection<Value> = (Value extends unknown ? (value: Value) => voi
  *
  * Repeatedly extracts the {@link LastOfUnion} member and prepends it to the accumulator
  *
- * @template Value - Union type to convert
- * @template Items - Accumulator for the resulting tuple _(internal)_
+ * @template Value Union type to convert
+ * @template Items Accumulator for the resulting tuple _(internal)_
  *
  * @example
  * ```ts
@@ -111,7 +111,7 @@ type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never]
  *
  * For tuples of length 2–5, returns all {@link TuplePermutations} to allow types in any order. Longer tuples are returned as-is
  *
- * @template Value - Tuple to potentially unwrap
+ * @template Value Tuple to potentially unwrap
  *
  * @example
  * ```ts
@@ -121,20 +121,11 @@ type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never]
  */
 type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only : Value['length'] extends 1 | 2 | 3 | 4 | 5 ? TuplePermutations<Value> : Value;
 /**
- * Basic value types
+ * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
  */
 type ValueName = keyof Values;
 /**
- * Maps type name strings to their TypeScript equivalents
- *
- * Used by the type system to resolve {@link ValueName} strings into actual types
- *
- * @example
- * ```ts
- * // Values['string']  => string
- * // Values['date']    => Date
- * // Values['null']    => null
- * ```
+ * Maps {@link ValueName} strings to their TypeScript equivalents
  */
 type Values = {
   array: unknown[];

package/dist/models/schema.plain.model.d.mts

@@ -4,7 +4,7 @@ import { Constructor } from "@oscarpalmer/atoms/models";
 
 //#region src/models/schema.plain.model.d.ts
 /**
- * A generic schema allowing {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry} as values
+ * A generic schema allowing nested schemas, {@link SchemaEntry} values, or arrays of {@link SchemaEntry} as values
  */
 type PlainSchema = {
   [key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
@@ -29,11 +29,11 @@ type Schema = SchemaIndex;
 /**
  * A union of all valid types for a single schema entry
  *
- * Can be a {@link Constructor}, nested {@link Schema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
  */
 type SchemaEntry = Constructor | PlainSchema | SchemaProperty | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
 /**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
+ * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link PlainSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
  */
 interface SchemaIndex {
   [key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
@@ -78,7 +78,7 @@ type SchemaPropertyType = Constructor | PlainSchema | Schematic<unknown> | Value
  *
  * Each key may hold a single validator or an array of validators that receive the typed value
  *
- * @template Value - `$type` value(s) to derive validator keys from
+ * @template Value `$type` value(s) to derive validator keys from
  *
  * @example
  * ```ts

package/dist/models/schema.typed.model.d.mts

@@ -8,7 +8,7 @@ import { PlainObject, Simplify } from "@oscarpalmer/atoms/models";
 /**
  * A typed optional property definition generated by {@link TypedSchema} for optional keys, with `$required` set to `false` and excludes `undefined` from the type
  *
- * @template Value - Property's type _(including `undefined`)_
+ * @template Value Property's type _(including `undefined`)_
  *
  * @example
  * ```ts
@@ -18,23 +18,14 @@ import { PlainObject, Simplify } from "@oscarpalmer/atoms/models";
  * ```
  */
 type TypedPropertyOptional<Value> = {
-  /**
-   * The property is not required
-   */
   $required: false;
-  /**
-   * The type(s) of the property
-   */
   $type: ToSchemaPropertyType<Exclude<Value, undefined>>;
-  /**
-   * Custom validators for the property and its types
-   */
   $validators?: PropertyValidators<ToSchemaPropertyType<Exclude<Value, undefined>>>;
 };
 /**
  * A typed required property definition generated by {@link TypedSchema} for required keys, with `$required` defaulting to `true`
  *
- * @template Value - Property's type
+ * @template Value Property's type
  *
  * @example
  * ```ts
@@ -44,17 +35,8 @@ type TypedPropertyOptional<Value> = {
  * ```
  */
 type TypedPropertyRequired<Value> = {
-  /**
-   * The property is required _(defaults to `true`)_
-   */
   $required?: true;
-  /**
-   * The type(s) of the property
-   */
   $type: ToSchemaPropertyType<Value>;
-  /**
-   * Custom validators for the property and its types
-   */
   $validators?: PropertyValidators<ToSchemaPropertyType<Value>>;
 };
 /**
@@ -62,7 +44,7 @@ type TypedPropertyRequired<Value> = {
  *
  * Required keys map to {@link ToSchemaType} or {@link TypedPropertyRequired}; plain object values may also use {@link Schematic}. Optional keys map to {@link TypedPropertyOptional} or, for plain objects, {@link TypedSchemaOptional}
  *
- * @template Model - Object type to generate a schema for
+ * @template Model Object type to generate a schema for
  *
  * @example
  * ```ts
@@ -79,7 +61,7 @@ type TypedSchema<Model extends PlainObject> = Simplify<{ [Key in RequiredKeys<Mo
 /**
  * A {@link TypedSchema} variant for optional nested objects, with `$required` fixed to `false`
  *
- * @template Model - Nested object type
+ * @template Model Nested object type
  */
 type TypedSchemaOptional<Model extends PlainObject> = {
   $required: false;
@@ -87,7 +69,7 @@ type TypedSchemaOptional<Model extends PlainObject> = {
 /**
  * A {@link TypedSchema} variant for required nested objects, with `$required` defaulting to `true`
  *
- * @template Model - Nested object type
+ * @template Model Nested object type
  */
 type TypedSchemaRequired<Model extends PlainObject> = {
   $required?: true;

package/dist/models/transform.model.d.mts

@@ -7,37 +7,33 @@ import { PlainObject } from "@oscarpalmer/atoms/models";
 /**
  * Maps each element of a tuple through {@link ToValueType}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 type MapToValueTypes<Value extends unknown[]> = Value extends [infer Head, ...infer Tail] ? [ToValueType<Head>, ...MapToValueTypes<Tail>] : [];
 /**
  * Maps each element of a tuple through {@link ToSchemaPropertyTypeEach}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 type MapToSchemaPropertyTypes<Value extends unknown[]> = Value extends [infer Head, ...infer Tail] ? [ToSchemaPropertyTypeEach<Head>, ...MapToSchemaPropertyTypes<Tail>] : [];
 /**
- * Converts a type into its corresponding {@link SchemaPropertyType}-representation
+ * Converts a TypeScript type to its {@link SchemaPropertyType} representation, suitable for use in a typed schema
  *
- * Deduplicates and unwraps single-element tuples via {@link UnwrapSingle}
- *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 type ToSchemaPropertyType<Value> = UnwrapSingle<DeduplicateTuple<MapToSchemaPropertyTypes<UnionToTuple<Value>>>>;
 /**
  * Converts a single type to its schema property equivalent
  *
- * {@link NestedSchema} values have `$required` stripped, plain objects become {@link TypedSchema}, and primitives go through {@link ToValueType}
+ * Plain objects become {@link TypedSchema}; primitives go through {@link ToValueType}
  *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 type ToSchemaPropertyTypeEach<Value> = Value extends PlainObject ? TypedSchema<Value> : ToValueType<Value>;
 /**
- * Converts a type into its corresponding {@link ValueName}-representation
- *
- * Deduplicates and unwraps single-element tuples via {@link UnwrapSingle}
+ * Converts a TypeScript type to its {@link ValueName} representation, suitable for use as a top-level schema entry
  *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 type ToSchemaType<Value> = UnwrapSingle<DeduplicateTuple<MapToValueTypes<UnionToTuple<Value>>>>;
 /**
@@ -45,7 +41,7 @@ type ToSchemaType<Value> = UnwrapSingle<DeduplicateTuple<MapToValueTypes<UnionTo
  *
  * Resolves {@link Schematic} types as-is, then performs a reverse-lookup against {@link Values} _(excluding `'object'`)_ to find a matching key. If no match is found, `object` types resolve to `'object'` or a type-guard function, and all other unrecognised types resolve to a type-guard function
  *
- * @template Value - type to map
+ * @template Value Type to map
  *
  * @example
  * ```ts