@oscarpalmer/jhunal 0.25.0 → 0.27.0

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

@@ -1,12 +1,13 @@
 import type {Constructor} from '@oscarpalmer/atoms/models';
 import type {Schema} from '../schema';
-import type {ExtractValueNames, ValueName, Values} from './misc.model';
+import type {Validator} from '../validator';
+import type {ExtractValueTypes, ValueType, Values} from './misc.model';
 
 /**
  * A generic schematic allowing nested schematics, {@link SchematicEntry} values, or arrays of {@link SchematicEntry} as values
  */
 export type PlainSchematic = {
-	[key: string]: PlainSchematic | SchematicEntry | SchematicEntry[] | undefined;
+	[key: string]: SchematicEntry | SchematicEntry[];
 } & {
 	$default?: never;
 	$required?: never;
@@ -31,14 +32,15 @@ export type Schematic = PlainSchematic;
 /**
  * A union of all valid types for a single schematic entry
  *
- * Can be a {@link Constructor}, {@link PlainSchematic}, {@link SchematicProperty}, {@link Schema}, {@link ValueName}, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link SchematicProperty}, {@link Schema}, {@link ValueType}, or a custom validator function
  */
 export type SchematicEntry =
 	| Constructor
 	| PlainSchematic
 	| Schema<unknown>
 	| SchematicProperty
-	| ValueName
+	| Validator<unknown>
+	| ValueType
 	| ((value: unknown) => boolean);
 
 /**
@@ -67,7 +69,7 @@ export type SchematicProperty = {
 	 */
 	$type: SchemaPropertyType | SchemaPropertyType[];
 	/**
-	 * Optional validators keyed by {@link ValueName}, applied during validation
+	 * Optional validators keyed by {@link ValueType}, applied during validation
 	 */
 	$validators?: PropertyValidators<SchemaPropertyType | SchemaPropertyType[]>;
 };
@@ -75,17 +77,18 @@ export type SchematicProperty = {
 /**
  * A union of valid types for a {@link SchematicProperty}'s `$type` field
  *
- * Can be a {@link Constructor}, {@link PlainSchematic}, {@link Schema}, {@link ValueName} string, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link Schema}, {@link ValueType} string, or a custom validator function
  */
 export type SchemaPropertyType =
 	| Constructor
 	| PlainSchematic
 	| Schema<unknown>
-	| ValueName
+	| Validator<unknown>
+	| ValueType
 	| ((value: unknown) => boolean);
 
 /**
- * A map of optional validator functions keyed by {@link ValueName}, used to add custom validation to {@link SchemaProperty} definitions
+ * A map of optional validator functions keyed by {@link ValueType}, used to add custom validation to {@link SchemaProperty} definitions
  *
  * Each key may hold a single validator or an array of validators that receive the typed value
  *
@@ -99,7 +102,7 @@ export type SchemaPropertyType =
  * ```
  */
 export type PropertyValidators<Value> = {
-	[Key in ExtractValueNames<Value>]?:
+	[Key in ExtractValueTypes<Value>]?:
 		| ((value: Values[Key]) => boolean)
 		| Array<(value: Values[Key]) => boolean>;
 };

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

@@ -63,11 +63,11 @@ export type TypedPropertyRequired<Value> = {
 export type TypedSchematic<Model extends PlainObject> = Simplify<
 	{
 		[Key in RequiredKeys<Model>]: Model[Key] extends PlainObject
-			? Schema<Model[Key]>
+			? Schema<Model[Key]> | TypedSchematic<Model[Key]>
 			: ToSchemaType<Model[Key]> | TypedPropertyRequired<Model[Key]>;
 	} & {
 		[Key in OptionalKeys<Model>]: Exclude<Model[Key], undefined> extends PlainObject
-			? Schema<Exclude<Model[Key], undefined>>
-			: TypedPropertyOptional<Model[Key]>;
+			? TypedPropertyOptional<Model[Key]>
+			: never;
 	}
 >;

package/src/models/transform.model.ts

@@ -45,7 +45,7 @@ export type ToSchemaPropertyTypeEach<Value> = Value extends PlainObject
 	: ToValueType<Value>;
 
 /**
- * Converts a TypeScript type to its {@link ValueName} representation, suitable for use as a top-level schema entry
+ * Converts a TypeScript type to its {@link ValueType} representation, suitable for use as a top-level schema entry
  *
  * @template Value Type to convert
  */
@@ -54,7 +54,7 @@ export type ToSchemaType<Value> = UnwrapSingle<
 >;
 
 /**
- * Maps a type to its {@link ValueName} string equivalent
+ * Maps a type to its {@link ValueType} string equivalent
  *
  * Resolves {@link Schema} 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
  *

package/src/models/validation.model.ts

@@ -1,18 +1,9 @@
 import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
-import {NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION} from '../constants';
+import {NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION, NAME_ERROR_VALIDATOR} from '../constants';
 import type {Schema} from '../schema';
-import type {ValueName} from './misc.model';
-
-// #region Named validation
-
-export type NamedValidatorHandlers = {
-	[Key in ValueName]?: Array<(value: unknown) => boolean>;
-};
-
-export type NamedValidators = Record<ValueName, (value: unknown) => boolean>;
-
-// #endregion
+import type {Validator} from '../validator';
+import type {ValueType} from './misc.model';
 
 // #region Reporting
 
@@ -24,11 +15,11 @@ export type ReportingInformation = Record<ReportingType, boolean> & {
  * Controls how validation failures are reported
  *
  * - `'none'`, returns a boolean _(default)_
- * - `'first'`, returns the first failure as a `Result`
+ * - `'first'` or `'result'`, returns the first failure as a `Result`
  * - `'all'`, returns all failures as a `Result` _(from same level)_
  * - `'throw'`, throws a {@link ValidationError} on failure
  */
-export type ReportingType = 'all' | 'first' | 'none' | 'throw';
+export type ReportingType = 'all' | 'first' | 'none' | 'result' | 'throw';
 
 // #endregion
 
@@ -49,7 +40,7 @@ export class SchematicError extends Error {
  * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
  */
 export class ValidationError extends Error {
-	constructor(readonly information: ValidationInformation[]) {
+	constructor(readonly information: PropertyValidation[]) {
 		super(
 			join(
 				information.map(item => item.message),
@@ -61,32 +52,57 @@ export class ValidationError extends Error {
 	}
 }
 
+/**
+ * Thrown when a validator definition is invalid
+ */
+export class ValidatorError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = NAME_ERROR_VALIDATOR;
+	}
+}
+
 // #endregion
 
 // #region Results
 
 /**
- * Describes a single validation failure
+ * Describes a single property validation failure
  */
-export type ValidationInformation = {
-	/** The key path of the property that failed */
-	key: ValidationInformationKey;
-	/** Human-readable description of the failure */
+export type PropertyValidation = {
+	/**
+	 * The key path of the property that failed
+	 */
+	key?: PropertyValidationKey;
+	/**
+	 * Human-readable description of the failure
+	 */
 	message: string;
-	/** The validator function that failed, if the failure was from a `$validators` entry */
+	/**
+	 * The validator function that failed, if the failure was from a `$validators` entry
+	 */
 	validator?: GenericCallback;
-	/** The value that was provided */
+	/**
+	 * The value that was provided
+	 */
 	value: unknown;
 };
 
 /**
- *
+ * The full and short key paths of a property; `full` is the complete path from the root, while `short` is the path from the current schema
  */
-export type ValidationInformationKey = {
+export type PropertyValidationKey = {
 	full: string;
 	short: string;
 };
 
+export type ValueValidation = {
+	message: string;
+	validator?: GenericCallback;
+	value: unknown;
+};
+
 // #endregion
 
 // #region Options
@@ -119,34 +135,56 @@ export type IsOptions<Errors extends ReportingType> = BaseOptions<Errors>;
 
 // #endregion
 
-// #region Validator
+// #region Type validation
+
+/**
+ * Object property validators
+ */
+export type Validators = {
+	[Key in ValueType]?: Array<(value: unknown) => boolean>;
+};
+
+/**
+ * Base type validators
+ */
+export type TypeValidators = Record<ValueType, (value: unknown) => boolean>;
+
+// #endregion
+
+// #region Validation handler
 
-export type Validator = (
+export type ValidationHandler = (
 	input: unknown,
-	parameters: ValidatorParameters,
+	parameters: ValidationHandlerParameters,
 	get: boolean,
-) => true | ValidationInformation[];
+) => true | PropertyValidation[];
 
-export type ValidatorDefaults = {
+export type ValidationHandlerDefaults = {
 	value: unknown;
 };
 
-export type ValidatorItem = {
-	defaults: ValidatorDefaults | undefined;
-	key: ValidationInformationKey;
+export type ValidationHandlerItem = {
+	defaults?: ValidationHandlerDefaults;
+	handler: ValidationHandler;
+	key: PropertyValidationKey;
 	required: boolean;
-	types: ValidatorType[];
-	validator: Validator;
+	types: ValidationHandlerType[];
 };
 
-export type ValidatorParameters = {
+export type ValidationHandlerParameters = {
 	clone: boolean;
-	information?: ValidationInformation[];
+	information?: PropertyValidation[];
+	key?: string;
 	output: PlainObject;
 	reporting: ReportingInformation;
 	strict: boolean;
 };
 
-export type ValidatorType = Function | PlainObject | Schema<unknown> | ValueName;
+export type ValidationHandlerType =
+	| Function
+	| PlainObject
+	| Schema<unknown>
+	| Validator<unknown>
+	| ValueType;
 
 // #endregion

package/src/schema.ts

@@ -1,9 +1,10 @@
 import {isPlainObject} from '@oscarpalmer/atoms/is';
 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_SCHEMA, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE} from './constants';
-import {getParameters, isSchema} from './helpers/misc.helper';
+import {getObjectHandler} from './handler/object.handler';
+import {isSchema} from './helpers/misc.helper';
+import {getResult, isResult} from './helpers/result.helper';
 import type {Infer} from './models/infer.model';
 import type {Schematic} from './models/schematic.plain.model';
 import type {TypedSchematic} from './models/schematic.typed.model';
@@ -11,10 +12,9 @@ import {
 	SchematicError,
 	type GetOptions,
 	type IsOptions,
-	type ValidationInformation,
-	type Validator,
+	type ValidationHandler,
+	type PropertyValidation,
 } from './models/validation.model';
-import {getObjectValidator} from './validator/object.validator';
 
 /**
  * A schema for validating objects
@@ -22,114 +22,100 @@ import {getObjectValidator} from './validator/object.validator';
 export class Schema<Model> {
 	declare private readonly $schema: true;
 
-	#validator: Validator;
+	readonly #handler: ValidationHandler;
 
-	constructor(validator: Validator) {
+	constructor(validator: ValidationHandler) {
 		Object.defineProperty(this, PROPERTY_SCHEMA, {
 			value: true,
 		});
 
-		this.#validator = validator;
+		this.#handler = validator;
 
-		schemaValidators.set(this, validator);
+		schemaHandlers.set(this, validator);
 	}
 
 	/**
 	 * 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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Value, if it matches the schema, otherwise throws an error
 	 */
 	get(value: unknown, options: GetOptions<'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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns 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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Result holding value or all validation information
 	 */
-	get(value: unknown, options: GetOptions<'all'>): Result<Model, ValidationInformation[]>;
+	get(value: unknown, options: GetOptions<'all'>): Result<Model, PropertyValidation[]>;
 
 	/**
 	 * 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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Result holding value or all validation information
 	 */
-	get(value: unknown, errors: 'all'): Result<Model, ValidationInformation[]>;
+	get(value: unknown, errors: 'all'): Result<Model, PropertyValidation[]>;
 
 	/**
 	 * Parse a value according to the schema
 	 *
-	 * Returns a deeply cloned version of the value or all validation information for the first failing property
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Result holding value or all validation information
 	 */
-	get(value: unknown, options: GetOptions<'first'>): Result<Model, ValidationInformation>;
+	get(value: unknown, options: GetOptions<'first'>): Result<Model, PropertyValidation>;
 
 	/**
 	 * Parse a value according to the schema
 	 *
-	 * Returns a deeply cloned version of the value or all validation information for the first failing property
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Result holding value or all validation information
 	 */
-	get(value: unknown, errors: 'first'): Result<Model, ValidationInformation>;
+	get(value: unknown, errors: 'first'): Result<Model, PropertyValidation>;
 
 	/**
 	 * 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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns Value, or `undefined` if it's invalid
 	 */
-	get(value: unknown, options: GetOptions<'none'>): Model | undefined;
+	get(value: unknown, options: Partial<GetOptions<'none'>>): Model | undefined;
 
 	/**
 	 * 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
+	 * Returns value _(deeply cloned, by default)_ 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
+	 * @returns 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 = this.#validator(value, parameters, true);
-
-		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]);
+		return getResult(this.#handler, value, options);
 	}
 
 	/**
@@ -160,7 +146,7 @@ export class Schema<Model> {
 	 * @param options Validation options
 	 * @returns Result holding `true` or all validation information
 	 */
-	is(value: unknown, options: IsOptions<'all'>): Result<true, ValidationInformation[]>;
+	is(value: unknown, options: IsOptions<'all'>): Result<true, PropertyValidation[]>;
 
 	/**
 	 * Does the value match the schema?
@@ -170,7 +156,7 @@ export class Schema<Model> {
 	 * @param errors Reporting type
 	 * @returns Result holding `true` or all validation information
 	 */
-	is(value: unknown, errors: 'all'): Result<true, ValidationInformation[]>;
+	is(value: unknown, errors: 'all'): Result<true, PropertyValidation[]>;
 
 	/**
 	 * Does the value match the schema?
@@ -178,9 +164,9 @@ export class Schema<Model> {
 	 * 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`
+	 * @returns Result holding `true` or all validation information
 	 */
-	is(value: unknown, options: IsOptions<'first'>): Result<true, ValidationInformation>;
+	is(value: unknown, options: IsOptions<'first'>): Result<true, PropertyValidation>;
 
 	/**
 	 * Does the value match the schema?
@@ -188,24 +174,24 @@ export class Schema<Model> {
 	 * 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`
+	 * @returns Result holding `true` or all validation information
 	 */
-	is(value: unknown, errors: 'first'): Result<true, ValidationInformation>;
+	is(value: unknown, errors: 'first'): Result<true, PropertyValidation>;
 
 	/**
 	 * 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` if it's valid, or `false` if not
 	 * @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;
+	is(value: unknown, options: Partial<IsOptions<'none'>>): value is 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` if it's valid, or `false` if not
 	 * @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`
@@ -213,19 +199,7 @@ export class Schema<Model> {
 	is(value: unknown, strict?: true): value is Model;
 
 	is(value: unknown, options?: unknown): unknown {
-		const parameters = getParameters(options);
-
-		const result = this.#validator(value, parameters, false);
-
-		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]);
+		return isResult(this.#handler, value, options);
 	}
 }
 
@@ -249,14 +223,14 @@ export function schema<Model extends PlainObject>(schema: TypedSchematic<Model>)
 
 export function schema<Model extends Schematic>(schema: Model): Schema<Model> {
 	if (isSchema(schema)) {
-		return schema;
+		return schema as Schema<Model>;
 	}
 
 	if (!isPlainObject(schema)) {
 		throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE);
 	}
 
-	return new Schema<Model>(getObjectValidator(schema));
+	return new Schema<Model>(getObjectHandler(schema));
 }
 
-export const schemaValidators = new WeakMap<Schema<unknown>, Validator>();
+export const schemaHandlers = new WeakMap<Schema<unknown>, ValidationHandler>();