@oscarpalmer/jhunal 0.22.0 → 0.24.0

package/src/helpers/message.helper.ts

@@ -0,0 +1,217 @@
+import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
+import {
+	COMMA,
+	CONJUNCTION_AND,
+	CONJUNCTION_AND_COMMA,
+	CONJUNCTION_OR,
+	CONJUNCTION_OR_COMMA,
+	PREFIXED_TYPES,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_DEFAULT_REQUIRED,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_DEFAULT_TYPE,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE,
+	TEMPLATE_PATTERN,
+	TYPE_ALL,
+	TYPE_ARRAY,
+	TYPE_FUNCTION_RESULT,
+	TYPE_NULL,
+	TYPE_OBJECT,
+	VALIDATION_MESSAGE_INVALID_INPUT,
+	VALIDATION_MESSAGE_INVALID_REQUIRED,
+	VALIDATION_MESSAGE_INVALID_TYPE,
+	VALIDATION_MESSAGE_INVALID_VALUE,
+	VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX,
+	VALIDATION_MESSAGE_UNKNOWN_KEYS,
+} from '../constants';
+import type {ValueName} from '../models/misc.model';
+import type {ValidatorType} from '../models/validation.model';
+
+// #region Defaults
+
+export function getDefaultRequiredMessage(key: string): string {
+	return SCHEMATIC_MESSAGE_SCHEMA_INVALID_DEFAULT_REQUIRED.replace(TEMPLATE_PATTERN, key);
+}
+
+export function getDefaultTypeMessage(key: string, types: ValidatorType[]): string {
+	let message = SCHEMATIC_MESSAGE_SCHEMA_INVALID_DEFAULT_TYPE.replace(TEMPLATE_PATTERN, key);
+
+	message = message.replace(TEMPLATE_PATTERN, renderTypes(types));
+
+	return message;
+}
+
+// #endregion
+
+// #region Disallowed
+
+export function getDisallowedMessage(key: string, property: string): string {
+	let message = SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED.replace(TEMPLATE_PATTERN, key);
+
+	message = message.replace(TEMPLATE_PATTERN, property);
+
+	return message;
+}
+
+// #endregion
+
+// #region Input
+
+export function getInputTypeMessage(actual: unknown): string {
+	return VALIDATION_MESSAGE_INVALID_INPUT.replace(TEMPLATE_PATTERN, getValueType(actual));
+}
+
+export function getInputPropertyMissingMessage(key: string, types: ValidatorType[]): string {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace(TEMPLATE_PATTERN, renderTypes(types));
+
+	message = message.replace(TEMPLATE_PATTERN, key);
+
+	return message;
+}
+
+export function getInputPropertyTypeMessage(
+	key: string,
+	types: ValidatorType[],
+	actual: unknown,
+): string {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace(TEMPLATE_PATTERN, renderTypes(types));
+
+	message = message.replace(TEMPLATE_PATTERN, key);
+	message = message.replace(TEMPLATE_PATTERN, getValueType(actual));
+
+	return message;
+}
+
+export function getInputPropertyValidatorMessage(
+	key: string,
+	type: ValueName,
+	index: number,
+	length: number,
+): string {
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace(TEMPLATE_PATTERN, key);
+
+	message = message.replace(TEMPLATE_PATTERN, type);
+
+	if (length > 1) {
+		message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace(TEMPLATE_PATTERN, String(index));
+	}
+
+	return message;
+}
+
+// #endregion
+
+// #region Schematic
+
+export function getSchematicPropertyNullableMessage(key: string): string {
+	return SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace(TEMPLATE_PATTERN, key);
+}
+
+export function getSchematicPropertyTypeMessage(key: string): string {
+	return SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE.replace(TEMPLATE_PATTERN, key);
+}
+
+// #endregion
+
+// #region Misc.
+
+function getPropertyType(type: ValidatorType): string {
+	switch (true) {
+		case typeof type === 'function':
+			return isConstructor(type) ? type.name : TYPE_FUNCTION_RESULT;
+
+		case TYPE_ALL.has(type as ValueName):
+			return PREFIXED_TYPES[type as ValueName];
+
+		default:
+			return PREFIXED_TYPES[TYPE_OBJECT];
+	}
+}
+
+function getValueType(value: unknown): string {
+	const valueType = typeof value;
+
+	switch (true) {
+		case value === null:
+			return TYPE_NULL;
+
+		case Array.isArray(value):
+			return PREFIXED_TYPES[TYPE_ARRAY];
+
+		case isPlainObject(value):
+			return PREFIXED_TYPES[TYPE_OBJECT];
+
+		case valueType !== TYPE_OBJECT:
+			return PREFIXED_TYPES[valueType as ValueName];
+
+		default:
+			return (value as object).constructor.name;
+	}
+}
+
+function renderKeys(keys: string[]): string {
+	return renderParts(
+		keys.map(key => `'${key}'`),
+		CONJUNCTION_AND,
+		CONJUNCTION_AND_COMMA,
+	);
+}
+
+function renderParts(parts: string[], delimiterShort: string, delimiterLong: string): string {
+	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 += COMMA;
+		} else if (index === length - 2) {
+			rendered += parts.length > 2 ? delimiterLong : delimiterShort;
+		}
+	}
+
+	return rendered;
+}
+
+function renderTypes(types: ValidatorType[]): 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);
+	}
+
+	return renderParts(parts, CONJUNCTION_OR, CONJUNCTION_OR_COMMA);
+}
+
+// #endregion
+
+// #region Required
+
+export function getRequiredMessage(key: string): string {
+	return SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED.replace(TEMPLATE_PATTERN, key);
+}
+
+// #endregion
+
+// #region Strictness
+
+export function getUnknownKeysMessage(keys: string[]): string {
+	return VALIDATION_MESSAGE_UNKNOWN_KEYS.replace(TEMPLATE_PATTERN, renderKeys(keys));
+}
+
+// #endregion

package/src/helpers/misc.helper.ts

@@ -0,0 +1,92 @@
+import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
+import type {Constructor} from '@oscarpalmer/atoms/models';
+import {
+	MESSAGE_CONSTRUCTOR,
+	PROPERTY_SCHEMATIC,
+	REPORTING_ALL,
+	REPORTING_FIRST,
+	REPORTING_NONE,
+	REPORTING_THROW,
+	REPORTING_TYPES,
+} from '../constants';
+import type {
+	ReportingInformation,
+	ReportingType,
+	ValidatorParameters,
+} from '../models/validation.model';
+import type {Schematic} from '../schematic';
+
+export function getParameters(input?: unknown): ValidatorParameters {
+	if (typeof input === 'boolean') {
+		return {
+			clone: true,
+			output: {},
+			reporting: getReporting(),
+			strict: input,
+		};
+	}
+
+	if (REPORTING_TYPES.has(input as ReportingType)) {
+		return {
+			clone: true,
+			output: {},
+			reporting: getReporting(input as ReportingType),
+			strict: false,
+		};
+	}
+
+	const options = isPlainObject(input) ? input : {};
+
+	return {
+		clone: typeof options.clone === 'boolean' ? options.clone : true,
+		output: {},
+		reporting: getReporting(options.errors),
+		strict: typeof options.strict === 'boolean' ? options.strict : false,
+	};
+}
+
+export function getReporting(value?: unknown): ReportingInformation {
+	const type = REPORTING_TYPES.has(value as ReportingType)
+		? (value as ReportingType)
+		: REPORTING_NONE;
+
+	return {
+		type,
+		[REPORTING_ALL]: type === REPORTING_ALL,
+		[REPORTING_FIRST]: type === REPORTING_FIRST,
+		[REPORTING_NONE]: type === REPORTING_NONE,
+		[REPORTING_THROW]: type === REPORTING_THROW,
+	} as ReportingInformation;
+}
+
+/**
+ * Creates a validator function for a given constructor
+ * @param constructor - Constructor to check against
+ * @throws Will throw a `TypeError` if the provided argument is not a valid constructor
+ * @returns Validator function that checks if a value is an instance of the constructor
+ */
+export function instanceOf<Instance>(
+	constructor: Constructor<Instance>,
+): (value: unknown) => value is Instance {
+	if (!isConstructor(constructor)) {
+		throw new TypeError(MESSAGE_CONSTRUCTOR);
+	}
+
+	return (value: unknown): value is Instance => {
+		return value instanceof constructor;
+	};
+}
+
+/**
+ * Is the value a schematic?
+ * @param value Value to check
+ * @returns `true` if the value is a schematic, `false` otherwise
+ */
+export function isSchematic(value: unknown): value is Schematic<never> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		PROPERTY_SCHEMATIC in value &&
+		value[PROPERTY_SCHEMATIC] === true
+	);
+}

package/src/index.ts

@@ -1,10 +1,10 @@
-export {instanceOf, isSchematic} from './helpers';
+export {instanceOf, isSchematic} from './helpers/misc.helper';
 export type {Schema} from './models/schema.plain.model';
 export type {TypedSchema} from './models/schema.typed.model';
 export {
 	SchematicError,
 	ValidationError,
-	type ValidationInformation,
-	type ValidationOptions,
+	type GetOptions,
+	type IsOptions,
 } from './models/validation.model';
 export {schematic, type Schematic} from './schematic';

package/src/models/schema.plain.model.ts

@@ -8,6 +8,7 @@ import type {ExtractValueNames, ValueName, Values} from './misc.model';
 export type PlainSchema = {
 	[key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
 } & {
+	$default?: never;
 	$required?: never;
 	$type?: never;
 	$validators?: never;
@@ -56,6 +57,7 @@ export type SchemaEntry =
  * ```
  */
 export type SchemaProperty = {
+	$default?: unknown;
 	/**
 	 * Whether the property is required _(defaults to `true`)_
 	 */

package/src/models/schema.typed.model.ts

@@ -17,6 +17,7 @@ import type {ToSchemaPropertyType, ToSchemaType} from './transform.model';
  * ```
  */
 export type TypedPropertyOptional<Value> = {
+	$default?: never;
 	$required: false;
 	$type: ToSchemaPropertyType<Exclude<Value, undefined>>;
 	$validators?: PropertyValidators<ToSchemaPropertyType<Exclude<Value, undefined>>>;
@@ -35,6 +36,7 @@ export type TypedPropertyOptional<Value> = {
  * ```
  */
 export type TypedPropertyRequired<Value> = {
+	$default?: unknown;
 	$required?: true;
 	$type: ToSchemaPropertyType<Value>;
 	$validators?: PropertyValidators<ToSchemaPropertyType<Value>>;
@@ -61,31 +63,11 @@ export type TypedPropertyRequired<Value> = {
 export type TypedSchema<Model extends PlainObject> = Simplify<
 	{
 		[Key in RequiredKeys<Model>]: Model[Key] extends PlainObject
-			? TypedSchemaRequired<Model[Key]> | Schematic<Model[Key]>
+			? Schematic<Model[Key]>
 			: ToSchemaType<Model[Key]> | TypedPropertyRequired<Model[Key]>;
 	} & {
 		[Key in OptionalKeys<Model>]: Exclude<Model[Key], undefined> extends PlainObject
-			?
-					| TypedSchemaOptional<Exclude<Model[Key], undefined>>
-					| Schematic<Exclude<Model[Key], undefined>>
+			? Schematic<Exclude<Model[Key], undefined>>
 			: TypedPropertyOptional<Model[Key]>;
 	}
 >;
-
-/**
- * A {@link TypedSchema} variant for optional nested objects, with `$required` fixed to `false`
- *
- * @template Model Nested object type
- */
-type TypedSchemaOptional<Model extends PlainObject> = {
-	$required: false;
-} & TypedSchema<Model>;
-
-/**
- * A {@link TypedSchema} variant for required nested objects, with `$required` defaulting to `true`
- *
- * @template Model Nested object type
- */
-type TypedSchemaRequired<Model extends PlainObject> = {
-	$required?: true;
-} & TypedSchema<Model>;

package/src/models/validation.model.ts

@@ -91,20 +91,32 @@ export type ValidationInformationKey = {
 
 // #region Options
 
-/**
- * Options for validation
- */
-export type ValidationOptions<Errors extends ReportingType> = {
+type BaseOptions<Errors extends ReportingType> = {
 	/**
 	 * How should validation failures be reported; see {@link ReportingType} _(defaults to `'none'`)_
 	 */
-	errors?: Errors;
+	errors: Errors;
 	/**
 	 * Validate if unknown keys are present in the object? _(defaults to `false`)_
 	 */
 	strict?: boolean;
 };
 
+/**
+ * Options for validating and getting a value from an input
+ */
+export type GetOptions<Errors extends ReportingType> = BaseOptions<Errors> & {
+	/**
+	 * Get a deeply cloned version of the input? _(defaults to `true`)_
+	 */
+	clone?: boolean;
+};
+
+/**
+ * Options for validation an input value
+ */
+export type IsOptions<Errors extends ReportingType> = BaseOptions<Errors>;
+
 // #endregion
 
 // #region Validator
@@ -113,9 +125,22 @@ export type Validator = (
 	input: unknown,
 	parameters: ValidatorParameters,
 	get: boolean,
-) => boolean | ValidationInformation[];
+) => true | ValidationInformation[];
+
+export type ValidatorDefaults = {
+	value: unknown;
+};
+
+export type ValidatorItem = {
+	defaults: ValidatorDefaults | undefined;
+	key: ValidationInformationKey;
+	required: boolean;
+	types: ValidatorType[];
+	validator: Validator;
+};
 
 export type ValidatorParameters = {
+	clone: boolean;
 	information?: ValidationInformation[];
 	output: PlainObject;
 	reporting: ReportingInformation;

package/src/schematic.ts

@@ -3,17 +3,18 @@ import type {PlainObject} from '@oscarpalmer/atoms/models';
 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 {getParameters, isSchematic} from './helpers';
+import {getParameters, isSchematic} from './helpers/misc.helper';
 import type {Infer} from './models/infer.model';
 import type {Schema} from './models/schema.plain.model';
 import type {TypedSchema} from './models/schema.typed.model';
 import {
 	SchematicError,
+	type GetOptions,
+	type IsOptions,
 	type ValidationInformation,
-	type ValidationOptions,
 	type Validator,
 } from './models/validation.model';
-import {getObjectValidator} from './validation';
+import {getObjectValidator} from './validator/object.validator';
 
 /**
  * A schematic for validating objects
@@ -41,7 +42,7 @@ export class Schematic<Model> {
 	 * @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;
+	get(value: unknown, options: GetOptions<'throw'>): Model;
 
 	/**
 	 * Parse a value according to the schema
@@ -61,7 +62,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns Result holding deeply cloned value or all validation information
 	 */
-	get(value: unknown, options: ValidationOptions<'all'>): Result<Model, ValidationInformation[]>;
+	get(value: unknown, options: GetOptions<'all'>): Result<Model, ValidationInformation[]>;
 
 	/**
 	 * Parse a value according to the schema
@@ -81,7 +82,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns Result holding deeply cloned value or all validation information
 	 */
-	get(value: unknown, options: ValidationOptions<'first'>): Result<Model, ValidationInformation>;
+	get(value: unknown, options: GetOptions<'first'>): Result<Model, ValidationInformation>;
 
 	/**
 	 * Parse a value according to the schema
@@ -93,6 +94,16 @@ export class Schematic<Model> {
 	 */
 	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 options Validation options
+	 * @returns Deeply cloned value, or `undefined` if it's invalid
+	 */
+	get(value: unknown, options: GetOptions<'none'>): Model | undefined;
+
 	/**
 	 * Parse a value according to the schema
 	 *
@@ -108,14 +119,16 @@ export class Schematic<Model> {
 
 		const result = this.#validator(value, parameters, true);
 
-		if (typeof result === 'boolean') {
-			return parameters.reporting.none
-				? result
-					? parameters.output
-					: undefined
+		if (result === true) {
+			return parameters.reporting.none || parameters.reporting.throw
+				? parameters.output
 				: ok(parameters.output);
 		}
 
+		if (parameters.reporting.none) {
+			return;
+		}
+
 		return error(parameters.reporting.all ? result : result[0]);
 	}
 
@@ -127,7 +140,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise throws an error
 	 */
-	is(value: unknown, options: ValidationOptions<'throw'>): asserts value is Model;
+	is(value: unknown, options: IsOptions<'throw'>): asserts value is Model;
 
 	/**
 	 * Does the value match the schema?
@@ -147,7 +160,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns Result holding `true` or all validation information
 	 */
-	is(value: unknown, options: ValidationOptions<'all'>): Result<true, ValidationInformation[]>;
+	is(value: unknown, options: IsOptions<'all'>): Result<true, ValidationInformation[]>;
 
 	/**
 	 * Does the value match the schema?
@@ -167,7 +180,7 @@ export class Schematic<Model> {
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise `false`
 	 */
-	is(value: unknown, options: ValidationOptions<'first'>): Result<true, ValidationInformation>;
+	is(value: unknown, options: IsOptions<'first'>): Result<true, ValidationInformation>;
 
 	/**
 	 * Does the value match the schema?
@@ -179,6 +192,16 @@ export class Schematic<Model> {
 	 */
 	is(value: unknown, errors: 'first'): Result<true, ValidationInformation>;
 
+	/**
+	 * 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
+	 * @param value Value to validate
+	 * @param options Validation options
+	 * @returns `true` if the value matches the schema, otherwise `false`
+	 */
+	is(value: unknown, options: IsOptions<'none'>): value is Model;
+
 	/**
 	 * Does the value match the schema?
 	 *
@@ -194,8 +217,12 @@ export class Schematic<Model> {
 
 		const result = this.#validator(value, parameters, false);
 
-		if (typeof result === 'boolean') {
-			return parameters.reporting.none ? result : ok(result);
+		if (result === true) {
+			return parameters.reporting.none || parameters.reporting.throw ? result : ok(result);
+		}
+
+		if (parameters.reporting.none) {
+			return false;
 		}
 
 		return error(parameters.reporting.all ? result : result[0]);

package/src/validator/base.validator.ts

@@ -0,0 +1,31 @@
+import type {ValidationInformation, Validator} from '../models/validation.model';
+
+export function getBaseValidator(validators: Validator[]): Validator {
+	const {length} = validators;
+
+	return (input, parameters, get) => {
+		const allInformation: ValidationInformation[] = [];
+
+		for (let index = 0; index < length; index += 1) {
+			const previousInformation = parameters.information;
+
+			const nextInformation: ValidationInformation[] = [];
+
+			parameters.information = nextInformation;
+
+			const result = validators[index](input, parameters, get);
+
+			parameters.information = previousInformation;
+
+			if (result === true) {
+				return true;
+			}
+
+			parameters.information?.push(...result);
+
+			allInformation.push(...result);
+		}
+
+		return allInformation;
+	};
+}

package/src/validator/function.validator.ts

@@ -0,0 +1,9 @@
+import {isConstructor} from '@oscarpalmer/atoms/is';
+import {instanceOf} from '../helpers/misc.helper';
+import type {Validator} from '../models/validation.model';
+
+export function getFunctionValidator(fn: Function): Validator {
+	const validator = isConstructor(fn) ? instanceOf(fn) : fn;
+
+	return input => (validator(input) ? true : []);
+}

package/src/validator/named.handler.ts

@@ -0,0 +1,65 @@
+import {isPlainObject} from '@oscarpalmer/atoms/is';
+import {
+	PROPERTY_VALIDATORS,
+	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED,
+	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY,
+	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE,
+	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE,
+	TEMPLATE_PATTERN,
+	TYPE_ALL,
+} from '../constants';
+import type {ValueName} from '../models/misc.model';
+import type {NamedValidatorHandlers} from '../models/validation.model';
+
+export function getNamedHandlers(
+	original: unknown,
+	prefix: string,
+	allowed: boolean,
+): NamedValidatorHandlers {
+	const handlers: NamedValidatorHandlers = {};
+
+	if (original == null) {
+		return handlers;
+	}
+
+	if (!allowed) {
+		throw new TypeError(
+			SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED.replace(
+				TEMPLATE_PATTERN,
+				prefix,
+			).replace(TEMPLATE_PATTERN, PROPERTY_VALIDATORS),
+		);
+	}
+
+	if (!isPlainObject(original)) {
+		throw new TypeError(SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE);
+	}
+
+	const keys = Object.keys(original);
+	const {length} = keys;
+
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+
+		if (!TYPE_ALL.has(key as never)) {
+			throw new TypeError(SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY.replace(TEMPLATE_PATTERN, key));
+		}
+
+		const value = original[key];
+
+		handlers[key as ValueName] = (Array.isArray(value) ? value : [value]).map(item => {
+			if (typeof item !== 'function') {
+				throw new TypeError(
+					SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE.replace(TEMPLATE_PATTERN, key).replace(
+						TEMPLATE_PATTERN,
+						prefix,
+					),
+				);
+			}
+
+			return item;
+		});
+	}
+
+	return handlers;
+}