552 lines
36 KiB
Plaintext
552 lines
36 KiB
Plaintext
page wrnexusvalidation {
|
|
seo {
|
|
title = "@wrnexus/validation"
|
|
description = "Typed schemas, coercion, validation, and browser descriptors."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<a href="#main" class="skip-link">Skip to content</a>
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.4</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main class="portal-main docs-layout">
|
|
<article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/validation</span></nav><section class="doc-intro"><span class="eyebrow">Security · Package reference</span><h1>@wrnexus/validation</h1><p>Typed schemas, coercion, validation, and browser descriptors.</p><div class="doc-meta"><span>v0.8.4</span><span>Private registry</span><span>Security</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/validation@0.8.4</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>One fluent schema, validated on the server (API bodies, env vars) and mirrored to an eval-free browser validator for forms.</blockquote>
|
|
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
|
|
<h3 id="boundary-contracts">Boundary contracts</h3>
|
|
<p>Use <code>ContractRegistry</code> with <code>defineContract</code> or <code>defineEvent</code> to publish the same schema descriptors for APIs, actions, webhooks, realtime, queues, cron, pub/sub, plugins, configuration, and environment variables.</p>
|
|
<pre data-language="ts"><code>import { ContractRegistry, defineEvent, v } from "@wrnexus/validation";
|
|
|
|
export const contracts = new ContractRegistry().register(
|
|
defineEvent({
|
|
name: "user.created",
|
|
version: 1,
|
|
consumers: ["notification-worker", "audit-service"],
|
|
payload: v.object({ userId: v.string().uuid(), createdAt: v.string().date() }),
|
|
}),
|
|
);</code></pre>
|
|
<p>Export the registry from <code>app/contracts.ts</code>, then accept a baseline with <code>wrnexus contracts snapshot</code>. CI can run <code>wrnexus contracts check</code>; removed contracts/fields, required-field additions, type changes, narrowed enums, and tighter validation fail with stable <code>WRN-CONTRACT-*</code> diagnostics and list known consumers. A generated <code>wrnexus.contracts.json</code> can be used instead of a module.</p>
|
|
<h3 id="overview">Overview</h3>
|
|
<p>Define a schema once with the fluent <code>v</code> builder, then reuse it in three places: <code>.parse()</code> runs server-side and returns coerced values plus per-field errors; <code>.describe()</code> emits a plain-JSON <code>SchemaDescriptor</code> that the browser runtime interprets (no <code>eval</code>, no bundled validator); and helpers like <code>parseBody</code> and <code>parseEnv</code> wire schemas straight into API routes and startup config. The server rule logic (<code>applyRule</code>/<code>checkField</code>) and the client runtime (<code>VALIDATE_RUNTIME</code>) mirror each other exactly, so a form validates identically in both places. Schemas are conventionally kept in <code>app/schemas/</code>.</p>
|
|
<pre data-language="bash"><code>bun add @wrnexus/validation</code></pre>
|
|
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
|
|
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
|
|
<h3 id="api">API</h3>
|
|
<h4 id="the-v-builder">The <code>v</code> builder</h4>
|
|
<pre data-language="ts"><code>import { v } from "@wrnexus/validation";</code></pre>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Factory</th><th>Returns</th><th>Field methods</th></tr></thead>
|
|
<tbody><tr><td><code>v.string()</code></td><td><code>StringSchema</code></td><td><code>email()</code>, <code>url()</code>, <code>uuid()</code>, <code>date()</code>, <code>length(n)</code>, <code>oneOf(string[])</code>, <code>pattern(re)</code>, <code>trim()</code>, <code>min(n)</code>, <code>max(n)</code></td></tr><tr><td><code>v.number()</code></td><td><code>NumberSchema</code></td><td><code>integer()</code>, <code>positive()</code>, <code>oneOf(number[])</code>, <code>min(n)</code>, <code>max(n)</code></td></tr><tr><td><code>v.boolean()</code></td><td><code>BooleanSchema</code></td><td>(base methods only)</td></tr><tr><td><code>v.object(fields)</code></td><td><code>ObjectSchema</code></td><td><code>parse(input)</code>, <code>describe()</code></td></tr></tbody></table></div>
|
|
<p>Every field schema is chainable and shares these base methods:</p>
|
|
<ul>
|
|
<li><code>min(n, message?)</code> / <code>max(n, message?)</code> — for strings, bounds the length; for numbers, bounds the value.</li>
|
|
<li><code>required(message?)</code> — require a non-empty value and optionally replace the default <code>"Required"</code> message on both server and browser validation.</li>
|
|
<li><code>optional()</code> — an empty/missing value passes instead of erroring <code>"Required"</code>.</li>
|
|
<li><code>label(text)</code> — human label carried into the descriptor.</li>
|
|
<li><code>default(value)</code> — value substituted when the field is absent (implies <code>optional</code>).</li>
|
|
<li><code>refine(fn, message?)</code> — <strong>server-only</strong> predicate. <code>fn</code> returns <code>true</code> (ok), <code>false</code> (use <code>message</code>), or a <code>string</code> (that error). Not serialized to the client.</li>
|
|
</ul>
|
|
<p>Each string rule accepts an optional trailing <code>message</code> to override the default error text.</p>
|
|
<h4 id="objectschema"><code>ObjectSchema</code></h4>
|
|
<pre data-language="ts"><code>schema.parse(input: unknown): ParseResult
|
|
schema.describe(): SchemaDescriptor</code></pre>
|
|
<p><code>parse</code> coerces each field (strings stay strings, <code>v.number()</code> runs <code>Number()</code>, <code>v.boolean()</code> treats <code>true</code> / <code>"true"</code> / <code>"on"</code> as true), applies its rules and refinements, fills in <code>default()</code> values, and returns:</p>
|
|
<pre data-language="ts"><code>interface ParseResult<T = Record<string, unknown>> {
|
|
ok: boolean; // true when errors is empty
|
|
value: T; // coerced values (present pass or fail)
|
|
errors: Record<string, string>; // field name → first failing message
|
|
}</code></pre>
|
|
<p><code>describe()</code> returns the JSON bridge for the client:</p>
|
|
<pre data-language="ts"><code>interface SchemaDescriptor {
|
|
type: "object";
|
|
fields: Record<string, FieldDescriptor>;
|
|
}
|
|
interface FieldDescriptor {
|
|
type: "string" | "number" | "boolean";
|
|
optional?: boolean;
|
|
label?: string;
|
|
trim?: boolean; // strings only
|
|
rules: RuleDescriptor[];
|
|
}</code></pre>
|
|
<h4 id="rules-and-coercion">Rules and coercion</h4>
|
|
<p><code>RuleDescriptor</code> is a discriminated union of the serializable rules — <code>min</code>, <code>max</code>, <code>length</code>, <code>email</code>, <code>url</code>, <code>uuid</code>, <code>date</code>, <code>oneOf</code>, <code>pattern</code>, <code>integer</code>. Two exported functions apply them and are shared by the server (the client runtime reimplements the same logic):</p>
|
|
<ul>
|
|
<li><code>applyRule(type, rule, value): string | null</code> — validate one already-coerced value against one rule.</li>
|
|
<li><code>checkField(desc, raw): { value, error }</code> — coerce and validate one field. Empty input (<code>undefined</code>/<code>null</code>/<code>""</code>) is <code>"Required"</code> unless <code>optional</code>. Strings with <code>trim</code> are trimmed first. Numbers that fail <code>Number()</code> yield <code>"Must be a number"</code>.</li>
|
|
</ul>
|
|
<p>Notes on specific rules: <code>email</code>/<code>url</code>/<code>uuid</code> test built-in regexes; <code>date</code> uses <code>Date.parse</code>; <code>pattern</code> reconstructs a <code>RegExp</code> from its <code>source</code>/<code>flags</code> and passes silently if the pattern is invalid; <code>integer</code> requires <code>Number.isInteger</code>; <code>positive()</code> is implemented as <code>min(Number.MIN_VALUE)</code>.</p>
|
|
<h4 id="api-helpers">API helpers</h4>
|
|
<pre data-language="ts"><code>invalid(errors: Record<string, string>): Response // ready 400 { ok:false, errors }
|
|
|
|
parseBody<T>(schema, req):
|
|
Promise<{ ok: true; value: T } | { ok: false; response: Response }></code></pre>
|
|
<p><code>parseBody</code> reads the request body from JSON, <code>application/x-www-form-urlencoded</code>, or <code>multipart/form-data</code>, validates it, and on failure hands back a ready 400 <code>Response</code>.</p>
|
|
<h4 id="environment-config">Environment config</h4>
|
|
<pre data-language="ts"><code>parseEnv<T>(schema: ObjectSchema, source?): T</code></pre>
|
|
<p>Validates env vars (from <code>Bun.env</code>, falling back to <code>process.env</code>) against a schema and coerces them (<code>PORT</code> → number, <code>DEBUG</code> → boolean). On any problem it throws <strong>one</strong> error listing every offending variable, so misconfiguration fails fast at startup.</p>
|
|
<h4 id="client-runtime-from-runtime-ts">Client runtime (from <code>runtime.ts</code>)</h4>
|
|
<pre data-language="ts"><code>renderSchemasScript(descriptors: Record<string, SchemaDescriptor>): string
|
|
VALIDATE_RUNTIME: string</code></pre>
|
|
<ul>
|
|
<li><code>renderSchemasScript</code> produces <code>window.__wireSchemas = { name: descriptor, … };</code> to inline in the page.</li>
|
|
<li><code>VALIDATE_RUNTIME</code> is a self-contained, eval-free IIFE string. Injected as a <code><script></code>, it binds every <code>form[data-schema]</code> and validates on submit and blur, writing messages into <code>[data-error="<field>"]</code> elements and toggling <code>aria-invalid</code> / <code>.wire-invalid</code>. On a valid submit it <code>fetch</code>es the form <code>action</code> as JSON (attaching the <code>wire-csrf</code> cookie as an <code>x-csrf-token</code> header), then follows <code>data-redirect</code> / a <code>redirect</code> in the response, surfaces server-side field errors, and fires <code>wire:success</code> / <code>wire:error</code> events. It exposes <code>window.__wireValidate.init(root)</code> and self-initializes on <code>DOMContentLoaded</code>.</li>
|
|
</ul>
|
|
<h3 id="usage">Usage</h3>
|
|
<p>Define a schema and validate an API body:</p>
|
|
<pre data-language="ts"><code>import { v, parseBody } from "@wrnexus/validation";
|
|
|
|
export const signupSchema = v.object({
|
|
email: v.string().required("Enter your email address").trim().email(),
|
|
password: v.string().required("Enter your password").min(8).max(200),
|
|
age: v.number().integer().min(13).max(120).optional(),
|
|
role: v.string().oneOf(["user", "admin"]).default("user"),
|
|
agree: v.boolean(),
|
|
});
|
|
|
|
// inside a route handler
|
|
const result = await parseBody(signupSchema, req);
|
|
if (!result.ok) return result.response; // ready 400 with field errors
|
|
const { email, password, role } = result.value;</code></pre>
|
|
<p>Server-only refinement:</p>
|
|
<pre data-language="ts"><code>const schema = v.object({
|
|
username: v
|
|
.string()
|
|
.min(3)
|
|
.refine((name) => !RESERVED.has(String(name)), "That name is taken"),
|
|
});</code></pre>
|
|
<p>Validate environment at startup:</p>
|
|
<pre data-language="ts"><code>import { v, parseEnv } from "@wrnexus/validation";
|
|
|
|
export const env = parseEnv(
|
|
v.object({
|
|
DATABASE_URL: v.string().min(1),
|
|
PORT: v.number().integer().default(3000),
|
|
DEBUG: v.boolean().optional(),
|
|
}),
|
|
);
|
|
// throws one readable error listing every bad variable if misconfigured</code></pre>
|
|
<p>Wire the same schema into the browser:</p>
|
|
<pre data-language="ts"><code>import { renderSchemasScript, VALIDATE_RUNTIME } from "@wrnexus/validation";
|
|
import { signupSchema } from "./app/schemas/signup.ts";
|
|
|
|
const head = `<script>${renderSchemasScript({ signup: signupSchema.describe() })}</script>
|
|
<script>${VALIDATE_RUNTIME}</script>`;
|
|
// render a <form data-schema="signup"> with [data-error="email"] etc.</code></pre>
|
|
<h3 id="requirements-notes">Requirements / Notes</h3>
|
|
<ul>
|
|
<li><strong>Bun-only.</strong> <code>parseEnv</code> reads <code>Bun.env</code> (falling back to <code>process.env</code>); <code>parseBody</code> and <code>invalid</code> use the Web <code>Request</code>/<code>Response</code> APIs that back <code>Bun.serve</code>.</li>
|
|
<li>Refinements (<code>refine</code>) run only server-side and are never serialized — client and server agree on every other rule because both interpret the same <code>RuleDescriptor</code> list.</li>
|
|
<li>No runtime dependencies. Ships as TypeScript source (<code>src/index.ts</code>) executed directly by Bun.</li>
|
|
<li>Pairs with the WRNexusJS server (<code>@wrnexus/core</code>) for route handlers and the SSR layer that injects <code>renderSchemasScript</code> / <code>VALIDATE_RUNTIME</code>.</li>
|
|
</ul>
|
|
<h3 id="helper-and-component-kit">Helper and component kit</h3>
|
|
<p>The public helper API includes <code>parseOrThrow</code>, <code>ValidationError</code>, <code>validationResponse</code>, <code>firstValidationError</code>, <code>validationSummary</code>, and <code>schemaFieldNames</code>.</p>
|
|
<p>Schema output is inferred automatically by <code>ObjectSchema</code>, <code>parseOrThrow</code>, <code>parseBody</code>, <code>parseEnv</code>, and <code>asyncSchema</code>. Use <code>InferSchema<typeof schema></code> when a named output type is useful:</p>
|
|
<pre data-language="ts"><code>const accountSchema = v.object({
|
|
email: v.string().email(),
|
|
attempts: v.number().integer(),
|
|
});
|
|
|
|
type AccountInput = InferSchema<typeof accountSchema>;
|
|
const account = parseOrThrow(accountSchema, input);
|
|
// account.email: string
|
|
// account.attempts: number</code></pre>
|
|
<p>Enable <code>validationPlugin()</code> for:</p>
|
|
<ul>
|
|
<li><code><ValidationSummary /></code></li>
|
|
<li><code><FieldError /></code></li>
|
|
</ul>
|
|
<p>The summary block composes <code>Alert</code> from <code>@wrnexus/ui</code>, while <code>FieldError</code> remains a lightweight accessible field-level primitive. Schemas can drive external contracts without maintaining a second definition:</p>
|
|
<pre data-language="ts"><code>import {
|
|
localizeDescriptor,
|
|
openApiRequestBody,
|
|
parseDescriptor,
|
|
toJsonSchema,
|
|
} from "@wrnexus/validation";
|
|
|
|
const jsonSchema = toJsonSchema(contactSchema, {
|
|
id: "urn:example:contact",
|
|
title: "Contact request",
|
|
});
|
|
const requestBody = openApiRequestBody(contactSchema);
|
|
|
|
const mr = localizeDescriptor(contactSchema, (key, params) =>
|
|
translations.t(`validation.${key}`, params),
|
|
);
|
|
const result = parseDescriptor(mr, input);</code></pre>
|
|
<p>JSON Schema output targets draft 2020-12, closes unknown object properties, and maps lengths/ranges/formats/enums/patterns/integer rules. OpenAPI request bodies reuse the same properties. Localized descriptors preserve explicit custom messages and fill default required, type-coercion, and rule messages; the same descriptor is consumable by server parsing and the eval-free browser runtime.</p></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>export { ValidationPluginOptions, validationComponentsDir, default as validationPlugin } from './plugin.js';
|
|
import '@wrnexus/plugin';
|
|
|
|
/**
|
|
* Client-side validation. `renderSchemasScript` bakes the discovered schema
|
|
* descriptors into `window.__wireSchemas`; `VALIDATE_RUNTIME` is a generic,
|
|
* eval-free validator that reads them and validates every `form[data-schema]`
|
|
* on submit and blur, writing messages into `[data-error="<field>"]` elements.
|
|
* The rule logic mirrors `checkField`/`applyRule` in index.ts.
|
|
*/
|
|
|
|
/** `window.__wireSchemas = { name: descriptor, ... }` for the client validator. */
|
|
declare function renderSchemasScript(descriptors: Record<string, SchemaDescriptor>): string;
|
|
declare const VALIDATE_RUNTIME: string;
|
|
|
|
interface AsyncValidationContext<T> {
|
|
value: T;
|
|
addIssue(field: keyof T | string, message: string): void;
|
|
signal?: AbortSignal;
|
|
}
|
|
type AsyncRefinement<T> = (context: AsyncValidationContext<T>) => void | Promise<void>;
|
|
declare class AsyncObjectSchema<T extends object = Record<string, unknown>> {
|
|
#private;
|
|
readonly base: ObjectSchema<T>;
|
|
constructor(base: ObjectSchema<T>);
|
|
refine(refinement: AsyncRefinement<T>): this;
|
|
describe(): SchemaDescriptor;
|
|
parse(input: unknown, signal?: AbortSignal): Promise<ParseResult<T>>;
|
|
}
|
|
declare function asyncSchema<T extends object>(schema: ObjectSchema<T>): AsyncObjectSchema<T>;
|
|
declare function parseBodyAsync<T extends object>(schema: AsyncObjectSchema<T>, request: Request, signal?: AbortSignal): Promise<{
|
|
ok: true;
|
|
value: T;
|
|
} | {
|
|
ok: false;
|
|
response: Response;
|
|
}>;
|
|
interface OpenApiSchema {
|
|
type: "object";
|
|
properties: Record<string, Record<string, unknown>>;
|
|
required?: string[];
|
|
}
|
|
declare function schemaToOpenApi(schema: ObjectSchema | AsyncObjectSchema): OpenApiSchema;
|
|
declare function mergeValidationResults<T>(...results: ParseResult<T>[]): ParseResult<T>;
|
|
|
|
declare class ValidationError<T = Record<string, unknown>> extends Error {
|
|
readonly result: ParseResult<T>;
|
|
constructor(result: ParseResult<T>);
|
|
}
|
|
declare function parseOrThrow<T extends object>(schema: ObjectSchema<T>, input: unknown): T;
|
|
declare function validationResponse(result: ParseResult, options?: {
|
|
successStatus?: number;
|
|
failureStatus?: number;
|
|
}): Response;
|
|
declare function firstValidationError(errors: Record<string, string>): string | null;
|
|
declare function validationSummary(errors: Record<string, string>): Array<{
|
|
field: string;
|
|
message: string;
|
|
}>;
|
|
declare function schemaFieldNames(schema: ObjectSchema | SchemaDescriptor): string[];
|
|
|
|
interface JsonSchemaDocument {
|
|
$schema: "https://json-schema.org/draft/2020-12/schema";
|
|
$id?: string;
|
|
title?: string;
|
|
type: "object";
|
|
properties: Record<string, Record<string, unknown>>;
|
|
required?: string[];
|
|
additionalProperties: false;
|
|
}
|
|
declare function toJsonSchema(schema: ObjectSchema | SchemaDescriptor, options?: {
|
|
id?: string;
|
|
title?: string;
|
|
}): JsonSchemaDocument;
|
|
declare function openApiRequestBody(schema: ObjectSchema | SchemaDescriptor, options?: {
|
|
description?: string;
|
|
required?: boolean;
|
|
contentTypes?: string[];
|
|
}): {
|
|
required: boolean;
|
|
content: {
|
|
[k: string]: {
|
|
schema: {
|
|
$id?: string;
|
|
title?: string;
|
|
type: "object";
|
|
properties: Record<string, Record<string, unknown>>;
|
|
required?: string[];
|
|
additionalProperties: false;
|
|
};
|
|
};
|
|
};
|
|
description?: string | undefined;
|
|
};
|
|
type ValidationMessageKey = "required" | "number" | `rule.${RuleDescriptor["kind"]}`;
|
|
type ValidationMessageTranslator = (key: ValidationMessageKey, params: Record<string, unknown>) => string;
|
|
declare function localizeDescriptor(schema: ObjectSchema | SchemaDescriptor, translate: ValidationMessageTranslator): SchemaDescriptor;
|
|
declare function parseDescriptor<T = Record<string, unknown>>(descriptor: SchemaDescriptor, source: Record<string, unknown>): ParseResult<T>;
|
|
|
|
type ContractKind = "api" | "action" | "webhook" | "realtime" | "queue" | "cron" | "pubsub" | "plugin" | "config" | "env";
|
|
interface ContractDefinition<T extends object = Record<string, unknown>> {
|
|
kind: ContractKind;
|
|
name: string;
|
|
version: number;
|
|
payload: ObjectSchema<T> | SchemaDescriptor;
|
|
consumers?: string[];
|
|
description?: string;
|
|
}
|
|
interface ContractRecord {
|
|
kind: ContractKind;
|
|
name: string;
|
|
version: number;
|
|
payload: SchemaDescriptor;
|
|
consumers: string[];
|
|
description?: string;
|
|
}
|
|
interface ContractSnapshot {
|
|
format: 1;
|
|
contracts: ContractRecord[];
|
|
}
|
|
interface ContractIssue {
|
|
code: "WRN-CONTRACT-REMOVED" | "WRN-CONTRACT-FIELD-REMOVED" | "WRN-CONTRACT-FIELD-REQUIRED" | "WRN-CONTRACT-FIELD-TYPE" | "WRN-CONTRACT-RULE-TIGHTENED";
|
|
contract: string;
|
|
field?: string;
|
|
message: string;
|
|
consumers: string[];
|
|
}
|
|
declare function defineContract<T extends object>(definition: ContractDefinition<T>): ContractDefinition<T>;
|
|
declare function defineEvent<T extends object>(definition: Omit<ContractDefinition<T>, "kind"> & {
|
|
kind?: "realtime" | "pubsub";
|
|
}): ContractDefinition<T>;
|
|
declare class ContractRegistry {
|
|
private readonly records;
|
|
register<T extends object>(definition: ContractDefinition<T>): this;
|
|
snapshot(): ContractSnapshot;
|
|
}
|
|
declare function checkContractCompatibility(previous: ContractSnapshot, current: ContractSnapshot): ContractIssue[];
|
|
|
|
/**
|
|
* @wrnexus/validation — one schema, validated on the server (API) and the browser
|
|
* (forms). A schema is a fluent builder; `.parse()` runs server-side and returns
|
|
* coerced values + field errors, while `.describe()` emits a JSON descriptor the
|
|
* eval-free client validator interprets. Define schemas once in `app/schemas/`.
|
|
*/
|
|
type RuleDescriptor = {
|
|
kind: "min";
|
|
n: number;
|
|
message?: string;
|
|
} | {
|
|
kind: "max";
|
|
n: number;
|
|
message?: string;
|
|
} | {
|
|
kind: "length";
|
|
n: number;
|
|
message?: string;
|
|
} | {
|
|
kind: "email";
|
|
message?: string;
|
|
} | {
|
|
kind: "url";
|
|
message?: string;
|
|
} | {
|
|
kind: "uuid";
|
|
message?: string;
|
|
} | {
|
|
kind: "date";
|
|
message?: string;
|
|
} | {
|
|
kind: "oneOf";
|
|
values: (string | number)[];
|
|
message?: string;
|
|
} | {
|
|
kind: "pattern";
|
|
source: string;
|
|
flags?: string;
|
|
message?: string;
|
|
} | {
|
|
kind: "integer";
|
|
message?: string;
|
|
};
|
|
interface FieldDescriptor {
|
|
type: "string" | "number" | "boolean" | "unknown";
|
|
optional?: boolean;
|
|
/** Message used when a required field is empty. Defaults to "Required". */
|
|
requiredMessage?: string;
|
|
/** Message used when coercion to the declared type fails. */
|
|
typeMessage?: string;
|
|
label?: string;
|
|
/** Trim string input before validating. */
|
|
trim?: boolean;
|
|
rules: RuleDescriptor[];
|
|
}
|
|
interface SchemaDescriptor {
|
|
type: "object";
|
|
fields: Record<string, FieldDescriptor>;
|
|
}
|
|
interface ParseResult<T = Record<string, unknown>> {
|
|
ok: boolean;
|
|
/** Coerced values (present whether or not validation passed). */
|
|
value: T;
|
|
/** Field name → message, only for fields that failed. */
|
|
errors: Record<string, string>;
|
|
}
|
|
/**
|
|
* Apply one rule to an already-coerced value. Shared by the server; the client
|
|
* runtime (runtime.ts) mirrors this exactly. Returns an error message or null.
|
|
*/
|
|
declare function applyRule(type: string, rule: RuleDescriptor, value: unknown): string | null;
|
|
/** Coerce + validate one field against its descriptor. */
|
|
declare function checkField(desc: FieldDescriptor, raw: unknown): {
|
|
value: unknown;
|
|
error: string | null;
|
|
};
|
|
/** A server-only refinement (a predicate that can't be serialized to the client). */
|
|
type Refinement = {
|
|
fn: (value: unknown) => boolean | string;
|
|
message?: string;
|
|
};
|
|
declare abstract class FieldSchema {
|
|
abstract readonly type: "string" | "number" | "boolean" | "unknown";
|
|
protected _optional: boolean;
|
|
protected _requiredMessage?: string;
|
|
protected _label?: string;
|
|
protected _default?: unknown;
|
|
protected rules: RuleDescriptor[];
|
|
protected refinements: Refinement[];
|
|
optional(): this;
|
|
/** Require a non-empty value and optionally replace the default message. */
|
|
required(message?: string): this;
|
|
label(label: string): this;
|
|
/** Value used when the field is absent (implies optional). */
|
|
default(value: unknown): this;
|
|
min(n: number, message?: string): this;
|
|
max(n: number, message?: string): this;
|
|
/**
|
|
* Custom SERVER-side validation. `fn` returns true (ok), false (use `message`),
|
|
* or a string (that error). Not mirrored to the client validator.
|
|
*/
|
|
refine(fn: (value: unknown) => boolean | string, message?: string): this;
|
|
getDefault(): unknown;
|
|
runRefinements(value: unknown): string | null;
|
|
describe(): FieldDescriptor;
|
|
}
|
|
declare class StringSchema<TValue extends string = string> extends FieldSchema {
|
|
/** Type-only marker used to preserve literal unions through schema inference. */
|
|
readonly __value: TValue;
|
|
readonly type: "string";
|
|
private _trim;
|
|
email(message?: string): this;
|
|
url(message?: string): this;
|
|
uuid(message?: string): this;
|
|
date(message?: string): this;
|
|
length(n: number, message?: string): this;
|
|
oneOf<const TValues extends readonly string[]>(values: TValues, message?: string): StringSchema<TValues extends readonly [string, ...string[]] ? TValues[number] : TValue>;
|
|
trim(): this;
|
|
pattern(re: RegExp, message?: string): this;
|
|
describe(): FieldDescriptor;
|
|
}
|
|
declare class NumberSchema<TValue extends number = number> extends FieldSchema {
|
|
/** Type-only marker used to preserve numeric literal unions through schema inference. */
|
|
readonly __value: TValue;
|
|
readonly type: "number";
|
|
integer(message?: string): this;
|
|
positive(message?: string): this;
|
|
oneOf<const TValues extends readonly number[]>(values: TValues, message?: string): NumberSchema<TValues extends readonly [number, ...number[]] ? TValues[number] : TValue>;
|
|
}
|
|
declare class BooleanSchema extends FieldSchema {
|
|
readonly type: "boolean";
|
|
}
|
|
declare class UnknownSchema extends FieldSchema {
|
|
readonly type: "unknown";
|
|
}
|
|
type AnyFieldSchema = StringSchema<string> | NumberSchema<number> | BooleanSchema | UnknownSchema;
|
|
/** Infer the runtime value produced by a field schema. */
|
|
type InferFieldValue<TField extends FieldSchema> = TField extends StringSchema<infer TValue> ? TValue : TField extends NumberSchema<infer TValue> ? TValue : TField extends BooleanSchema ? boolean : unknown;
|
|
/** Infer the validated object produced by a field map. */
|
|
type InferObjectFields<TFields extends Record<string, FieldSchema>> = {
|
|
[K in keyof TFields]: InferFieldValue<TFields[K]>;
|
|
};
|
|
/** Infer the object value produced by an object schema. */
|
|
type InferSchema<TSchema extends ObjectSchema> = TSchema extends ObjectSchema<infer TValue> ? TValue : never;
|
|
declare class ObjectSchema<TValue extends object = Record<string, unknown>> {
|
|
private readonly fields;
|
|
/** Type-only marker used by helper functions to infer validated output. */
|
|
readonly __output: TValue;
|
|
constructor(fields: Record<string, FieldSchema>);
|
|
/** Return a defensive copy of the schema fields. */
|
|
getFields(): Readonly<Record<string, FieldSchema>>;
|
|
/** Create a new schema with fields added or replaced. The original is unchanged. */
|
|
extend<TFields extends Record<string, FieldSchema>>(fields: TFields): ObjectSchema<Omit<TValue, keyof TFields> & InferObjectFields<TFields>>;
|
|
/** Create a new schema containing fields from both schemas. */
|
|
merge<TOther extends object>(schema: ObjectSchema<TOther>): ObjectSchema<TValue & TOther>;
|
|
/** Validate an input object; returns coerced values + per-field errors. */
|
|
parse(input: unknown): ParseResult<TValue>;
|
|
describe(): SchemaDescriptor;
|
|
}
|
|
/** The fluent schema builder. */
|
|
declare const v: {
|
|
string: () => StringSchema<string>;
|
|
number: () => NumberSchema<number>;
|
|
boolean: () => BooleanSchema;
|
|
unknown: () => UnknownSchema;
|
|
object: <TFields extends Record<string, FieldSchema>>(fields: TFields) => ObjectSchema<InferObjectFields<TFields>>;
|
|
};
|
|
/**
|
|
* Validate environment variables against a schema at startup. Values are read
|
|
* from `Bun.env` / `process.env` by default and coerced by the schema (so
|
|
* `PORT` becomes a number, `DEBUG` a boolean). On any problem it throws ONE
|
|
* readable error listing every offending variable, so misconfiguration fails
|
|
* fast with an actionable message instead of surfacing deep inside the app.
|
|
*
|
|
* export const env = parseEnv(v.object({
|
|
* DATABASE_URL: v.string().min(1),
|
|
* PORT: v.number(),
|
|
* }));
|
|
*/
|
|
declare function parseEnv<T extends object>(schema: ObjectSchema<T>, source?: Record<string, string | undefined>): T;
|
|
/** A 400 response carrying field errors, for API routes. */
|
|
declare function invalid(errors: Record<string, string>): Response;
|
|
/**
|
|
* Parse a request's JSON body against a schema. On failure returns
|
|
* `{ ok: false, response }` (a ready 400); on success `{ ok: true, value }`.
|
|
*/
|
|
declare function parseBody<T extends object>(schema: ObjectSchema<T>, req: Request): Promise<{
|
|
ok: true;
|
|
value: T;
|
|
} | {
|
|
ok: false;
|
|
response: Response;
|
|
}>;
|
|
|
|
export { type AnyFieldSchema, AsyncObjectSchema, type AsyncRefinement, type AsyncValidationContext, BooleanSchema, type ContractDefinition, type ContractIssue, type ContractKind, type ContractRecord, ContractRegistry, type ContractSnapshot, type FieldDescriptor, FieldSchema, type InferFieldValue, type InferObjectFields, type InferSchema, type JsonSchemaDocument, NumberSchema, ObjectSchema, type OpenApiSchema, type ParseResult, type RuleDescriptor, type SchemaDescriptor, StringSchema, UnknownSchema, VALIDATE_RUNTIME, ValidationError, type ValidationMessageKey, type ValidationMessageTranslator, applyRule, asyncSchema, checkContractCompatibility, checkField, defineContract, defineEvent, firstValidationError, invalid, localizeDescriptor, mergeValidationResults, openApiRequestBody, parseBody, parseBodyAsync, parseDescriptor, parseEnv, parseOrThrow, renderSchemasScript, schemaFieldNames, schemaToOpenApi, toJsonSchema, v, validationResponse, validationSummary };
|
|
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>Define a schema and validate an API body</h3><pre data-language="ts"><code>import { v, parseBody } from "@wrnexus/validation";
|
|
|
|
export const signupSchema = v.object({
|
|
email: v.string().required("Enter your email address").trim().email(),
|
|
password: v.string().required("Enter your password").min(8).max(200),
|
|
age: v.number().integer().min(13).max(120).optional(),
|
|
role: v.string().oneOf(["user", "admin"]).default("user"),
|
|
agree: v.boolean(),
|
|
});
|
|
|
|
// inside a route handler
|
|
const result = await parseBody(signupSchema, req);
|
|
if (!result.ok) return result.response; // ready 400 with field errors
|
|
const { email, password, role } = result.value;</code></pre></article><article class="example-card"><h3>Server-only refinement</h3><pre data-language="ts"><code>const schema = v.object({
|
|
username: v
|
|
.string()
|
|
.min(3)
|
|
.refine((name) => !RESERVED.has(String(name)), "That name is taken"),
|
|
});</code></pre></article><article class="example-card"><h3>Validate environment at startup</h3><pre data-language="ts"><code>import { v, parseEnv } from "@wrnexus/validation";
|
|
|
|
export const env = parseEnv(
|
|
v.object({
|
|
DATABASE_URL: v.string().min(1),
|
|
PORT: v.number().integer().default(3000),
|
|
DEBUG: v.boolean().optional(),
|
|
}),
|
|
);
|
|
// throws one readable error listing every bad variable if misconfigured</code></pre></article><article class="example-card"><h3>Wire the same schema into the browser</h3><pre data-language="ts"><code>import { renderSchemasScript, VALIDATE_RUNTIME } from "@wrnexus/validation";
|
|
import { signupSchema } from "./app/schemas/signup.ts";
|
|
|
|
const head = `<script>${renderSchemasScript({ signup: signupSchema.describe() })}</script>
|
|
<script>${VALIDATE_RUNTIME}</script>`;
|
|
// render a <form data-schema="signup"> with [data-error="email"] etc.</code></pre></article></div></section></article>
|
|
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#boundary-contracts">Boundary contracts</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#the-v-builder">The v builder</a><a class="toc-level-4" href="#objectschema">ObjectSchema</a><a class="toc-level-4" href="#rules-and-coercion">Rules and coercion</a><a class="toc-level-4" href="#api-helpers">API helpers</a><a class="toc-level-4" href="#environment-config">Environment config</a><a class="toc-level-4" href="#client-runtime-from-runtime-ts">Client runtime (from runtime.ts)</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-3" href="#helper-and-component-kit">Helper and component kit</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
|
</main>
|
|
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.4</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
|
</div>
|
|
}
|
|
}
|