typescript

TypeScript and Zod

Rules

• strict and noUncheckedIndexedAccess are on: handle undefined from index access, do not assert it away.
• Zod first for outside data (API, forms, search params, env): write the schema, derive the type with z.infer.
• Zod 4 APIs: z.email(), z.url(), z.uuid(), z.iso.datetime() instead of z.string().email() and similar. Custom messages are a string or { error }.
• type for shapes and unions. interface only for declaration merging, such as module augmentation.
• satisfies checks a value against a type without widening it.
• Model variants as discriminated unions.
• as const objects or z.enum instead of enum.
• Branded types are recommended for ids that are easy to mix up (UserId, OrderId).

Bans

• any. Use unknown and narrow it.
• as casts outside tests and low-level wrappers in src/lib/. Parse with Zod instead. as const is fine.
• Non-null assertions (!).
• @ts-ignore. Use @ts-expect-error with a reason when it is unavoidable.
• More than two nested utility types. Derive from schemas with .pick(), .omit() and .extend().

export const userSchema = z.object({ id: z.string(), email: z.email(), role: z.enum(["admin", "member"]), });

export type User = z.infer;

export type SaveState = | { status: "idle" } | { status: "saved"; savedAt: Date } | { status: "failed"; reason: string };

export const roleLabels = { admin: "Admin", member: "Member" } satisfies Record<User["role"], string>;

</example>

<incorrect-example>
```ts
interface IUser {
  id: any;
}
const user = data as IUser;