[WIP] V6

[ealush]

Q	A
Bug fix?	✔/✖
New feature?	✔/✖
Breaking change?	✔/✖
Deprecations?	✔/✖
Documentation?	✔/✖
Tests added?	✔/✖
Types added?	✔/✖
Related issues

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
vest	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 2, 2025 10:00pm
vest-next	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 2, 2025 10:00pm

[Copilot]

Pull Request Overview

This pull request involves updating suite method invocation from direct function calls to using .run() method across documentation and codebase. The changes primarily focus on modifying examples and test files to use the new API pattern.

• Replace direct suite invocation suite() with suite.run() method calls
• Update documentation examples and code samples to reflect the new API
• Refactor internal test utilities and helper functions to use the new pattern

Reviewed Changes

Copilot reviewed 163 out of 165 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
website/versioned_docs/version-4.x/writing_your_suite/optional_fields.md	Update code examples from suite() to suite.run()
website/versioned_docs/version-4.x/utilities/classnames.md	Update suite invocation in utility examples
website/versioned_docs/version-4.x/upgrade_guide.md	Update migration examples to use .run() method
website/docs/writing_your_suite/optional_fields.md	Update documentation examples to use new API
website/docs/writing_your_suite/dirty_checking.md	Update dirty checking examples
website/docs/utilities/classnames.md	Update classnames utility examples
website/docs/upgrade_guide.md	Update upgrade guide examples
website/docs/typescript_support.md	Update TypeScript examples and fix documentation typo
website/docs/server_side_validations.md	Update server-side validation examples
packages/vest/src/testUtils/suiteDummy.ts	Update test utilities to use .run() method
packages/vest/src/suiteResult/selectors/tests/*.test.ts	Update test files to use new API pattern

[Copilot]

The documentation incorrectly states that SuiteResult is 'the same as SuiteResult' - this appears to be a copy-paste error. It should likely state 'the same as SuiteRunResult' or provide a clearer distinction between the two types.

Suggested change

	Non-actionable suite result, meaning - the same as SuiteResult, but without the `done()` function. The return type of `suite.get()`.
	Non-actionable suite result, meaning - the same as SuiteRunResult, but without the `done()` function. The return type of `suite.get()`.

[the-ult]

Great to see you are working on a v6.
Do you have a summary of what the intention of this new major version is? What improvements do you have in mind, etc.

And is standardschema something that could be applied? Or does it serve a completely different purpose? So vestjs is more / easier compatible with tooling supporting the standardschema?

[the-ult]

I checked out the PR and use Claude Sonnet 4.5 to help with an analysis if VestJs could implement/be compatible with StandardSchema

This was the result :-) Might give you some great (extra) insights/ideas?

---

StandardSchema Support - PR Feedback/Suggestion

Summary

Add StandardSchema support to enable dual-layer validation: Zod/Valibot for type validation (shared across your entire stack) + Vest.js for business logic (async checks, cross-field rules, progressive UX). Best of both worlds.

Recommendation

** Implement StandardSchema support in the n4s/enforce package**

Why This Matters

The Opportunity: Complementary, Not Competing

Key Insight from ngx-vest-forms: Zod and Vest.js solve different problems and are stronger together:

• Zod/Valibot (Layer 1): Type/structure validation (sync, portable, ecosystem-wide)
• Vest.js (Layer 2): Business logic validation (async, UX-focused, form-specific)

The Value Proposition

StandardSchema support enables:

1. Dual-Layer Validation

   User Input → Zod validates type/structure → Vest validates business logic → ✅
   

2. Ecosystem Integration (The killer feature!)

   • Share same Zod schema in Angular, React, tRPC, Hono, TanStack Form
   • Vest adds business logic layer on top
   • One schema for entire stack (frontend + backend)

3. Performance Optimization

   • Type validation acts as "gatekeeper"
   • Skip expensive async checks when structure invalid
   • ~0.1ms type check vs ~50-200ms async check = 99.9% faster

4. Framework Compatibility

   • 30+ tools accept StandardSchema (Angular v21+, TanStack, React Hook Form, tRPC, Hono)
   • Vest becomes the business logic layer for all of them

Implementation Approach

Extend n4s/enforce (NOT Vest Suites) with Three-Tier API

// Create schema with enforce.shape()
const userSchema = enforce.shape({
  username: enforce.isString().longerThan(3),
  email: enforce.isString().matches(/^.+@.+\..+$/),
});

// 1️⃣ Existing API (unchanged - backward compatible)
const result1 = userSchema.run(userData); // {pass: boolean, message?: string}
const result2 = userSchema.test(userData); // boolean

// 2️⃣ NEW: Zod/Valibot-like API (better DX, easier migration)
try {
  const validated = userSchema.parse(userData); // throws on error
  console.log('Valid:', validated);
} catch (error) {
  console.log('Invalid:', error.message);
}

const safeResult = userSchema.safeParse(userData);
if (safeResult.success) {
  console.log('Valid:', safeResult.data);
} else {
  console.log('Errors:', safeResult.errors);
}

// 3️⃣ NEW: StandardSchema API (for framework integration)
const control = new FormControl('', {
  validators: [userSchema['~standard'].validate],
});

Why Three APIs?

• run()/test() - Existing users keep their code working
• parse()/safeParse() - Zod/Valibot users feel at home
• ~standard.validate() - Framework integration (Angular, React Hook Form, etc.)

Impact

Aspect	Impact
Strategic Positioning	✅ Complementary to Zod/Valibot (not competing)
Ecosystem Integration	✅ Share schemas across entire stack (Angular, React, tRPC, Hono, etc.)
Performance	✅ Skip expensive checks when type validation fails (99.9% faster)
Breaking Changes	✅ Zero (additive only)
Framework Support	✅ 30+ tools (Angular, React Hook Form, TanStack, tRPC, Hono)
Bundle Size	✅ ~2KB increase (parse/safeParse methods)
Architecture Fit	✅ Perfect match with n4s/enforce
Migration from Zod	✅ Easy - same .parse() and .safeParse() methods
Developer Experience	✅ Dual-layer validation - types + business logic
Development Time	⚠️ 5 weeks (4 phases)

Why n4s/enforce (Not Vest Suites)?

Aspect	n4s/enforce	Vest Suites	StandardSchema Requires
Target	Single value ✅	Multiple fields ❌	Single value
State	Stateless ✅	Stateful ❌	Stateless
Result	Simple ✅	Rich metadata ❌	Simple
Use Case	Schema validation ✅	Form flow ❌	Schema validation

Vest Suites are for complex form validation flows with state management.
n4s/enforce is for simple schema/value validation (like Zod/Yup) - perfect for StandardSchema.

What Users Get

Before v6: Single-Layer Validation

// ❌ Everything in Vest (mixing type validation with business logic)
const userSuite = vest.create(data => {
  // Type validation in Vest (awkward)
  vest.test('email', 'Must be a string', () => {
    enforce(typeof data.email).equals('string');
  });

  vest.test('email', 'Invalid format', () => {
    enforce(data.email).matches(/^.+@.+$/);
  });

  // Business validation in Vest (correct place)
  vest.test('email', 'Already taken', async () => {
    await checkEmailAvailability(data.email);
  });
});

// Problems:
// 🔴 Can't share schema with backend/tRPC
// 🔴 Type checks always run (even on invalid data)
// 🔴 No type inference

After v6: Dual-Layer Validation ⭐

// ✅ Layer 1: Type validation (Zod - portable everywhere)
const UserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// ✅ Layer 2: Business validation (Vest - form UX)
const userSuite = vest.create((data: z.infer<typeof UserSchema>) => {
  vest.test('email', 'Already taken', async () => {
    await checkEmailAvailability(data.email);
  });

  vest.test('password', 'Passwords must match', () => {
    enforce(data.password).equals(data.confirmPassword);
  });
});

// Use the SAME schema everywhere:

// 1️⃣ Angular forms (Zod type check + Vest business logic)
const form = createVestForm(userSuite, model, {
  schema: UserSchema, // Layer 1: Type validation
});

// 2️⃣ tRPC backend (same schema!)
const router = t.router({
  createUser: t.procedure
    .input(UserSchema) // ✅ Same type validation
    .mutation(async ({ input }) => db.users.create(input)),
});

// 3️⃣ React forms (TanStack, React Hook Form)
const reactForm = useForm({
  validators: { onChange: UserSchema }, // ✅ Same schema
});

// 4️⃣ Hono API routes
app.post('/users', zValidator('json', UserSchema), async c => {
  // ✅ Same schema validates API input
});

// Benefits:
// ✅ Single source of truth (one schema, entire stack)
// ✅ Type safety everywhere (frontend + backend)
// ✅ Performance (skip Vest when Zod fails)
// ✅ Clear separation (types vs business logic)

🚀 Strategic Positioning: Complementary, Not Competing

The Ecosystem Play

Vest v6 doesn't compete with Zod/Valibot - it complements them!

┌─────────────────────────────────────────────┐
│        Modern Validation Stack              │
├─────────────────────────────────────────────┤
│  Layer 1: Type/Structure Validation         │
│  • Zod, Valibot, ArkType                    │
│  • Sync, portable, type-safe                │
│  • Used: Angular, React, tRPC, Hono, etc.   │
├─────────────────────────────────────────────┤
│  Layer 2: Business Logic Validation         │
│  • Vest.js ← WE FIT HERE!                   │
│  • Async, cross-field, UX-focused           │
│  • Used: Forms (progressive disclosure)     │
└─────────────────────────────────────────────┘

Competitive Analysis

Library	Type Validation	Business Logic	Async Support	Form UX	Ecosystem
Zod	✅ Excellent	⚠️ Basic	⚠️ Limited	❌	✅ Wide
Valibot	✅ Excellent	⚠️ Basic	⚠️ Limited	❌	✅ Wide
Yup	✅ Good	⚠️ Basic	✅ Good	❌	✅ Wide
Vest v6	⚠️ Via enforce	✅ Best	✅ Best	✅ Best	✅ NEW!

Vest's Unique Position:

• ✅ Best business logic validation (async, cross-field, conditional)
• ✅ Best form UX (progressive disclosure, touch state, warnings)
• ✅ Works WITH Zod/Valibot (not instead of)
• ✅ Full-stack solution (share Zod types, add Vest business logic)

Real-World Use Case

E-commerce Registration Form:

// Type validation (shared with backend)
const UserSchema = z.object({
  email: z.string().email(),
  age: z.number().min(0).max(150),
});

// Business validation (frontend only)
const userSuite = vest.create((data: z.infer<typeof UserSchema>) => {
  // Email availability (async API check)
  vest.test('email', 'Email already registered', async () => {
    await fetch(`/api/check-email/${data.email}`);
  });

  // Age requirement (business rule)
  vest.test('age', 'Must be 18+', () => {
    enforce(data.age).greaterThanOrEquals(18);
  });
});

// User types "invalid"
// ⚡ Zod fails: "Invalid email" (0.1ms)
// 🚫 Vest SKIPPED (no wasted API call)

// User types "test@example.com"
// ✅ Zod passes
// ⏳ Vest runs: check availability (50-200ms)

Performance Gain: 99.9% faster by skipping async checks on invalid types!

Ecosystem Compatibility

Frameworks accepting StandardSchema:

• ✅ Angular Signal Forms v21+
• ✅ TanStack Form (React, Vue, Solid)
• ✅ React Hook Form
• ✅ tRPC (API type safety)
• ✅ Hono (web framework)
• ✅ UploadThing
• ✅ 25+ more tools

Vest v6 positions as:

• "The business logic layer" for StandardSchema ecosystem
• Works seamlessly WITH Zod/Valibot (not replacing them)
• Unique value: async validation + form UX that type validators lack

Documentation

Full analysis and implementation details in:

• STANDARDSCHEMA_DUAL_LAYER_APPROACH.md - NEW! How Zod + Vest work together
• INSIGHTS_FROM_NGX_VEST_FORMS.md - NEW! Key learnings and action items
• STANDARDSCHEMA_ANALYSIS.md - Technical analysis and implementation options
• PRD_STANDARDSCHEMA_SUPPORT.md - Complete PRD with requirements
• website/docs/upgrade_guide_v6.md - User migration guide
• STANDARDSCHEMA_DOCS_README.md - Documentation index

❓ Questions & Concerns

Q: Doesn't this just make Vest a Zod clone?

A: No! This is the key insight: Zod and Vest solve different problems and work better together.

• Zod: Type/structure validation (portable, ecosystem-wide)
• Vest: Business logic validation (async, form UX)

Think of it as layers, not competitors:

Zod validates types → Vest validates business rules → Complete solution

Q: Will this break existing code?

A: No. This is purely additive. All existing enforce.shape() functionality remains unchanged.

Q: What about Vest Suites?

A: Vest Suites remain the best choice for complex form flows. StandardSchema support is for the dual-layer pattern (Zod + Vest working together).

Q: Should I migrate from Zod to Vest?

A: No! Use both together! This is the recommended pattern:

// ✅ RECOMMENDED: Use both
const schema = z.object({
  /* type validation */
});
const suite = vest.create(/* business validation */);

// ❌ NOT RECOMMENDED: Pick one or the other

Q: What about bundle size?

A: Tree-shakeable and opt-in:

• Zod: ~8KB (only if you import it)
• Vest: ~5KB (always)
• Together: ~13KB for complete validation

You choose what to use!

Q: Can I use this without Zod?

A: Yes! Three approaches:

1. Zod + Vest (recommended for full-stack apps)
2. Vest only (business logic without type schemas)
3. Vest enforce.shape() (simple type validation + business logic)

Q: What's the maintenance burden?

A: Low. StandardSchema v1 has stability guarantees. The spec is finalized and won't change without a major version.

Q: Is this proven? Has anyone done dual-layer validation?

A: Yes! ngx-vest-forms (Angular library) pioneered this pattern with great success:

• Layer 1: Zod/Valibot type validation
• Layer 2: Vest business validation
• Result: Best-in-class developer experience

We're adopting their proven architecture.

✅ Recommendation for PR

Approve adding StandardSchema support to v6.0 roadmap

Why This is Strategic

1. Positioning Shift: Complementary, Not Competing

• Vest becomes "the business logic layer" for StandardSchema ecosystem
• Works WITH Zod/Valibot (not instead of)
• Larger addressable market (Zod users + Vest users)

2. Ecosystem Integration (The Killer Feature)

• Share Zod schemas across entire stack (Angular, React, tRPC, Hono)
• Vest adds business logic layer on top
• Single source of truth for data structure

3. Performance Benefits

• Type validation acts as "gatekeeper"
• Skip expensive async checks when structure invalid
• 99.9% faster (0.1ms vs 50-200ms)

4. Zero Breaking Changes

• Purely additive (backward compatible)
• Fits naturally with existing architecture
• Can be implemented in v6 timeline

5. Proven Architecture

• ngx-vest-forms successfully uses dual-layer pattern
• Industry trend: separation of type validation from business logic
• Aligns with modern full-stack development practices

The Value Equation

Vest v6 = Vest Suites (existing) + enforce.shape() with StandardSchema (new)
        = Best form UX + Best business logic + Ecosystem integration
        = Complete validation solution

---

Ready to discuss? See comprehensive analysis:

• STANDARDSCHEMA_DUAL_LAYER_APPROACH.md - How Zod + Vest work together
• INSIGHTS_FROM_NGX_VEST_FORMS.md - Key learnings and recommendations
• STANDARDSCHEMA_ANALYSIS.md - Technical implementation details

---

If you'd like I could also add the more detailed analysis and possible solution into another comment