@zudojs/validation 1.1.1 → 1.2.0

package/dist/index.d.ts

@@ -13,4 +13,3 @@ export * from "./validationResult/index.js";
 export * from "./validationSchema/index.js";
 export * from "./validationTransformer/index.js";
 export * from "./validationFactory/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -13,4 +13,3 @@ export * from "./validationResult/index.js";
 export * from "./validationSchema/index.js";
 export * from "./validationTransformer/index.js";
 export * from "./validationFactory/index.js";
-//# sourceMappingURL=index.js.map

package/dist/validationComposer/index.d.ts

@@ -6,4 +6,3 @@
 export * from "./validationComposer.core.js";
 export * from "./validationComposer.combinators.js";
 export * from "./validationComposer.wrappers.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationComposer/index.js

@@ -6,4 +6,3 @@
 export * from "./validationComposer.core.js";
 export * from "./validationComposer.combinators.js";
 export * from "./validationComposer.wrappers.js";
-//# sourceMappingURL=index.js.map

package/dist/validationComposer/validationComposer.combinators.d.ts

@@ -18,4 +18,3 @@ export declare function any<T>(...validators: readonly ValidationStep<T>[]): Val
 export declare function first<T>(...validators: readonly ValidationStep<T>[]): ValidationStep<T>;
 /** Negates a validation step. */
 export declare function negate<T>(validator: ValidationStep<T>): ValidationStep<T>;
-//# sourceMappingURL=validationComposer.combinators.d.ts.map

package/dist/validationComposer/validationComposer.combinators.js

@@ -75,4 +75,3 @@ export function negate(validator) {
         return success(value);
     };
 }
-//# sourceMappingURL=validationComposer.combinators.js.map

package/dist/validationComposer/validationComposer.core.d.ts

@@ -34,4 +34,3 @@ export declare function schemaStep<T>(schema: ValidationSchema<T>): ValidationSt
 export declare function constraintStep<T>(constraint: ValidationConstraint<T>): ValidationStep<T>;
 /** Creates a validation step from multiple constraints. */
 export declare function constraintsStep<T>(constraints: readonly ValidationConstraint<T>[]): ValidationStep<T>;
-//# sourceMappingURL=validationComposer.core.d.ts.map

package/dist/validationComposer/validationComposer.core.js

@@ -51,4 +51,3 @@ export function constraintStep(constraint) {
 export function constraintsStep(constraints) {
     return (value) => checkConstraints(constraints, value);
 }
-//# sourceMappingURL=validationComposer.core.js.map

package/dist/validationComposer/validationComposer.wrappers.d.ts

@@ -35,4 +35,3 @@ export declare function mapValidated<T, U>(validator: ValidationStep<T>, mapper:
  * validated value without changing it.
  */
 export declare function tapValidated<T>(validator: ValidationStep<T>, observe: (value: T) => void): ValidationStep<T>;
-//# sourceMappingURL=validationComposer.wrappers.d.ts.map

package/dist/validationComposer/validationComposer.wrappers.js

@@ -93,4 +93,3 @@ export function tapValidated(validator, observe) {
         return success(result.data);
     };
 }
-//# sourceMappingURL=validationComposer.wrappers.js.map

package/dist/validationConstraints/collection/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationConstraints.array.js";
 export * from "./validationConstraints.collection.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationConstraints/collection/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationConstraints.array.js";
 export * from "./validationConstraints.collection.js";
-//# sourceMappingURL=index.js.map

package/dist/validationConstraints/collection/validationConstraints.array.d.ts

@@ -13,10 +13,15 @@ export declare function maxItems<T>(maximum: number): ValidationConstraint<reado
 export declare function exactItems<T>(length: number): ValidationConstraint<readonly T[]>;
 /**
  * Requires every array item to satisfy a constraint.
+ *
+ * The message says it is about the items ("Every item must satisfy: …").
+ * Reusing the item constraint's message verbatim told a caller who sent a
+ * number instead of an array that the "value must be a valid email address".
+ * The issue is reported at the array's path: a constraint yields one issue,
+ * so the failing index is not part of it.
  */
 export declare function everyItem<T>(constraint: ValidationConstraint<T>): ValidationConstraint<readonly T[]>;
 /**
  * Requires at least one array item to satisfy a constraint.
  */
 export declare function someItem<T>(constraint: ValidationConstraint<T>): ValidationConstraint<readonly T[]>;
-//# sourceMappingURL=validationConstraints.array.d.ts.map

package/dist/validationConstraints/collection/validationConstraints.array.js

@@ -65,12 +65,18 @@ export function exactItems(length) {
 }
 /**
  * Requires every array item to satisfy a constraint.
+ *
+ * The message says it is about the items ("Every item must satisfy: …").
+ * Reusing the item constraint's message verbatim told a caller who sent a
+ * number instead of an array that the "value must be a valid email address".
+ * The issue is reported at the array's path: a constraint yields one issue,
+ * so the failing index is not part of it.
  */
 export function everyItem(constraint) {
     return createConstraint((values) => !scanItems(values, constraint, false), {
         name: `every_${constraint.name}`,
         code: "item_constraint_failed",
-        message: constraint.message,
+        message: `Every item must satisfy: ${constraint.message}`,
         guard: isArrayOf,
     });
 }
@@ -85,4 +91,3 @@ export function someItem(constraint) {
         guard: isArrayOf,
     });
 }
-//# sourceMappingURL=validationConstraints.array.js.map

package/dist/validationConstraints/collection/validationConstraints.collection.d.ts

@@ -7,4 +7,3 @@ export declare function oneOf<T>(values: readonly T[]): ValidationConstraint<T>;
  * Requires a value not to belong to a provided collection.
  */
 export declare function noneOf<T>(values: readonly T[]): ValidationConstraint<T>;
-//# sourceMappingURL=validationConstraints.collection.d.ts.map

package/dist/validationConstraints/collection/validationConstraints.collection.js

@@ -19,4 +19,3 @@ export function noneOf(values) {
         message: "Value is not allowed.",
     });
 }
-//# sourceMappingURL=validationConstraints.collection.js.map

package/dist/validationConstraints/index.d.ts

@@ -8,4 +8,3 @@ export type { ValidationConstraint, ConstraintOptions, } from "./validationConst
 export * from "./scalar/index.js";
 export * from "./collection/index.js";
 export * from "./structure/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationConstraints/index.js

@@ -11,4 +11,3 @@ export * from "./scalar/index.js";
 export * from "./collection/index.js";
 // Structural guards: depth, size, and circular references
 export * from "./structure/index.js";
-//# sourceMappingURL=index.js.map

package/dist/validationConstraints/scalar/index.d.ts

@@ -6,4 +6,3 @@
 export * from "./validationConstraints.string.js";
 export * from "./validationConstraints.number.js";
 export * from "./validationConstraints.date.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationConstraints/scalar/index.js

@@ -6,4 +6,3 @@
 export * from "./validationConstraints.string.js";
 export * from "./validationConstraints.number.js";
 export * from "./validationConstraints.date.js";
-//# sourceMappingURL=index.js.map

package/dist/validationConstraints/scalar/validationConstraints.date.d.ts

@@ -10,4 +10,3 @@ export declare const futureDate: import("../validationConstraints.base.js").Vali
  * Requires a date to be in the past.
  */
 export declare const pastDate: import("../validationConstraints.base.js").ValidationConstraint<Date>;
-//# sourceMappingURL=validationConstraints.date.d.ts.map

package/dist/validationConstraints/scalar/validationConstraints.date.js

@@ -42,4 +42,3 @@ export const pastDate = createConstraint((value) => value.getTime() < Date.now()
     message: "Date must be in the past.",
     guard: isDate,
 });
-//# sourceMappingURL=validationConstraints.date.js.map

package/dist/validationConstraints/scalar/validationConstraints.number.d.ts

@@ -35,4 +35,3 @@ export declare const even: ValidationConstraint<number>;
  * Requires a number to be odd.
  */
 export declare const odd: ValidationConstraint<number>;
-//# sourceMappingURL=validationConstraints.number.d.ts.map

package/dist/validationConstraints/scalar/validationConstraints.number.js

@@ -100,4 +100,3 @@ export const odd = createConstraint((value) => Number.isInteger(value) && Math.a
     message: "Value must be an odd integer.",
     guard: isNumber,
 });
-//# sourceMappingURL=validationConstraints.number.js.map

package/dist/validationConstraints/scalar/validationConstraints.string.d.ts

@@ -65,4 +65,3 @@ export declare const letters: ValidationConstraint<string>;
  * Requires a lowercase, hyphen-separated slug.
  */
 export declare const slug: ValidationConstraint<string>;
-//# sourceMappingURL=validationConstraints.string.d.ts.map

package/dist/validationConstraints/scalar/validationConstraints.string.js

@@ -1,10 +1,6 @@
 import { ValidationLength, ValidationPattern } from "@zudojs/constants";
-import { formatCount } from "@zudojs/types";
+import { characterLength, formatCount } from "@zudojs/types";
 import { createConstraint, assertNonNegativeInteger, } from "../validationConstraints.base.js";
-/** Counts Unicode code points rather than UTF-16 code units. */
-function characterLength(value) {
-    return [...value].length;
-}
 /**
  * Requires a string to be non-empty after trimming.
  */
@@ -160,4 +156,3 @@ export const slug = createConstraint((value) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.te
     message: "Value must be a slug: lowercase letters and digits, separated by single hyphens.",
     guard: (value) => typeof value === "string",
 });
-//# sourceMappingURL=validationConstraints.string.js.map

package/dist/validationConstraints/structure/index.d.ts

@@ -7,4 +7,3 @@ export * from "./validationConstraints.traverse.js";
 export * from "./validationConstraints.depth.js";
 export * from "./validationConstraints.size.js";
 export * from "./validationConstraints.circular.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationConstraints/structure/index.js

@@ -7,4 +7,3 @@ export * from "./validationConstraints.traverse.js";
 export * from "./validationConstraints.depth.js";
 export * from "./validationConstraints.size.js";
 export * from "./validationConstraints.circular.js";
-//# sourceMappingURL=index.js.map

package/dist/validationConstraints/structure/validationConstraints.children.d.ts

@@ -12,4 +12,3 @@ export declare function isContainer(value: unknown): value is object;
  * is also how `JSON.stringify` writes it (as `null`).
  */
 export declare function childrenOf(value: object): Array<[string, unknown]>;
-//# sourceMappingURL=validationConstraints.children.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.children.js

@@ -38,4 +38,3 @@ export function childrenOf(value) {
     const record = value;
     return Object.keys(record).map((key) => [`.${key}`, record[key]]);
 }
-//# sourceMappingURL=validationConstraints.children.js.map

package/dist/validationConstraints/structure/validationConstraints.circular.d.ts

@@ -33,4 +33,3 @@ export declare function assertNoCircularReference(value: unknown, path?: string,
  * Does not throw — use assertNoCircularReference for throwing behavior.
  */
 export declare function hasCircularReference(value: unknown): boolean;
-//# sourceMappingURL=validationConstraints.circular.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.circular.js

@@ -61,4 +61,3 @@ export function hasCircularReference(value) {
         throw error;
     }
 }
-//# sourceMappingURL=validationConstraints.circular.js.map

package/dist/validationConstraints/structure/validationConstraints.depth.d.ts

@@ -48,4 +48,3 @@ export declare function getSerializationDepth(value: unknown, limit?: number): n
  *   `statusCode` 400 and `expose: true` (see {@link UNTRUSTED_DEPTH_ERROR}).
  */
 export declare function assertDepthWithinLimit(value: unknown, maxDepth: number): void;
-//# sourceMappingURL=validationConstraints.depth.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.depth.js

@@ -69,4 +69,3 @@ export function assertDepthWithinLimit(value, maxDepth) {
         throw error;
     }
 }
-//# sourceMappingURL=validationConstraints.depth.js.map

package/dist/validationConstraints/structure/validationConstraints.size.d.ts

@@ -7,6 +7,10 @@
 /**
  * Estimate the byte size of a value as JSON without allocating a string.
  *
+ * The estimate is meant to sit at or above the real UTF-8 size: strings are
+ * measured exactly, numbers are charged their worst case, and containers
+ * their punctuation.
+ *
  * A value referenced from several places is charged once per occurrence, the
  * way a serializer expands it. Counting it once let a compact payload built
  * from shared subtrees estimate at a few hundred bytes while serializing to
@@ -36,4 +40,3 @@ export declare function estimateSerializedSize(value: unknown, maxBytes?: number
  * @throws {SerializationPayloadTooLargeError} when the estimate exceeds maxSize.
  */
 export declare function assertSizeWithinLimit(value: unknown, maxSize: number): void;
-//# sourceMappingURL=validationConstraints.size.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.size.js

@@ -6,15 +6,24 @@
  */
 import { SerializationLimits } from "@zudojs/constants";
 import { SerializationPayloadTooLargeError } from "@zudojs/errors";
+import { jsonStringByteLength } from "@zudojs/types";
 import { MAX_MEASURABLE_DEPTH } from "./validationConstraints.depth.js";
 import { TraversalLimitError, traverse, } from "./validationConstraints.traverse.js";
-/** Bytes charged for a single node, excluding its children. */
+/**
+ * Bytes charged for a single node, excluding its children.
+ *
+ * Strings are charged their UTF-8 size as JSON writes them (quotes and
+ * escapes included). The previous `length * 2` was the UTF-16 size, which
+ * undercounts every character above U+07FF: a thousand "₦" estimated at
+ * 2,013 bytes against 3,002 on the wire, so `assertSizeWithinLimit` let
+ * bodies half again larger than the limit through.
+ */
 function chargeFor(value) {
     if (value === null || value === undefined)
         return 4;
     switch (typeof value) {
         case "string":
-            return value.length * 2 + 2;
+            return jsonStringByteLength(value);
         case "number":
             // JSON emits up to 21 characters for a double; charge the worst case
             // rather than a flat 8, which under-counted every numeric field.
@@ -41,7 +50,7 @@ function chargeFor(value) {
         return 2 + Math.max(0, value.size - 1);
     const keys = Object.keys(value);
     return (2 +
-        keys.reduce((total, key) => total + key.length + 4, 0) +
+        keys.reduce((total, key) => total + jsonStringByteLength(key) + 2, 0) +
         Math.max(0, keys.length - 1));
 }
 /**
@@ -65,6 +74,10 @@ function resolveToJson(value) {
 /**
  * Estimate the byte size of a value as JSON without allocating a string.
  *
+ * The estimate is meant to sit at or above the real UTF-8 size: strings are
+ * measured exactly, numbers are charged their worst case, and containers
+ * their punctuation.
+ *
  * A value referenced from several places is charged once per occurrence, the
  * way a serializer expands it. Counting it once let a compact payload built
  * from shared subtrees estimate at a few hundred bytes while serializing to
@@ -127,4 +140,3 @@ export function assertSizeWithinLimit(value, maxSize) {
         throw error;
     }
 }
-//# sourceMappingURL=validationConstraints.size.js.map

package/dist/validationConstraints/structure/validationConstraints.traverse.d.ts

@@ -56,4 +56,3 @@ export interface TraversalReport {
  * @throws {TraversalLimitError} as soon as a bound is exceeded.
  */
 export declare function traverse(root: unknown, visitor: TraversalVisitor, rootPath?: string): TraversalReport;
-//# sourceMappingURL=validationConstraints.traverse.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.traverse.js

@@ -95,4 +95,3 @@ export function traverse(root, visitor, rootPath = "root") {
     }
     return { depth: deepest, cost };
 }
-//# sourceMappingURL=validationConstraints.traverse.js.map

package/dist/validationConstraints/validationConstraints.base.d.ts

@@ -45,10 +45,19 @@ export declare function checkConstraint<T>(constraint: ValidationConstraint<T>,
 export declare function checkConstraints<T>(constraints: readonly ValidationConstraint<T>[], value: T, path?: readonly (string | number)[]): ValidationResult<T>;
 /**
  * Combines constraints into a single constraint.
+ *
+ * The combined message lists the member messages, so a failure says what
+ * was required ("Value must contain at least 3 characters. Value must
+ * contain only letters.") rather than "One or more validation constraints
+ * failed."
  */
 export declare function combineConstraints<T>(...constraints: readonly ValidationConstraint<T>[]): ValidationConstraint<T>;
 /**
  * Creates a negated constraint.
+ *
+ * Without an explicit `message` the default names the inner constraint in
+ * words (`Value must not satisfy the "one of" constraint.`) instead of its
+ * internal identifier (`one_of`).
  */
 export declare function not<T>(constraint: ValidationConstraint<T>, options?: ConstraintOptions<T>): ValidationConstraint<T>;
 /**
@@ -59,4 +68,3 @@ export declare const required: ValidationConstraint<unknown>;
  * Asserts that a value is a non-negative integer.
  */
 export declare function assertNonNegativeInteger(value: number, name: string): void;
-//# sourceMappingURL=validationConstraints.base.d.ts.map

package/dist/validationConstraints/validationConstraints.base.js

@@ -73,19 +73,37 @@ export function checkConstraints(constraints, value, path = []) {
         return failure(issues);
     return success(value);
 }
+/** Turns an internal constraint name (`one_of`, `min_length_3`) into words. */
+function describeConstraint(name) {
+    return name.replace(/_+/g, " ").trim() || "custom";
+}
 /**
  * Combines constraints into a single constraint.
+ *
+ * The combined message lists the member messages, so a failure says what
+ * was required ("Value must contain at least 3 characters. Value must
+ * contain only letters.") rather than "One or more validation constraints
+ * failed."
  */
 export function combineConstraints(...constraints) {
+    const messages = [
+        ...new Set(constraints.map((constraint) => constraint.message)),
+    ].filter((message) => message.length > 0);
     return createConstraint((value) => constraints.every((constraint) => runConstraint(constraint, value)), {
         name: constraints.map((constraint) => constraint.name).join("_and_") ||
             "combined",
         code: "combined_constraint_failed",
-        message: "One or more validation constraints failed.",
+        message: messages.length > 0
+            ? messages.join(" ")
+            : "One or more validation constraints failed.",
     });
 }
 /**
  * Creates a negated constraint.
+ *
+ * Without an explicit `message` the default names the inner constraint in
+ * words (`Value must not satisfy the "one of" constraint.`) instead of its
+ * internal identifier (`one_of`).
  */
 export function not(constraint, options = {}) {
     // Negation must not fail open. A value of the wrong type, or one that makes
@@ -103,7 +121,8 @@ export function not(constraint, options = {}) {
     }, {
         name: options.name ?? `not_${constraint.name}`,
         code: options.code ?? "negated_constraint_failed",
-        message: options.message ?? `Value must not satisfy ${constraint.name}.`,
+        message: options.message ??
+            `Value must not satisfy the "${describeConstraint(constraint.name)}" constraint.`,
         ...(guard ? { guard } : {}),
     });
 }
@@ -123,4 +142,3 @@ export function assertNonNegativeInteger(value, name) {
         throw new RangeError(`${name} must be a non-negative integer.`);
     }
 }
-//# sourceMappingURL=validationConstraints.base.js.map

package/dist/validationErrors/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationError.base.js";
 export * from "./validationError.types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationErrors/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationError.base.js";
 export * from "./validationError.types.js";
-//# sourceMappingURL=index.js.map

package/dist/validationErrors/validationError.base.d.ts

@@ -67,6 +67,10 @@ export declare function toValidationError(error: unknown, fallbackMessage?: stri
 export declare function isValidationError(error: unknown): error is ValidationError;
 /** Returns whether a validation error has a specific code. */
 export declare function hasValidationErrorCode(error: unknown, code: ValidationErrorCode): boolean;
-/** Creates a validation error from a collection of issues. */
+/**
+ * Creates a validation error from a collection of issues.
+ *
+ * The code defaults to `INVALID_INPUT` (the issues describe rejected input),
+ * not `UNKNOWN`, which is reserved for errors whose cause really is unknown.
+ */
 export declare function createValidationError(issues: readonly ValidationIssue[], options?: ValidationErrorOptions): ValidationError;
-//# sourceMappingURL=validationError.base.d.ts.map

package/dist/validationErrors/validationError.base.js

@@ -114,8 +114,12 @@ export function isValidationError(error) {
 export function hasValidationErrorCode(error, code) {
     return isValidationError(error) && error.validationCode === code;
 }
-/** Creates a validation error from a collection of issues. */
+/**
+ * Creates a validation error from a collection of issues.
+ *
+ * The code defaults to `INVALID_INPUT` (the issues describe rejected input),
+ * not `UNKNOWN`, which is reserved for errors whose cause really is unknown.
+ */
 export function createValidationError(issues, options = {}) {
-    return new ValidationError(formatIssues(issues) || "Validation failed.", issues, options);
+    return new ValidationError(formatIssues(issues) || "Validation failed.", issues, { ...options, code: options.code ?? ValidationErrorCode.INVALID_INPUT });
 }
-//# sourceMappingURL=validationError.base.js.map

package/dist/validationErrors/validationError.types.d.ts

@@ -27,4 +27,3 @@ export declare class ConstraintValidationError extends ValidationError {
 export declare class SchemaValidationError extends ValidationError {
     constructor(message?: string, issues?: readonly ValidationIssue[], options?: Omit<ValidationErrorOptions, "code">);
 }
-//# sourceMappingURL=validationError.types.d.ts.map

package/dist/validationErrors/validationError.types.js

@@ -59,4 +59,3 @@ export class SchemaValidationError extends ValidationError {
         this.name = "SchemaValidationError";
     }
 }
-//# sourceMappingURL=validationError.types.js.map

package/dist/validationFactory/index.d.ts

@@ -4,4 +4,3 @@
  * Validation schema factory functions.
  */
 export * from "./validationFactory.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationFactory/index.js

@@ -4,4 +4,3 @@
  * Validation schema factory functions.
  */
 export * from "./validationFactory.core.js";
-//# sourceMappingURL=index.js.map

package/dist/validationFactory/validationFactory.core.d.ts

@@ -38,4 +38,3 @@ export declare function createValidationFactory(options?: ValidationFactoryOptio
  * calling `registry.clear()` silently removes rules another module registered.
  */
 export declare function createScopedValidationFactory(parent: ValidationFactory): ValidationFactory;
-//# sourceMappingURL=validationFactory.core.d.ts.map

package/dist/validationFactory/validationFactory.core.js

@@ -69,4 +69,3 @@ export function createValidationFactory(options = {}) {
 export function createScopedValidationFactory(parent) {
     return new ValidationFactory({ registry: parent.registry });
 }
-//# sourceMappingURL=validationFactory.core.js.map

package/dist/validationNormalizer/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationNormalizer.core.js";
 export * from "./validationNormalizer.helpers.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationNormalizer/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationNormalizer.core.js";
 export * from "./validationNormalizer.helpers.js";
-//# sourceMappingURL=index.js.map

package/dist/validationNormalizer/validationNormalizer.core.d.ts

@@ -24,4 +24,3 @@ export interface AsyncValidationNormalizer<T> {
 export declare function createNormalizer<T>(normalizer: Normalizer<T>, options?: NormalizerOptions): ValidationNormalizer<T>;
 /** Creates a reusable asynchronous normalizer. */
 export declare function createAsyncNormalizer<T>(normalizer: AsyncNormalizer<T>, options?: NormalizerOptions): AsyncValidationNormalizer<T>;
-//# sourceMappingURL=validationNormalizer.core.d.ts.map

package/dist/validationNormalizer/validationNormalizer.core.js

@@ -58,4 +58,3 @@ export function createAsyncNormalizer(normalizer, options = {}) {
         },
     });
 }
-//# sourceMappingURL=validationNormalizer.core.js.map

package/dist/validationNormalizer/validationNormalizer.helpers.d.ts

@@ -68,4 +68,3 @@ export declare function normalizeOptionalString(value: string | undefined): stri
 export declare function normalizeNullableString(value: string | null): string | null;
 /** Normalizes an optional nullable string. */
 export declare function normalizeOptionalNullableString(value: string | null | undefined): string | null | undefined;
-//# sourceMappingURL=validationNormalizer.helpers.d.ts.map

package/dist/validationNormalizer/validationNormalizer.helpers.js

@@ -127,4 +127,3 @@ export function normalizeOptionalNullableString(value) {
         return value;
     return normalizeWhitespace(normalizeUnicode(value));
 }
-//# sourceMappingURL=validationNormalizer.helpers.js.map

package/dist/validationParser/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationParser.core.js";
 export * from "./validationParser.collection.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationParser/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationParser.core.js";
 export * from "./validationParser.collection.js";
-//# sourceMappingURL=index.js.map

package/dist/validationParser/validationParser.collection.d.ts

@@ -25,4 +25,3 @@ export declare function parseOptional<T>(schema: ValidationSchema<T>, value: unk
 export declare function parseNullable<T>(schema: ValidationSchema<T>, value: unknown, options?: ParseOptions): ValidationResult<T | null>;
 /** Parses an optional nullable value. */
 export declare function parseOptionalNullable<T>(schema: ValidationSchema<T>, value: unknown, options?: ParseOptions): ValidationResult<T | null | undefined>;
-//# sourceMappingURL=validationParser.collection.d.ts.map

package/dist/validationParser/validationParser.collection.js

@@ -94,4 +94,3 @@ export function parseOptionalNullable(schema, value, options = {}) {
         return success(value);
     return validate(schema, value, options);
 }
-//# sourceMappingURL=validationParser.collection.js.map

package/dist/validationParser/validationParser.core.d.ts

@@ -27,4 +27,3 @@ export declare function createAsyncValidationParser<T>(schema: ValidationSchema<
 export declare function parseOr<T>(schema: ValidationSchema<T>, value: unknown, fallback: T): T;
 /** Parses a value and returns a fallback produced by a function when validation fails. */
 export declare function parseOrElse<T>(schema: ValidationSchema<T>, value: unknown, fallback: (error: SchemaValidationError) => T): T;
-//# sourceMappingURL=validationParser.core.d.ts.map

package/dist/validationParser/validationParser.core.js

@@ -44,4 +44,3 @@ export function parseOrElse(schema, value, fallback) {
         return result.data;
     return fallback(new SchemaValidationError("Schema validation failed.", result.issues));
 }
-//# sourceMappingURL=validationParser.core.js.map

package/dist/validationRegistry/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationRegistry.core.js";
 export * from "./validationRegistry.readonly.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationRegistry/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationRegistry.core.js";
 export * from "./validationRegistry.readonly.js";
-//# sourceMappingURL=index.js.map

package/dist/validationRegistry/validationRegistry.core.d.ts

@@ -13,7 +13,12 @@ export interface ValidationRule<T = unknown> {
 export interface ValidationRuleOptions {
     readonly overwrite?: boolean;
 }
-/** Registry of reusable validation schemas and constraints. */
+/**
+ * Registry of reusable validation schemas and constraints.
+ *
+ * Misuse (an empty or unknown rule name, a duplicate registration, a rule
+ * without a schema or constraints) throws `ConfigurationError`.
+ */
 export declare class ValidationRegistry {
     private readonly rules;
     register<T>(rule: ValidationRule<T>, options?: ValidationRuleOptions): this;
@@ -26,6 +31,11 @@ export declare class ValidationRegistry {
         readonly overwrite?: boolean;
     }): this;
     get<T = unknown>(name: string): ValidationRule<T> | undefined;
+    /**
+     * Returns a registered rule.
+     *
+     * @throws {ConfigurationError} when no rule of that name is registered.
+     */
     require<T = unknown>(name: string): ValidationRule<T>;
     has(name: string): boolean;
     unregister(name: string): boolean;
@@ -52,4 +62,3 @@ export declare class ValidationRegistry {
 export declare function createValidationRegistry(): ValidationRegistry;
 /** Creates a registry from an initial collection of rules. */
 export declare function createRegistryFromRules(rules: readonly ValidationRule[]): ValidationRegistry;
-//# sourceMappingURL=validationRegistry.core.d.ts.map

package/dist/validationRegistry/validationRegistry.core.js

@@ -1,22 +1,41 @@
+import { ConfigurationError } from "@zudojs/errors";
 import { checkConstraints } from "../validationConstraints/index.js";
 import { validate } from "../validationSchema/validationSchema.core.js";
 import { ReadonlyValidationRegistry } from "./validationRegistry.readonly.js";
 /** Normalizes registry keys. */
 function normalizeRuleName(name) {
-    const normalized = name.trim();
-    if (normalized.length === 0)
-        throw new TypeError("Validation rule name cannot be empty.");
+    const normalized = typeof name === "string" ? name.trim() : "";
+    if (normalized.length === 0) {
+        throw registryError("Validation rule name cannot be empty.");
+    }
     return normalized;
 }
-/** Registry of reusable validation schemas and constraints. */
+/**
+ * A registry mistake is a wiring error in the service, not bad input: it is
+ * a `ConfigurationError` (500, not exposed) rather than a bare `Error`, so
+ * callers can tell it from a defect and from a validation failure.
+ */
+function registryError(message, ruleName) {
+    return new ConfigurationError(message, {
+        component: "ValidationRegistry",
+        ...(ruleName !== undefined ? { configKey: ruleName } : {}),
+    });
+}
+/**
+ * Registry of reusable validation schemas and constraints.
+ *
+ * Misuse (an empty or unknown rule name, a duplicate registration, a rule
+ * without a schema or constraints) throws `ConfigurationError`.
+ */
 export class ValidationRegistry {
     rules = new Map();
     register(rule, options = {}) {
         const name = normalizeRuleName(rule.name);
-        if (!options.overwrite && this.rules.has(name))
-            throw new Error(`Validation rule "${name}" is already registered.`);
+        if (!options.overwrite && this.rules.has(name)) {
+            throw registryError(`Validation rule "${name}" is already registered.`, name);
+        }
         if (!rule.schema && (!rule.constraints || rule.constraints.length === 0)) {
-            throw new TypeError(`Validation rule "${name}" must define a schema or at least one constraint.`);
+            throw registryError(`Validation rule "${name}" must define a schema or at least one constraint.`, name);
         }
         this.rules.set(name, Object.freeze({
             ...rule,
@@ -36,10 +55,16 @@ export class ValidationRegistry {
     get(name) {
         return this.rules.get(normalizeRuleName(name));
     }
+    /**
+     * Returns a registered rule.
+     *
+     * @throws {ConfigurationError} when no rule of that name is registered.
+     */
     require(name) {
         const rule = this.get(name);
-        if (!rule)
-            throw new Error(`Validation rule "${name}" is not registered.`);
+        if (!rule) {
+            throw registryError(`Validation rule "${name}" is not registered.`, name);
+        }
         return rule;
     }
     has(name) {
@@ -83,7 +108,7 @@ export class ValidationRegistry {
         }
         if (constraints.length > 0)
             return checkConstraints(constraints, value);
-        throw new TypeError(`Validation rule "${name}" has no validation implementation.`);
+        throw registryError(`Validation rule "${name}" has no validation implementation.`, name);
     }
     clone() {
         const registry = new ValidationRegistry();
@@ -111,4 +136,3 @@ export function createRegistryFromRules(rules) {
         registry.register(rule);
     return registry;
 }
-//# sourceMappingURL=validationRegistry.core.js.map

package/dist/validationRegistry/validationRegistry.readonly.d.ts

@@ -15,4 +15,3 @@ export declare class ReadonlyValidationRegistry {
     get size(): number;
     validate<T>(name: string, value: unknown): ValidationResult<T>;
 }
-//# sourceMappingURL=validationRegistry.readonly.d.ts.map

package/dist/validationRegistry/validationRegistry.readonly.js

@@ -28,4 +28,3 @@ export class ReadonlyValidationRegistry {
         return this.registry.validate(name, value);
     }
 }
-//# sourceMappingURL=validationRegistry.readonly.js.map

package/dist/validationResult/index.d.ts

@@ -4,4 +4,3 @@
  * Validation result types and helpers.
  */
 export * from "./validationResult.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationResult/index.js

@@ -4,4 +4,3 @@
  * Validation result types and helpers.
  */
 export * from "./validationResult.type.js";
-//# sourceMappingURL=index.js.map

package/dist/validationResult/validationResult.type.d.ts

@@ -10,7 +10,12 @@ export interface ValidationIssue {
     readonly expected?: unknown;
     readonly received?: unknown;
 }
-/** Formats validation issues into a human-readable string. */
+/**
+ * Formats validation issues into a human-readable string.
+ *
+ * An issue with an empty path (one about the value as a whole) prints just
+ * its message rather than ": message".
+ */
 export declare function formatIssues(issues: readonly ValidationIssue[]): string;
 /**
  * Groups validation issues by their first path segment.
@@ -81,4 +86,3 @@ export declare class ValidationResultError extends SharedValidationError {
         message: string;
     };
 }
-//# sourceMappingURL=validationResult.type.d.ts.map

package/dist/validationResult/validationResult.type.js

@@ -2,11 +2,18 @@
  * Validation result types and helpers.
  */
 import { ValidationError as SharedValidationError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/** Formats validation issues into a human-readable string. */
+/**
+ * Formats validation issues into a human-readable string.
+ *
+ * An issue with an empty path (one about the value as a whole) prints just
+ * its message rather than ": message".
+ */
 export function formatIssues(issues) {
     if (issues.length === 0)
         return "";
-    return issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return issues
+        .map((i) => i.path.length > 0 ? `${i.path.join(".")}: ${i.message}` : i.message)
+        .join("; ");
 }
 /**
  * Groups validation issues by their first path segment.
@@ -122,4 +129,3 @@ export class ValidationResultError extends SharedValidationError {
         };
     }
 }
-//# sourceMappingURL=validationResult.type.js.map

package/dist/validationSchema/index.d.ts

@@ -4,4 +4,3 @@
  * Schema definitions and Zod integration.
  */
 export * from "./validationSchema.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationSchema/index.js

@@ -4,4 +4,3 @@
  * Schema definitions and Zod integration.
  */
 export * from "./validationSchema.core.js";
-//# sourceMappingURL=index.js.map

package/dist/validationSchema/validationSchema.core.d.ts

@@ -8,7 +8,14 @@ export interface ParseOptions {
 }
 /** Maps a Zod error into the package's normalized issue format. */
 export declare function mapZodIssues(error: ZodError, pathPrefix?: readonly (string | number)[]): ValidationIssue[];
-/** Safely parses input using a Zod schema. */
+/**
+ * Safely parses input using a Zod schema.
+ *
+ * Invalid input is always a `{ success: false }` result. The one throw is a
+ * schema with async refinements (see `validateAsync`).
+ *
+ * @throws {ConfigurationError} when the schema needs `validateAsync()`.
+ */
 export declare function validate<T>(schema: ValidationSchema<T>, value: unknown, options?: ParseOptions): ValidationResult<T>;
 /** Parses input using a schema and throws when validation fails. */
 export declare function parse<T>(schema: ValidationSchema<T>, value: unknown, options?: ParseOptions): T;
@@ -36,4 +43,3 @@ export declare function assertValid<T>(result: ValidationResult<T>): asserts res
 };
 /** Re-exports Zod so consumers do not need to depend on a second version of Zod. */
 export { z };
-//# sourceMappingURL=validationSchema.core.d.ts.map

package/dist/validationSchema/validationSchema.core.js

@@ -1,4 +1,5 @@
 import { z, ZodError } from "zod";
+import { ConfigurationError } from "@zudojs/errors";
 import { failure, success } from "../validationResult/validationResult.type.js";
 import { SchemaValidationError } from "../validationErrors/validationError.types.js";
 /** Maps a Zod error into the package's normalized issue format. */
@@ -15,9 +16,39 @@ export function mapZodIssues(error, pathPrefix = []) {
             : {}),
     }));
 }
-/** Safely parses input using a Zod schema. */
+/**
+ * Runs a synchronous Zod parse, turning Zod's "async schema in a sync parse"
+ * fault into a framework error.
+ *
+ * A schema with an async `refine`/`transform` cannot be parsed synchronously;
+ * Zod throws a bare `Error`, which escaped `validate()` and `isValid()` as an
+ * anonymous 500. It is a wiring mistake, not invalid input, so it is reported
+ * as a `ConfigurationError` naming the fix rather than as a validation
+ * failure (which would return a 400 for a bug in the service).
+ *
+ * @throws {ConfigurationError} when the schema needs `validateAsync()`.
+ */
+function safeParseSync(schema, value) {
+    try {
+        return schema.safeParse(value);
+    }
+    catch (error) {
+        if (error instanceof z.core.$ZodAsyncError) {
+            throw new ConfigurationError("The schema contains an async refine() or transform() and cannot be parsed synchronously; use validateAsync(), parseAsync() or createAsyncValidator().", { component: "@zudojs/validation", cause: error });
+        }
+        throw error;
+    }
+}
+/**
+ * Safely parses input using a Zod schema.
+ *
+ * Invalid input is always a `{ success: false }` result. The one throw is a
+ * schema with async refinements (see `validateAsync`).
+ *
+ * @throws {ConfigurationError} when the schema needs `validateAsync()`.
+ */
 export function validate(schema, value, options = {}) {
-    const result = schema.safeParse(value);
+    const result = safeParseSync(schema, value);
     if (result.success)
         return success(result.data);
     return failure(mapZodIssues(result.error, options.pathPrefix));
@@ -45,7 +76,7 @@ export async function parseAsync(schema, value, options = {}) {
 }
 /** Determines whether a value matches a schema. */
 export function isValid(schema, value) {
-    return schema.safeParse(value).success;
+    return safeParseSync(schema, value).success;
 }
 /** Creates a validation function from a schema. */
 export function createValidator(schema) {
@@ -74,4 +105,3 @@ export function assertValid(result) {
 }
 /** Re-exports Zod so consumers do not need to depend on a second version of Zod. */
 export { z };
-//# sourceMappingURL=validationSchema.core.js.map

package/dist/validationTransformer/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./validationTransformer.core.js";
 export * from "./validationTransformer.helpers.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/validationTransformer/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./validationTransformer.core.js";
 export * from "./validationTransformer.helpers.js";
-//# sourceMappingURL=index.js.map

package/dist/validationTransformer/validationTransformer.core.d.ts

@@ -26,4 +26,3 @@ export interface AsyncValidationTransformer<T, U> {
 export declare function createValidationTransformer<T, U>(transform: ValidationTransform<T, U>, options?: TransformerOptions): ValidationTransformer<T, U>;
 /** Creates an asynchronous transformer. */
 export declare function createAsyncValidationTransformer<T, U>(transform: AsyncValidationTransform<T, U>, options?: TransformerOptions): AsyncValidationTransformer<T, U>;
-//# sourceMappingURL=validationTransformer.core.d.ts.map

package/dist/validationTransformer/validationTransformer.core.js

@@ -61,4 +61,3 @@ export function createAsyncValidationTransformer(transform, options = {}) {
         },
     });
 }
-//# sourceMappingURL=validationTransformer.core.js.map

package/dist/validationTransformer/validationTransformer.helpers.d.ts

@@ -20,4 +20,3 @@ export declare function transformArray<T, U>(values: readonly T[], transform: Va
 export declare function transformArrayAsync<T, U>(values: readonly T[], transform: AsyncValidationTransform<T, U>): Promise<U[]>;
 /** Creates a schema that transforms the validated value. */
 export declare function withTransformer<T, U>(schema: ValidationSchema<T>, transform: ValidationTransform<T, U>): ValidationSchema<U>;
-//# sourceMappingURL=validationTransformer.helpers.d.ts.map

package/dist/validationTransformer/validationTransformer.helpers.js

@@ -64,4 +64,3 @@ export async function transformArrayAsync(values, transform) {
 export function withTransformer(schema, transform) {
     return schema.transform(transform);
 }
-//# sourceMappingURL=validationTransformer.helpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/validation",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Schema validation with Zod integration, constraints, parsers, composers, circular detection, and depth/size checks.",
   "license": "MIT",
   "author": {
@@ -25,9 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.3",
-    "@zudojs/errors": "1.3.1",
-    "@zudojs/types": "1.2.0",
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/types": "1.3.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {