@oscarpalmer/jhunal 0.19.0 → 0.21.0

package/dist/index.mjs

@@ -1,7 +1,12 @@
 import { isConstructor, isPlainObject } from "@oscarpalmer/atoms/is";
 import { join } from "@oscarpalmer/atoms/string";
-import { error } from "@oscarpalmer/atoms/result/misc";
+import { error, ok } from "@oscarpalmer/atoms/result/misc";
+import { clone } from "@oscarpalmer/atoms/value/clone";
 //#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 +20,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";
@@ -58,23 +64,41 @@ const TYPE_ALL = new Set([
 function getInvalidInputMessage(actual) {
 	return VALIDATION_MESSAGE_INVALID_INPUT.replace("<>", getValueType(actual));
 }
-function getInvalidMissingMessage(property) {
-	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace("<>", renderTypes(property.types));
-	message = message.replace("<>", property.key.full);
+function getInvalidMissingMessage(key, types) {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace("<>", renderTypes(types));
+	message = message.replace("<>", key);
 	return message;
 }
-function getInvalidTypeMessage(property, actual) {
-	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace("<>", renderTypes(property.types));
-	message = message.replace("<>", property.key.full);
+function getInvalidTypeMessage(key, types, actual) {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace("<>", renderTypes(types));
+	message = message.replace("<>", key);
 	message = message.replace("<>", getValueType(actual));
 	return message;
 }
-function getInvalidValidatorMessage(property, type, index, length) {
-	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace("<>", property.key.full);
+function getInvalidValidatorMessage(key, type, index, length) {
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace("<>", key);
 	message = message.replace("<>", type);
 	if (length > 1) message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace("<>", String(index));
 	return message;
 }
+function getParameters(input) {
+	if (typeof input === "boolean") return {
+		output: {},
+		reporting: getReporting(REPORTING_NONE),
+		strict: input
+	};
+	if (REPORTING_TYPES.has(input)) return {
+		output: {},
+		reporting: getReporting(input),
+		strict: false
+	};
+	const options = isPlainObject(input) ? input : {};
+	return {
+		output: {},
+		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 +108,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 +150,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 +173,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 +186,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), "; "));
@@ -176,9 +214,8 @@ function getProperties(original, prefix, fromType) {
 	const properties = [];
 	for (let keyIndex = 0; keyIndex < keysLength; keyIndex += 1) {
 		const key = keys[keyIndex];
-		const prefixed = join([prefix, key], ".");
 		const value = original[key];
-		if (value == null) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", prefixed));
+		if (value == null) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", join([prefix, key], ".")));
 		const types = [];
 		let required = true;
 		let validators = {};
@@ -190,12 +227,9 @@ function getProperties(original, prefix, fromType) {
 		} else types.push(...getTypes(key, value, prefix));
 		if (!required && !types.includes("undefined")) types.push(TYPE_UNDEFINED);
 		properties.push({
+			key,
 			types,
 			validators,
-			key: {
-				full: prefixed,
-				short: key
-			},
 			required: required && !types.includes("undefined")
 		});
 	}
@@ -250,18 +284,21 @@ function getValidators(original) {
 }
 //#endregion
 //#region src/validation/value.validation.ts
-function validateNamed(property, name, value, validation) {
+function validateNamed(name, value, parameters) {
 	if (!validators[name](value)) return false;
-	const propertyValidators = property.validators[name];
+	const propertyValidators = parameters.origin.validators[name];
 	if (propertyValidators == null || propertyValidators.length === 0) return true;
 	const { length } = propertyValidators;
 	for (let index = 0; index < length; index += 1) {
 		const validator = propertyValidators[index];
 		if (!validator(value)) {
-			validation.push({
+			parameters.information.push({
 				value,
-				key: { ...property.key },
-				message: getInvalidValidatorMessage(property, name, index, length),
+				key: {
+					full: parameters.prefix,
+					short: parameters.origin.key
+				},
+				message: getInvalidValidatorMessage(parameters.prefix, name, index, length),
 				validator
 			});
 			return false;
@@ -269,69 +306,121 @@ function validateNamed(property, name, value, validation) {
 	}
 	return true;
 }
-function validateObject(obj, properties, reporting, property, validation) {
+function validateObject(obj, properties, parameters, get) {
 	if (!isPlainObject(obj)) {
+		const key = parameters?.origin == null ? {
+			full: "",
+			short: ""
+		} : {
+			full: parameters.prefix,
+			short: parameters.origin.key
+		};
 		const information = {
-			key: {
-				full: "",
-				short: ""
-			},
-			message: property == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage(property, obj),
+			key,
+			message: parameters?.origin == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage(key.full, parameters.origin.types, obj),
 			value: obj
 		};
-		if (reporting.throw) throw new ValidationError([information]);
-		return reporting.none ? false : [information];
+		if (parameters.reporting.throw) throw new ValidationError([information]);
+		parameters?.information?.push(information);
+		return parameters.reporting.none ? void 0 : [information];
+	}
+	if (parameters.strict) {
+		const objKeys = Object.keys(obj);
+		const propertiesKeys = new Set(properties.map((property) => property.key));
+		const unknownKeys = objKeys.filter((key) => !propertiesKeys.has(key));
+		if (unknownKeys.length > 0) {
+			const information = {
+				key: parameters?.origin == null ? {
+					full: "",
+					short: ""
+				} : {
+					full: join([parameters.prefix, parameters.origin?.key], "."),
+					short: parameters.origin.key
+				},
+				message: getUnknownKeysMessage(unknownKeys.map((key) => join([parameters?.prefix, key], "."))),
+				value: obj
+			};
+			if (parameters.reporting.throw) throw new ValidationError([information]);
+			parameters?.information?.push(information);
+			return parameters.reporting.none ? void 0 : [information];
+		}
 	}
 	const allInformation = [];
+	const output = {};
 	const propertiesLength = properties.length;
 	outer: for (let propertyIndex = 0; propertyIndex < propertiesLength; propertyIndex += 1) {
 		const property = properties[propertyIndex];
 		const { key, required, types } = property;
-		const value = obj[key.short];
+		const value = obj[key];
+		if (get && value === void 0 && !required) continue;
 		if (value === void 0 && required) {
+			const prefixedKey = join([parameters.prefix, key], ".");
 			const information = {
 				value,
-				key: { ...key },
-				message: getInvalidMissingMessage(property)
+				key: {
+					full: prefixedKey,
+					short: key
+				},
+				message: getInvalidMissingMessage(prefixedKey, property.types)
 			};
-			if (reporting.throw && validation == null) throw new ValidationError([information]);
-			if (validation != null) validation.push(information);
-			if (reporting.all) {
+			if (parameters.reporting.throw) throw new ValidationError([information]);
+			parameters?.information?.push(information);
+			if (parameters.reporting.all) {
 				allInformation.push(information);
 				continue;
 			}
-			return reporting.none ? false : [information];
+			return parameters.reporting.none ? void 0 : [information];
 		}
+		const prefixedKey = join([parameters.prefix, key], ".");
 		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, value, {
+				information,
+				output,
+				origin: property,
+				prefix: prefixedKey,
+				reporting: parameters.reporting,
+				strict: parameters.strict
+			}, get)) {
+				if (get) output[key] = clone(value);
+				continue outer;
+			}
 		}
 		if (information.length === 0) information.push({
 			value,
-			key: { ...key },
-			message: getInvalidTypeMessage(property, value)
+			key: {
+				full: prefixedKey,
+				short: key
+			},
+			message: getInvalidTypeMessage(prefixedKey, property.types, value)
 		});
-		if (reporting.throw && validation == null) throw new ValidationError(information);
-		validation?.push(...information);
-		if (reporting.all) {
+		if (parameters.reporting.throw) throw new ValidationError(information);
+		parameters?.information?.push(...information);
+		if (parameters.reporting.all) {
 			allInformation.push(...information);
 			continue;
 		}
-		return reporting.none ? false : information;
+		return parameters.reporting.none ? void 0 : information;
 	}
-	return reporting.none ? true : allInformation.length === 0 ? true : allInformation;
+	if (get) if (parameters.origin == null) parameters.output = output;
+	else parameters.output[parameters.origin.key] = output;
+	return parameters.reporting.none || allInformation.length === 0 ? parameters.output : allInformation;
 }
-function validateValue(type, property, value, reporting, validation) {
+function validateSchematic(schematic, value, parameters, get) {
+	const result = validateObject(value, schematicProperties.get(schematic), parameters, get);
+	return result == null || Array.isArray(result) ? false : true;
+}
+function validateValue(type, value, parameters, get) {
 	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 result = validateObject(value, type, parameters, get);
+			return result == null || Array.isArray(result) ? false : true;
 		}
-		case isSchematic(type): return type.is(value, reporting);
-		default: return validateNamed(property, type, value, validation);
+		case isSchematic(type): return validateSchematic(type, value, parameters, get);
+		default: return validateNamed(type, value, parameters);
 	}
 }
 const validators = {
@@ -357,12 +446,21 @@ var Schematic = class {
 	constructor(properties) {
 		Object.defineProperty(this, PROPERTY_SCHEMATIC, { value: true });
 		this.#properties = properties;
+		schematicProperties.set(this, properties);
+	}
+	get(value, options) {
+		const parameters = getParameters(options);
+		const result = validateObject(value, this.#properties, parameters, true);
+		if (result == null) return;
+		if (!Array.isArray(result)) return parameters.reporting.none ? result : ok(result);
+		return error(parameters.reporting.all ? result : result[0]);
 	}
-	is(value, errors) {
-		const reporting = getReporting(errors);
-		const result = validateObject(value, this.#properties, reporting);
-		if (typeof result === "boolean") return result;
-		return error(reporting.all ? result : result[0]);
+	is(value, options) {
+		const parameters = getParameters(options);
+		const result = validateObject(value, this.#properties, parameters, false);
+		if (result == null) return false;
+		if (!Array.isArray(result)) return parameters.reporting.none ? true : ok(true);
+		return error(parameters.reporting.all ? result : result[0]);
 	}
 };
 function schematic(schema) {
@@ -370,5 +468,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;