22 KiB
22 KiB
@suaveplan/validation - Runtime schema validation with Zod-compatible API — self-contained parse engine, exhaustive schema types, async refinements, hooks, structured errors
Summary
Runtime schema validation with a Zod-compatible API. This package is a self-contained parse engine — it does not import Zod or any other validation library — so it is safe to use in environments where Zod is absent or where bundle size is a constraint. It covers the full schema surface expected from a production validator: all primitive and composite types, parse/safeParse/parseAsync, refine (sync + async), transform, describe, object shape builders (pick, omit, partial, extend, merge), three unknown-key modes, async lifecycle hooks, and composable helpers (pipe, mergeResults). Structured errors surface via @suaveplan/error with stable VALIDATION.* codes. When Zod is already a project dependency and you need its ecosystem (inference helpers, plugins), use Zod directly; use this package for internal platform code and zero-dep environments.
Documentation tree
- schema — (no submodules)
- schema — (no submodules)
- errors — (no submodules)
- errors — (no submodules)
- otel — (no submodules)
- validation-otel — (no submodules)
- array — (no submodules)
- array — (no submodules)
- boolean — (no submodules)
- boolean — (no submodules)
- date — (no submodules)
- date — (no submodules)
- enum — (no submodules)
- enum — (no submodules)
- intersection — (no submodules)
- intersection — (no submodules)
- literal — (no submodules)
- literal — (no submodules)
- nullable — (no submodules)
- nullable — (no submodules)
- number — (no submodules)
- number — (no submodules)
- object — (no submodules)
- object — (no submodules)
- optional — (no submodules)
- optional — (no submodules)
- record — (no submodules)
- record — (no submodules)
- string — (no submodules)
- string — (no submodules)
- tuple — (no submodules)
- tuple — (no submodules)
- union — (no submodules)
- union — (no submodules)
- common —
common.tsdefines the core type contracts shared across the entire@suaveplan/validationpackage: validation codes,… - validation-hooks —
validation-hooks.tsdefines the lifecycle hook types for schema validation observability. These hooks allow consumers… - coerce — The coerce utilities allow schemas to accept a broader range of input types by converting them before validation. They…
- compose — The compose utilities provide functional combinators for working with validation results and schemas.
mergeResultsag…
- validation-hooks —
validation-hooks.tsdefines the lifecycle hook types for schema validation observability. These hooks allow consumers… - coerce — The coerce utilities allow schemas to accept a broader range of input types by converting them before validation. They…
- compose — The compose utilities provide functional combinators for working with validation results and schemas.
mergeResultsag… - schema — (no submodules)- errors — (no submodules)- errors — (no submodules)- otel — (no submodules)- validation-otel — (no submodules)- array — (no submodules)- array — (no submodules)- boolean — (no submodules)- boolean — (no submodules)- date — (no submodules)- date — (no submodules)- enum — (no submodules)- enum — (no submodules)- intersection — (no submodules)- intersection — (no submodules)- literal — (no submodules)- literal — (no submodules)- nullable — (no submodules)- nullable — (no submodules)- number — (no submodules)- number — (no submodules)- object — (no submodules)- object — (no submodules)- optional — (no submodules)- optional — (no submodules)- record — (no submodules)- record — (no submodules)- string — (no submodules)- string — (no submodules)- tuple — (no submodules)- tuple — (no submodules)- union — (no submodules)- union — (no submodules)- common —
common.tsdefines the core type contracts shared across the entire@suaveplan/validationpackage: validation codes,… - validation-hooks —
validation-hooks.tsdefines the lifecycle hook types for schema validation observability. These hooks allow consumers… - coerce — The coerce utilities allow schemas to accept a broader range of input types by converting them before validation. They…
- compose — The compose utilities provide functional combinators for working with validation results and schemas.
mergeResultsag… - schema — (no submodules)- errors — (no submodules)- errors — (no submodules)- otel — (no submodules)- validation-otel — (no submodules)- array — (no submodules)- array — (no submodules)- boolean — (no submodules)- boolean — (no submodules)- date — (no submodules)- date — (no submodules)- enum — (no submodules)- enum — (no submodules)- intersection — (no submodules)- intersection — (no submodules)- literal — (no submodules)- literal — (no submodules)- nullable — (no submodules)- nullable — (no submodules)- number — (no submodules)- number — (no submodules)- object — (no submodules)- object — (no submodules)- optional — (no submodules)- optional — (no submodules)- record — (no submodules)- record — (no submodules)- string — (no submodules)- string — (no submodules)- tuple — (no submodules)- tuple — (no submodules)- union — (no submodules)- union — (no submodules)- common —
common.tsdefines the core type contracts shared across the entire@suaveplan/validationpackage: validation codes,… - validation-hooks —
validation-hooks.tsdefines the lifecycle hook types for schema validation observability. These hooks allow consumers… - coerce — The coerce utilities allow schemas to accept a broader range of input types by converting them before validation. They…
- compose — The compose utilities provide functional combinators for working with validation results and schemas.
mergeResultsag… - schema — (no submodules)- errors — (no submodules) - errors — (no submodules)- otel — (no submodules) - validation-otel — (no submodules)- array — (no submodules) - array — (no submodules)- boolean — (no submodules) - boolean — (no submodules)- date — (no submodules) - date — (no submodules)- enum — (no submodules) - enum — (no submodules)- intersection — (no submodules) - intersection — (no submodules)- literal — (no submodules) - literal — (no submodules)- nullable — (no submodules) - nullable — (no submodules)- number — (no submodules) - number — (no submodules)- object — (no submodules) - object — (no submodules)- optional — (no submodules) - optional — (no submodules)- record — (no submodules) - record — (no submodules)- string — (no submodules) - string — (no submodules)- tuple — (no submodules) - tuple — (no submodules)- union — (no submodules) - union — (no submodules)- common —
common.tsdefines the core type contracts shared across the entire@suaveplan/validationpackage: validation codes,… - validation-hooks —
validation-hooks.tsdefines the lifecycle hook types for schema validation observability. These hooks allow consumers… - coerce — The coerce utilities allow schemas to accept a broader range of input types by converting them before validation. They…
- compose — The compose utilities provide functional combinators for working with validation results and schemas.
mergeResultsag…
Features
- Exhaustive schema types:
string,number,boolean,date,array,object,record,tuple,literal,enum,union,intersection,optional,nullable parse()/safeParse()/parseAsync()/safeParseAsync()—parse()andsafeParse()throwVALIDATION.ASYNC_REFINEMENT_REQUIRES_PARSEASYNCwhen the schema carries any async refinement (no silent skip; useparseAsync()for async-refined schemas)refine()(sync and async),transform(),describe()- Object shape builders:
pick,omit,partial,extend,merge, three unknown-key modes - Input coercion utilities:
coerce,coerceString,coerceNumber,coerceBoolean,coerceDate - Functional combinators:
mergeResults,pipe - Structured errors:
ValidationErrorwithflatten()andformat(), 21 typed codes - OTel instrumentation: success/failure counters and duration histogram
Infer<S>type helper for extracting output types
Quick Start
import { object, string, number, array, Infer } from "@suaveplan/validation";
const UserSchema = object({
id: string().uuid(),
name: string().min(1).max(100),
age: number().int().min(0),
tags: array(string()).max(10),
});
type User = Infer<typeof UserSchema>;
const result = UserSchema.safeParse({ id: "550e8400-e29b-41d4-a716-446655440000", name: "Alice", age: 30, tags: [] });
if (result.success) {
console.log(result.data);
} else {
const { formErrors, fieldErrors } = result.error.flatten();
console.error(formErrors, fieldErrors);
}