typescript-zod

name	typescript-zod
description	Enforces TypeScript strict mode and Zod validation patterns in carwash-saas. Use this when writing types, interfaces, Zod schemas, form validation, or any TypeScript code. Covers no-any policy, type vs interface, schema conventions, type imports, and common strict-mode pitfalls.

TypeScript + Zod Patterns

TypeScript configuration

Strict mode is enabled everywhere via @carwash/config:

• strict: true (enables strictNullChecks, noImplicitAny, etc.)
• noUnusedLocals: true
• noUnusedParameters: true
• noImplicitReturns: true
• moduleResolution: bundler

These are not optional. Every file in every package and app must satisfy them.

---

No any

any disables type checking entirely. It is never acceptable.

// WRONG
function processData(data: any) { ... }
const result = response.data as any;

// CORRECT — use unknown and narrow
function processData(data: unknown) {
  if (typeof data !== 'object' || data === null) throw new Error('Invalid data');
  // narrow further as needed
}

// CORRECT — use a specific type
const result = response.data as TransactionRow[];

When you receive data from Supabase that TypeScript can't infer perfectly, define a local type and cast to it — not to any:

type StaffRow = { id: string; name: string; role: string };
return (data ?? []) as StaffRow[]; // explicit, reviewable cast

---

type vs interface

• Use type for all object shapes, unions, and aliases derived from Zod schemas
• Use interface only when extending HTML element attributes

// CORRECT — type for plain shapes
type StatCardProps = {
  label: string;
  value: number;
  color: "blue" | "emerald" | "violet";
};

// CORRECT — interface when extending HTML attrs (packages/ui pattern)
interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "danger" | "ghost";
  loading?: boolean;
}

// WRONG — interface for a plain data shape
interface TransactionRow {
  id: string;
  wash_type: string;
}

---

Zod schemas

Location

All schemas live in packages/types/src/models.ts. Import from @carwash/types, never from deep paths:

// CORRECT
import type { Customer, LogWash } from "@carwash/types";
import { CustomerUpsertSchema, LogWashSchema } from "@carwash/types";

// WRONG
import { CustomerUpsertSchema } from "../../packages/types/src/models";

Naming convention

• Schema: PascalCase suffixed with Schema → CustomerUpsertSchema
• Inferred type: PascalCase without suffix → type CustomerUpsert = z.infer<typeof CustomerUpsertSchema>
• Always export both together:

export const CustomerUpsertSchema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  phone: z
    .string()
    .regex(/^(\+62|0)[0-9]{8,12}$/, "Enter a valid Indonesian phone number"),
});
export type CustomerUpsert = z.infer<typeof CustomerUpsertSchema>;

Domain models vs form input schemas

Keep them separate — domain models reflect DB rows, form schemas reflect what the user inputs:

// Domain model — matches database shape, includes server-generated fields
export const CustomerSchema = z.object({
  id: z.string().uuid(),
  merchant_id: z.string().uuid(),
  name: z.string().min(1),
  phone: z.string().min(1),
  created_at: z.string(),
});
export type Customer = z.infer<typeof CustomerSchema>;

// Form input schema — only what the user provides; different validation messages
export const CustomerUpsertSchema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  phone: z
    .string()
    .regex(/^(\+62|0)[0-9]{8,12}$/, "Enter a valid Indonesian phone number"),
});
export type CustomerUpsert = z.infer<typeof CustomerUpsertSchema>;

Enums: always z.enum(), never TypeScript enum

// WRONG — TypeScript enum
enum WashType {
  Basic = "basic",
  Premium = "premium",
  Detail = "detail",
}

// CORRECT — Zod enum (runtime-validated, inferred type, portable)
export const WashTypeSchema = z.enum(["basic", "premium", "detail"]);
export type WashType = z.infer<typeof WashTypeSchema>;

Validation on both client and server

• Client (form submit): use schema.safeParse() before sending to the server
• Server (API route / RPC): re-validate with schema.parse() — never trust client input

// Client-side form validation
const result = CustomerUpsertSchema.safeParse({ name, phone });
if (!result.success) {
  const fieldErrors = result.error.flatten().fieldErrors;
  setErrors(fieldErrors);
  return;
}
// proceed with result.data — fully typed

// Server-side (API route or server action)
const parsed = LogWashSchema.parse(requestBody); // throws ZodError on failure

---

Type imports

Use import type whenever importing only types. This ensures the import is erased at compile time and never included in the bundle:

// CORRECT
import type { Database } from "@carwash/types";
import type { Customer, LogWash } from "@carwash/types";
import type { ButtonHTMLAttributes } from "react";

// WRONG — value import for a type-only use
import { Customer } from "@carwash/types";

Mix value and type imports in one statement:

import { CustomerUpsertSchema, type CustomerUpsert } from "@carwash/types";

---

Handling Supabase return types

database.types.ts contains the full DB schema. Use it for strong typing, but define lean local types for what you actually select:

import type { Database } from "@carwash/types";

// Full row type — use when you need the entire row
type FullProfile = Database["public"]["Tables"]["profiles"]["Row"];

// Projected type — preferred when you .select() only some columns
type StaffRow = Pick<
  FullProfile,
  "id" | "name" | "role" | "qr_token" | "is_active"
>;

Never cast to any to work around Supabase type inference issues. Instead, define the expected shape and cast explicitly:

// Supabase can't always infer join shapes — define the type explicitly
type TransactionRow = {
  id: string;
  wash_type: string;
  amount_paid: number;
  is_free_redemption: boolean;
  created_at: string;
  customers: { name: string; phone: string } | null;
  staff: { name: string } | null;
};

return (data ?? []) as unknown as TransactionRow[];
// `as unknown as T` is the safe two-step cast for incompatible Supabase inferred types

---

Strict-mode common pitfalls

noUnusedLocals / noUnusedParameters

// WRONG — unused param
function process(data: string, _unused: number) {
  return data;
}

// CORRECT — prefix with _ to signal intentionally unused
function process(data: string, _count: number) {
  return data;
}

noImplicitReturns

// WRONG — implicit undefined return in some code paths
function getLabel(type: WashType): string {
  if (type === "basic") return "Basic";
  if (type === "premium") return "Premium";
  // TypeScript error: not all code paths return a value
}

// CORRECT — exhaustive
function getLabel(type: WashType): string {
  if (type === "basic") return "Basic";
  if (type === "premium") return "Premium";
  return "Detail";
}

strictNullChecks

// WRONG — data could be null
const name = supabaseData.customers.name;

// CORRECT — optional chaining
const name = supabaseData.customers?.name ?? "—";

---

Import order

1. External dependencies (react, next/*, @tanstack/*, zod)
2. Workspace packages (@carwash/types, @carwash/lib, @carwash/ui)
3. Local app aliases (@/lib/supabase/client, @/components/Providers)
4. Relative imports (./loyalty, ../utils)

Blank line between each group.

---

Common anti-patterns to reject

Anti-pattern	Correct approach
any type	Use unknown + narrowing, or an explicit type
as any cast	as unknown as TargetType if truly necessary
TypeScript enum	z.enum([...]) + z.infer<>
interface for a plain data shape	Use type
Deep path import from packages/types	Import from @carwash/types barrel
Value import for type-only use	import type { Foo }
Inline anonymous types in function params	Extract to a named type
Schema without exported inferred type	Always export type Foo = z.infer<typeof FooSchema>
Client-only validation	Validate on both client (safeParse) and server (parse)
data.field without null check	data?.field ?? fallback