8.9 KiB
validation
Purpose
Self-contained runtime schema validation for the Suaveplan monorepo with a Zod-compatible API surface — parse, safeParse, parseAsync, safeParseAsync, refine, transform, optional, nullable — implemented independently of Zod. Provides exhaustive schema types (string, number, boolean, date, array, object with strip/strict/passthrough modes, record, tuple, union, intersection, literal, enum), async refinements, lifecycle hooks, and structured ValidationError codes under the VALIDATION.* namespace.
Requirements
VL-01 — Self-contained schema engine
@suaveplan/validation is its own schema parser — it does NOT depend on Zod. It exposes a Zod-compatible API surface (parse, safeParse, parseAsync, safeParseAsync, refine, transform, optional, nullable) but is implemented independently.
Verified by: tests/dep-graph.test.ts AND src/core/schema/schema.spec-conformance.test.ts::"string().parse returns string and accepts unknown input" AND src/core/schema/schema.spec-conformance.test.ts::"refine, transform, optional, nullable are present".
VL-02 — Never-throw contract
.parse() and .parseAsync() MUST throw ValidationError on failure (never raw errors). .safeParse() and .safeParseAsync() MUST return ParseResult<T> and NEVER throw.
Verified by: src/core/schema/schema.test.ts::"throws ValidationError for invalid input" AND src/core/schema/schema.test.ts::"returns failure for invalid input" AND src/core/schema/schema.spec-conformance.test.ts::"safeParse never throws on bizarre input" AND src/core/schema/schema.spec-conformance.test.ts::"safeParseAsync never throws on bizarre input".
VL-03 — ValidationError shape
ValidationError MUST extend SuaveplanError and carry an issues: ValidationIssue[] array. .flatten() MUST return FlattenedErrors with formErrors (top-level issues) and fieldErrors (keyed by path). .format() MUST return a nested error tree. Error codes under VALIDATION.* namespace.
Verified by: src/errors/errors.test.ts (full suite — extends SuaveplanError, flatten / format, code registry).
VL-04 — String schema constraints
StringSchema MUST enforce: min, max, length, regex, email, url, uuid, startsWith, endsWith, includes. Transform helpers trim, toLowerCase, toUpperCase MUST mutate the output value, not fail.
Verified by: src/schemas/string/string.test.ts (full suite — min / max / length / regex / email / url / uuid / startsWith / endsWith / includes + trim / toLowerCase / toUpperCase).
VL-05 — Number schema constraints
NumberSchema MUST enforce: min, max, int, positive, negative, multipleOf, finite.
Verified by: src/schemas/number/number.test.ts (full suite — min / max / int / positive / negative / multipleOf / finite).
VL-06 — Object schema modes
ObjectSchema MUST support three unknown-key modes: strip (default, drops unknown keys), strict (fails on unknown keys), passthrough (includes unknown keys). .pick(), .omit(), .partial(), .required(), .extend(), .merge() MUST each return a new ObjectSchema without mutating the original.
Verified by: src/schemas/object/object.test.ts (full suite — strip / strict / passthrough + pick / omit / partial / required / extend / merge).
VL-07 — Union short-circuit
UnionSchema MUST attempt each arm in order and return the result of the first successful parse. If no arm matches, it MUST return ParseFailure with all arm errors listed as issues.
Verified by: src/schemas/union/union.test.ts (full suite — first-match short-circuit + aggregated arm errors).
VL-08 — Async refinements
.refine(fn) MUST accept both synchronous and async predicate functions. Async refinements are awaited via .parseAsync() / .safeParseAsync(). The synchronous parse paths (.parse() / .safeParse()) MUST NOT silently skip async refinements: see VL-13.
Verified by: src/core/schema/schema.test.ts::"async refinement passes" AND src/core/schema/schema.test.ts::"async refinement fails" AND src/core/schema/schema.test.ts::"sync parse throws ASYNC_REFINEMENT_REQUIRES_PARSEASYNC when an async refinement is present".
VL-09 — Coerce utilities
coerce(schema) MUST coerce string inputs to the target type before parsing. coerceString, coerceNumber, coerceBoolean, coerceDate are pure functions; a failed coercion returns null (which the wrapper translates into ParseFailure) rather than throwing. coerceString returns null for non-coercible inputs (symbol); other inputs are coerced via String().
Verified by: src/utils/coerce.test.ts (full suite — coerceString / coerceNumber / coerceBoolean / coerceDate + coerce wrapper) AND src/utils/coerce.test.ts::"returns null for symbol input (non-coercible per VL-09)".
VL-10 — Hooks
Schemas MUST support optional lifecycle hooks { beforeValidate, afterValidate, onError } settable via a .withHooks(hooks) method on BaseSchema that returns an immutable clone with the supplied hooks merged onto any pre-existing hooks (per-key replace semantics). Hooks are called from every terminal branch of parse / safeParse / parseAsync / safeParseAsync: beforeValidate is called before _parse, afterValidate on successful resolution, onError immediately before ValidationError is thrown / surfaced. In the synchronous path the hook return value (including any returned promise) is discarded; in the async path returned promises are awaited.
Verified by: src/core/schema/schema.spec-conformance.test.ts::"calls beforeValidate and afterValidate on successful sync parse" AND src/core/schema/schema.spec-conformance.test.ts::"calls onError on sync parse failure" AND src/core/schema/schema.spec-conformance.test.ts::"calls onError when sync refinement fails" AND src/core/schema/schema.spec-conformance.test.ts::"awaits async beforeValidate/afterValidate in parseAsync" AND src/core/schema/schema.spec-conformance.test.ts::"awaits async onError on async parse failure (type mismatch)" AND src/core/schema/schema.spec-conformance.test.ts::"awaits async onError when async refinement fails" AND src/core/schema/schema.spec-conformance.test.ts::"merges hooks across multiple withHooks calls (clone path)".
VL-11 — OTel instrumentation
validation.parse.success and validation.parse.failure counters and validation.parse.duration_ms histogram MUST be emitted via @opentelemetry/api from every terminal branch of BaseSchema.parse and BaseSchema.parseAsync (not opt-in). Each metric carries a schema.type attribute equal to this.constructor.name (e.g. "StringSchema", "ObjectSchema"). Duration is measured via performance.now(). All emission is a no-op when no MeterProvider is registered.
Verified by: src/core/schema/schema.spec-conformance.test.ts::"emits validation.parse.success on successful parse" AND src/core/schema/schema.spec-conformance.test.ts::"emits validation.parse.failure on failed parse" AND src/core/schema/schema.spec-conformance.test.ts::"emits failure on sync refinement failure" AND src/core/schema/schema.spec-conformance.test.ts::"emits success on async parse + emits duration histogram" AND src/core/schema/schema.spec-conformance.test.ts::"emits failure on async parse failure (type mismatch)" AND src/core/schema/schema.spec-conformance.test.ts::"emits failure on async refinement failure" AND src/otel/validation-otel.test.ts (no-op + lazy init).
VL-12 — sideEffects: false + coverage 100%
"sideEffects": false with tree-shake test. Vitest thresholds at 100/100/100/100. No .skip / .only in src/.
Verified by: tests/tree-shake.test.ts::"sideEffects is false" AND coverage gate bunx turbo test:coverage --filter=@suaveplan/validation.
VL-13 — Async-refinement loud-fail in synchronous parse
BaseSchema.parse and BaseSchema.safeParse MUST refuse to run when any refinement attached to the schema is async. parse MUST throw a ValidationError whose first issue carries the code VALIDATION.ASYNC_REFINEMENT_REQUIRES_PARSEASYNC. safeParse MUST return ParseFailure with the same code. This eliminates the prior silent-skip behaviour where async predicates' promises were discarded and the value was reported valid regardless of the predicate's eventual result, which is a security-grade footgun for revocation / uniqueness / rate-limit checks. parseAsync / safeParseAsync are unchanged — they continue to await async refinements normally.
Verified by: src/core/schema/schema.test.ts::"sync parse throws ASYNC_REFINEMENT_REQUIRES_PARSEASYNC when an async refinement is present" AND src/core/schema/schema.test.ts::"safeParse returns ASYNC_REFINEMENT_REQUIRES_PARSEASYNC failure when async refinement is present" AND src/core/schema/schema.test.ts::"async refinement passes" AND src/core/schema/schema.test.ts::"async refinement fails".