@oscarpalmer/jhunal 0.19.0 → 0.21.0

package/package.json

@@ -1,54 +1,54 @@
 {
-  "name": "@oscarpalmer/jhunal",
-  "version": "0.19.0",
-  "description": "Flies free beneath the glistening moons…",
-  "keywords": [
-    "schema",
-    "validation"
-  ],
-  "license": "MIT",
-  "author": {
-    "name": "Oscar Palmér",
-    "url": "https://oscarpalmer.se"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/oscarpalmer/jhunal.git"
-  },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "type": "module",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
-    }
-  },
-  "scripts": {
-    "build": "npx vp pack && npm run tsdown:build",
-    "tsdown:build": "npx tsdown -c ./tsdown.config.ts",
-    "tsdown:watch": "npx tsdown -c ./tsdown.config.ts --watch",
-    "test": "npx vp test run --coverage",
-    "test:leak": "npx vp test run --detect-async-leaks --coverage",
-    "watch": "npx vite build --watch"
-  },
-  "dependencies": {
-    "@oscarpalmer/atoms": "^0.169"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5",
-    "@vitest/coverage-istanbul": "^4.1",
-    "jsdom": "^29.0",
-    "tsdown": "^0.21",
-    "typescript": "^5.9",
-    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-    "vite-plus": "latest",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
-  },
-  "packageManager": "npm@11.11.1"
+	"name": "@oscarpalmer/jhunal",
+	"version": "0.21.0",
+	"description": "Flies free beneath the glistening moons…",
+	"keywords": [
+		"schema",
+		"validation"
+	],
+	"license": "MIT",
+	"author": {
+		"name": "Oscar Palmér",
+		"url": "https://oscarpalmer.se"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/oscarpalmer/jhunal.git"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"type": "module",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./dist/index.d.mts",
+			"default": "./dist/index.mjs"
+		}
+	},
+	"scripts": {
+		"build": "npx vp pack && npm run tsdown:build",
+		"tsdown:build": "npx tsdown -c ./tsdown.config.ts",
+		"tsdown:watch": "npx tsdown -c ./tsdown.config.ts --watch",
+		"test": "npx vp test run --coverage",
+		"test:leak": "npx vp test run --detect-async-leaks --coverage",
+		"watch": "npx vite build --watch"
+	},
+	"dependencies": {
+		"@oscarpalmer/atoms": "^0.170"
+	},
+	"devDependencies": {
+		"@types/node": "^25.5",
+		"@vitest/coverage-istanbul": "^4.1",
+		"jsdom": "^29.0",
+		"tsdown": "^0.21",
+		"typescript": "^5.9",
+		"vite": "npm:@voidzero-dev/vite-plus-core@latest",
+		"vite-plus": "latest",
+		"vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+	},
+	"packageManager": "npm@11.11.1"
 }

package/src/constants.ts

@@ -1,6 +1,20 @@
 import type {ValueName} from './models/misc.model';
 import type {ReportingType} from './models/validation.model';
 
+// #region Grammar
+
+export const COMMA = ', ';
+
+export const CONJUNCTION_OR = ' or ';
+
+export const CONJUNCTION_OR_COMMA = ', or ';
+
+export const CONJUNCTION_AND = ' and ';
+
+export const CONJUNCTION_AND_COMMA = ', and ';
+
+// #endregion
+
 // #region Misc.
 
 export const MESSAGE_CONSTRUCTOR = 'Expected a constructor function';
@@ -42,6 +56,8 @@ export const VALIDATION_MESSAGE_INVALID_VALUE =
 
 export const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = ' at index <>';
 
+export const VALIDATION_MESSAGE_UNKNOWN_KEYS = 'Found keys that are not defined in the schema: <>';
+
 // #endregion
 
 // #region Reporting

package/src/helpers.ts

@@ -1,6 +1,11 @@
 import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
 import type {Constructor} from '@oscarpalmer/atoms/models';
 import {
+	COMMA,
+	CONJUNCTION_AND,
+	CONJUNCTION_AND_COMMA,
+	CONJUNCTION_OR,
+	CONJUNCTION_OR_COMMA,
 	MESSAGE_CONSTRUCTOR,
 	NAME_SCHEMATIC,
 	PROPERTY_SCHEMATIC,
@@ -19,6 +24,7 @@ import {
 	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 {
@@ -26,6 +32,7 @@ import type {
 	ReportingType,
 	ValidatedProperty,
 	ValidatedPropertyType,
+	ValidationParameters,
 } from './models/validation.model';
 import type {Schematic} from './schematic';
 
@@ -33,36 +40,34 @@ 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),
-	);
+export function getInvalidMissingMessage(key: string, types: ValidatedPropertyType[]): string {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace(TEMPLATE_PATTERN, renderTypes(types));
 
-	message = message.replace(TEMPLATE_PATTERN, property.key.full);
+	message = message.replace(TEMPLATE_PATTERN, key);
 
 	return message;
 }
 
-export function getInvalidTypeMessage(property: ValidatedProperty, actual: unknown): string {
-	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace(
-		TEMPLATE_PATTERN,
-		renderTypes(property.types),
-	);
+export function getInvalidTypeMessage(
+	key: string,
+	types: ValidatedPropertyType[],
+	actual: unknown,
+): string {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace(TEMPLATE_PATTERN, renderTypes(types));
 
-	message = message.replace(TEMPLATE_PATTERN, property.key.full);
+	message = message.replace(TEMPLATE_PATTERN, key);
 	message = message.replace(TEMPLATE_PATTERN, getValueType(actual));
 
 	return message;
 }
 
 export function getInvalidValidatorMessage(
-	property: ValidatedProperty,
+	key: string,
 	type: ValueName,
 	index: number,
 	length: number,
 ): string {
-	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace(TEMPLATE_PATTERN, property.key.full);
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace(TEMPLATE_PATTERN, key);
 
 	message = message.replace(TEMPLATE_PATTERN, type);
 
@@ -73,6 +78,32 @@ export function getInvalidValidatorMessage(
 	return message;
 }
 
+export function getParameters(input?: unknown): ValidationParameters {
+	if (typeof input === 'boolean') {
+		return {
+			output: {},
+			reporting: getReporting(REPORTING_NONE),
+			strict: input,
+		};
+	}
+
+	if (REPORTING_TYPES.has(input as ReportingType)) {
+		return {
+			output: {},
+			reporting: getReporting(input as ReportingType),
+			strict: false,
+		};
+	}
+
+	const options = isPlainObject(input) ? input : {};
+
+	return {
+		output: {},
+		reporting: getReporting(options.errors),
+		strict: typeof options.strict === 'boolean' ? options.strict : false,
+	};
+}
+
 function getPropertyType(original: ValidatedPropertyType): string {
 	if (typeof original === 'function') {
 		return 'a validated value';
@@ -95,6 +126,7 @@ export function getReporting(value: unknown): ReportingInformation {
 		: REPORTING_NONE;
 
 	return {
+		type,
 		[REPORTING_ALL]: type === REPORTING_ALL,
 		[REPORTING_FIRST]: type === REPORTING_FIRST,
 		[REPORTING_NONE]: type === REPORTING_NONE,
@@ -102,6 +134,10 @@ export function getReporting(value: unknown): ReportingInformation {
 	} as ReportingInformation;
 }
 
+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;
 
@@ -161,34 +197,50 @@ export function isSchematic(value: unknown): value is Schematic<never> {
 	);
 }
 
-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]);
+function renderKeys(keys: string[]): string {
+	return renderParts(
+		keys.map(key => `'${key}'`),
+		CONJUNCTION_AND,
+		CONJUNCTION_AND_COMMA,
+	);
+}
 
-		if (unique.has(rendered)) {
-			continue;
-		}
+function renderParts(parts: string[], delimiterShort: string, delimiterLong: string): string {
+	const {length} = parts;
 
-		unique.add(rendered);
-		parts.push(rendered);
+	if (length === 1) {
+		return parts[0];
 	}
 
-	const {length} = parts;
-
 	let rendered = '';
 
 	for (let index = 0; index < length; index += 1) {
 		rendered += parts[index];
 
 		if (index < length - 2) {
-			rendered += ', ';
+			rendered += COMMA;
 		} else if (index === length - 2) {
-			rendered += parts.length > 2 ? ', or ' : ' or ';
+			rendered += parts.length > 2 ? delimiterLong : delimiterShort;
 		}
 	}
 
 	return rendered;
 }
+
+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);
+	}
+
+	return renderParts(parts, CONJUNCTION_OR, CONJUNCTION_OR_COMMA);
+}

package/src/models/infer.model.ts

@@ -6,7 +6,7 @@ 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
+ * @template Model Schema to infer types from
  *
  * @example
  * ```ts
@@ -38,20 +38,20 @@ export type InferOptionalKeys<Model extends Schema> = keyof {
 };
 
 /**
- * Infers the TypeScript type of a {@link SchemaProperty}'s `$type` field, unwrapping arrays to infer their item type
+ * Infers the TypeScript type from a {@link SchemaProperty}'s `$type` field
  *
- * @template Value - `$type` value _(single or array)_
+ * @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
+ * 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
+ * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link ValueName} strings, and nested {@link PlainSchema} objects
  *
- * @template Value - single type definition
+ * @template Value single type definition
  */
 export type InferPropertyValue<Value> =
 	Value extends Constructor<infer Instance>
@@ -67,27 +67,27 @@ export type InferPropertyValue<Value> =
 /**
  * Extracts keys from a {@link Schema} whose entries are required _(i.e., `$required` is not `false`)_
  *
- * @template Model - Schema to extract required keys from
+ * @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
+ * Infers the TypeScript type from a top-level {@link Schema} entry
  *
- * @template Value - Schema entry value _(single or array)_
+ * @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
+ * Maps a single top-level 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
+ * Resolves, in order: {@link Constructor} instances, {@link Schematic} models, {@link SchemaProperty} objects, {@link PlainSchema} objects, and {@link ValueName} strings
  *
- * @template Value - single schema entry
+ * @template Value single schema entry
  */
 export type InferSchemaEntryValue<Value> =
 	Value extends Constructor<infer Instance>

package/src/models/misc.model.ts

@@ -3,8 +3,8 @@ 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)_
+ * @template Value Tuple to deduplicate
+ * @template Seen Accumulator for already-seen types _(internal)_
  *
  * @example
  * ```ts
@@ -24,7 +24,7 @@ export type DeduplicateTuple<Value extends unknown[], Seen extends unknown[] = [
 /**
  * Recursively extracts {@link ValueName} strings from a type, unwrapping arrays and readonly arrays
  *
- * @template Value - Type to extract value names from
+ * @template Value Type to extract value names from
  *
  * @example
  * ```ts
@@ -43,9 +43,9 @@ export type ExtractValueNames<Value> = Value extends ValueName
 /**
  * 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`
+ * Returns `true` if the entry is a {@link SchemaProperty} with `$required` set to `false`; otherwise returns `false`
  *
- * @template Value - Schema entry to check
+ * @template Value Schema entry to check
  */
 export type IsOptionalProperty<Value> = Value extends SchemaProperty
 	? Value['$required'] extends false
@@ -54,9 +54,9 @@ export type IsOptionalProperty<Value> = Value extends SchemaProperty
 	: false;
 
 /**
- * Extracts the last member from a union type by leveraging intersection of function return types
+ * Extracts the last member from a union type by leveraging contravariance of function parameter types
  *
- * @template Value - Union type
+ * @template Value Union type
  */
 export type LastOfUnion<Value> =
 	UnionToIntersection<Value extends unknown ? () => Value : never> extends () => infer Item
@@ -66,7 +66,7 @@ export type LastOfUnion<Value> =
 /**
  * Extracts keys from an object type that are optional
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 export type OptionalKeys<Value> = {
 	[Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never;
@@ -75,7 +75,7 @@ export type OptionalKeys<Value> = {
 /**
  * Extracts keys from an object type that are required _(i.e., not optional)_
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 export type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
 
@@ -84,8 +84,8 @@ export type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
  *
  * 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)_
+ * @template Tuple Tuple to permute
+ * @template Elput Accumulator for the current permutation _(internal; name is Tuple backwards)_
  *
  * @example
  * ```ts
@@ -110,9 +110,9 @@ export type TuplePermutations<
  *
  * 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)_
+ * @template Items Tuple to remove from
+ * @template Item Index as a string literal
+ * @template Prefix Accumulator for elements before the target _(internal)_
  */
 export type TupleRemoveAt<
 	Items extends unknown[],
@@ -129,7 +129,7 @@ export type TupleRemoveAt<
  *
  * Uses the contravariance of function parameter types to collapse a union into an intersection
  *
- * @template Value - Union type to convert
+ * @template Value Union type to convert
  *
  * @example
  * ```ts
@@ -148,8 +148,8 @@ export type UnionToIntersection<Value> = (
  *
  * 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)_
+ * @template Value Union type to convert
+ * @template Items Accumulator for the resulting tuple _(internal)_
  *
  * @example
  * ```ts
@@ -166,7 +166,7 @@ export type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends
  *
  * 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
+ * @template Value Tuple to potentially unwrap
  *
  * @example
  * ```ts
@@ -181,21 +181,12 @@ export type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only]
 		: Value;
 
 /**
- * Basic value types
+ * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
  */
 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
- * ```
+ * Maps {@link ValueName} strings to their TypeScript equivalents
  */
 export type Values = {
 	array: unknown[];

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

@@ -3,7 +3,7 @@ import type {Schematic} from '../schematic';
 import type {ExtractValueNames, ValueName, Values} from './misc.model';
 
 /**
- * A generic schema allowing {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry} as values
+ * A generic schema allowing nested schemas, {@link SchemaEntry} values, or arrays of {@link SchemaEntry} as values
  */
 export type PlainSchema = {
 	[key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
@@ -30,7 +30,7 @@ export 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
+ * Can be a {@link Constructor}, {@link PlainSchema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
  */
 export type SchemaEntry =
 	| Constructor
@@ -41,7 +41,7 @@ export type SchemaEntry =
 	| ((value: unknown) => boolean);
 
 /**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
+ * 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[];
@@ -94,7 +94,7 @@ export type SchemaPropertyType =
  *
  * 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
+ * @template Value `$type` value(s) to derive validator keys from
  *
  * @example
  * ```ts

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

@@ -7,7 +7,7 @@ import type {ToSchemaPropertyType, ToSchemaType} from './transform.model';
 /**
  * A typed optional property definition generated by {@link TypedSchema} for optional keys, with `$required` set to `false` and excludes `undefined` from the type
  *
- * @template Value - Property's type _(including `undefined`)_
+ * @template Value Property's type _(including `undefined`)_
  *
  * @example
  * ```ts
@@ -17,24 +17,15 @@ import type {ToSchemaPropertyType, ToSchemaType} from './transform.model';
  * ```
  */
 export type TypedPropertyOptional<Value> = {
-	/**
-	 * The property is not required
-	 */
 	$required: false;
-	/**
-	 * The type(s) of the property
-	 */
 	$type: ToSchemaPropertyType<Exclude<Value, undefined>>;
-	/**
-	 * Custom validators for the property and its types
-	 */
 	$validators?: PropertyValidators<ToSchemaPropertyType<Exclude<Value, undefined>>>;
 };
 
 /**
  * A typed required property definition generated by {@link TypedSchema} for required keys, with `$required` defaulting to `true`
  *
- * @template Value - Property's type
+ * @template Value Property's type
  *
  * @example
  * ```ts
@@ -44,17 +35,8 @@ export type TypedPropertyOptional<Value> = {
  * ```
  */
 export type TypedPropertyRequired<Value> = {
-	/**
-	 * The property is required _(defaults to `true`)_
-	 */
 	$required?: true;
-	/**
-	 * The type(s) of the property
-	 */
 	$type: ToSchemaPropertyType<Value>;
-	/**
-	 * Custom validators for the property and its types
-	 */
 	$validators?: PropertyValidators<ToSchemaPropertyType<Value>>;
 };
 
@@ -63,7 +45,7 @@ export type TypedPropertyRequired<Value> = {
  *
  * Required keys map to {@link ToSchemaType} or {@link TypedPropertyRequired}; plain object values may also use {@link Schematic}. Optional keys map to {@link TypedPropertyOptional} or, for plain objects, {@link TypedSchemaOptional}
  *
- * @template Model - Object type to generate a schema for
+ * @template Model Object type to generate a schema for
  *
  * @example
  * ```ts
@@ -93,7 +75,7 @@ export type TypedSchema<Model extends PlainObject> = Simplify<
 /**
  * A {@link TypedSchema} variant for optional nested objects, with `$required` fixed to `false`
  *
- * @template Model - Nested object type
+ * @template Model Nested object type
  */
 type TypedSchemaOptional<Model extends PlainObject> = {
 	$required: false;
@@ -102,7 +84,7 @@ type TypedSchemaOptional<Model extends PlainObject> = {
 /**
  * A {@link TypedSchema} variant for required nested objects, with `$required` defaulting to `true`
  *
- * @template Model - Nested object type
+ * @template Model Nested object type
  */
 type TypedSchemaRequired<Model extends PlainObject> = {
 	$required?: true;