@oscarpalmer/jhunal 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscarpalmer/jhunal",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Flies free beneath the glistening moons…",
   "keywords": [
     "schema",
@@ -38,7 +38,7 @@
     "watch": "npx vite build --watch"
   },
   "dependencies": {
-    "@oscarpalmer/atoms": "^0.166"
+    "@oscarpalmer/atoms": "^0.169"
   },
   "devDependencies": {
     "@types/node": "^25.5",
@@ -51,4 +51,4 @@
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
   },
   "packageManager": "npm@11.11.1"
-}
+}

package/src/constants.ts

@@ -1,42 +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';
-
-export const EXPRESSION_PROPERTY = /(^|\.)\$(required|type|validators)(\.|$)/;
+// #region Misc.
 
 export const MESSAGE_CONSTRUCTOR = 'Expected a constructor function';
 
-export const MESSAGE_SCHEMA_INVALID_EMPTY = 'Schema must have at least one property';
-
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED =
-	"'<key>.<property>' property is not allowed for schemas in $type";
+// #endregion
 
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED = "'<>.$required' property must be a boolean";
+// #region Names
 
-export const MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE = "'<>' property must be of a valid type";
+export const NAME_SCHEMATIC = 'Schematic';
 
-export const MESSAGE_SCHEMA_INVALID_TYPE = 'Schema must be an object';
+export const NAME_ERROR_SCHEMATIC = 'SchematicError';
 
-export const MESSAGE_VALIDATOR_INVALID_KEY = "Validator '<>' does not exist";
+export const NAME_ERROR_VALIDATION = 'ValidationError';
 
-export const MESSAGE_VALIDATOR_INVALID_TYPE = 'Validators must be an object';
+// #endregion
 
-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';
 
@@ -55,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;

package/src/models/misc.model.ts

@@ -0,0 +1,212 @@
+import type {SchemaProperty} from './schema.plain.model';
+
+/**
+ * Removes duplicate types from a tuple, preserving first occurrence order
+ *
+ * @template Value - Tuple to deduplicate
+ * @template Seen - Accumulator for already-seen types _(internal)_
+ *
+ * @example
+ * ```ts
+ * // DeduplicateTuple<['string', 'number', 'string']>
+ * // => ['string', 'number']
+ * ```
+ */
+export type DeduplicateTuple<Value extends unknown[], Seen extends unknown[] = []> = Value extends [
+	infer Head,
+	...infer Tail,
+]
+	? Head extends Seen[number]
+		? DeduplicateTuple<Tail, Seen>
+		: DeduplicateTuple<Tail, [...Seen, Head]>
+	: Seen;
+
+/**
+ * Recursively extracts {@link ValueName} strings from a type, unwrapping arrays and readonly arrays
+ *
+ * @template Value - Type to extract value names from
+ *
+ * @example
+ * ```ts
+ * // ExtractValueNames<'string'>         => 'string'
+ * // ExtractValueNames<['string', 'number']> => 'string' | 'number'
+ * ```
+ */
+export type ExtractValueNames<Value> = Value extends ValueName
+	? Value
+	: Value extends (infer Item)[]
+		? ExtractValueNames<Item>
+		: Value extends readonly (infer Item)[]
+			? ExtractValueNames<Item>
+			: never;
+
+/**
+ * Determines whether a schema entry is optional
+ *
+ * Returns `true` if the entry is a {@link SchemaProperty} or {@link NestedSchema} with `$required` set to `false`; otherwise returns `false`
+ *
+ * @template Value - Schema entry to check
+ */
+export type IsOptionalProperty<Value> = Value extends SchemaProperty
+	? Value['$required'] extends false
+		? true
+		: false
+	: false;
+
+/**
+ * Extracts the last member from a union type by leveraging intersection of function return types
+ *
+ * @template Value - Union type
+ */
+export type LastOfUnion<Value> =
+	UnionToIntersection<Value extends unknown ? () => Value : never> extends () => infer Item
+		? Item
+		: never;
+
+/**
+ * Extracts keys from an object type that are optional
+ *
+ * @template Value - Object type to inspect
+ */
+export type OptionalKeys<Value> = {
+	[Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never;
+}[keyof Value];
+
+/**
+ * Extracts keys from an object type that are required _(i.e., not optional)_
+ *
+ * @template Value - Object type to inspect
+ */
+export type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
+
+/**
+ * Generates all permutations of a tuple type
+ *
+ * Used by {@link UnwrapSingle} to allow schema types in any order for small tuples _(length ≤ 5)_
+ *
+ * @template Tuple - Tuple to permute
+ * @template Elput - Accumulator for the current permutation _(internal; name is Tuple backwards)_
+ *
+ * @example
+ * ```ts
+ * // TuplePermutations<['string', 'number']>
+ * // => ['string', 'number'] | ['number', 'string']
+ * ```
+ */
+export type TuplePermutations<
+	Tuple extends unknown[],
+	Elput extends unknown[] = [],
+> = Tuple['length'] extends 0
+	? Elput
+	: {
+			[Key in keyof Tuple]: TuplePermutations<
+				TupleRemoveAt<Tuple, Key & `${number}`>,
+				[...Elput, Tuple[Key]]
+			>;
+		}[keyof Tuple & `${number}`];
+
+/**
+ * Removes the element at a given index from a tuple
+ *
+ * Used internally by {@link TuplePermutations}
+ *
+ * @template Items - Tuple to remove from
+ * @template Item - Stringified index to remove
+ * @template Prefix - Accumulator for elements before the target _(internal)_
+ */
+export type TupleRemoveAt<
+	Items extends unknown[],
+	Item extends string,
+	Prefix extends unknown[] = [],
+> = Items extends [infer Head, ...infer Tail]
+	? `${Prefix['length']}` extends Item
+		? [...Prefix, ...Tail]
+		: TupleRemoveAt<Tail, Item, [...Prefix, Head]>
+	: Prefix;
+
+/**
+ * Converts a union type into an intersection
+ *
+ * Uses the contravariance of function parameter types to collapse a union into an intersection
+ *
+ * @template Value - Union type to convert
+ *
+ * @example
+ * ```ts
+ * // UnionToIntersection<{ a: 1 } | { b: 2 }>
+ * // => { a: 1 } & { b: 2 }
+ * ```
+ */
+export type UnionToIntersection<Value> = (
+	Value extends unknown ? (value: Value) => void : never
+) extends (value: infer Item) => void
+	? Item
+	: never;
+
+/**
+ * Converts a union type into an ordered tuple
+ *
+ * Repeatedly extracts the {@link LastOfUnion} member and prepends it to the accumulator
+ *
+ * @template Value - Union type to convert
+ * @template Items - Accumulator for the resulting tuple _(internal)_
+ *
+ * @example
+ * ```ts
+ * // UnionToTuple<'a' | 'b' | 'c'>
+ * // => ['a', 'b', 'c']
+ * ```
+ */
+export type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never]
+	? Items
+	: UnionToTuple<Exclude<Value, LastOfUnion<Value>>, [LastOfUnion<Value>, ...Items]>;
+
+/**
+ * Unwraps a single-element tuple to its inner type
+ *
+ * For tuples of length 2–5, returns all {@link TuplePermutations} to allow types in any order. Longer tuples are returned as-is
+ *
+ * @template Value - Tuple to potentially unwrap
+ *
+ * @example
+ * ```ts
+ * // UnwrapSingle<['string']>            => 'string'
+ * // UnwrapSingle<['string', 'number']>  => ['string', 'number'] | ['number', 'string']
+ * ```
+ */
+export type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only]
+	? Only
+	: Value['length'] extends 1 | 2 | 3 | 4 | 5
+		? TuplePermutations<Value>
+		: Value;
+
+/**
+ * Basic value types
+ */
+export type ValueName = keyof Values;
+
+/**
+ * Maps type name strings to their TypeScript equivalents
+ *
+ * Used by the type system to resolve {@link ValueName} strings into actual types
+ *
+ * @example
+ * ```ts
+ * // Values['string']  => string
+ * // Values['date']    => Date
+ * // Values['null']    => null
+ * ```
+ */
+export type Values = {
+	array: unknown[];
+	bigint: bigint;
+	boolean: boolean;
+	date: Date;
+	function: Function;
+	null: null;
+	number: number;
+	object: object;
+	string: string;
+	symbol: symbol;
+	undefined: undefined;
+};