first commit

docs/foundation/data/validation/src/errors/errors.md

@@ -0,0 +1,90 @@
+# ValidationError
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`ValidationError` is the single error class for the `@suaveplan/validation` package. It extends `SuaveplanError` from `@suaveplan/error`, giving it a stable `code` (taken from the first issue), a `timestamp`, and optional `traceId`. Its `issues` array carries every `ValidationIssue` produced during a parse run, enabling rich error reporting for form validation, API input checking, and CLI tools.
+
+The `VALIDATION_CODES` registry uses `defineCodes` from `@suaveplan/error` to produce fully-qualified, type-safe code strings like `"VALIDATION.STRING.TOO_SHORT"`. All 21 validation codes are registered there.
+
+## Features
+
+- Extends `SuaveplanError` — compatible with `walkCauses`, `toSpanEvent`, `toJSON`
+- `issues: ValidationIssue[]` — full list of all parse failures with path and message
+- `flatten()` — splits issues into `formErrors` (root path) and `fieldErrors` (field-keyed, dot-separated path)
+- `format()` — builds a nested `Record<string, unknown>` with `_errors` arrays per node
+- `VALIDATION_CODES` — typed registry of all error codes
+
+## Usage: Basic Example
+
+```typescript
+import { string } from "@suaveplan/validation";
+
+const result = string().min(5).safeParse("hi");
+if (!result.success) {
+  console.log(result.error.issues);
+  // [{ code: "VALIDATION.STRING.TOO_SHORT", path: [], message: "..." }]
+}
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { object, string, number } from "@suaveplan/validation";
+
+const schema = object({ name: string().min(2), age: number().positive() });
+const result = schema.safeParse({ name: "A", age: -1 });
+
+if (!result.success) {
+  const { formErrors, fieldErrors } = result.error.flatten();
+  // fieldErrors: { name: ["String must be at least 2 character(s)"], age: ["Number must be positive"] }
+
+  const formatted = result.error.format();
+  // { _errors: [], name: { _errors: ["..."] }, age: { _errors: ["..."] } }
+}
+```
+
+## API Reference
+
+### `class ValidationError extends SuaveplanError<ValidationCode>`
+
+#### Constructor
+
+`new ValidationError(issues: ValidationIssue[], opts?: ValidationErrorOptions)`
+
+- `issues` — array of `ValidationIssue`; the first issue's `code` and `message` become the error's primary code and message
+- `opts.cause` — optional underlying cause
+- `opts.traceId` — optional OTel trace id
+
+#### `readonly issues: ValidationIssue[]`
+
+All issues collected during parsing.
+
+#### `flatten(): FlattenedErrors`
+
+Returns `{ formErrors: string[], fieldErrors: Record<string, string[]> }`. Root-level issues (empty path) go to `formErrors`; all others are keyed by dot-joined path segments.
+
+#### `format(): Record<string, unknown>`
+
+Returns a nested record where each node has an `_errors: string[]` array. Useful for rendering field-level errors in UI frameworks.
+
+### `VALIDATION_CODES`
+
+Frozen record of all `VALIDATION.*` codes. Use when constructing custom issues.
+
+### `ValidationErrorOptions`
+
+```typescript
+interface ValidationErrorOptions {
+  cause?: unknown;
+  traceId?: string;
+}
+```
+
+## Implementation Notes
+
+- An empty `issues` array produces `code: "VALIDATION.INVALID_TYPE"` and message `"Validation failed"` as safe fallbacks.
+- `format()` traverses path segments iteratively, creating intermediate nodes as needed, so deeply nested paths are handled without recursion.
+- `flatten()` uses a dot-joined path key (`"user.address.city"`) matching the most common form-library convention.