@oscarpalmer/jhunal 0.20.0 → 0.22.0

package/package.json

@@ -1,54 +1,54 @@
 {
-  "name": "@oscarpalmer/jhunal",
-  "version": "0.20.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.22.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/helpers.ts

@@ -30,8 +30,8 @@ import type {ValueName} from './models/misc.model';
 import type {
 	ReportingInformation,
 	ReportingType,
-	ValidatedProperty,
-	ValidatedPropertyType,
+	ValidatorParameters,
+	ValidatorType,
 } from './models/validation.model';
 import type {Schematic} from './schematic';
 
@@ -39,36 +39,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: ValidatorType[]): 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: ValidatorType[],
+	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);
 
@@ -79,9 +77,10 @@ export function getInvalidValidatorMessage(
 	return message;
 }
 
-export function getOptions(input: unknown) {
+export function getParameters(input?: unknown): ValidatorParameters {
 	if (typeof input === 'boolean') {
 		return {
+			output: {},
 			reporting: getReporting(REPORTING_NONE),
 			strict: input,
 		};
@@ -89,6 +88,7 @@ export function getOptions(input: unknown) {
 
 	if (REPORTING_TYPES.has(input as ReportingType)) {
 		return {
+			output: {},
 			reporting: getReporting(input as ReportingType),
 			strict: false,
 		};
@@ -97,17 +97,22 @@ export function getOptions(input: unknown) {
 	const options = isPlainObject(input) ? input : {};
 
 	return {
+		output: {},
 		reporting: getReporting(options.errors),
 		strict: typeof options.strict === 'boolean' ? options.strict : false,
 	};
 }
 
-function getPropertyType(original: ValidatedPropertyType): string {
+function getPropertyType(original: ValidatorType): string {
 	if (typeof original === 'function') {
 		return 'a validated value';
 	}
 
 	if (Array.isArray(original)) {
+		return `'array'`;
+	}
+
+	if (isPlainObject(original)) {
 		return `'${TYPE_OBJECT}'`;
 	}
 
@@ -196,7 +201,11 @@ export function isSchematic(value: unknown): value is Schematic<never> {
 }
 
 function renderKeys(keys: string[]): string {
-	return renderParts(keys.map(key => `'${key}'`), CONJUNCTION_AND, CONJUNCTION_AND_COMMA);
+	return renderParts(
+		keys.map(key => `'${key}'`),
+		CONJUNCTION_AND,
+		CONJUNCTION_AND_COMMA,
+	);
 }
 
 function renderParts(parts: string[], delimiterShort: string, delimiterLong: string): string {
@@ -221,7 +230,7 @@ function renderParts(parts: string[], delimiterShort: string, delimiterLong: str
 	return rendered;
 }
 
-function renderTypes(types: ValidatedPropertyType[]): string {
+function renderTypes(types: ValidatorType[]): string {
 	const unique = new Set<string>();
 	const parts: string[] = [];
 

package/src/index.ts

@@ -1,5 +1,10 @@
 export {instanceOf, isSchematic} from './helpers';
 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 ValidationInformation,
+	type ValidationOptions,
+} 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

@@ -1,14 +1,21 @@
-import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
 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,76 +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: ValidatedPropertyKey;
-	/**
-	 * Whether the property is required
-	 */
-	required: boolean;
-	/**
-	 * The allowed types for this property
-	 */
-	types: ValidatedPropertyType[];
-	/**
-	 * Custom validators grouped by {@link ValueName}
-	 */
-	validators: ValidatedPropertyValidators;
-};
-
-/**
- * The full and short forms of a property's key path
- *
- * For a nested property `address.street`: `full` is `'address.street'`, `short` is `'street'`
- */
-export type ValidatedPropertyKey = {
-	full: string;
-	short: string;
-};
-
-/**
- * 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
  */
@@ -124,6 +61,10 @@ export class ValidationError extends Error {
 	}
 }
 
+// #endregion
+
+// #region Results
+
 /**
  * Describes a single validation failure
  */
@@ -139,9 +80,16 @@ export type ValidationInformation = {
 };
 
 /**
- * Same shape as {@link ValidatedPropertyKey}; the key path of a failed property
+ *
  */
-export type ValidationInformationKey = ValidatedPropertyKey;
+export type ValidationInformationKey = {
+	full: string;
+	short: string;
+};
+
+// #endregion
+
+// #region Options
 
 /**
  * Options for validation
@@ -157,9 +105,23 @@ export type ValidationOptions<Errors extends ReportingType> = {
 	strict?: boolean;
 };
 
-export type ValidationOptionsExtended = {
+// #endregion
+
+// #region Validator
+
+export type Validator = (
+	input: unknown,
+	parameters: ValidatorParameters,
+	get: boolean,
+) => boolean | ValidationInformation[];
+
+export type ValidatorParameters = {
+	information?: ValidationInformation[];
+	output: PlainObject;
 	reporting: ReportingInformation;
 	strict: boolean;
 };
 
+export type ValidatorType = Function | PlainObject | Schematic<unknown> | ValueName;
+
 // #endregion

package/src/schematic.ts

@@ -1,20 +1,19 @@
 import {isPlainObject} from '@oscarpalmer/atoms/is';
 import type {PlainObject} from '@oscarpalmer/atoms/models';
-import {error} from '@oscarpalmer/atoms/result/misc';
+import {error, ok} from '@oscarpalmer/atoms/result/misc';
 import type {Result} from '@oscarpalmer/atoms/result/models';
 import {PROPERTY_SCHEMATIC, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE} from './constants';
-import {getOptions, isSchematic} from './helpers';
+import {getParameters, isSchematic} from './helpers';
 import type {Infer} from './models/infer.model';
 import type {Schema} from './models/schema.plain.model';
 import type {TypedSchema} from './models/schema.typed.model';
 import {
 	SchematicError,
-	type ValidatedProperty,
 	type ValidationInformation,
 	type ValidationOptions,
+	type Validator,
 } from './models/validation.model';
-import {getProperties} from './validation/property.validation';
-import {validateObject} from './validation/value.validation';
+import {getObjectValidator} from './validation';
 
 /**
  * A schematic for validating objects
@@ -22,22 +21,108 @@ import {validateObject} from './validation/value.validation';
 export class Schematic<Model> {
 	declare private readonly $schematic: true;
 
-	#properties: ValidatedProperty[];
+	#validator: Validator;
 
-	constructor(properties: ValidatedProperty[]) {
+	constructor(validator: Validator) {
 		Object.defineProperty(this, PROPERTY_SCHEMATIC, {
 			value: true,
 		});
 
-		this.#properties = properties;
+		this.#validator = validator;
 
-		schematicProperties.set(this, properties);
+		schematicValidator.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
+	 * @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
+	 */
+	get(value: unknown, options: ValidationOptions<'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
+	 * @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
+	 */
+	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
+	 * @param value Value to parse
+	 * @param options Validation options
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, options: ValidationOptions<'all'>): Result<Model, ValidationInformation[]>;
+
+	/**
+	 * 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
+	 * @param value Value to parse
+	 * @param errors Reporting type
+	 * @returns Result holding deeply cloned value or all validation information
+	 */
+	get(value: unknown, errors: 'all'): Result<Model, ValidationInformation[]>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value 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
+	 */
+	get(value: unknown, options: ValidationOptions<'first'>): Result<Model, ValidationInformation>;
+
+	/**
+	 * Parse a value according to the schema
+	 *
+	 * Returns a deeply cloned version of the value 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
+	 */
+	get(value: unknown, errors: 'first'): Result<Model, ValidationInformation>;
+
+	/**
+	 * 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
+	 * @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
+	 */
+	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 (typeof result === 'boolean') {
+			return parameters.reporting.none
+				? result
+					? parameters.output
+					: undefined
+				: ok(parameters.output);
+		}
+
+		return error(parameters.reporting.all ? result : result[0]);
 	}
 
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
 	 * @param value Value to validate
 	 * @param options Validation options
 	 * @returns `true` if the value matches the schema, otherwise throws an error
@@ -47,7 +132,7 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+	 * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
 	 * @param value Value to validate
 	 * @param errors Reporting type
 	 * @returns `true` if the value matches the schema, otherwise throws an error
@@ -57,27 +142,27 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the object.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
 	 * @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: ValidationOptions<'all'>): Result<true, ValidationInformation[]>;
 
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the object.
+	 * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
 	 * @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: 'all'): Result<true, ValidationInformation[]>;
 
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the failing property.
+	 * 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`
@@ -87,7 +172,7 @@ export class Schematic<Model> {
 	/**
 	 * Does the value match the schema?
 	 *
-	 * Will validate that the value matches the schema and return a result of `true` or all validation information for the failing property.
+	 * 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`
@@ -97,7 +182,7 @@ export class Schematic<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` or `false`, without any validation information for validation failures
 	 * @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`
@@ -105,15 +190,15 @@ export class Schematic<Model> {
 	is(value: unknown, strict?: true): value is Model;
 
 	is(value: unknown, options?: unknown): unknown {
-		const {reporting, strict} = getOptions(options);
+		const parameters = getParameters(options);
 
-		const result = validateObject(value, this.#properties, {reporting, strict});
+		const result = this.#validator(value, parameters, false);
 
 		if (typeof result === 'boolean') {
-			return result;
+			return parameters.reporting.none ? result : ok(result);
 		}
 
-		return error(reporting.all ? result : result[0]);
+		return error(parameters.reporting.all ? result : result[0]);
 	}
 }
 
@@ -144,7 +229,7 @@ export function schematic<Model extends Schema>(schema: Model): Schematic<Model>
 		throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE);
 	}
 
-	return new Schematic<Model>(getProperties(schema));
+	return new Schematic<Model>(getObjectValidator(schema));
 }
 
-export const schematicProperties = new WeakMap<Schematic<unknown>, ValidatedProperty[]>();
+export const schematicValidator = new WeakMap<Schematic<unknown>, Validator>();