@zudojs/validation 1.0.2 → 1.1.0

package/README.md

@@ -46,6 +46,14 @@ assertSizeWithinLimit(body, 1_000_000);
 assertNoCircularReference(body);
 ```
 
+A too-deep payload throws `SerializationDepthError` with `statusCode` 400
+and `expose: true` from both `assertDepthWithinLimit` and
+`assertNoCircularReference`: untrusted input that nests too far is a client
+error, and the message names only the observed depth and the limit
+(`Maximum serialization depth exceeded: 40 > 32`), never the payload.
+Constructed directly, `SerializationDepthError` still defaults to an
+unexposed 500, which is right for data your own server built.
+
 ## Safety Notes
 
 - Constraint failures do **not** carry the rejected value. `ValidationError` is

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

@@ -1,3 +1,4 @@
+import { formatCount } from "@zudojs/types";
 import { createConstraint, assertNonNegativeInteger, } from "../validationConstraints.base.js";
 /** Narrows an unknown value to a readonly array. */
 function isArrayOf(value) {
@@ -34,7 +35,7 @@ export function minItems(minimum) {
     return createConstraint((value) => value.length >= minimum, {
         name: `min_items_${minimum}`,
         code: "min_items",
-        message: `Value must contain at least ${minimum} items.`,
+        message: `Value must contain at least ${formatCount(minimum, "item")}.`,
         guard: isArrayOf,
     });
 }
@@ -46,7 +47,7 @@ export function maxItems(maximum) {
     return createConstraint((value) => value.length <= maximum, {
         name: `max_items_${maximum}`,
         code: "max_items",
-        message: `Value must contain at most ${maximum} items.`,
+        message: `Value must contain at most ${formatCount(maximum, "item")}.`,
         guard: isArrayOf,
     });
 }
@@ -58,7 +59,7 @@ export function exactItems(length) {
     return createConstraint((value) => value.length === length, {
         name: `exact_items_${length}`,
         code: "exact_items",
-        message: `Value must contain exactly ${length} items.`,
+        message: `Value must contain exactly ${formatCount(length, "item")}.`,
         guard: isArrayOf,
     });
 }

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

@@ -1,4 +1,5 @@
 import { ValidationLength, ValidationPattern } from "@zudojs/constants";
+import { formatCount } from "@zudojs/types";
 import { createConstraint, assertNonNegativeInteger, } from "../validationConstraints.base.js";
 /** Counts Unicode code points rather than UTF-16 code units. */
 function characterLength(value) {
@@ -22,7 +23,7 @@ export function minLength(minimum) {
     return createConstraint((value) => characterLength(value) >= minimum, {
         name: `min_length_${minimum}`,
         code: "min_length",
-        message: `Value must contain at least ${minimum} characters.`,
+        message: `Value must contain at least ${formatCount(minimum, "character")}.`,
         guard: (value) => typeof value === "string",
     });
 }
@@ -34,7 +35,7 @@ export function maxLength(maximum) {
     return createConstraint((value) => characterLength(value) <= maximum, {
         name: `max_length_${maximum}`,
         code: "max_length",
-        message: `Value must contain at most ${maximum} characters.`,
+        message: `Value must contain at most ${formatCount(maximum, "character")}.`,
         guard: (value) => typeof value === "string",
     });
 }

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

@@ -17,12 +17,19 @@
  * @param maxDepth - Depth ceiling, so a deep graph cannot exhaust the stack
  *   before a cycle is reported.
  * @throws {CircularReferenceError} on the first cycle found.
+ * @throws {SerializationDepthError} when the graph is deeper than `maxDepth`
+ *   (a 400 with `expose: true`, like `assertDepthWithinLimit`).
+ *   Running out of depth is not evidence of a cycle, and reporting it as one
+ *   told callers a payload referenced itself when it merely nested too far.
  */
 export declare function assertNoCircularReference(value: unknown, path?: string, maxDepth?: number): void;
 /**
  * Check whether a value contains circular references.
  *
- * Returns true if a cycle is found, false otherwise.
+ * Returns true if a cycle is found, false otherwise. A graph too deep to walk
+ * within the measurable ceiling reports false: no cycle was found, and the
+ * depth is the caller's own `assertDepthWithinLimit` to report.
+ *
  * Does not throw — use assertNoCircularReference for throwing behavior.
  */
 export declare function hasCircularReference(value: unknown): boolean;

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

@@ -4,8 +4,8 @@
  * Detects circular references in object graphs before serialization
  * or validation to prevent stack overflows and provide clear error messages.
  */
-import { CircularReferenceError } from "@zudojs/errors";
-import { MAX_MEASURABLE_DEPTH } from "./validationConstraints.depth.js";
+import { CircularReferenceError, SerializationDepthError, } from "@zudojs/errors";
+import { MAX_MEASURABLE_DEPTH, UNTRUSTED_DEPTH_ERROR, } from "./validationConstraints.depth.js";
 import { TraversalLimitError, traverse, } from "./validationConstraints.traverse.js";
 /**
  * Detect circular references in a value graph.
@@ -20,6 +20,10 @@ import { TraversalLimitError, traverse, } from "./validationConstraints.traverse
  * @param maxDepth - Depth ceiling, so a deep graph cannot exhaust the stack
  *   before a cycle is reported.
  * @throws {CircularReferenceError} on the first cycle found.
+ * @throws {SerializationDepthError} when the graph is deeper than `maxDepth`
+ *   (a 400 with `expose: true`, like `assertDepthWithinLimit`).
+ *   Running out of depth is not evidence of a cycle, and reporting it as one
+ *   told callers a payload referenced itself when it merely nested too far.
  */
 export function assertNoCircularReference(value, path = "root", maxDepth = MAX_MEASURABLE_DEPTH) {
     try {
@@ -30,7 +34,7 @@ export function assertNoCircularReference(value, path = "root", maxDepth = MAX_M
             throw new CircularReferenceError(error.path);
         }
         if (error instanceof TraversalLimitError && error.halt === "depth") {
-            throw new CircularReferenceError(`${error.path} (exceeded ${maxDepth} levels)`);
+            throw new SerializationDepthError(error.observed, maxDepth, UNTRUSTED_DEPTH_ERROR);
         }
         throw error;
     }
@@ -38,7 +42,10 @@ export function assertNoCircularReference(value, path = "root", maxDepth = MAX_M
 /**
  * Check whether a value contains circular references.
  *
- * Returns true if a cycle is found, false otherwise.
+ * Returns true if a cycle is found, false otherwise. A graph too deep to walk
+ * within the measurable ceiling reports false: no cycle was found, and the
+ * depth is the caller's own `assertDepthWithinLimit` to report.
+ *
  * Does not throw — use assertNoCircularReference for throwing behavior.
  */
 export function hasCircularReference(value) {
@@ -49,6 +56,8 @@ export function hasCircularReference(value) {
     catch (error) {
         if (error instanceof CircularReferenceError)
             return true;
+        if (error instanceof SerializationDepthError)
+            return false;
         throw error;
     }
 }

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

@@ -11,6 +11,19 @@
  * that overflows the stack on the input it was checking protects nothing.
  */
 export declare const MAX_MEASURABLE_DEPTH = 512;
+/**
+ * Error options for depth failures found by these guards.
+ *
+ * The guards exist to check UNTRUSTED input, so input that nests too deep is
+ * a client error: a 400 that may be exposed. `SerializationDepthError` alone
+ * defaults to an unexposed 500, which turned a too-deep request body into an
+ * opaque server error. The message carries only the observed depth and the
+ * limit, never the payload.
+ */
+export declare const UNTRUSTED_DEPTH_ERROR: Readonly<{
+    statusCode: 400;
+    expose: true;
+}>;
 /**
  * Compute the maximum nesting depth of a value.
  *
@@ -31,7 +44,8 @@ export declare function getSerializationDepth(value: unknown, limit?: number): n
  *
  * @param value - The value to check.
  * @param maxDepth - Maximum permitted nesting depth.
- * @throws {SerializationDepthError} when depth exceeds the limit.
+ * @throws {SerializationDepthError} when depth exceeds the limit, with
+ *   `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

@@ -13,6 +13,19 @@ import { TraversalLimitError, traverse, } from "./validationConstraints.traverse
  * that overflows the stack on the input it was checking protects nothing.
  */
 export const MAX_MEASURABLE_DEPTH = 512;
+/**
+ * Error options for depth failures found by these guards.
+ *
+ * The guards exist to check UNTRUSTED input, so input that nests too deep is
+ * a client error: a 400 that may be exposed. `SerializationDepthError` alone
+ * defaults to an unexposed 500, which turned a too-deep request body into an
+ * opaque server error. The message carries only the observed depth and the
+ * limit, never the payload.
+ */
+export const UNTRUSTED_DEPTH_ERROR = Object.freeze({
+    statusCode: 400,
+    expose: true,
+});
 /**
  * Compute the maximum nesting depth of a value.
  *
@@ -42,7 +55,8 @@ export function getSerializationDepth(value, limit = MAX_MEASURABLE_DEPTH) {
  *
  * @param value - The value to check.
  * @param maxDepth - Maximum permitted nesting depth.
- * @throws {SerializationDepthError} when depth exceeds the limit.
+ * @throws {SerializationDepthError} when depth exceeds the limit, with
+ *   `statusCode` 400 and `expose: true` (see {@link UNTRUSTED_DEPTH_ERROR}).
  */
 export function assertDepthWithinLimit(value, maxDepth) {
     try {
@@ -50,7 +64,7 @@ export function assertDepthWithinLimit(value, maxDepth) {
     }
     catch (error) {
         if (error instanceof TraversalLimitError && error.halt === "depth") {
-            throw new SerializationDepthError(error.observed, maxDepth);
+            throw new SerializationDepthError(error.observed, maxDepth, UNTRUSTED_DEPTH_ERROR);
         }
         throw error;
     }

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

@@ -12,8 +12,16 @@
  * from shared subtrees estimate at a few hundred bytes while serializing to
  * hundreds of megabytes.
  *
+ * Charging every occurrence means the subtree memo that keeps the walk linear
+ * has to be off, so the budget is the only thing that bounds the work: `n`
+ * shared `{a:node,b:node}` pairs expand to `2^n` visits. The default budget is
+ * therefore finite — {@link SerializationLimits.MAX_SIZE} — rather than
+ * `Infinity`, which left an untrusted 1 KB payload able to burn minutes of CPU.
+ * Pass an explicit `Infinity` only for input you trust.
+ *
  * @param value - The value to measure.
  * @param maxBytes - Stop counting past this budget; the budget is returned.
+ *   Defaults to {@link SerializationLimits.MAX_SIZE}.
  * @returns The estimated serialized size in bytes.
  */
 export declare function estimateSerializedSize(value: unknown, maxBytes?: number): number;

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

@@ -4,6 +4,7 @@
  * Estimates serialized payload size to prevent memory exhaustion
  * from excessively large payloads.
  */
+import { SerializationLimits } from "@zudojs/constants";
 import { SerializationPayloadTooLargeError } from "@zudojs/errors";
 import { MAX_MEASURABLE_DEPTH } from "./validationConstraints.depth.js";
 import { TraversalLimitError, traverse, } from "./validationConstraints.traverse.js";
@@ -69,11 +70,19 @@ function resolveToJson(value) {
  * from shared subtrees estimate at a few hundred bytes while serializing to
  * hundreds of megabytes.
  *
+ * Charging every occurrence means the subtree memo that keeps the walk linear
+ * has to be off, so the budget is the only thing that bounds the work: `n`
+ * shared `{a:node,b:node}` pairs expand to `2^n` visits. The default budget is
+ * therefore finite — {@link SerializationLimits.MAX_SIZE} — rather than
+ * `Infinity`, which left an untrusted 1 KB payload able to burn minutes of CPU.
+ * Pass an explicit `Infinity` only for input you trust.
+ *
  * @param value - The value to measure.
  * @param maxBytes - Stop counting past this budget; the budget is returned.
+ *   Defaults to {@link SerializationLimits.MAX_SIZE}.
  * @returns The estimated serialized size in bytes.
  */
-export function estimateSerializedSize(value, maxBytes = Number.POSITIVE_INFINITY) {
+export function estimateSerializedSize(value, maxBytes = SerializationLimits.MAX_SIZE) {
     try {
         return traverse(value, {
             maxDepth: MAX_MEASURABLE_DEPTH,

package/dist/validationParser/validationParser.collection.js

@@ -3,10 +3,9 @@
  *
  * @module validationParser/validationParser.collection
  */
+import { SCHEMA_FORBIDDEN_KEYS } from "@zudojs/constants";
 import { validate, validateAsync, } from "../validationSchema/validationSchema.core.js";
 import { failure, success } from "../validationResult/validationResult.type.js";
-/** Property names that would mutate a prototype instead of adding a key. */
-const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 /** Parses multiple values using the same schema. Succeeds only when every value is valid. */
 export function parseMany(schema, values) {
     const parsed = [];
@@ -52,7 +51,7 @@ export function parseRecord(schema, values) {
     const parsed = Object.create(null);
     const issues = [];
     for (const [key, value] of Object.entries(values)) {
-        if (FORBIDDEN_KEYS.has(key)) {
+        if (SCHEMA_FORBIDDEN_KEYS.has(key)) {
             issues.push({
                 path: [key],
                 code: "forbidden_key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/validation",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Schema validation with Zod integration, constraints, parsers, composers, circular detection, and depth/size checks.",
   "license": "MIT",
   "author": {
@@ -25,13 +25,14 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/errors": "1.1.0",
-    "zod": "^4.4.3"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/types": "1.2.0",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -45,7 +46,7 @@
     "zod",
     "schemas"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-validation",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },