@oscarpalmer/jhunal 0.18.0 → 0.20.0

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;

package/src/models/transform.model.ts

@@ -6,7 +6,7 @@ import type {TypedSchema} from './schema.typed.model';
 /**
  * Maps each element of a tuple through {@link ToValueType}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 export type MapToValueTypes<Value extends unknown[]> = Value extends [infer Head, ...infer Tail]
 	? [ToValueType<Head>, ...MapToValueTypes<Tail>]
@@ -15,7 +15,7 @@ export type MapToValueTypes<Value extends unknown[]> = Value extends [infer Head
 /**
  * Maps each element of a tuple through {@link ToSchemaPropertyTypeEach}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 export type MapToSchemaPropertyTypes<Value extends unknown[]> = Value extends [
 	infer Head,
@@ -25,11 +25,9 @@ export type MapToSchemaPropertyTypes<Value extends unknown[]> = Value extends [
 	: [];
 
 /**
- * Converts a type into its corresponding {@link SchemaPropertyType}-representation
+ * Converts a TypeScript type to its {@link SchemaPropertyType} representation, suitable for use in a typed schema
  *
- * Deduplicates and unwraps single-element tuples via {@link UnwrapSingle}
- *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 export type ToSchemaPropertyType<Value> = UnwrapSingle<
 	DeduplicateTuple<MapToSchemaPropertyTypes<UnionToTuple<Value>>>
@@ -38,20 +36,18 @@ export type ToSchemaPropertyType<Value> = UnwrapSingle<
 /**
  * Converts a single type to its schema property equivalent
  *
- * {@link NestedSchema} values have `$required` stripped, plain objects become {@link TypedSchema}, and primitives go through {@link ToValueType}
+ * Plain objects become {@link TypedSchema}; primitives go through {@link ToValueType}
  *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 export type ToSchemaPropertyTypeEach<Value> = Value extends PlainObject
 	? TypedSchema<Value>
 	: ToValueType<Value>;
 
 /**
- * Converts a type into its corresponding {@link ValueName}-representation
- *
- * Deduplicates and unwraps single-element tuples via {@link UnwrapSingle}
+ * Converts a TypeScript type to its {@link ValueName} representation, suitable for use as a top-level schema entry
  *
- * @template Value - type to convert
+ * @template Value Type to convert
  */
 export type ToSchemaType<Value> = UnwrapSingle<
 	DeduplicateTuple<MapToValueTypes<UnionToTuple<Value>>>
@@ -62,7 +58,7 @@ export type ToSchemaType<Value> = UnwrapSingle<
  *
  * Resolves {@link Schematic} types as-is, then performs a reverse-lookup against {@link Values} _(excluding `'object'`)_ to find a matching key. If no match is found, `object` types resolve to `'object'` or a type-guard function, and all other unrecognised types resolve to a type-guard function
  *
- * @template Value - type to map
+ * @template Value Type to map
  *
  * @example
  * ```ts

package/src/models/validation.model.ts

@@ -6,8 +6,21 @@ import type {ValueName} from './misc.model';
 
 // #region Reporting
 
-export type ReportingInformation = Record<ReportingType, boolean>;
+/**
+ * Maps each {@link ReportingType} to a boolean flag
+ */
+export type ReportingInformation = Record<ReportingType, boolean> & {
+	type: ReportingType;
+};
 
+/**
+ * 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
+ */
 export type ReportingType = 'all' | 'first' | 'none' | 'throw';
 
 // #endregion
@@ -15,7 +28,7 @@ export type ReportingType = 'all' | 'first' | 'none' | 'throw';
 // #region Schematic validation
 
 /**
- * A custom error class for schematic validation failures
+ * Thrown when a schema definition is invalid
  */
 export class SchematicError extends Error {
 	constructor(message: string) {
@@ -62,16 +75,12 @@ export type ValidatedProperty = {
 };
 
 /**
- * Property name in schema
+ * 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 property key, including parent keys for nested properties _(e.g., `address.street`)_
-	 */
 	full: string;
-	/**
-	 * The last segment of the property key _(e.g., `street` for `address.street`)_
-	 */
 	short: string;
 };
 
@@ -99,6 +108,9 @@ export type ValidatedPropertyValidators = {
 
 // #region Property validation
 
+/**
+ * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
+ */
 export class ValidationError extends Error {
 	constructor(readonly information: ValidationInformation[]) {
 		super(
@@ -112,12 +124,42 @@ export class ValidationError extends Error {
 	}
 }
 
+/**
+ * Describes a single validation failure
+ */
 export type ValidationInformation = {
+	/** The key path of the property that failed */
 	key: ValidationInformationKey;
+	/** Human-readable description of the failure */
 	message: string;
+	/** The validator function that failed, if the failure was from a `$validators` entry */
 	validator?: GenericCallback;
+	/** The value that was provided */
+	value: unknown;
 };
 
+/**
+ * Same shape as {@link ValidatedPropertyKey}; the key path of a failed property
+ */
 export type ValidationInformationKey = ValidatedPropertyKey;
 
+/**
+ * Options for validation
+ */
+export type ValidationOptions<Errors extends ReportingType> = {
+	/**
+	 * How should validation failures be reported; see {@link ReportingType} _(defaults to `'none'`)_
+	 */
+	errors?: Errors;
+	/**
+	 * Validate if unknown keys are present in the object? _(defaults to `false`)_
+	 */
+	strict?: boolean;
+};
+
+export type ValidationOptionsExtended = {
+	reporting: ReportingInformation;
+	strict: boolean;
+};
+
 // #endregion

package/src/schematic.ts

@@ -1,11 +1,18 @@
 import {isPlainObject} from '@oscarpalmer/atoms/is';
 import type {PlainObject} from '@oscarpalmer/atoms/models';
-import {SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE, PROPERTY_SCHEMATIC} from './constants';
-import {getReporting, isSchematic} from './helpers';
+import {error} 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 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} from './models/validation.model';
+import {
+	SchematicError,
+	type ValidatedProperty,
+	type ValidationInformation,
+	type ValidationOptions,
+} from './models/validation.model';
 import {getProperties} from './validation/property.validation';
 import {validateObject} from './validation/value.validation';
 
@@ -23,29 +30,90 @@ export class Schematic<Model> {
 		});
 
 		this.#properties = properties;
+
+		schematicProperties.set(this, properties);
 	}
 
 	/**
 	 * 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.
 	 * @param value Value to validate
-	 * @param errors Throws an error for the first validation failure
+	 * @param options Validation options
+	 * @returns `true` if the value matches the schema, otherwise throws an error
+	 */
+	is(value: unknown, options: ValidationOptions<'throw'>): asserts value is 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.
+	 * @param value Value to validate
+	 * @param errors Reporting type
 	 * @returns `true` if the value matches the schema, otherwise throws an error
 	 */
 	is(value: unknown, errors: 'throw'): asserts value is 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.
+	 * @param value Value to validate
+	 * @param options Validation options
+	 * @returns `true` if the value matches the schema, otherwise `false`
+	 */
+	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.
+	 * @param value Value to validate
+	 * @param errors Reporting type
+	 * @returns `true` if the value matches the schema, otherwise `false`
+	 */
+	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.
+	 * @param value Value to validate
+	 * @param options Validation options
+	 * @returns `true` if the value matches the schema, otherwise `false`
+	 */
+	is(value: unknown, options: ValidationOptions<'first'>): 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.
+	 * @param value Value to validate
+	 * @param errors Reporting type
+	 * @returns `true` if the value matches the schema, otherwise `false`
+	 */
+	is(value: unknown, errors: 'first'): Result<true, ValidationInformation>;
+
+	/**
+	 * 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.
 	 * @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`
 	 */
-	is(value: unknown): value is Model;
+	is(value: unknown, strict?: true): value is Model;
 
-	is(value: unknown, errors?: unknown): boolean {
-		return validateObject(value, this.#properties, getReporting(errors));
+	is(value: unknown, options?: unknown): unknown {
+		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]);
 	}
 }
 
@@ -78,3 +146,5 @@ export function schematic<Model extends Schema>(schema: Model): Schematic<Model>
 
 	return new Schematic<Model>(getProperties(schema));
 }
+
+export const schematicProperties = new WeakMap<Schematic<unknown>, ValidatedProperty[]>();

package/src/validation/property.validation.ts

@@ -2,6 +2,9 @@ import {isConstructor, isPlainObject} from '@oscarpalmer/atoms/is';
 import type {PlainObject} from '@oscarpalmer/atoms/models';
 import {join} from '@oscarpalmer/atoms/string';
 import {
+	PROPERTY_REQUIRED,
+	PROPERTY_TYPE,
+	PROPERTY_VALIDATORS,
 	SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY,
 	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED,
 	SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE,
@@ -10,12 +13,8 @@ import {
 	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY,
 	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE,
 	SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE,
-	PROPERTY_REQUIRED,
-	PROPERTY_TYPE,
-	PROPERTY_VALIDATORS,
 	TEMPLATE_PATTERN,
 	TYPE_ALL,
-	TYPE_OBJECT,
 	TYPE_UNDEFINED,
 	VALIDATABLE_TYPES,
 } from '../constants';