@oscarpalmer/jhunal 0.17.0 → 0.18.0

package/dist/index.mjs

@@ -1,23 +1,39 @@
 import { isConstructor, isPlainObject } from "@oscarpalmer/atoms/is";
 import { join } from "@oscarpalmer/atoms/string";
 //#region src/constants.ts
-const ERROR_NAME = "SchematicError";
 const MESSAGE_CONSTRUCTOR = "Expected a constructor function";
-const MESSAGE_SCHEMA_INVALID_EMPTY = "Schema must have at least one property";
-const MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED = "'<key>.<property>' property is not allowed for schemas in $type";
-const MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE = "'<>' property must not be 'null' or 'undefined'";
-const MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED = "'<>.$required' property must be a boolean";
-const MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE = "'<>' property must be of a valid type";
-const MESSAGE_SCHEMA_INVALID_TYPE = "Schema must be an object";
-const MESSAGE_VALIDATOR_INVALID_KEY = "Validator '<>' does not exist";
-const MESSAGE_VALIDATOR_INVALID_TYPE = "Validators must be an object";
-const MESSAGE_VALIDATOR_INVALID_VALUE = "Validator '<>' must be a function or an array of functions";
+const NAME_SCHEMATIC = "Schematic";
+const NAME_ERROR_SCHEMATIC = "SchematicError";
+const NAME_ERROR_VALIDATION = "ValidationError";
 const PROPERTY_REQUIRED = "$required";
+const PROPERTY_SCHEMATIC = "$schematic";
 const PROPERTY_TYPE = "$type";
 const PROPERTY_VALIDATORS = "$validators";
-const SCHEMATIC_NAME = "$schematic";
-const TEMPLATE_PATTERN_KEY = "<key>";
-const TEMPLATE_PATTERN_PROPERTY = "<property>";
+const VALIDATION_MESSAGE_INVALID_INPUT = "Expected 'object' as input but received <>";
+const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required property '<>'";
+const VALIDATION_MESSAGE_INVALID_TYPE = "Expected <> for '<>' but received <>";
+const VALIDATION_MESSAGE_INVALID_VALUE = "Value does not satisfy validator for '<>' and type '<>'";
+const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = " at index <>";
+const REPORTING_FIRST = "first";
+const REPORTING_NONE = "none";
+const REPORTING_THROW = "throw";
+const REPORTING_TYPES = new Set([
+	"all",
+	REPORTING_FIRST,
+	REPORTING_NONE,
+	REPORTING_THROW
+]);
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY = "Schema must have at least one property";
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED = "'<>.<>' property is not allowed for schemas in $type";
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE = "'<>' property must not be 'null' or 'undefined'";
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED = "'<>.$required' property must be a boolean";
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE = "'<>' property must be of a valid type";
+const SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE = "Schema must be an object";
+const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY = "Validator '<>' does not exist";
+const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE = "Validators must be an object";
+const SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE = "Validator '<>' must be a function or an array of functions";
+const TYPE_ARRAY = "array";
+const TYPE_NULL = "null";
 const TYPE_OBJECT = "object";
 const TYPE_UNDEFINED = "undefined";
 const VALIDATABLE_TYPES = new Set([
@@ -38,6 +54,53 @@ const TYPE_ALL = new Set([
 ]);
 //#endregion
 //#region src/helpers.ts
+function getInvalidInputMessage(actual) {
+	return VALIDATION_MESSAGE_INVALID_INPUT.replace("<>", getValueType(actual));
+}
+function getInvalidMissingMessage(property) {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace("<>", renderTypes(property.types));
+	message = message.replace("<>", property.key.full);
+	return message;
+}
+function getInvalidTypeMessage(property, actual) {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace("<>", renderTypes(property.types));
+	message = message.replace("<>", property.key.full);
+	message = message.replace("<>", getValueType(actual));
+	return message;
+}
+function getInvalidValidatorMessage(property, type, index, length) {
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace("<>", property.key.full);
+	message = message.replace("<>", type);
+	if (length > 1) message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace("<>", String(index));
+	return message;
+}
+function getPropertyType(original) {
+	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)}'`;
+}
+function getReporting(value) {
+	const type = REPORTING_TYPES.has(value) ? value : REPORTING_NONE;
+	return {
+		["all"]: type === "all",
+		[REPORTING_FIRST]: type === REPORTING_FIRST,
+		[REPORTING_NONE]: type === REPORTING_NONE,
+		[REPORTING_THROW]: type === REPORTING_THROW
+	};
+}
+function getValueType(value) {
+	const valueType = typeof value;
+	switch (true) {
+		case value === null: return `'${TYPE_NULL}'`;
+		case value === void 0: 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
@@ -58,15 +121,40 @@ function instanceOf(constructor) {
 function isSchematic(value) {
 	return typeof value === "object" && value !== null && "$schematic" in value && value["$schematic"] === true;
 }
+function renderTypes(types) {
+	const unique = /* @__PURE__ */ new Set();
+	const parts = [];
+	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;
+}
 //#endregion
-//#region src/models.ts
+//#region src/models/validation.model.ts
 /**
 * A custom error class for schematic validation failures
 */
 var SchematicError = class extends Error {
 	constructor(message) {
 		super(message);
-		this.name = ERROR_NAME;
+		this.name = NAME_ERROR_SCHEMATIC;
+	}
+};
+var ValidationError = class extends Error {
+	constructor(information) {
+		super(join(information.map((item) => item.message), "; "));
+		this.information = information;
+		this.name = NAME_ERROR_VALIDATION;
 	}
 };
 //#endregion
@@ -77,32 +165,36 @@ function getDisallowedProperty(obj) {
 	if ("$validators" in obj) return PROPERTY_VALIDATORS;
 }
 function getProperties(original, prefix, fromType) {
-	if (Object.keys(original).length === 0) throw new SchematicError(MESSAGE_SCHEMA_INVALID_EMPTY);
+	if (Object.keys(original).length === 0) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY);
 	if (fromType ?? false) {
 		const property = getDisallowedProperty(original);
-		if (property != null) throw new SchematicError(MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED.replace(TEMPLATE_PATTERN_KEY, prefix).replace(TEMPLATE_PATTERN_PROPERTY, property));
+		if (property != null) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED.replace("<>", prefix).replace("<>", property));
 	}
 	const keys = Object.keys(original);
 	const keysLength = keys.length;
 	const properties = [];
 	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(MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", join([prefix, key], ".")));
+		if (value == null) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", prefixed));
 		const types = [];
 		let required = true;
 		let validators = {};
 		if (isPlainObject(value)) {
 			required = getRequired(key, value) ?? required;
 			validators = getValidators(value[PROPERTY_VALIDATORS]);
-			if ("$type" in value) types.push(TYPE_OBJECT, ...getTypes(key, value[PROPERTY_TYPE], prefix, true));
-			else types.push(TYPE_OBJECT, ...getTypes(key, value, prefix));
+			const hasType = PROPERTY_TYPE in value;
+			types.push(...getTypes(key, hasType ? value[PROPERTY_TYPE] : value, prefix, hasType));
 		} else types.push(...getTypes(key, value, prefix));
 		if (!required && !types.includes("undefined")) types.push(TYPE_UNDEFINED);
 		properties.push({
-			key,
 			types,
 			validators,
+			key: {
+				full: prefixed,
+				short: key
+			},
 			required: required && !types.includes("undefined")
 		});
 	}
@@ -110,7 +202,7 @@ function getProperties(original, prefix, fromType) {
 }
 function getRequired(key, obj) {
 	if (!("$required" in obj)) return;
-	if (typeof obj["$required"] !== "boolean") throw new SchematicError(MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED.replace("<>", key));
+	if (typeof obj["$required"] !== "boolean") throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED.replace("<>", key));
 	return obj[PROPERTY_REQUIRED];
 }
 function getTypes(key, original, prefix, fromType) {
@@ -124,7 +216,7 @@ function getTypes(key, original, prefix, fromType) {
 				types.push(isConstructor(value) ? instanceOf(value) : value);
 				break;
 			case isPlainObject(value):
-				types.push(...getProperties(value, join([prefix, key], "."), fromType));
+				types.push(getProperties(value, join([prefix, key], "."), fromType));
 				break;
 			case isSchematic(value):
 				types.push(value);
@@ -132,55 +224,106 @@ function getTypes(key, original, prefix, fromType) {
 			case TYPE_ALL.has(value):
 				types.push(value);
 				break;
-			default: throw new SchematicError(MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE.replace("<>", join([prefix, key], ".")));
+			default: throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE.replace("<>", join([prefix, key], ".")));
 		}
 	}
-	if (types.length === 0) throw new SchematicError(MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE.replace("<>", join([prefix, key], ".")));
+	if (types.length === 0) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE.replace("<>", join([prefix, key], ".")));
 	return types;
 }
 function getValidators(original) {
 	const validators = {};
 	if (original == null) return validators;
-	if (!isPlainObject(original)) throw new TypeError(MESSAGE_VALIDATOR_INVALID_TYPE);
+	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 (!VALIDATABLE_TYPES.has(key)) throw new TypeError(MESSAGE_VALIDATOR_INVALID_KEY.replace("<>", key));
+		if (!VALIDATABLE_TYPES.has(key)) throw new TypeError(SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY.replace("<>", key));
 		const value = original[key];
-		validators[key] = (Array.isArray(value) ? value : [value]).filter((item) => {
-			if (typeof item !== "function") throw new TypeError(MESSAGE_VALIDATOR_INVALID_VALUE.replace("<>", key));
-			return true;
+		validators[key] = (Array.isArray(value) ? value : [value]).map((item) => {
+			if (typeof item !== "function") throw new TypeError(SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE.replace("<>", key));
+			return item;
 		});
 	}
 	return validators;
 }
 //#endregion
 //#region src/validation/value.validation.ts
-function validateObject(obj, properties) {
-	if (!isPlainObject(obj)) return false;
+function validateNamed(property, name, value, validation) {
+	if (!validators[name](value)) return false;
+	const propertyValidators = property.validators[name];
+	if (propertyValidators == null || propertyValidators.length === 0) return true;
+	const { length } = propertyValidators;
+	for (let index = 0; index < length; index += 1) {
+		const validator = propertyValidators[index];
+		if (!validator(value)) {
+			validation.push({
+				key: { ...property.key },
+				message: getInvalidValidatorMessage(property, name, index, length),
+				validator
+			});
+			return false;
+		}
+	}
+	return true;
+}
+function validateObject(obj, properties, reporting, validation) {
+	if (!isPlainObject(obj)) {
+		if (reporting.throw && validation == null) throw new ValidationError([{
+			key: {
+				full: "",
+				short: ""
+			},
+			message: getInvalidInputMessage(obj)
+		}]);
+		return false;
+	}
 	const propertiesLength = properties.length;
 	outer: for (let propertyIndex = 0; propertyIndex < propertiesLength; propertyIndex += 1) {
 		const property = properties[propertyIndex];
 		const { key, required, types } = property;
-		const value = obj[key];
-		if (value === void 0 && required) return false;
+		const value = obj[key.short];
+		if (value === void 0 && required) {
+			const information = {
+				key: { ...key },
+				message: getInvalidMissingMessage(property)
+			};
+			if (reporting.throw && validation == null) throw new ValidationError([information]);
+			if (validation != null) validation.push(information);
+			return false;
+		}
 		const typesLength = types.length;
+		const information = [];
 		for (let typeIndex = 0; typeIndex < typesLength; typeIndex += 1) {
 			const type = types[typeIndex];
-			if (validateValue(type, property, value)) continue outer;
+			if (validateValue(type, property, value, reporting, information)) continue outer;
 		}
+		if (reporting.throw && validation == null) throw new ValidationError(information.length === 0 ? [{
+			key: { ...key },
+			message: getInvalidTypeMessage(property, value)
+		}] : information);
+		validation?.push(...information);
 		return false;
 	}
 	return true;
 }
-function validateValue(type, property, value) {
+function validateValue(type, property, value, reporting, validation) {
+	let result;
 	switch (true) {
-		case isSchematic(type): return type.is(value);
-		case typeof type === "function": return type(value);
-		case typeof type === "object": return validateObject(value, [type]);
-		default: return validators[type](value) && (property.validators[type]?.every((validator) => validator(value)) ?? true);
+		case typeof type === "function":
+			result = type(value);
+			break;
+		case Array.isArray(type):
+			result = validateObject(value, type, reporting, validation);
+			break;
+		case isSchematic(type):
+			result = type.is(value, reporting);
+			break;
+		default:
+			result = validateNamed(property, type, value, validation);
+			break;
 	}
+	return result;
 }
 const validators = {
 	array: Array.isArray,
@@ -203,22 +346,17 @@ const validators = {
 var Schematic = class {
 	#properties;
 	constructor(properties) {
-		Object.defineProperty(this, SCHEMATIC_NAME, { value: true });
+		Object.defineProperty(this, PROPERTY_SCHEMATIC, { value: true });
 		this.#properties = properties;
 	}
-	/**
-	* Does the value match the schema?
-	* @param value Value to validate
-	* @returns `true` if the value matches the schema, otherwise `false`
-	*/
-	is(value) {
-		return validateObject(value, this.#properties);
+	is(value, errors) {
+		return validateObject(value, this.#properties, getReporting(errors));
 	}
 };
 function schematic(schema) {
 	if (isSchematic(schema)) return schema;
-	if (!isPlainObject(schema)) throw new SchematicError(MESSAGE_SCHEMA_INVALID_TYPE);
+	if (!isPlainObject(schema)) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE);
 	return new Schematic(getProperties(schema));
 }
 //#endregion
-export { SchematicError, instanceOf, isSchematic, schematic };
+export { SchematicError, ValidationError, instanceOf, isSchematic, schematic };

package/dist/models/infer.model.d.mts

@@ -0,0 +1,66 @@
+import { Schematic } from "../schematic.mjs";
+import { PlainSchema, Schema, SchemaProperty } from "./schema.plain.model.mjs";
+import { IsOptionalProperty, ValueName, Values } from "./misc.model.mjs";
+import { Constructor, Simplify } from "@oscarpalmer/atoms/models";
+
+//#region src/models/infer.model.d.ts
+/**
+ * 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 }
+ * ```
+ */
+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
+ */
+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)_
+ */
+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
+ */
+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
+ */
+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)_
+ */
+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
+ */
+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;
+//#endregion
+export { Infer, InferOptionalKeys, InferPropertyType, InferPropertyValue, InferRequiredKeys, InferSchemaEntry, InferSchemaEntryValue };

package/dist/models/infer.model.mjs

@@ -0,0 +1 @@
+export {};

package/dist/models/misc.model.d.mts

@@ -0,0 +1,153 @@
+import { SchemaProperty } from "./schema.plain.model.mjs";
+
+//#region src/models/misc.model.d.ts
+/**
+ * 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']
+ * ```
+ */
+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'
+ * ```
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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']
+ * ```
+ */
+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)_
+ */
+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 }
+ * ```
+ */
+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']
+ * ```
+ */
+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']
+ * ```
+ */
+type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only : Value['length'] extends 1 | 2 | 3 | 4 | 5 ? TuplePermutations<Value> : Value;
+/**
+ * Basic value types
+ */
+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
+ * ```
+ */
+type Values = {
+  array: unknown[];
+  bigint: bigint;
+  boolean: boolean;
+  date: Date;
+  function: Function;
+  null: null;
+  number: number;
+  object: object;
+  string: string;
+  symbol: symbol;
+  undefined: undefined;
+};
+//#endregion
+export { DeduplicateTuple, ExtractValueNames, IsOptionalProperty, LastOfUnion, OptionalKeys, RequiredKeys, TuplePermutations, TupleRemoveAt, UnionToIntersection, UnionToTuple, UnwrapSingle, ValueName, Values };

package/dist/models/misc.model.mjs

@@ -0,0 +1 @@
+export {};

package/dist/models/schema.plain.model.d.mts

@@ -0,0 +1,92 @@
+import { Schematic } from "../schematic.mjs";
+import { ExtractValueNames, ValueName, Values } from "./misc.model.mjs";
+import { Constructor } from "@oscarpalmer/atoms/models";
+
+//#region src/models/schema.plain.model.d.ts
+/**
+ * A generic schema allowing {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry} as values
+ */
+type PlainSchema = {
+  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
+} & {
+  $required?: never;
+  $type?: never;
+  $validators?: never;
+};
+/**
+ * A schema for validating objects
+ *
+ * @example
+ * ```ts
+ * const schema: Schema = {
+ *   name: 'string',
+ *   age: 'number',
+ *   tags: ['string', 'number'],
+ * };
+ * ```
+ */
+type Schema = SchemaIndex;
+/**
+ * A union of all valid types for a single schema entry
+ *
+ * Can be a {@link Constructor}, nested {@link Schema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ */
+type SchemaEntry = Constructor | PlainSchema | SchemaProperty | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
+/**
+ * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
+ */
+interface SchemaIndex {
+  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
+}
+/**
+ * A property definition with explicit type(s), an optional requirement flag, and optional validators
+ *
+ * @example
+ * ```ts
+ * const prop: SchemaProperty = {
+ *   $required: false,
+ *   $type: ['string', 'number'],
+ *   $validators: {
+ *     string: (v) => v.length > 0,
+ *     number: (v) => v > 0,
+ *   },
+ * };
+ * ```
+ */
+type SchemaProperty = {
+  /**
+   * Whether the property is required _(defaults to `true`)_
+   */
+  $required?: boolean;
+  /**
+   * The type(s) the property value must match; a single {@link SchemaPropertyType} or an array
+   */
+  $type: SchemaPropertyType | SchemaPropertyType[];
+  /**
+   * Optional validators keyed by {@link ValueName}, applied during validation
+   */
+  $validators?: PropertyValidators<SchemaPropertyType | SchemaPropertyType[]>;
+};
+/**
+ * A union of valid types for a {@link SchemaProperty}'s `$type` field
+ *
+ * Can be a {@link Constructor}, {@link PlainSchema}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ */
+type SchemaPropertyType = Constructor | PlainSchema | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
+/**
+ * A map of optional validator functions keyed by {@link ValueName}, 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
+ *
+ * @template Value - `$type` value(s) to derive validator keys from
+ *
+ * @example
+ * ```ts
+ * const validators: PropertyValidators<'string'> = {
+ *   string: (value) => value.length > 0,
+ * };
+ * ```
+ */
+type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value: Values[Key]) => boolean) | Array<(value: Values[Key]) => boolean> };
+//#endregion
+export { PlainSchema, PropertyValidators, Schema, SchemaEntry, SchemaIndex, SchemaProperty, SchemaPropertyType };