@devmunna/agent-skillkit 0.1.0

package/skills/zod-validation/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: zod-validation
+version: 2.0.0
+description: >
+  Apply this skill for any task involving Zod: writing validation schemas, validating request bodies/params/query, inferring TypeScript types, validating environment variables, composing schemas, or handling validation errors. Triggers: "validate with Zod", "Zod schema", "request validation", "env validation", "parse input", "schema inference". Updated for Zod v4.
+stack: [zod]
+depends: []
+---
+
+# Zod Validation Skill — v4
+
+TypeScript-first schema validation. This skill covers **Zod v4** (current in IPSUM PLMS and recommended for all new projects).
+
+---
+
+## Zod v4 — Key Differences from v3
+
+| Feature | v3 | v4 |
+|---------|----|----|
+| Error accessor | `error.errors` or `error.flatten()` | **`error.issues`** (primary) |
+| Field errors | `error.flatten().fieldErrors` | `error.issues.map(i => ({ field: i.path.join('.'), message: i.message }))` |
+| Performance | Baseline | 10–100x faster parsing |
+| Bundle size | ~50kb | ~30kb |
+| JSON Schema | External lib | `z.toJSONSchema()` built-in |
+| API compatibility | — | Mostly backwards-compatible |
+
+---
+
+## Core Principle
+
+Zod validates AND transforms. After `safeParse`, the output is the coerced/defaulted value — always use `result.data`, never the raw input.
+
+---
+
+## Request Validation Middleware
+
+### Zod v4 — IPSUM PLMS pattern (body-only)
+
+```js
+// src/middlewares/validate.middleware.js — IPSUM pattern
+export const validate = (schema) => (req, res, next) => {
+  const result = schema.safeParse(req.body);
+
+  if (!result.success) {
+    // Zod v4: use .issues (array of { path, message, code })
+    const errors = result.error.issues.map((e) => ({
+      field:   e.path.join('.'),
+      message: e.message,
+    }));
+
+    return res.status(400).json({
+      success: false,
+      message: 'Validation failed',
+      errors,
+    });
+  }
+
+  req.body = result.data; // replace with parsed/coerced data
+  next();
+};
+```
+
+### Zod v4 — Full pattern (body + params + query)
+
+```js
+export const validate = (schema) => (req, res, next) => {
+  const result = schema.safeParse({
+    body: req.body,
+    params: req.params,
+    query: req.query,
+  });
+
+  if (!result.success) {
+    const errors = result.error.issues.map((e) => ({
+      field:   e.path.join('.'),
+      message: e.message,
+    }));
+    return res.status(422).json({ success: false, message: 'Validation failed', errors });
+  }
+
+  if (result.data.body)   req.body   = result.data.body;
+  if (result.data.params) req.params = result.data.params;
+  if (result.data.query)  req.query  = result.data.query;
+  next();
+};
+```
+```
+
+---
+
+## Schema Structure
+
+Always wrap in `z.object({ body?, params?, query? })` for the validate middleware:
+
+```js
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  body: z.object({
+    name: z.string().min(2).max(100),
+    email: z.string().email(),
+    password: z.string().min(8),
+    role: z.enum(['USER', 'ADMIN']).default('USER'),
+  }).strict(),
+});
+
+export const getUserSchema = z.object({
+  params: z.object({ id: z.string().uuid() }),
+});
+
+export const listUsersSchema = z.object({
+  query: z.object({
+    page: z.coerce.number().int().positive().default(1),
+    limit: z.coerce.number().int().positive().max(100).default(10),
+    search: z.string().optional(),
+    role: z.enum(['USER', 'ADMIN']).optional(),
+  }),
+});
+```
+
+---
+
+## Type Inference (TypeScript)
+
+```ts
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+// Infer type from schema
+type CreateUserDto = z.infer<typeof createUserSchema>;
+// { name: string; email: string }
+```
+
+For JavaScript (JSDoc):
+```js
+/** @typedef {import('zod').infer<typeof createUserSchema>} CreateUserDto */
+```
+
+---
+
+## Validation Pattern Reference
+
+### Strings
+```js
+z.string().min(1, 'Required').max(255)
+z.string().email()
+z.string().uuid()
+z.string().url()
+z.string().regex(/^\d{11}$/, '11 digits required')
+z.string().trim().toLowerCase()   // transform on parse
+```
+
+### Numbers
+```js
+z.number().int().positive()
+z.number().min(0).max(100)
+z.coerce.number()                  // coerce string → number (use for query params)
+z.coerce.number().int().positive()
+```
+
+### Optional / Nullable
+```js
+z.string().optional()              // value | undefined
+z.string().nullable()              // value | null
+z.string().nullish()               // value | null | undefined
+z.string().default('fallback')     // use fallback if undefined
+```
+
+### Enums
+```js
+z.enum(['active', 'inactive', 'pending'])
+z.nativeEnum(MyTypeScriptEnum)     // for TS enums
+```
+
+### Objects
+```js
+z.object({ name: z.string() })
+z.object({ name: z.string() }).strict()      // reject extra keys
+z.object({ name: z.string() }).passthrough() // keep extra keys
+z.object({ name: z.string() }).pick({ name: true })
+z.object({ name: z.string() }).omit({ name: true })
+z.object({ name: z.string() }).partial()     // all fields optional
+```
+
+### Arrays
+```js
+z.array(z.string())
+z.array(z.string()).min(1).max(10)
+z.array(z.string()).nonempty()
+```
+
+### Dates
+```js
+z.coerce.date()                    // string/number → Date
+z.date().min(new Date('2020-01-01'))
+```
+
+### Conditional / Refine
+```js
+z.object({
+  type: z.enum(['individual', 'company']),
+  companyName: z.string().optional(),
+}).refine(
+  (d) => d.type !== 'company' || !!d.companyName,
+  { message: 'companyName required for company type', path: ['companyName'] }
+)
+```
+
+### Transform
+```js
+z.string().transform((val) => val.trim().toLowerCase())
+z.string().transform((val) => parseInt(val, 10))
+z.preprocess((val) => String(val).trim(), z.string())
+```
+
+---
+
+## Environment Variables
+
+```js
+// src/config/env.js
+import { z } from 'zod';
+import 'dotenv/config';
+
+const schema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
+  JWT_EXPIRES_IN: z.string().default('7d'),
+  REDIS_URL: z.string().url().optional(),
+}).strict();
+
+const result = schema.safeParse(process.env);
+
+if (!result.success) {
+  console.error('❌ Invalid environment variables:');
+  // v4: use .issues
+  console.error(result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
+  process.exit(1);
+}
+
+export const env = result.data;
+// env.PORT is number, not string — coercion worked
+```
+
+---
+
+## Schema Composition
+
+```js
+// Reuse base schema across create/update
+const baseProductSchema = z.object({
+  name: z.string().min(1).max(255),
+  price: z.number().positive(),
+});
+
+const createProductSchema = z.object({ body: baseProductSchema.strict() });
+const updateProductSchema = z.object({
+  body: baseProductSchema.partial().strict(),   // all fields optional
+  params: z.object({ id: z.string().uuid() }),
+});
+```