@oscarpalmer/jhunal 0.20.0 → 0.21.0

package/dist/schematic.d.mts

@@ -13,10 +13,73 @@ declare class Schematic<Model> {
   #private;
   private readonly $schematic;
   constructor(properties: ValidatedProperty[]);
+  /**
+   * 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;
   /**
    * 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
@@ -25,7 +88,7 @@ declare 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
@@ -34,25 +97,25 @@ declare 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`
@@ -61,7 +124,7 @@ declare 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`
@@ -70,7 +133,7 @@ declare 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`

package/dist/schematic.mjs

@@ -1,10 +1,10 @@
 import { PROPERTY_SCHEMATIC, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE } from "./constants.mjs";
-import { getOptions, isSchematic } from "./helpers.mjs";
+import { getParameters, isSchematic } from "./helpers.mjs";
 import { SchematicError } from "./models/validation.model.mjs";
 import { getProperties } from "./validation/property.validation.mjs";
 import { validateObject } from "./validation/value.validation.mjs";
 import { isPlainObject } from "@oscarpalmer/atoms/is";
-import { error } from "@oscarpalmer/atoms/result/misc";
+import { error, ok } from "@oscarpalmer/atoms/result/misc";
 //#region src/schematic.ts
 /**
 * A schematic for validating objects
@@ -16,14 +16,19 @@ var Schematic = class {
 		this.#properties = properties;
 		schematicProperties.set(this, properties);
 	}
+	get(value, options) {
+		const parameters = getParameters(options);
+		const result = validateObject(value, this.#properties, parameters, true);
+		if (result == null) return;
+		if (!Array.isArray(result)) return parameters.reporting.none ? result : ok(result);
+		return error(parameters.reporting.all ? result : result[0]);
+	}
 	is(value, options) {
-		const { reporting, strict } = getOptions(options);
-		const result = validateObject(value, this.#properties, {
-			reporting,
-			strict
-		});
-		if (typeof result === "boolean") return result;
-		return error(reporting.all ? result : result[0]);
+		const parameters = getParameters(options);
+		const result = validateObject(value, this.#properties, parameters, false);
+		if (result == null) return false;
+		if (!Array.isArray(result)) return parameters.reporting.none ? true : ok(true);
+		return error(parameters.reporting.all ? result : result[0]);
 	}
 };
 function schematic(schema) {

package/dist/validation/property.validation.mjs

@@ -20,9 +20,8 @@ function getProperties(original, prefix, fromType) {
 	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(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", prefixed));
+		if (value == null) throw new SchematicError(SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE.replace("<>", join([prefix, key], ".")));
 		const types = [];
 		let required = true;
 		let validators = {};
@@ -34,12 +33,9 @@ function getProperties(original, prefix, fromType) {
 		} 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")
 		});
 	}

package/dist/validation/value.validation.d.mts

@@ -1,6 +1,7 @@
-import { ValidatedProperty, ValidationInformation, ValidationOptionsExtended } from "../models/validation.model.mjs";
+import { ValidatedProperty, ValidationInformation, ValidationParameters } from "../models/validation.model.mjs";
+import { PlainObject } from "@oscarpalmer/atoms/models";
 
 //#region src/validation/value.validation.d.ts
-declare function validateObject(obj: unknown, properties: ValidatedProperty[], options: ValidationOptionsExtended, origin?: ValidatedProperty, validation?: ValidationInformation[]): boolean | ValidationInformation[];
+declare function validateObject(obj: unknown, properties: ValidatedProperty[], parameters: ValidationParameters, get: boolean): PlainObject | ValidationInformation[] | undefined;
 //#endregion
 export { validateObject };

package/dist/validation/value.validation.mjs

@@ -4,19 +4,23 @@ import { ValidationError } from "../models/validation.model.mjs";
 import { schematicProperties } from "../schematic.mjs";
 import { isPlainObject } from "@oscarpalmer/atoms/is";
 import { join } from "@oscarpalmer/atoms/string";
+import { clone } from "@oscarpalmer/atoms/value/clone";
 //#region src/validation/value.validation.ts
-function validateNamed(property, name, value, validation) {
+function validateNamed(name, value, parameters) {
 	if (!validators[name](value)) return false;
-	const propertyValidators = property.validators[name];
+	const propertyValidators = parameters.origin.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({
+			parameters.information.push({
 				value,
-				key: { ...property.key },
-				message: getInvalidValidatorMessage(property, name, index, length),
+				key: {
+					full: parameters.prefix,
+					short: parameters.origin.key
+				},
+				message: getInvalidValidatorMessage(parameters.prefix, name, index, length),
 				validator
 			});
 			return false;
@@ -24,103 +28,121 @@ function validateNamed(property, name, value, validation) {
 	}
 	return true;
 }
-function validateObject(obj, properties, options, origin, validation) {
+function validateObject(obj, properties, parameters, get) {
 	if (!isPlainObject(obj)) {
-		const key = origin == null ? {
+		const key = parameters?.origin == null ? {
 			full: "",
 			short: ""
-		} : { ...origin.key };
+		} : {
+			full: parameters.prefix,
+			short: parameters.origin.key
+		};
 		const information = {
 			key,
-			message: origin == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage({
-				...origin,
-				key
-			}, obj),
+			message: parameters?.origin == null ? getInvalidInputMessage(obj) : getInvalidTypeMessage(key.full, parameters.origin.types, obj),
 			value: obj
 		};
-		if (options.reporting.throw) throw new ValidationError([information]);
-		validation?.push(information);
-		return options.reporting.none ? false : [information];
+		if (parameters.reporting.throw) throw new ValidationError([information]);
+		parameters?.information?.push(information);
+		return parameters.reporting.none ? void 0 : [information];
 	}
-	if (options.strict) {
+	if (parameters.strict) {
 		const objKeys = Object.keys(obj);
-		const propertiesKeys = new Set(properties.map((property) => property.key.short));
+		const propertiesKeys = new Set(properties.map((property) => property.key));
 		const unknownKeys = objKeys.filter((key) => !propertiesKeys.has(key));
 		if (unknownKeys.length > 0) {
 			const information = {
-				key: origin == null ? {
+				key: parameters?.origin == null ? {
 					full: "",
 					short: ""
-				} : { ...origin.key },
-				message: getUnknownKeysMessage(unknownKeys.map((key) => join([origin?.key.full, key], "."))),
+				} : {
+					full: join([parameters.prefix, parameters.origin?.key], "."),
+					short: parameters.origin.key
+				},
+				message: getUnknownKeysMessage(unknownKeys.map((key) => join([parameters?.prefix, key], "."))),
 				value: obj
 			};
-			if (options.reporting.throw) throw new ValidationError([information]);
-			validation?.push(information);
-			return options.reporting.none ? false : [information];
+			if (parameters.reporting.throw) throw new ValidationError([information]);
+			parameters?.information?.push(information);
+			return parameters.reporting.none ? void 0 : [information];
 		}
 	}
 	const allInformation = [];
+	const output = {};
 	const propertiesLength = properties.length;
 	outer: for (let propertyIndex = 0; propertyIndex < propertiesLength; propertyIndex += 1) {
-		let property = properties[propertyIndex];
-		property = {
-			...property,
-			key: {
-				full: join([origin?.key.full, property.key.short], "."),
-				short: property.key.short
-			}
-		};
+		const property = properties[propertyIndex];
 		const { key, required, types } = property;
-		const value = obj[key.short];
+		const value = obj[key];
+		if (get && value === void 0 && !required) continue;
 		if (value === void 0 && required) {
+			const prefixedKey = join([parameters.prefix, key], ".");
 			const information = {
 				value,
-				key: { ...key },
-				message: getInvalidMissingMessage(property)
+				key: {
+					full: prefixedKey,
+					short: key
+				},
+				message: getInvalidMissingMessage(prefixedKey, property.types)
 			};
-			if (options.reporting.throw && validation == null) throw new ValidationError([information]);
-			if (validation != null) validation.push(information);
-			if (options.reporting.all) {
+			if (parameters.reporting.throw) throw new ValidationError([information]);
+			parameters?.information?.push(information);
+			if (parameters.reporting.all) {
 				allInformation.push(information);
 				continue;
 			}
-			return options.reporting.none ? false : [information];
+			return parameters.reporting.none ? void 0 : [information];
 		}
+		const prefixedKey = join([parameters.prefix, key], ".");
 		const typesLength = types.length;
 		const information = [];
 		for (let typeIndex = 0; typeIndex < typesLength; typeIndex += 1) {
 			const type = types[typeIndex];
-			if (validateValue(type, property, value, options, information)) continue outer;
+			if (validateValue(type, value, {
+				information,
+				output,
+				origin: property,
+				prefix: prefixedKey,
+				reporting: parameters.reporting,
+				strict: parameters.strict
+			}, get)) {
+				if (get) output[key] = clone(value);
+				continue outer;
+			}
 		}
 		if (information.length === 0) information.push({
 			value,
-			key: { ...key },
-			message: getInvalidTypeMessage(property, value)
+			key: {
+				full: prefixedKey,
+				short: key
+			},
+			message: getInvalidTypeMessage(prefixedKey, property.types, value)
 		});
-		if (options.reporting.throw && validation == null) throw new ValidationError(information);
-		validation?.push(...information);
-		if (options.reporting.all) {
+		if (parameters.reporting.throw) throw new ValidationError(information);
+		parameters?.information?.push(...information);
+		if (parameters.reporting.all) {
 			allInformation.push(...information);
 			continue;
 		}
-		return options.reporting.none ? false : information;
+		return parameters.reporting.none ? void 0 : information;
 	}
-	return options.reporting.none || allInformation.length === 0 ? true : allInformation;
+	if (get) if (parameters.origin == null) parameters.output = output;
+	else parameters.output[parameters.origin.key] = output;
+	return parameters.reporting.none || allInformation.length === 0 ? parameters.output : allInformation;
 }
-function validateSchematic(property, schematic, value, options, validation) {
-	const result = validateObject(value, schematicProperties.get(schematic), options, property, validation);
-	return typeof result === "boolean" ? result : result.length === 0;
+function validateSchematic(schematic, value, parameters, get) {
+	const result = validateObject(value, schematicProperties.get(schematic), parameters, get);
+	return result == null || Array.isArray(result) ? false : true;
 }
-function validateValue(type, property, value, options, validation) {
+function validateValue(type, value, parameters, get) {
 	switch (true) {
 		case typeof type === "function": return type(value);
 		case Array.isArray(type): {
-			const validated = validateObject(value, type, options, property, validation);
-			return typeof validated === "boolean" ? validated : false;
+			const result = validateObject(value, type, parameters, get);
+			return result == null || Array.isArray(result) ? false : true;
 		}
-		case isSchematic(type): return validateSchematic(property, type, value, options, validation);
-		default: return validateNamed(property, type, value, validation);
+		case isSchematic(type): return validateSchematic(type, value, parameters, get);
+		default: return validateNamed(type, value, parameters);
 	}
 }
 const validators = {

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.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/helpers.ts

@@ -32,6 +32,7 @@ import type {
 	ReportingType,
 	ValidatedProperty,
 	ValidatedPropertyType,
+	ValidationParameters,
 } from './models/validation.model';
 import type {Schematic} from './schematic';
 
@@ -39,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);
 
@@ -79,9 +78,10 @@ export function getInvalidValidatorMessage(
 	return message;
 }
 
-export function getOptions(input: unknown) {
+export function getParameters(input?: unknown): ValidationParameters {
 	if (typeof input === 'boolean') {
 		return {
+			output: {},
 			reporting: getReporting(REPORTING_NONE),
 			strict: input,
 		};
@@ -89,6 +89,7 @@ export function getOptions(input: unknown) {
 
 	if (REPORTING_TYPES.has(input as ReportingType)) {
 		return {
+			output: {},
 			reporting: getReporting(input as ReportingType),
 			strict: false,
 		};
@@ -97,6 +98,7 @@ export function getOptions(input: unknown) {
 	const options = isPlainObject(input) ? input : {};
 
 	return {
+		output: {},
 		reporting: getReporting(options.errors),
 		strict: typeof options.strict === 'boolean' ? options.strict : false,
 	};
@@ -196,7 +198,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 {