typescript-zod

Files (1)

• SKILL.md

SKILL.md (first lines)

# TypeScript 5 & Zod v4 Guidelines

## Core TypeScript Principles
- **NO `any` types**: The use of `any` is strictly prohibited. If a type is truly unknown, use `unknown` and safely narrow it down with type guards.
- **No Implicit Types**: Every function MUST have an explicit return type. Every function parameter MUST be explicitly typed.
- **Interfaces over Types**: Use `interface` for object shapes and data contracts. Use `type` ONLY for unions, intersections, or primitive aliases.
- **VaultLock Context**: All Supabase database queries must be strictly typed using generic interfaces. The `ciphertext` encrypted payload must have a strict, exported interface defining exactly what properties are inside.

## Zod v4 (Source of Truth)

**IMPORTANT:** Zod v4 introduces breaking changes to string formats, enums, error handling, and recursive types.

### When to Use Zod
Zod is for **runtime type validation** — parsing untrusted data at system boundaries (API input, form data, env vars, external services). For compile-time-only types, plain TypeScript is sufficient. Co-locate schemas with their boundary layer; domain types use `z.infer`.

### Quick Reference Rules

#### 1. Parsing & Type Safety (CRITICAL)
- `parse-use-safeParse` — Use `safeParse()` for user input instead of `parse()` which throws.
- `parse-async-required` — Must use `parseAsync()`/`safeParseAsync()` when schema has async refinements.
- `parse-infer-types` — Use `z.infer<typeof Schema>` for output types; never manually duplicate types.

#### 2. Schema Design (CRITICAL)
- `schema-object-unknowns` — `z.object()` strips unknown keys; use `strictObject` or `looseObject`.
- `schema-union-discriminated` — Use `z.discriminatedUnion()` for tagged unions, not `z.union()`.
- `schema-coercion-pitfalls` — `z.coerce.boolean()` makes `"false"` → `true`; use `z.stringbool()`.
- `schema-recursive-types` — Use getter pattern for recursive schemas; `z.lazy()` is removed in v4.

#### 3. Refinements & Transforms (HIGH)
- `refine-never-throw` — Never throw inside `.refine()` or `.transform()`; use `ctx.addIssue()`.
- `refine-vs-transform` — `.refine()` for validation, `.transform()` for conversion, `.pipe()` for staging.
- `refine-cross-field` — `.superRefine()` on parent object for cross-field validation with `path`.

#### 4. Error Handling & Observability (HIGH)
- `error-custom-messages` — Use v4 `error` parameter; `required_error`/`invalid_type_error` are removed.
- `error-formatting` — `z.flattenError()` for forms, `z.treeifyError()` for nested; `formatError` deprecated. Use for structured logs with correlation IDs.
- `error-input-security` — Never use `reportInput: true` in production; leaks sensitive data.

#### 5. v4 Migration & Performance (MEDIUM)
- `migrate-string-formats` — Use `z.email()`, `z.uuid()`, `z.url()` not `z.string().email()`.
- `migrate-native-enum` — Use unified `z.enum()` for TS enums; `z.nativeEnum()` is deprecated.
- `migrate-error-api` — Use `error` parameter everywhere; `message`, `errorMap` are removed.
- `perf-extend-spread` — Use `{ ...Schema.shape }` spread over chained `.extend()` for large schemas.
- `perf-reuse-schemas` — Define once, derive with `.pick()`, `.omit()`, `.partial()`.

#### 6. Advanced Patterns
- `pattern-branded-types` — `.brand<"Name">()` for nominal typing (USD vs EUR).
- `pattern-codecs` — `z.codec()` for bidirectional transforms (parse + serialize).
- `pattern-pipe` — `.pipe()` for staged parsing (string → number → validate range).

From 2004sfm/vaultlock, MIT.

More from 2004sfm/vaultlock