@zudojs/validation 1.0.3 → 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,7 +17,8 @@
  * @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`.
+ * @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.
  */

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

@@ -5,7 +5,7 @@
  * or validation to prevent stack overflows and provide clear error messages.
  */
 import { CircularReferenceError, SerializationDepthError, } from "@zudojs/errors";
-import { MAX_MEASURABLE_DEPTH } from "./validationConstraints.depth.js";
+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,7 +20,8 @@ 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`.
+ * @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.
  */
@@ -33,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 SerializationDepthError(error.observed, maxDepth);
+            throw new SerializationDepthError(error.observed, maxDepth, UNTRUSTED_DEPTH_ERROR);
         }
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/validation",
-  "version": "1.0.3",
+  "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.1",
-    "@zudojs/errors": "1.2.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"
   },