@oscarpalmer/jhunal 0.17.0 → 0.19.0

package/dist/validation/value.validation.mjs

@@ -1,29 +1,90 @@
-import { isSchematic } from "../helpers.mjs";
+import "../constants.mjs";
+import { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, isSchematic } from "../helpers.mjs";
+import { ValidationError } from "../models/validation.model.mjs";
 import { isPlainObject } from "@oscarpalmer/atoms/is";
 //#region src/validation/value.validation.ts
-function validateObject(obj, properties) {
-	if (!isPlainObject(obj)) return false;
+function validateNamed(property, name, value, validation) {
+	if (!validators[name](value)) return false;
+	const propertyValidators = property.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({
+				value,
+				key: { ...property.key },
+				message: getInvalidValidatorMessage(property, name, index, length),
+				validator
+			});
+			return false;
+		}
+	}
+	return true;
+}
+function validateObject(obj, properties, reporting, property, validation) {
+	if (!isPlainObject(obj)) {
+		const information = {
+			key: {
+				full: "",
+				short: ""
+			},
+			message: property == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage(property, obj),
+			value: obj
+		};
+		if (reporting.throw) throw new ValidationError([information]);
+		return reporting.none ? false : [information];
+	}
+	const allInformation = [];
 	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];
-		if (value === void 0 && required) return false;
+		const value = obj[key.short];
+		if (value === void 0 && required) {
+			const information = {
+				value,
+				key: { ...key },
+				message: getInvalidMissingMessage(property)
+			};
+			if (reporting.throw && validation == null) throw new ValidationError([information]);
+			if (validation != null) validation.push(information);
+			if (reporting.all) {
+				allInformation.push(information);
+				continue;
+			}
+			return 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)) continue outer;
+			if (validateValue(type, property, value, reporting, 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);
+		validation?.push(...information);
+		if (reporting.all) {
+			allInformation.push(...information);
+			continue;
 		}
-		return false;
+		return reporting.none ? false : information;
 	}
-	return true;
+	return reporting.none ? true : allInformation.length === 0 ? true : allInformation;
 }
-function validateValue(type, property, value) {
+function validateValue(type, property, value, reporting, validation) {
 	switch (true) {
-		case isSchematic(type): return type.is(value);
 		case typeof type === "function": return type(value);
-		case typeof type === "object": return validateObject(value, [type]);
-		default: return validators[type](value) && (property.validators[type]?.every((validator) => validator(value)) ?? true);
+		case Array.isArray(type): {
+			const nested = validateObject(value, type, reporting, property, validation);
+			return typeof nested !== "boolean" ? false : nested;
+		}
+		case isSchematic(type): return type.is(value, reporting);
+		default: return validateNamed(property, type, value, validation);
 	}
 }
 const validators = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscarpalmer/jhunal",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Flies free beneath the glistening moons…",
   "keywords": [
     "schema",
@@ -38,7 +38,7 @@
     "watch": "npx vite build --watch"
   },
   "dependencies": {
-    "@oscarpalmer/atoms": "^0.168"
+    "@oscarpalmer/atoms": "^0.169"
   },
   "devDependencies": {
     "@types/node": "^25.5",

package/src/constants.ts

@@ -1,43 +1,106 @@
-import type {ValueName} from './models';
+import type {ValueName} from './models/misc.model';
+import type {ReportingType} from './models/validation.model';
 
-export const ERROR_NAME = 'SchematicError';
+// #region Misc.
 
 export const MESSAGE_CONSTRUCTOR = 'Expected a constructor function';
 
-export const MESSAGE_SCHEMA_INVALID_EMPTY = 'Schema must have at least one property';
+// #endregion
 
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED =
-	"'<key>.<property>' property is not allowed for schemas in $type";
+// #region Names
 
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE =
-	"'<>' property must not be 'null' or 'undefined'";
-
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED = "'<>.$required' property must be a boolean";
+export const NAME_SCHEMATIC = 'Schematic';
 
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE = "'<>' property must be of a valid type";
+export const NAME_ERROR_SCHEMATIC = 'SchematicError';
 
-export const MESSAGE_SCHEMA_INVALID_TYPE = 'Schema must be an object';
+export const NAME_ERROR_VALIDATION = 'ValidationError';
 
-export const MESSAGE_VALIDATOR_INVALID_KEY = "Validator '<>' does not exist";
+// #endregion
 
-export const MESSAGE_VALIDATOR_INVALID_TYPE = 'Validators must be an object';
-
-export const MESSAGE_VALIDATOR_INVALID_VALUE =
-	"Validator '<>' must be a function or an array of functions";
+// #region Properties
 
 export const PROPERTY_REQUIRED = '$required';
 
+export const PROPERTY_SCHEMATIC = '$schematic';
+
 export const PROPERTY_TYPE = '$type';
 
 export const PROPERTY_VALIDATORS = '$validators';
 
-export const SCHEMATIC_NAME = '$schematic';
+// #endregion
+
+// #region Property validation
+
+export const VALIDATION_MESSAGE_INVALID_INPUT = "Expected 'object' as input but received <>";
+
+export const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required property '<>'";
+
+export const VALIDATION_MESSAGE_INVALID_TYPE = "Expected <> for '<>' but received <>";
+
+export const VALIDATION_MESSAGE_INVALID_VALUE =
+	"Value does not satisfy validator for '<>' and type '<>'";
+
+export const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = ' at index <>';
+
+// #endregion
+
+// #region Reporting
+
+export const REPORTING_ALL: ReportingType = 'all';
+
+export const REPORTING_FIRST: ReportingType = 'first';
+
+export const REPORTING_NONE: ReportingType = 'none';
+
+export const REPORTING_THROW: ReportingType = 'throw';
+
+export const REPORTING_TYPES = new Set<ReportingType>([
+	REPORTING_ALL,
+	REPORTING_FIRST,
+	REPORTING_NONE,
+	REPORTING_THROW,
+]);
+
+// #endregion
+
+// #region Schematic validation
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY = 'Schema must have at least one property';
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED =
+	"'<>.<>' property is not allowed for schemas in $type";
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE =
+	"'<>' property must not be 'null' or 'undefined'";
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED =
+	"'<>.$required' property must be a boolean";
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE =
+	"'<>' property must be of a valid type";
+
+export const SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE = 'Schema must be an object';
+
+export const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY = "Validator '<>' does not exist";
+
+export const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE = 'Validators must be an object';
+
+export const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE =
+	"Validator '<>' must be a function or an array of functions";
+
+// #endregion
+
+// #region Templates
 
 export const TEMPLATE_PATTERN = '<>';
 
-export const TEMPLATE_PATTERN_KEY = '<key>';
+// #endregion
+
+// #region Types
 
-export const TEMPLATE_PATTERN_PROPERTY = '<property>';
+export const TYPE_ARRAY = 'array';
+
+export const TYPE_NULL = 'null';
 
 export const TYPE_OBJECT = 'object';
 
@@ -56,3 +119,5 @@ export const VALIDATABLE_TYPES = new Set<ValueName>([
 ]);
 
 export const TYPE_ALL = new Set<ValueName>([...VALIDATABLE_TYPES, 'null', TYPE_UNDEFINED]);
+
+// #endregion

package/src/helpers.ts

@@ -1,8 +1,134 @@
-import {isConstructor} from '@oscarpalmer/atoms/is';
+import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
 import type {Constructor} from '@oscarpalmer/atoms/models';
-import {MESSAGE_CONSTRUCTOR, SCHEMATIC_NAME} from './constants';
+import {
+	MESSAGE_CONSTRUCTOR,
+	NAME_SCHEMATIC,
+	PROPERTY_SCHEMATIC,
+	REPORTING_ALL,
+	REPORTING_FIRST,
+	REPORTING_NONE,
+	REPORTING_THROW,
+	REPORTING_TYPES,
+	TEMPLATE_PATTERN,
+	TYPE_ARRAY,
+	TYPE_NULL,
+	TYPE_OBJECT,
+	TYPE_UNDEFINED,
+	VALIDATION_MESSAGE_INVALID_INPUT,
+	VALIDATION_MESSAGE_INVALID_REQUIRED,
+	VALIDATION_MESSAGE_INVALID_TYPE,
+	VALIDATION_MESSAGE_INVALID_VALUE,
+	VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX,
+} from './constants';
+import type {ValueName} from './models/misc.model';
+import type {
+	ReportingInformation,
+	ReportingType,
+	ValidatedProperty,
+	ValidatedPropertyType,
+} from './models/validation.model';
 import type {Schematic} from './schematic';
 
+export function getInvalidInputMessage(actual: unknown): string {
+	return VALIDATION_MESSAGE_INVALID_INPUT.replace(TEMPLATE_PATTERN, getValueType(actual));
+}
+
+export function getInvalidMissingMessage(property: ValidatedProperty): string {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace(
+		TEMPLATE_PATTERN,
+		renderTypes(property.types),
+	);
+
+	message = message.replace(TEMPLATE_PATTERN, property.key.full);
+
+	return message;
+}
+
+export function getInvalidTypeMessage(property: ValidatedProperty, actual: unknown): string {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace(
+		TEMPLATE_PATTERN,
+		renderTypes(property.types),
+	);
+
+	message = message.replace(TEMPLATE_PATTERN, property.key.full);
+	message = message.replace(TEMPLATE_PATTERN, getValueType(actual));
+
+	return message;
+}
+
+export function getInvalidValidatorMessage(
+	property: ValidatedProperty,
+	type: ValueName,
+	index: number,
+	length: number,
+): string {
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace(TEMPLATE_PATTERN, property.key.full);
+
+	message = message.replace(TEMPLATE_PATTERN, type);
+
+	if (length > 1) {
+		message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace(TEMPLATE_PATTERN, String(index));
+	}
+
+	return message;
+}
+
+function getPropertyType(original: ValidatedPropertyType): string {
+	if (typeof original === 'function') {
+		return 'a validated value';
+	}
+
+	if (Array.isArray(original)) {
+		return `'${TYPE_OBJECT}'`;
+	}
+
+	if (isSchematic(original)) {
+		return `a ${NAME_SCHEMATIC}`;
+	}
+
+	return `'${String(original)}'`;
+}
+
+export function getReporting(value: unknown): ReportingInformation {
+	const type = REPORTING_TYPES.has(value as ReportingType)
+		? (value as ReportingType)
+		: REPORTING_NONE;
+
+	return {
+		[REPORTING_ALL]: type === REPORTING_ALL,
+		[REPORTING_FIRST]: type === REPORTING_FIRST,
+		[REPORTING_NONE]: type === REPORTING_NONE,
+		[REPORTING_THROW]: type === REPORTING_THROW,
+	} as ReportingInformation;
+}
+
+function getValueType(value: unknown): string {
+	const valueType = typeof value;
+
+	switch (true) {
+		case value === null:
+			return `'${TYPE_NULL}'`;
+
+		case value === undefined:
+			return `'${TYPE_UNDEFINED}'`;
+
+		case valueType !== TYPE_OBJECT:
+			return `'${valueType}'`;
+
+		case Array.isArray(value):
+			return `'${TYPE_ARRAY}'`;
+
+		case isPlainObject(value):
+			return `'${TYPE_OBJECT}'`;
+
+		case isSchematic(value):
+			return `a ${NAME_SCHEMATIC}`;
+
+		default:
+			return value.constructor.name;
+	}
+}
+
 /**
  * Creates a validator function for a given constructor
  * @param constructor - Constructor to check against
@@ -30,7 +156,39 @@ export function isSchematic(value: unknown): value is Schematic<never> {
 	return (
 		typeof value === 'object' &&
 		value !== null &&
-		SCHEMATIC_NAME in value &&
-		value[SCHEMATIC_NAME] === true
+		PROPERTY_SCHEMATIC in value &&
+		value[PROPERTY_SCHEMATIC] === true
 	);
 }
+
+function renderTypes(types: ValidatedPropertyType[]): string {
+	const unique = new Set<string>();
+	const parts: string[] = [];
+
+	for (let index = 0; index < types.length; index += 1) {
+		const rendered = getPropertyType(types[index]);
+
+		if (unique.has(rendered)) {
+			continue;
+		}
+
+		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;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
 export {instanceOf, isSchematic} from './helpers';
-export {SchematicError, type Schema, type TypedSchema} from './models';
+export type {Schema} from './models/schema.plain.model';
+export type {TypedSchema} from './models/schema.typed.model';
+export {SchematicError, ValidationError} from './models/validation.model';
 export {schematic, type Schematic} from './schematic';

package/src/models/infer.model.ts

@@ -0,0 +1,105 @@
+import type {Constructor, Simplify} from '@oscarpalmer/atoms/models';
+import type {Schematic} from '../schematic';
+import type {IsOptionalProperty, ValueName, Values} from './misc.model';
+import type {PlainSchema, Schema, SchemaProperty} from './schema.plain.model';
+
+/**
+ * Infers the TypeScript type from a {@link Schema} definition
+ *
+ * @template Model - Schema to infer types from
+ *
+ * @example
+ * ```ts
+ * const userSchema = {
+ *   name: 'string',
+ *   age: 'number',
+ *   address: { $required: false, $type: 'string' },
+ * } satisfies Schema;
+ *
+ * type User = Infer<typeof userSchema>;
+ * // { name: string; age: number; address?: string }
+ * ```
+ */
+export type Infer<Model extends Schema> = Simplify<
+	{
+		[Key in InferRequiredKeys<Model>]: InferSchemaEntry<Model[Key]>;
+	} & {
+		[Key in InferOptionalKeys<Model>]?: InferSchemaEntry<Model[Key]>;
+	}
+>;
+
+/**
+ * Extracts keys from a {@link Schema} whose entries are optional _(i.e., `$required` is `false`)_
+ *
+ * @template Model - {@link Schema} to extract optional keys from
+ */
+export 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
+ *
+ * @template Value - `$type` value _(single or array)_
+ */
+export type InferPropertyType<Value> = Value extends (infer Item)[]
+	? InferPropertyValue<Item>
+	: InferPropertyValue<Value>;
+
+/**
+ * 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
+ *
+ * @template Value - single type definition
+ */
+export 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
+ */
+export 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
+ *
+ * @template Value - Schema entry value _(single or array)_
+ */
+export type InferSchemaEntry<Value> = Value extends (infer Item)[]
+	? InferSchemaEntryValue<Item>
+	: InferSchemaEntryValue<Value>;
+
+/**
+ * Resolves a single 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
+ *
+ * @template Value - single schema entry
+ */
+export 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;