@oscarpalmer/jhunal 0.18.0 → 0.20.0

package/dist/constants.d.mts

@@ -2,6 +2,11 @@ import { ReportingType } from "./models/validation.model.mjs";
 import { Values } from "./models/misc.model.mjs";
 
 //#region src/constants.d.ts
+declare const COMMA = ", ";
+declare const CONJUNCTION_OR = " or ";
+declare const CONJUNCTION_OR_COMMA = ", or ";
+declare const CONJUNCTION_AND = " and ";
+declare const CONJUNCTION_AND_COMMA = ", and ";
 declare const MESSAGE_CONSTRUCTOR = "Expected a constructor function";
 declare const NAME_SCHEMATIC = "Schematic";
 declare const NAME_ERROR_SCHEMATIC = "SchematicError";
@@ -15,6 +20,7 @@ declare const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required pr
 declare const VALIDATION_MESSAGE_INVALID_TYPE = "Expected <> for '<>' but received <>";
 declare const VALIDATION_MESSAGE_INVALID_VALUE = "Value does not satisfy validator for '<>' and type '<>'";
 declare const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = " at index <>";
+declare const VALIDATION_MESSAGE_UNKNOWN_KEYS = "Found keys that are not defined in the schema: <>";
 declare const REPORTING_ALL: ReportingType;
 declare const REPORTING_FIRST: ReportingType;
 declare const REPORTING_NONE: ReportingType;
@@ -37,4 +43,4 @@ declare const TYPE_UNDEFINED = "undefined";
 declare const VALIDATABLE_TYPES: Set<keyof Values>;
 declare const TYPE_ALL: Set<keyof Values>;
 //#endregion
-export { MESSAGE_CONSTRUCTOR, NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION, NAME_SCHEMATIC, PROPERTY_REQUIRED, PROPERTY_SCHEMATIC, PROPERTY_TYPE, PROPERTY_VALIDATORS, REPORTING_ALL, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE, TEMPLATE_PATTERN, TYPE_ALL, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATABLE_TYPES, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX };
+export { COMMA, CONJUNCTION_AND, CONJUNCTION_AND_COMMA, CONJUNCTION_OR, CONJUNCTION_OR_COMMA, MESSAGE_CONSTRUCTOR, NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION, NAME_SCHEMATIC, PROPERTY_REQUIRED, PROPERTY_SCHEMATIC, PROPERTY_TYPE, PROPERTY_VALIDATORS, REPORTING_ALL, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE, TEMPLATE_PATTERN, TYPE_ALL, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATABLE_TYPES, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX, VALIDATION_MESSAGE_UNKNOWN_KEYS };

package/dist/constants.mjs

@@ -1,4 +1,9 @@
 //#region src/constants.ts
+const COMMA = ", ";
+const CONJUNCTION_OR = " or ";
+const CONJUNCTION_OR_COMMA = ", or ";
+const CONJUNCTION_AND = " and ";
+const CONJUNCTION_AND_COMMA = ", and ";
 const MESSAGE_CONSTRUCTOR = "Expected a constructor function";
 const NAME_SCHEMATIC = "Schematic";
 const NAME_ERROR_SCHEMATIC = "SchematicError";
@@ -12,6 +17,7 @@ const VALIDATION_MESSAGE_INVALID_REQUIRED = "Expected <> for required property '
 const VALIDATION_MESSAGE_INVALID_TYPE = "Expected <> for '<>' but received <>";
 const VALIDATION_MESSAGE_INVALID_VALUE = "Value does not satisfy validator for '<>' and type '<>'";
 const VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX = " at index <>";
+const VALIDATION_MESSAGE_UNKNOWN_KEYS = "Found keys that are not defined in the schema: <>";
 const REPORTING_ALL = "all";
 const REPORTING_FIRST = "first";
 const REPORTING_NONE = "none";
@@ -53,4 +59,4 @@ const TYPE_ALL = new Set([
 	TYPE_UNDEFINED
 ]);
 //#endregion
-export { MESSAGE_CONSTRUCTOR, NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION, NAME_SCHEMATIC, PROPERTY_REQUIRED, PROPERTY_SCHEMATIC, PROPERTY_TYPE, PROPERTY_VALIDATORS, REPORTING_ALL, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE, TEMPLATE_PATTERN, TYPE_ALL, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATABLE_TYPES, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX };
+export { COMMA, CONJUNCTION_AND, CONJUNCTION_AND_COMMA, CONJUNCTION_OR, CONJUNCTION_OR_COMMA, MESSAGE_CONSTRUCTOR, NAME_ERROR_SCHEMATIC, NAME_ERROR_VALIDATION, NAME_SCHEMATIC, PROPERTY_REQUIRED, PROPERTY_SCHEMATIC, PROPERTY_TYPE, PROPERTY_VALIDATORS, REPORTING_ALL, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, SCHEMATIC_MESSAGE_SCHEMA_INVALID_EMPTY, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_DISALLOWED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_NULLABLE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_REQUIRED, SCHEMATIC_MESSAGE_SCHEMA_INVALID_PROPERTY_TYPE, SCHEMATIC_MESSAGE_SCHEMA_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_KEY, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_TYPE, SCHEMATIC_MESSAGE_VALIDATOR_INVALID_VALUE, TEMPLATE_PATTERN, TYPE_ALL, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATABLE_TYPES, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX, VALIDATION_MESSAGE_UNKNOWN_KEYS };

package/dist/helpers.d.mts

@@ -8,7 +8,12 @@ declare function getInvalidInputMessage(actual: unknown): string;
 declare function getInvalidMissingMessage(property: ValidatedProperty): string;
 declare function getInvalidTypeMessage(property: ValidatedProperty, actual: unknown): string;
 declare function getInvalidValidatorMessage(property: ValidatedProperty, type: ValueName, index: number, length: number): string;
+declare function getOptions(input: unknown): {
+  reporting: ReportingInformation;
+  strict: boolean;
+};
 declare function getReporting(value: unknown): ReportingInformation;
+declare function getUnknownKeysMessage(keys: string[]): string;
 /**
  * Creates a validator function for a given constructor
  * @param constructor - Constructor to check against
@@ -23,4 +28,4 @@ declare function instanceOf<Instance>(constructor: Constructor<Instance>): (valu
  */
 declare function isSchematic(value: unknown): value is Schematic<never>;
 //#endregion
-export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getReporting, instanceOf, isSchematic };
+export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getOptions, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };

package/dist/helpers.mjs

@@ -1,4 +1,4 @@
-import { MESSAGE_CONSTRUCTOR, NAME_SCHEMATIC, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX } from "./constants.mjs";
+import { CONJUNCTION_AND, CONJUNCTION_AND_COMMA, CONJUNCTION_OR, CONJUNCTION_OR_COMMA, MESSAGE_CONSTRUCTOR, NAME_SCHEMATIC, REPORTING_FIRST, REPORTING_NONE, REPORTING_THROW, REPORTING_TYPES, TYPE_ARRAY, TYPE_NULL, TYPE_OBJECT, TYPE_UNDEFINED, VALIDATION_MESSAGE_INVALID_INPUT, VALIDATION_MESSAGE_INVALID_REQUIRED, VALIDATION_MESSAGE_INVALID_TYPE, VALIDATION_MESSAGE_INVALID_VALUE, VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX, VALIDATION_MESSAGE_UNKNOWN_KEYS } from "./constants.mjs";
 import { isConstructor, isPlainObject } from "@oscarpalmer/atoms/is";
 //#region src/helpers.ts
 function getInvalidInputMessage(actual) {
@@ -21,6 +21,21 @@ function getInvalidValidatorMessage(property, type, index, length) {
 	if (length > 1) message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace("<>", String(index));
 	return message;
 }
+function getOptions(input) {
+	if (typeof input === "boolean") return {
+		reporting: getReporting(REPORTING_NONE),
+		strict: input
+	};
+	if (REPORTING_TYPES.has(input)) return {
+		reporting: getReporting(input),
+		strict: false
+	};
+	const options = isPlainObject(input) ? input : {};
+	return {
+		reporting: getReporting(options.errors),
+		strict: typeof options.strict === "boolean" ? options.strict : false
+	};
+}
 function getPropertyType(original) {
 	if (typeof original === "function") return "a validated value";
 	if (Array.isArray(original)) return `'${TYPE_OBJECT}'`;
@@ -30,12 +45,16 @@ function getPropertyType(original) {
 function getReporting(value) {
 	const type = REPORTING_TYPES.has(value) ? value : REPORTING_NONE;
 	return {
+		type,
 		["all"]: type === "all",
 		[REPORTING_FIRST]: type === REPORTING_FIRST,
 		[REPORTING_NONE]: type === REPORTING_NONE,
 		[REPORTING_THROW]: type === REPORTING_THROW
 	};
 }
+function getUnknownKeysMessage(keys) {
+	return VALIDATION_MESSAGE_UNKNOWN_KEYS.replace("<>", renderKeys(keys));
+}
 function getValueType(value) {
 	const valueType = typeof value;
 	switch (true) {
@@ -68,6 +87,20 @@ function instanceOf(constructor) {
 function isSchematic(value) {
 	return typeof value === "object" && value !== null && "$schematic" in value && value["$schematic"] === true;
 }
+function renderKeys(keys) {
+	return renderParts(keys.map((key) => `'${key}'`), CONJUNCTION_AND, CONJUNCTION_AND_COMMA);
+}
+function renderParts(parts, delimiterShort, delimiterLong) {
+	const { length } = parts;
+	if (length === 1) return parts[0];
+	let rendered = "";
+	for (let index = 0; index < length; index += 1) {
+		rendered += parts[index];
+		if (index < length - 2) rendered += ", ";
+		else if (index === length - 2) rendered += parts.length > 2 ? delimiterLong : delimiterShort;
+	}
+	return rendered;
+}
 function renderTypes(types) {
 	const unique = /* @__PURE__ */ new Set();
 	const parts = [];
@@ -77,14 +110,7 @@ function renderTypes(types) {
 		unique.add(rendered);
 		parts.push(rendered);
 	}
-	const { length } = parts;
-	let rendered = "";
-	for (let index = 0; index < length; index += 1) {
-		rendered += parts[index];
-		if (index < length - 2) rendered += ", ";
-		else if (index === length - 2) rendered += parts.length > 2 ? ", or " : " or ";
-	}
-	return rendered;
+	return renderParts(parts, CONJUNCTION_OR, CONJUNCTION_OR_COMMA);
 }
 //#endregion
-export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getReporting, instanceOf, isSchematic };
+export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getOptions, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };

package/dist/index.d.mts

@@ -1,10 +1,11 @@
 import { Constructor, GenericCallback, PlainObject, Simplify } from "@oscarpalmer/atoms/models";
+import { Result } from "@oscarpalmer/atoms/result/models";
 
 //#region src/models/infer.model.d.ts
 /**
  * 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
@@ -26,37 +27,37 @@ type Infer<Model extends Schema> = Simplify<{ [Key in InferRequiredKeys<Model>]:
  */
 type InferOptionalKeys<Model extends Schema> = keyof { [Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? Key : never]: never };
 /**
- * Infers the TypeScript type of a {@link SchemaProperty}'s `$type` field, unwrapping arrays to infer their item type
+ * 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)_
  */
 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
  */
 type InferPropertyValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schematic<infer Model> ? Model : Value extends ValueName ? Values[Value & ValueName] : Value extends Schema ? Infer<Value> : never;
 /**
  * Extracts keys from a {@link Schema} whose entries are required _(i.e., `$required` is not `false`)_
  *
- * @template Model - Schema to extract required keys from
+ * @template Model Schema to extract required keys from
  */
 type InferRequiredKeys<Model extends Schema> = keyof { [Key in keyof Model as IsOptionalProperty<Model[Key]> extends true ? never : Key]: never };
 /**
- * Infers the type for a top-level {@link Schema} entry, unwrapping arrays to infer their item type
+ * 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)_
  */
 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
  */
 type InferSchemaEntryValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schematic<infer Model> ? Model : Value extends SchemaProperty ? InferPropertyType<Value['$type']> : Value extends PlainSchema ? Infer<Value & Schema> : Value extends ValueName ? Values[Value & ValueName] : Value extends Schema ? Infer<Value> : never;
 //#endregion
@@ -64,37 +65,33 @@ type InferSchemaEntryValue<Value> = Value extends Constructor<infer Instance> ?
 /**
  * Maps each element of a tuple through {@link ToValueType}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 type MapToValueTypes<Value extends unknown[]> = Value extends [infer Head, ...infer Tail] ? [ToValueType<Head>, ...MapToValueTypes<Tail>] : [];
 /**
  * Maps each element of a tuple through {@link ToSchemaPropertyTypeEach}
  *
- * @template Value - Tuple of types to map
+ * @template Value Tuple of types to map
  */
 type MapToSchemaPropertyTypes<Value extends unknown[]> = Value extends [infer Head, ...infer Tail] ? [ToSchemaPropertyTypeEach<Head>, ...MapToSchemaPropertyTypes<Tail>] : [];
 /**
- * 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
  */
 type ToSchemaPropertyType<Value> = UnwrapSingle<DeduplicateTuple<MapToSchemaPropertyTypes<UnionToTuple<Value>>>>;
 /**
  * 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
  */
 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
  */
 type ToSchemaType<Value> = UnwrapSingle<DeduplicateTuple<MapToValueTypes<UnionToTuple<Value>>>>;
 /**
@@ -102,7 +99,7 @@ type ToSchemaType<Value> = UnwrapSingle<DeduplicateTuple<MapToValueTypes<UnionTo
  *
  * 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
@@ -117,7 +114,7 @@ type ToValueType<Value> = Value extends Schematic<any> ? Value : { [Key in keyof
 /**
  * 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
@@ -127,23 +124,14 @@ type ToValueType<Value> = Value extends Schematic<any> ? Value : { [Key in keyof
  * ```
  */
 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
@@ -153,17 +141,8 @@ type TypedPropertyOptional<Value> = {
  * ```
  */
 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>>;
 };
 /**
@@ -171,7 +150,7 @@ 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
@@ -188,7 +167,7 @@ type TypedSchema<Model extends PlainObject> = Simplify<{ [Key in RequiredKeys<Mo
 /**
  * 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;
@@ -196,7 +175,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;
@@ -204,7 +183,16 @@ type TypedSchemaRequired<Model extends PlainObject> = {
 //#endregion
 //#region src/models/validation.model.d.ts
 /**
- * A custom error class for schematic validation failures
+ * 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
+ */
+type ReportingType = 'all' | 'first' | 'none' | 'throw';
+/**
+ * Thrown when a schema definition is invalid
  */
 declare class SchematicError extends Error {
   constructor(message: string);
@@ -241,16 +229,12 @@ type ValidatedProperty = {
   validators: ValidatedPropertyValidators;
 };
 /**
- * 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'`
  */
 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;
 };
 /**
@@ -265,16 +249,39 @@ type ValidatedPropertyType = GenericCallback | ValidatedProperty[] | Schematic<u
  * Each key holds an array of validator functions that receive an `unknown` value and return a `boolean`
  */
 type ValidatedPropertyValidators = { [Key in ValueName]?: Array<(value: unknown) => boolean> };
+/**
+ * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
+ */
 declare class ValidationError extends Error {
   readonly information: ValidationInformation[];
   constructor(information: ValidationInformation[]);
 }
+/**
+ * Describes a single validation failure
+ */
 type ValidationInformation = {
-  key: ValidationInformationKey;
-  message: string;
-  validator?: GenericCallback;
+  /** 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
+ */
 type ValidationInformationKey = ValidatedPropertyKey;
+/**
+ * Options for validation
+ */
+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;
+};
 //#endregion
 //#region src/schematic.d.ts
 /**
@@ -289,18 +296,64 @@ declare class Schematic<Model> {
    *
    * 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;
 }
 /**
  * Create a schematic from a schema
@@ -321,7 +374,7 @@ declare function schematic<Model extends PlainObject>(schema: TypedSchema<Model>
 //#endregion
 //#region src/models/schema.plain.model.d.ts
 /**
- * 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
  */
 type PlainSchema = {
   [key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
@@ -346,11 +399,11 @@ 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
  */
 type SchemaEntry = Constructor | PlainSchema | SchemaProperty | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
 /**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link NestedSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
+ * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link PlainSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
  */
 interface SchemaIndex {
   [key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
@@ -395,7 +448,7 @@ type SchemaPropertyType = Constructor | PlainSchema | Schematic<unknown> | Value
  *
  * 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
@@ -410,8 +463,8 @@ type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value:
 /**
  * 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
@@ -423,7 +476,7 @@ type DeduplicateTuple<Value extends unknown[], Seen extends unknown[] = []> = Va
 /**
  * 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
@@ -435,27 +488,27 @@ type ExtractValueNames<Value> = Value extends ValueName ? Value : Value extends
 /**
  * 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
  */
 type IsOptionalProperty<Value> = Value extends SchemaProperty ? Value['$required'] extends false ? true : false : false;
 /**
- * Extracts the last member from a union type by leveraging intersection of function return types
+ * Extracts the last member from a union type by leveraging contravariance of function parameter types
  *
- * @template Value - Union type
+ * @template Value Union type
  */
 type LastOfUnion<Value> = UnionToIntersection<Value extends unknown ? () => Value : never> extends (() => infer Item) ? Item : never;
 /**
  * Extracts keys from an object type that are optional
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 type OptionalKeys<Value> = { [Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never }[keyof Value];
 /**
  * Extracts keys from an object type that are required _(i.e., not optional)_
  *
- * @template Value - Object type to inspect
+ * @template Value Object type to inspect
  */
 type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
 /**
@@ -463,8 +516,8 @@ 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
@@ -478,9 +531,9 @@ type TuplePermutations<Tuple extends unknown[], Elput extends unknown[] = []> =
  *
  * 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)_
  */
 type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends unknown[] = []> = Items extends [infer Head, ...infer Tail] ? `${Prefix['length']}` extends Item ? [...Prefix, ...Tail] : TupleRemoveAt<Tail, Item, [...Prefix, Head]> : Prefix;
 /**
@@ -488,7 +541,7 @@ type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends
  *
  * 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
@@ -502,8 +555,8 @@ type UnionToIntersection<Value> = (Value extends unknown ? (value: Value) => voi
  *
  * 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
@@ -517,7 +570,7 @@ type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never]
  *
  * 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
@@ -527,20 +580,11 @@ type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never]
  */
 type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only : Value['length'] extends 1 | 2 | 3 | 4 | 5 ? TuplePermutations<Value> : Value;
 /**
- * Basic value types
+ * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
  */
 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
  */
 type Values = {
   array: unknown[];