Proposal: Native Runtime Type Safety for PayloadCMS with Guardz Generator

[thiennp]

Proposal: Native Runtime Type Safety for PayloadCMS with Guardz Generator

Problem Statement

PayloadCMS generates rich TypeScript types, but lacks runtime validation — leaving APIs and data handling vulnerable to mismatches at runtime:

• API Response Validation: No way to validate incoming API responses at runtime
• Form Data Integrity: Manual validation required for form submissions
• Type Safety Loss: Type safety is lost at runtime boundaries
• Developer Experience: Developers must manually implement validation logic

Proposed Solution

We propose integrating guardz-generator to automatically generate lightweight, runtime-safe validation functions from the payload-types.ts file.

How It Works

1. Automatic Generation: Guardz-generator reads payload-types.ts and generates runtime validation functions
2. Zero Configuration: Works out of the box with existing PayloadCMS projects
3. Type Safety: Provides runtime type safety for all PayloadCMS types
4. Performance: Minimal overhead (~15KB gzipped, microseconds per validation)

Example Integration

// 1. Add to package.json scripts
{
  "scripts": {
    "generate:types": "payload generate:types",
    "generate:guards": "guardz-generator generate payload-types.ts",
    "build": "npm run generate:types && npm run generate:guards"
  }
}

// 2. Generated guard (isUser.guardz.ts)
import { isString, isArrayWithEachItem, isOneOf, isType } from 'guardz';

export const isUser = (value: unknown): value is User => {
  return isType(value, {
    id: isString,
    email: isString,
    roles: isArrayWithEachItem(isOneOf(['admin', 'editor', 'user'])),
    // ... validates all fields
  });
};

// 3. Use in API endpoints
import { isUser } from './payload-types/isUser.guardz';

app.post('/api/users', (req, res) => {
  if (isUser(req.body)) {
    // Type-safe access to user data
    const { email, roles } = req.body; // ✅ TypeScript knows this is safe
    return res.json({ success: true });
  }
  return res.status(400).json({ error: 'Invalid user data' });
});

Benefits

✅ Zero Breaking Changes

• Optional integration
• Works with existing PayloadCMS projects
• No changes to current API or behavior

✅ Runtime Type Safety

• Validate all API responses
• Ensure form data integrity
• Catch type errors at runtime

✅ Better Developer Experience

• Type-safe data handling
• Clear validation errors
• IntelliSense support for validated data

✅ Performance Optimized

• ~15KB gzipped bundle size
• Microsecond-level validation overhead
• Intelligent caching and optimization

✅ Easy Integration

• Works with existing build process
• Zero configuration required
• Comprehensive documentation

Real-World Use Cases

1. API Response Validation

// Validate API responses before processing
const handleUserResponse = (response: unknown) => {
  if (isUser(response)) {
    return response; // Type-safe access
  }
  throw new Error('Invalid API response');
};

2. Form Data Validation

// Frontend form validation
const validateUserForm = (formData: unknown) => {
  if (isUser(formData)) {
    return { valid: true, data: formData };
  }
  return { valid: false, errors: ['Invalid form data'] };
};

3. Database Response Validation

// Validate database responses
const getUser = async (id: string) => {
  const user = await db.users.findById(id);
  
  if (isUser(user)) {
    return user; // Type-safe
  }
  
  throw new Error('Invalid user data from database');
};

Implementation Details

Technical Requirements

• Dependencies: guardz-generator and guardz packages
• Build Process: Add guard generation to existing type generation
• Configuration: Optional configuration file for customization
• Documentation: Comprehensive integration guide

Performance Impact

• Bundle Size: +15KB gzipped (guardz library)
• Runtime Performance: < 1ms per validation
• Build Time: +1-2 seconds for guard generation

Compatibility

• TypeScript: Full support for all TypeScript features
• PayloadCMS: Works with all PayloadCMS versions
• Frameworks: Compatible with Next.js, Express, etc.

Demo

Working Demo: payloadcms-guardz-demo

The demo shows:

• ✅ Automatic type guard generation from PayloadCMS types
• ✅ Runtime validation working correctly
• ✅ Type safety maintained throughout
• ✅ Zero configuration required

Questions for Discussion

1. Community Value: Would this be valuable for the PayloadCMS community?
2. Integration Level: Should this be optional or included by default?
3. Bundle Size: Are there concerns about the 15KB bundle size impact?
4. Performance: Any concerns about runtime performance overhead?
5. Documentation: What level of documentation would be most helpful?

Proposed Timeline

Phase 1: Community Feedback (Week 1-2)

• Gather community feedback on this proposal
• Address any concerns or questions
• Refine implementation based on feedback

Phase 2: Technical Implementation (Week 3-6)

• Create PayloadCMS plugin for seamless integration
• Add comprehensive documentation
• Create examples and templates

Phase 3: Official Integration (Week 7-8)

• Submit PR to PayloadCMS repository
• Add to official documentation
• Create migration guide for existing users

Next Steps

• Community Feedback: Gather input from PayloadCMS community
• Technical Review: Review implementation details
• Documentation: Create comprehensive integration guide
• Examples: Build real-world examples
• Pull Request: Submit official integration PR

Resources

• Guardz-Generator: GitHub Repository
• Guardz Library: Runtime Type Validation
• Demo: Working Integration Demo

---

Note: This proposal aims to enhance PayloadCMS's type safety capabilities while maintaining zero breaking changes. The integration is designed to be optional and provide immediate value to developers who need runtime validation.