@oscarpalmer/jhunal 0.20.0 → 0.21.0

package/src/models/validation.model.ts

@@ -1,4 +1,4 @@
-import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
 import {NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION} from '../constants';
 import type {Schematic} from '../schematic';
@@ -59,7 +59,7 @@ export type ValidatedProperty = {
 	/**
 	 * The property name in the schema
 	 */
-	key: ValidatedPropertyKey;
+	key: string;
 	/**
 	 * Whether the property is required
 	 */
@@ -74,16 +74,6 @@ export type ValidatedProperty = {
 	validators: ValidatedPropertyValidators;
 };
 
-/**
- * The full and short forms of a property's key path
- *
- * For a nested property `address.street`: `full` is `'address.street'`, `short` is `'street'`
- */
-export type ValidatedPropertyKey = {
-	full: string;
-	short: string;
-};
-
 /**
  * A union of valid types for a {@link ValidatedProperty}'s `types` array
  *
@@ -139,9 +129,12 @@ export type ValidationInformation = {
 };
 
 /**
- * Same shape as {@link ValidatedPropertyKey}; the key path of a failed property
+ * 
  */
-export type ValidationInformationKey = ValidatedPropertyKey;
+export type ValidationInformationKey = {
+	full: string;
+	short: string;
+};
 
 /**
  * Options for validation
@@ -157,7 +150,11 @@ export type ValidationOptions<Errors extends ReportingType> = {
 	strict?: boolean;
 };
 
-export type ValidationOptionsExtended = {
+export type ValidationParameters = {
+	information?: ValidationInformation[];
+	origin?: ValidatedProperty;
+	output: PlainObject;
+	prefix?: string;
 	reporting: ReportingInformation;
 	strict: boolean;
 };

package/src/schematic.ts

@@ -1,9 +1,9 @@
 import {isPlainObject} from '@oscarpalmer/atoms/is';
 import type {PlainObject} from '@oscarpalmer/atoms/models';
-import {error} from '@oscarpalmer/atoms/result/misc';
+import {error, ok} from '@oscarpalmer/atoms/result/misc';
 import type {Result} from '@oscarpalmer/atoms/result/models';
 import {PROPERTY_SCHEMATIC, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE} from './constants';
-import {getOptions, isSchematic} from './helpers';
+import {getParameters, isSchematic} from './helpers';
 import type {Infer} from './models/infer.model';
 import type {Schema} from './models/schema.plain.model';
 import type {TypedSchema} from './models/schema.typed.model';
@@ -34,10 +34,96 @@ export class Schematic<Model> {
 		schematicProperties.set(this, properties);
 	}
 
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value or throws an error for the first property that fails validation
+	 * @param value Value to parse
+	 * @param options Validation options
+	 * @returns Deeply cloned version of the value if it matches the schema, otherwise throws an error
+	 */
+	get(value: unknown, options: ValidationOptions<'throw'>): Model;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value or throws an error for the first property that fails validation
+	 * @param value Value to parse
+	 * @param errors Reporting type
+	 * @returns Deeply cloned version of the value if it matches the schema, otherwise throws an error
+	 */
+	get(value: unknown, errors: 'throw'): Model;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a result of a deeply cloned version of the value or all validation information for validation failures from the same depth in the value
+	 * @param value Value to parse
+	 * @param options Validation options
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, options: ValidationOptions<'all'>): Result<Model, ValidationInformation[]>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a result of a deeply cloned version of the value or all validation information for validation failures from the same depth in the value
+	 * @param value Value to parse
+	 * @param errors Reporting type
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, errors: 'all'): Result<Model, ValidationInformation[]>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value or all validation information for the first failing property
+	 * @param value Value to parse
+	 * @param options Validation options
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, options: ValidationOptions<'first'>): Result<Model, ValidationInformation>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value or all validation information for the first failing property
+	 * @param value Value to parse
+	 * @param errors Reporting type
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, errors: 'first'): Result<Model, ValidationInformation>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value or `undefined` if the value does not match the schema
+	 * @param value Value to parse
+	 * @param strict Validate if unknown keys are present in the object? _(defaults to `false`)_
+	 * @returns Deeply cloned value, or `undefined` if it's invalid
+	 */
+	get(value: unknown, strict?: true): Model | undefined;
+
+	get(value: unknown, options?: unknown): unknown {
+		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]);
+	}
+
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
 	 * @param value Value to validate
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise throws an error
@@ -47,7 +133,7 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
 	 * @param value Value to validate
 	 * @param errors Reporting type
 	 * @returns `true` if the value matches the schema, otherwise throws an error
@@ -57,27 +143,27 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the object.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
 	 * @param value Value to validate
 	 * @param options Validation options
-	 * @returns `true` if the value matches the schema, otherwise `false`
+	 * @returns Result holding `true` or all validation information
 	 */
 	is(value: unknown, options: ValidationOptions<'all'>): Result<true, ValidationInformation[]>;
 
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the object.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
 	 * @param value Value to validate
 	 * @param errors Reporting type
-	 * @returns `true` if the value matches the schema, otherwise `false`
+	 * @returns Result holding `true` or all validation information
 	 */
 	is(value: unknown, errors: 'all'): Result<true, ValidationInformation[]>;
 
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the failing property.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the first failing property
 	 * @param value Value to validate
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise `false`
@@ -87,7 +173,7 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the failing property.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the first failing property
 	 * @param value Value to validate
 	 * @param errors Reporting type
 	 * @returns `true` if the value matches the schema, otherwise `false`
@@ -97,7 +183,7 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return `true` or `false`, without any validation information for validation failures.
+	 * Will validate that the value matches the schema and return `true` or `false`, without any validation information for validation failures
 	 * @param value Value to validate
 	 * @param strict Validate if unknown keys are present in the object? _(defaults to `false`)_
 	 * @returns `true` if the value matches the schema, otherwise `false`
@@ -105,15 +191,19 @@ export class Schematic<Model> {
 	is(value: unknown, strict?: true): value is Model;
 
 	is(value: unknown, options?: unknown): unknown {
-		const {reporting, strict} = getOptions(options);
+		const parameters = getParameters(options);
 
-		const result = validateObject(value, this.#properties, {reporting, strict});
+		const result = validateObject(value, this.#properties, parameters, false);
+
+		if (result == null) {
+			return false;
+		}
 
-		if (typeof result === 'boolean') {
-			return result;
+		if (!Array.isArray(result)) {
+			return parameters.reporting.none ? true : ok(true);
 		}
 
-		return error(reporting.all ? result : result[0]);
+		return error(parameters.reporting.all ? result : result[0]);
 	}
 }
 

package/src/validation/property.validation.ts

@@ -70,13 +70,14 @@ export function getProperties(
 
 	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(TEMPLATE_PATTERN, prefixed),
+				SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace(
+					TEMPLATE_PATTERN,
+					join([prefix, key], '.'),
+				),
 			);
 		}
 
@@ -101,12 +102,9 @@ export function getProperties(
 		}
 
 		properties.push({
+			key,
 			types,
 			validators,
-			key: {
-				full: prefixed,
-				short: key,
-			},
 			required: required && !types.includes(TYPE_UNDEFINED),
 		});
 	}

package/src/validation/value.validation.ts

@@ -1,6 +1,7 @@
 import {isPlainObject} from '@oscarpalmer/atoms/is';
-import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
+import {clone} from '@oscarpalmer/atoms/value/clone';
 import {TYPE_OBJECT} from '../constants';
 import {
 	getInvalidInputMessage,
@@ -16,21 +17,16 @@ import {
 	type ValidatedProperty,
 	type ValidatedPropertyType,
 	type ValidationInformation,
-	type ValidationOptionsExtended,
+	type ValidationParameters,
 } from '../models/validation.model';
 import {schematicProperties, type Schematic} from '../schematic';
 
-function validateNamed(
-	property: ValidatedProperty,
-	name: ValueName,
-	value: unknown,
-	validation: ValidationInformation[],
-): boolean {
+function validateNamed(name: ValueName, value: unknown, parameters: ValidationParameters): boolean {
 	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;
@@ -42,10 +38,13 @@ function validateNamed(
 		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: validator as GenericCallback,
 			});
 
@@ -59,106 +58,118 @@ function validateNamed(
 export function validateObject(
 	obj: unknown,
 	properties: ValidatedProperty[],
-	options: ValidationOptionsExtended,
-	origin?: ValidatedProperty,
-	validation?: ValidationInformation[],
-): boolean | ValidationInformation[] {
+	parameters: ValidationParameters,
+	get: boolean,
+): PlainObject | ValidationInformation[] | undefined {
 	if (!isPlainObject(obj)) {
-		const key = origin == null ? {full: '', short: ''} : {...origin.key};
+		const key =
+			parameters?.origin == null
+				? {full: '', short: ''}
+				: {
+						full: parameters.prefix!,
+						short: parameters.origin.key,
+					};
 
 		const information = {
 			key,
 			message:
-				origin == null
+				parameters?.origin == null
 					? getInvalidInputMessage(obj)
-					: getInvalidTypeMessage(
-							{
-								...origin,
-								key,
-							},
-							obj,
-						),
+					: getInvalidTypeMessage(key.full, parameters.origin.types, obj),
 			value: obj,
 		};
 
-		if (options.reporting.throw) {
+		if (parameters.reporting.throw) {
 			throw new ValidationError([information]);
 		}
 
-		validation?.push(information);
+		parameters?.information?.push(information);
 
-		return options.reporting.none ? false : [information];
+		return parameters.reporting.none ? undefined : [information];
 	}
 
-	if (options.strict) {
+	if (parameters.strict) {
 		const objKeys = Object.keys(obj);
 
-		const propertiesKeys = new Set(properties.map(property => property.key.short));
+		const propertiesKeys = new Set(properties.map(property => property.key));
 
 		const unknownKeys = objKeys.filter(key => !propertiesKeys.has(key));
 
 		if (unknownKeys.length > 0) {
-			const key = origin == null ? {full: '', short: ''} : {...origin.key};
+			const key =
+				parameters?.origin == null
+					? {full: '', short: ''}
+					: {
+							full: join([parameters.prefix, parameters.origin?.key], '.'),
+							short: parameters.origin.key,
+						};
 
 			const information: ValidationInformation = {
 				key,
-				message: getUnknownKeysMessage(unknownKeys.map(key => join([origin?.key.full, key], '.'))),
+				message: getUnknownKeysMessage(
+					unknownKeys.map(key => join([parameters?.prefix, key], '.')),
+				),
 				value: obj,
 			};
 
-			if (options.reporting.throw) {
+			if (parameters.reporting.throw) {
 				throw new ValidationError([information]);
 			}
 
-			validation?.push(information);
+			parameters?.information?.push(information);
 
-			return options.reporting.none ? false : [information];
+			return parameters.reporting.none ? undefined : [information];
 		}
 	}
 
 	const allInformation: ValidationInformation[] = [];
 
+	const output: PlainObject = {};
+
 	const propertiesLength = properties.length;
 
 	outer: for (let propertyIndex = 0; propertyIndex < propertiesLength; propertyIndex += 1) {
-		let property = properties[propertyIndex];
-
-		property = {
-			...property,
-			key: {
-				full: join([origin?.key.full, property.key.short], '.'),
-				short: property.key.short,
-			},
-		};
+		const property = properties[propertyIndex];
 
 		const {key, required, types} = property;
 
-		const value = obj[key.short];
+		const value = obj[key];
+
+		if (get && value === undefined && !required) {
+			// TODO: during get, respect a default value for the property
+
+			continue;
+		}
 
 		if (value === undefined && required) {
+			const prefixedKey = join([parameters.prefix, key], '.');
+
 			const information: ValidationInformation = {
 				value,
-				key: {...key},
-				message: getInvalidMissingMessage(property),
+				key: {
+					full: prefixedKey,
+					short: key,
+				},
+				message: getInvalidMissingMessage(prefixedKey, property.types),
 			};
 
-			if (options.reporting.throw && validation == null) {
+			if (parameters.reporting.throw) {
 				throw new ValidationError([information]);
 			}
 
-			if (validation != null) {
-				validation.push(information);
-			}
+			parameters?.information?.push(information);
 
-			if (options.reporting.all) {
+			if (parameters.reporting.all) {
 				allInformation.push(information);
 
 				continue;
 			}
 
-			return options.reporting.none ? false : [information];
+			return parameters.reporting.none ? undefined : [information];
 		}
 
+		const prefixedKey = join([parameters.prefix, key], '.');
+
 		const typesLength = types.length;
 
 		const information: ValidationInformation[] = [];
@@ -166,7 +177,25 @@ export function validateObject(
 		for (let typeIndex = 0; typeIndex < typesLength; typeIndex += 1) {
 			const type = types[typeIndex];
 
-			if (validateValue(type, property, value, options, information)) {
+			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;
 			}
 		}
@@ -174,65 +203,76 @@ export function validateObject(
 		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 (options.reporting.throw && validation == null) {
+		if (parameters.reporting.throw) {
 			throw new ValidationError(information);
 		}
 
-		validation?.push(...information);
+		parameters?.information?.push(...information);
 
-		if (options.reporting.all) {
+		if (parameters.reporting.all) {
 			allInformation.push(...information);
 
 			continue;
 		}
 
-		return options.reporting.none ? false : information;
+		return parameters.reporting.none ? undefined : information;
+	}
+
+	if (get) {
+		if (parameters.origin == null) {
+			parameters.output = output;
+		} else {
+			parameters.output[parameters.origin.key] = output;
+		}
 	}
 
-	return options.reporting.none || allInformation.length === 0 ? true : allInformation;
+	return parameters.reporting.none || allInformation.length === 0
+		? parameters.output
+		: allInformation;
 }
 
 function validateSchematic(
-	property: ValidatedProperty,
 	schematic: Schematic<unknown>,
 	value: unknown,
-	options: ValidationOptionsExtended,
-	validation: ValidationInformation[],
+	parameters: ValidationParameters,
+	get: boolean,
 ): boolean {
 	const properties = schematicProperties.get(schematic)!;
 
-	const result = validateObject(value, properties, options, property, validation);
+	const result = validateObject(value, properties, parameters, get);
 
-	return typeof result === 'boolean' ? result : result.length === 0;
+	return result == null || Array.isArray(result) ? false : true;
 }
 
 function validateValue(
 	type: ValidatedPropertyType,
-	property: ValidatedProperty,
 	value: unknown,
-	options: ValidationOptionsExtended,
-	validation: ValidationInformation[],
+	parameters: ValidationParameters,
+	get: boolean,
 ): boolean {
 	switch (true) {
 		case typeof type === 'function':
 			return (type as GenericCallback)(value);
 
 		case Array.isArray(type): {
-			const validated = validateObject(value, type, options, property, validation);
+			const result = validateObject(value, type, parameters, get);
 
-			return typeof validated === 'boolean' ? validated : false;
+			return result == null || Array.isArray(result) ? false : true;
 		}
 
 		case isSchematic(type):
-			return validateSchematic(property, type, value, options, validation);
+			return validateSchematic(type, value, parameters, get);
 
 		default:
-			return validateNamed(property, type as ValueName, value, validation);
+			return validateNamed(type as ValueName, value, parameters);
 	}
 }