@oscarpalmer/jhunal 0.21.0 → 0.23.0

package/src/constants.ts

@@ -25,6 +25,8 @@ export const MESSAGE_CONSTRUCTOR = 'Expected a constructor function';
 
 export const NAME_SCHEMATIC = 'Schematic';
 
+export const NAME_SCHEMATIC_PREFIXED = 'a Schematic';
+
 export const NAME_ERROR_SCHEMATIC = 'SchematicError';
 
 export const NAME_ERROR_VALIDATION = 'ValidationError';
@@ -45,7 +47,7 @@ export const PROPERTY_VALIDATORS = '$validators';
 
 // #region Property validation
 
-export const VALIDATION_MESSAGE_INVALID_INPUT = "Expected 'object' as input but received <>";
+export const VALIDATION_MESSAGE_INVALID_INPUT = 'Expected an object as input but received <>';
 
 export const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required property '<>'";
 
@@ -116,24 +118,54 @@ export const TEMPLATE_PATTERN = '<>';
 
 export const TYPE_ARRAY = 'array';
 
+const TYPE_BIGINT = 'bigint';
+
+const TYPE_BOOLEAN = 'boolean';
+
+const TYPE_DATE = 'date';
+
+export const TYPE_FUNCTION = 'function';
+
+export const TYPE_FUNCTION_RESULT = 'a validated value';
+
 export const TYPE_NULL = 'null';
 
+const TYPE_NUMBER = 'number';
+
 export const TYPE_OBJECT = 'object';
 
+const TYPE_STRING = 'string';
+
+const TYPE_SYMBOL = 'symbol';
+
 export const TYPE_UNDEFINED = 'undefined';
 
 export const VALIDATABLE_TYPES = new Set<ValueName>([
-	'array',
-	'bigint',
-	'boolean',
-	'date',
-	'function',
-	'number',
-	'string',
-	'symbol',
+	TYPE_ARRAY,
+	TYPE_BIGINT,
+	TYPE_BOOLEAN,
+	TYPE_DATE,
+	TYPE_FUNCTION,
+	TYPE_NUMBER,
 	TYPE_OBJECT,
+	TYPE_STRING,
+	TYPE_SYMBOL,
 ]);
 
-export const TYPE_ALL = new Set<ValueName>([...VALIDATABLE_TYPES, 'null', TYPE_UNDEFINED]);
+export const TYPE_ALL = new Set<ValueName>([...VALIDATABLE_TYPES, TYPE_NULL, TYPE_UNDEFINED]);
+
+export const PREFIXED_TYPES: Record<ValueName, string> = {
+	[TYPE_ARRAY]: `an ${TYPE_ARRAY}`,
+	[TYPE_BIGINT]: `a ${TYPE_BIGINT}`,
+	[TYPE_BOOLEAN]: `a ${TYPE_BOOLEAN}`,
+	[TYPE_DATE]: `a ${TYPE_DATE}`,
+	[TYPE_FUNCTION]: `a ${TYPE_FUNCTION}`,
+	[TYPE_NULL]: TYPE_NULL,
+	[TYPE_NUMBER]: `a ${TYPE_NUMBER}`,
+	[TYPE_STRING]: `a ${TYPE_STRING}`,
+	[TYPE_SYMBOL]: `a ${TYPE_SYMBOL}`,
+	[TYPE_OBJECT]: `an ${TYPE_OBJECT}`,
+	[TYPE_UNDEFINED]: TYPE_UNDEFINED,
+};
 
 // #endregion

package/src/helpers/message.helper.ts

@@ -0,0 +1,152 @@
+import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
+import {
+	COMMA,
+	CONJUNCTION_AND,
+	CONJUNCTION_AND_COMMA,
+	CONJUNCTION_OR,
+	CONJUNCTION_OR_COMMA,
+	PREFIXED_TYPES,
+	TEMPLATE_PATTERN,
+	TYPE_ALL,
+	TYPE_ARRAY,
+	TYPE_FUNCTION,
+	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';
+
+export function getInvalidInputMessage(actual: unknown): string {
+	return VALIDATION_MESSAGE_INVALID_INPUT.replace(TEMPLATE_PATTERN, getValueType(actual));
+}
+
+export function getInvalidMissingMessage(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 getInvalidTypeMessage(
+	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 getInvalidValidatorMessage(
+	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;
+}
+
+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];
+	}
+}
+
+export function getUnknownKeysMessage(keys: string[]): string {
+	return VALIDATION_MESSAGE_UNKNOWN_KEYS.replace(TEMPLATE_PATTERN, renderKeys(keys));
+}
+
+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);
+}

package/src/helpers/misc.helper.ts

@@ -0,0 +1,93 @@
+import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
+import type {Constructor, PlainObject} from '@oscarpalmer/atoms/models';
+import {
+	MESSAGE_CONSTRUCTOR,
+	PROPERTY_SCHEMATIC,
+	REPORTING_ALL,
+	REPORTING_FIRST,
+	REPORTING_NONE,
+	REPORTING_THROW,
+	REPORTING_TYPES,
+	TYPE_OBJECT,
+} 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(REPORTING_NONE),
+			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 === TYPE_OBJECT &&
+		value !== null &&
+		PROPERTY_SCHEMATIC in (value as PlainObject) &&
+		(value as PlainObject)[PROPERTY_SCHEMATIC] === true
+	);
+}

package/src/index.ts

@@ -1,5 +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} from './models/validation.model';
+export {
+	SchematicError,
+	ValidationError,
+	type GetOptions,
+	type IsOptions,
+} from './models/validation.model';
 export {schematic, type Schematic} from './schematic';

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

@@ -25,7 +25,7 @@ export type PlainSchema = {
  * };
  * ```
  */
-export type Schema = SchemaIndex;
+export type Schema = PlainSchema;
 
 /**
  * A union of all valid types for a single schema entry
@@ -40,13 +40,6 @@ export type SchemaEntry =
 	| ValueName
 	| ((value: unknown) => boolean);
 
-/**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link PlainSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
- */
-export interface SchemaIndex {
-	[key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
-}
-
 /**
  * A property definition with explicit type(s), an optional requirement flag, and optional validators
  *

package/src/models/validation.model.ts

@@ -4,11 +4,18 @@ import {NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION} from '../constants';
 import type {Schematic} from '../schematic';
 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
+
 // #region Reporting
 
-/**
- * Maps each {@link ReportingType} to a boolean flag
- */
 export type ReportingInformation = Record<ReportingType, boolean> & {
 	type: ReportingType;
 };
@@ -16,16 +23,16 @@ 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`
- * - `'all'` — returns all failures as a `Result` _(from same level)_
- * - `'throw'` — throws a {@link ValidationError} on failure
+ * - `'none'`, returns a boolean _(default)_
+ * - `'first'`, 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';
 
 // #endregion
 
-// #region Schematic validation
+// #region Errors
 
 /**
  * Thrown when a schema definition is invalid
@@ -38,66 +45,6 @@ export class SchematicError extends Error {
 	}
 }
 
-// #endregion
-
-// #region Validated property
-
-/**
- * The runtime representation of a parsed schema property, used internally during validation
- *
- * @example
- * ```ts
- * const parsed: ValidatedProperty = {
- *   key: 'age',
- *   required: true,
- *   types: ['number'],
- *   validators: { number: [(v) => v > 0] },
- * };
- * ```
- */
-export type ValidatedProperty = {
-	/**
-	 * The property name in the schema
-	 */
-	key: string;
-	/**
-	 * Whether the property is required
-	 */
-	required: boolean;
-	/**
-	 * The allowed types for this property
-	 */
-	types: ValidatedPropertyType[];
-	/**
-	 * Custom validators grouped by {@link ValueName}
-	 */
-	validators: ValidatedPropertyValidators;
-};
-
-/**
- * A union of valid types for a {@link ValidatedProperty}'s `types` array
- *
- * Can be a callback _(custom validator)_, a {@link Schematic}, a nested {@link ValidatedProperty}, or a {@link ValueName} string
- */
-export type ValidatedPropertyType =
-	| GenericCallback
-	| ValidatedProperty[]
-	| Schematic<unknown>
-	| ValueName;
-
-/**
- * A map of validator functions keyed by {@link ValueName}, used at runtime in {@link ValidatedProperty}
- *
- * Each key holds an array of validator functions that receive an `unknown` value and return a `boolean`
- */
-export type ValidatedPropertyValidators = {
-	[Key in ValueName]?: Array<(value: unknown) => boolean>;
-};
-
-// #endregion
-
-// #region Property validation
-
 /**
  * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
  */
@@ -114,6 +61,10 @@ export class ValidationError extends Error {
 	}
 }
 
+// #endregion
+
+// #region Results
+
 /**
  * Describes a single validation failure
  */
@@ -129,34 +80,61 @@ export type ValidationInformation = {
 };
 
 /**
- * 
+ *
  */
 export type ValidationInformationKey = {
 	full: string;
 	short: string;
 };
 
-/**
- * Options for validation
- */
-export type ValidationOptions<Errors extends ReportingType> = {
+// #endregion
+
+// #region Options
+
+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;
 };
 
-export type ValidationParameters = {
+/**
+ * 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
+
+export type Validator = (
+	input: unknown,
+	parameters: ValidatorParameters,
+	get: boolean,
+) => true | ValidationInformation[];
+
+export type ValidatorParameters = {
+	clone: boolean;
 	information?: ValidationInformation[];
-	origin?: ValidatedProperty;
 	output: PlainObject;
-	prefix?: string;
 	reporting: ReportingInformation;
 	strict: boolean;
 };
 
+export type ValidatorType = Function | PlainObject | Schematic<unknown> | ValueName;
+
 // #endregion