plcode-linux-arm64-musl 2.1.0

package/.plcode/skill/core/backend-dev-guidelines/resources/validation-patterns.md

@@ -0,0 +1,750 @@
+# Validation Patterns - Input Validation with Zod
+
+Complete guide to input validation using Zod schemas for type-safe validation.
+
+## Table of Contents
+
+- [Why Zod?](#why-zod)
+- [Basic Zod Patterns](#basic-zod-patterns)
+- [Schema Examples from Codebase](#schema-examples-from-codebase)
+- [Route-Level Validation](#route-level-validation)
+- [Controller Validation](#controller-validation)
+- [DTO Pattern](#dto-pattern)
+- [Error Handling](#error-handling)
+- [Advanced Patterns](#advanced-patterns)
+
+---
+
+## Why Zod?
+
+### Benefits Over Joi/Other Libraries
+
+**Type Safety:**
+
+- ✅ Full TypeScript inference
+- ✅ Runtime + compile-time validation
+- ✅ Automatic type generation
+
+**Developer Experience:**
+
+- ✅ Intuitive API
+- ✅ Composable schemas
+- ✅ Excellent error messages
+
+**Performance:**
+
+- ✅ Fast validation
+- ✅ Small bundle size
+- ✅ Tree-shakeable
+
+### Migration from Joi
+
+Modern validation uses Zod instead of Joi:
+
+```typescript
+// ❌ OLD - Joi (being phased out)
+const schema = Joi.object({
+  email: Joi.string().email().required(),
+  name: Joi.string().min(3).required(),
+})
+
+// ✅ NEW - Zod (preferred)
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(3),
+})
+```
+
+---
+
+## Basic Zod Patterns
+
+### Primitive Types
+
+```typescript
+import { z } from "zod"
+
+// Strings
+const nameSchema = z.string()
+const emailSchema = z.string().email()
+const urlSchema = z.string().url()
+const uuidSchema = z.string().uuid()
+const minLengthSchema = z.string().min(3)
+const maxLengthSchema = z.string().max(100)
+
+// Numbers
+const ageSchema = z.number().int().positive()
+const priceSchema = z.number().positive()
+const rangeSchema = z.number().min(0).max(100)
+
+// Booleans
+const activeSchema = z.boolean()
+
+// Dates
+const dateSchema = z.string().datetime() // ISO 8601 string
+const nativeDateSchema = z.date() // Native Date object
+
+// Enums
+const roleSchema = z.enum(["admin", "operations", "user"])
+const statusSchema = z.enum(["PENDING", "APPROVED", "REJECTED"])
+```
+
+### Objects
+
+```typescript
+// Simple object
+const userSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().int().positive(),
+})
+
+// Nested objects
+const addressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+  zipCode: z.string().regex(/^\d{5}$/),
+})
+
+const userWithAddressSchema = z.object({
+  name: z.string(),
+  address: addressSchema,
+})
+
+// Optional fields
+const userSchema = z.object({
+  name: z.string(),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+})
+
+// Nullable fields
+const userSchema = z.object({
+  name: z.string(),
+  middleName: z.string().nullable(),
+})
+```
+
+### Arrays
+
+```typescript
+// Array of primitives
+const rolesSchema = z.array(z.string())
+const numbersSchema = z.array(z.number())
+
+// Array of objects
+const usersSchema = z.array(
+  z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+)
+
+// Array with constraints
+const tagsSchema = z.array(z.string()).min(1).max(10)
+const nonEmptyArray = z.array(z.string()).nonempty()
+```
+
+---
+
+## Schema Examples from Codebase
+
+### Form Validation Schemas
+
+**File:** `/form/src/helpers/zodSchemas.ts`
+
+```typescript
+import { z } from "zod"
+
+// Question types enum
+export const questionTypeSchema = z.enum([
+  "input",
+  "textbox",
+  "editor",
+  "dropdown",
+  "autocomplete",
+  "checkbox",
+  "radio",
+  "upload",
+])
+
+// Upload types
+export const uploadTypeSchema = z.array(z.enum(["pdf", "image", "excel", "video", "powerpoint", "word"]).nullable())
+
+// Input types
+export const inputTypeSchema = z.enum(["date", "number", "input", "currency"]).nullable()
+
+// Question option
+export const questionOptionSchema = z.object({
+  id: z.number().int().positive().optional(),
+  controlTag: z.string().max(150).nullable().optional(),
+  label: z.string().max(100).nullable().optional(),
+  order: z.number().int().min(0).default(0),
+})
+
+// Question schema
+export const questionSchema = z.object({
+  id: z.number().int().positive().optional(),
+  formID: z.number().int().positive(),
+  sectionID: z.number().int().positive().optional(),
+  options: z.array(questionOptionSchema).optional(),
+  label: z.string().max(500),
+  description: z.string().max(5000).optional(),
+  type: questionTypeSchema,
+  uploadTypes: uploadTypeSchema.optional(),
+  inputType: inputTypeSchema.optional(),
+  tags: z.array(z.string().max(150)).optional(),
+  required: z.boolean(),
+  isStandard: z.boolean().optional(),
+  deprecatedKey: z.string().nullable().optional(),
+  maxLength: z.number().int().positive().nullable().optional(),
+  isOptionsSorted: z.boolean().optional(),
+})
+
+// Form section schema
+export const formSectionSchema = z.object({
+  id: z.number().int().positive(),
+  formID: z.number().int().positive(),
+  questions: z.array(questionSchema).optional(),
+  label: z.string().max(500),
+  description: z.string().max(5000).optional(),
+  isStandard: z.boolean(),
+})
+
+// Create form schema
+export const createFormSchema = z.object({
+  id: z.number().int().positive(),
+  label: z.string().max(150),
+  description: z.string().max(6000).nullable().optional(),
+  isPhase: z.boolean().optional(),
+  username: z.string(),
+})
+
+// Update order schema
+export const updateOrderSchema = z.object({
+  source: z.object({
+    index: z.number().int().min(0),
+    sectionID: z.number().int().min(0),
+  }),
+  destination: z.object({
+    index: z.number().int().min(0),
+    sectionID: z.number().int().min(0),
+  }),
+})
+
+// Controller-specific validation schemas
+export const createQuestionValidationSchema = z.object({
+  formID: z.number().int().positive(),
+  sectionID: z.number().int().positive(),
+  question: questionSchema,
+  index: z.number().int().min(0).nullable().optional(),
+  username: z.string(),
+})
+
+export const updateQuestionValidationSchema = z.object({
+  questionID: z.number().int().positive(),
+  username: z.string(),
+  question: questionSchema,
+})
+```
+
+### Proxy Relationship Schema
+
+```typescript
+// Proxy relationship validation
+const createProxySchema = z.object({
+  originalUserID: z.string().min(1),
+  proxyUserID: z.string().min(1),
+  startsAt: z.string().datetime(),
+  expiresAt: z.string().datetime(),
+})
+
+// With custom validation
+const createProxySchemaWithValidation = createProxySchema.refine(
+  (data) => new Date(data.expiresAt) > new Date(data.startsAt),
+  {
+    message: "expiresAt must be after startsAt",
+    path: ["expiresAt"],
+  },
+)
+```
+
+### Workflow Validation
+
+```typescript
+// Workflow start schema
+const startWorkflowSchema = z.object({
+  workflowCode: z.string().min(1),
+  entityType: z.enum(["Post", "User", "Comment"]),
+  entityID: z.number().int().positive(),
+  dryRun: z.boolean().optional().default(false),
+})
+
+// Workflow step completion schema
+const completeStepSchema = z.object({
+  stepInstanceID: z.number().int().positive(),
+  answers: z.record(z.string(), z.any()),
+  dryRun: z.boolean().optional().default(false),
+})
+```
+
+---
+
+## Route-Level Validation
+
+### Pattern 1: Inline Validation
+
+```typescript
+// routes/proxyRoutes.ts
+import { z } from "zod"
+
+const createProxySchema = z.object({
+  originalUserID: z.string().min(1),
+  proxyUserID: z.string().min(1),
+  startsAt: z.string().datetime(),
+  expiresAt: z.string().datetime(),
+})
+
+router.post("/", SSOMiddlewareClient.verifyLoginStatus, async (req, res) => {
+  try {
+    // Validate at route level
+    const validated = createProxySchema.parse(req.body)
+
+    // Delegate to service
+    const proxy = await proxyService.createProxyRelationship(validated)
+
+    res.status(201).json({ success: true, data: proxy })
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return res.status(400).json({
+        success: false,
+        error: {
+          message: "Validation failed",
+          details: error.errors,
+        },
+      })
+    }
+    handler.handleException(res, error)
+  }
+})
+```
+
+**Pros:**
+
+- Quick and simple
+- Good for simple routes
+
+**Cons:**
+
+- Validation logic in routes
+- Harder to test
+- Not reusable
+
+---
+
+## Controller Validation
+
+### Pattern 2: Controller Validation (Recommended)
+
+```typescript
+// validators/userSchemas.ts
+import { z } from "zod"
+
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  roles: z.array(z.enum(["admin", "operations", "user"])),
+  isActive: z.boolean().default(true),
+})
+
+export const updateUserSchema = z.object({
+  email: z.string().email().optional(),
+  name: z.string().min(2).max(100).optional(),
+  roles: z.array(z.enum(["admin", "operations", "user"])).optional(),
+  isActive: z.boolean().optional(),
+})
+
+export type CreateUserDTO = z.infer<typeof createUserSchema>
+export type UpdateUserDTO = z.infer<typeof updateUserSchema>
+```
+
+```typescript
+// controllers/UserController.ts
+import { Request, Response } from "express"
+import { BaseController } from "./BaseController"
+import { UserService } from "../services/userService"
+import { createUserSchema, updateUserSchema } from "../validators/userSchemas"
+import { z } from "zod"
+
+export class UserController extends BaseController {
+  private userService: UserService
+
+  constructor() {
+    super()
+    this.userService = new UserService()
+  }
+
+  async createUser(req: Request, res: Response): Promise<void> {
+    try {
+      // Validate input
+      const validated = createUserSchema.parse(req.body)
+
+      // Call service
+      const user = await this.userService.createUser(validated)
+
+      this.handleSuccess(res, user, "User created successfully", 201)
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        // Handle validation errors with 400 status
+        return this.handleError(error, res, "createUser", 400)
+      }
+      this.handleError(error, res, "createUser")
+    }
+  }
+
+  async updateUser(req: Request, res: Response): Promise<void> {
+    try {
+      // Validate params and body
+      const userId = req.params.id
+      const validated = updateUserSchema.parse(req.body)
+
+      const user = await this.userService.updateUser(userId, validated)
+
+      this.handleSuccess(res, user, "User updated successfully")
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return this.handleError(error, res, "updateUser", 400)
+      }
+      this.handleError(error, res, "updateUser")
+    }
+  }
+}
+```
+
+**Pros:**
+
+- Clean separation
+- Reusable schemas
+- Easy to test
+- Type-safe DTOs
+
+**Cons:**
+
+- More files to manage
+
+---
+
+## DTO Pattern
+
+### Type Inference from Schemas
+
+```typescript
+import { z } from "zod"
+
+// Define schema
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+  age: z.number().int().positive(),
+})
+
+// Infer TypeScript type from schema
+type CreateUserDTO = z.infer<typeof createUserSchema>
+
+// Equivalent to:
+// type CreateUserDTO = {
+//     email: string;
+//     name: string;
+//     age: number;
+// }
+
+// Use in service
+class UserService {
+  async createUser(data: CreateUserDTO): Promise<User> {
+    // data is fully typed!
+    console.log(data.email) // ✅ TypeScript knows this exists
+    console.log(data.invalid) // ❌ TypeScript error!
+  }
+}
+```
+
+### Input vs Output Types
+
+```typescript
+// Input schema (what API receives)
+const createUserInputSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+  password: z.string().min(8),
+})
+
+// Output schema (what API returns)
+const userOutputSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+  // password excluded!
+})
+
+type CreateUserInput = z.infer<typeof createUserInputSchema>
+type UserOutput = z.infer<typeof userOutputSchema>
+```
+
+---
+
+## Error Handling
+
+### Zod Error Format
+
+```typescript
+try {
+  const validated = schema.parse(data)
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    console.log(error.errors)
+    // [
+    //   {
+    //     code: 'invalid_type',
+    //     expected: 'string',
+    //     received: 'number',
+    //     path: ['email'],
+    //     message: 'Expected string, received number'
+    //   }
+    // ]
+  }
+}
+```
+
+### Custom Error Messages
+
+```typescript
+const userSchema = z.object({
+  email: z.string().email({ message: "Please provide a valid email address" }),
+  name: z.string().min(2, { message: "Name must be at least 2 characters" }),
+  age: z.number().int().positive({ message: "Age must be a positive number" }),
+})
+```
+
+### Formatted Error Response
+
+```typescript
+// Helper function to format Zod errors
+function formatZodError(error: z.ZodError) {
+    return {
+        message: 'Validation failed',
+        errors: error.errors.map((err) => ({
+            field: err.path.join('.'),
+            message: err.message,
+            code: err.code,
+        })),
+    };
+}
+
+// In controller
+catch (error) {
+    if (error instanceof z.ZodError) {
+        return res.status(400).json({
+            success: false,
+            error: formatZodError(error),
+        });
+    }
+}
+
+// Response example:
+// {
+//   "success": false,
+//   "error": {
+//     "message": "Validation failed",
+//     "errors": [
+//       {
+//         "field": "email",
+//         "message": "Invalid email",
+//         "code": "invalid_string"
+//       }
+//     ]
+//   }
+// }
+```
+
+---
+
+## Advanced Patterns
+
+### Conditional Validation
+
+```typescript
+// Validate based on other field values
+const submissionSchema = z
+  .object({
+    type: z.enum(["NEW", "UPDATE"]),
+    postId: z.number().optional(),
+  })
+  .refine(
+    (data) => {
+      // If type is UPDATE, postId is required
+      if (data.type === "UPDATE") {
+        return data.postId !== undefined
+      }
+      return true
+    },
+    {
+      message: "postId is required when type is UPDATE",
+      path: ["postId"],
+    },
+  )
+```
+
+### Transform Data
+
+```typescript
+// Transform strings to numbers
+const userSchema = z.object({
+  name: z.string(),
+  age: z.string().transform((val) => parseInt(val, 10)),
+})
+
+// Transform dates
+const eventSchema = z.object({
+  name: z.string(),
+  date: z.string().transform((str) => new Date(str)),
+})
+```
+
+### Preprocess Data
+
+```typescript
+// Trim strings before validation
+const userSchema = z.object({
+  email: z.preprocess((val) => (typeof val === "string" ? val.trim().toLowerCase() : val), z.string().email()),
+  name: z.preprocess((val) => (typeof val === "string" ? val.trim() : val), z.string().min(2)),
+})
+```
+
+### Union Types
+
+```typescript
+// Multiple possible types
+const idSchema = z.union([z.string(), z.number()])
+
+// Discriminated unions
+const notificationSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("email"),
+    recipient: z.string().email(),
+    subject: z.string(),
+  }),
+  z.object({
+    type: z.literal("sms"),
+    phoneNumber: z.string(),
+    message: z.string(),
+  }),
+])
+```
+
+### Recursive Schemas
+
+```typescript
+// For nested structures like trees
+type Category = {
+  id: number
+  name: string
+  children?: Category[]
+}
+
+const categorySchema: z.ZodType<Category> = z.lazy(() =>
+  z.object({
+    id: z.number(),
+    name: z.string(),
+    children: z.array(categorySchema).optional(),
+  }),
+)
+```
+
+### Schema Composition
+
+```typescript
+// Base schemas
+const timestampsSchema = z.object({
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+})
+
+const auditSchema = z.object({
+  createdBy: z.string(),
+  updatedBy: z.string(),
+})
+
+// Compose schemas
+const userSchema = z
+  .object({
+    id: z.string(),
+    email: z.string().email(),
+    name: z.string(),
+  })
+  .merge(timestampsSchema)
+  .merge(auditSchema)
+
+// Extend schemas
+const adminUserSchema = userSchema.extend({
+  adminLevel: z.number().int().min(1).max(5),
+  permissions: z.array(z.string()),
+})
+
+// Pick specific fields
+const publicUserSchema = userSchema.pick({
+  id: true,
+  name: true,
+  // email excluded
+})
+
+// Omit fields
+const userWithoutTimestamps = userSchema.omit({
+  createdAt: true,
+  updatedAt: true,
+})
+```
+
+### Validation Middleware
+
+```typescript
+// Create reusable validation middleware
+import { Request, Response, NextFunction } from "express"
+import { z } from "zod"
+
+export function validateBody<T extends z.ZodType>(schema: T) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    try {
+      req.body = schema.parse(req.body)
+      next()
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return res.status(400).json({
+          success: false,
+          error: {
+            message: "Validation failed",
+            details: error.errors,
+          },
+        })
+      }
+      next(error)
+    }
+  }
+}
+
+// Usage
+router.post("/users", validateBody(createUserSchema), async (req, res) => {
+  // req.body is validated and typed!
+  const user = await userService.createUser(req.body)
+  res.json({ success: true, data: user })
+})
+```
+
+---
+
+**Related Files:**
+
+- SKILL.md - Main guide
+- [routing-and-controllers.md](routing-and-controllers.md) - Using validation in controllers
+- [services-and-repositories.md](services-and-repositories.md) - Using DTOs in services
+- [async-and-errors.md](async-and-errors.md) - Error handling patterns