markdown# CLAUDE.md

## TypeScript Standards
- Target: ES2022, strict mode enabled
- Runtime: Node.js 22 / browser (specify per file if mixed)
- Formatter: Prettier 3.x, tab width 2
- Linter: ESLint with @typescript-eslint/recommended-type-checked

## Type Conventions
- Prefer `interface` for object shapes that will be extended
- Use `type` for unions, intersections, mapped types
- Never use `any` — use `unknown` and narrow, or `never` for exhaustive checks
- Export types alongside implementations, not in separate files

## Key Libraries
- Validation: zod 3.x (always generate zod schemas alongside types)
- HTTP client: ky (not axios or fetch directly)
- Date handling: date-fns 3.x (not luxon or dayjs)

I need a TypeScript utility type called `DeepPartial<T>` that makes all properties 
optional recursively — including nested objects and arrays. It should:
- Handle arrays by making each element DeepPartial
- Not modify primitive types (string, number, boolean, Date, null, undefined)
- Work with class instances (don't recurse into class methods)

typescripttype Primitive = string | number | boolean | null | undefined | Date | bigint | symbol;

type DeepPartial<T> = T extends Primitive
  ? T
  : T extends Array<infer U>
  ? Array<DeepPartial<U>>
  : T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T;

// Usage examples
type User = {
  id: number;
  profile: {
    name: string;
    address: {
      city: string;
      zip: string;
    };
  };
  tags: string[];
};

type PartialUser = DeepPartial<User>;
// Result:
// {
//   id?: number;
//   profile?: {
//     name?: string;
//     address?: { city?: string; zip?: string; };
//   };
//   tags?: string[];
// }

Convert this TypeScript interface to a Zod schema. The schema should:
- Validate all fields including nested objects
- Add sensible string length limits (name: 1-100 chars, email: valid format)
- Export both the schema and the inferred type

interface CreateUserRequest {
  name: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  metadata?: {
    source: string;
    campaignId: number;
  };
}

typescriptimport { z } from 'zod';

export const createUserRequestSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email().max(254),
  role: z.enum(['admin', 'editor', 'viewer']),
  metadata: z
    .object({
      source: z.string().min(1).max(100),
      campaignId: z.number().int().positive(),
    })
    .optional(),
});

export type CreateUserRequest = z.infer<typeof createUserRequestSchema>;

I'm getting this TypeScript error and don't understand it:

Type 'Promise<{ id: string; data: Buffer; }>' is not assignable to type 
'Promise<ApiResponse<UserData>>'.
  Type '{ id: string; data: Buffer; }' is not assignable to type 'ApiResponse<UserData>'.
    Types of property 'data' are incompatible.
      Type 'Buffer' is not assignable to type 'UserData'.

Here's my code: [paste code]

Refactor this TypeScript file to remove all `any` types. Replace them with 
proper types, use `unknown` where the shape is truly unknown, and add type 
guards where needed. Preserve existing behavior — don't change logic.

[paste file contents]

Write a type-safe Hono route handler for POST /users that:
- Validates the request body with zod (name, email, role as 'admin'|'user')
- Returns typed responses: 201 with UserResponse, 400 with ValidationError
- Uses a typed database client (assume a `db.users.create()` method)
- Handles errors properly without leaking internal details

typescriptimport { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
});

type UserResponse = {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
  createdAt: string;
};

type ValidationError = {
  error: 'VALIDATION_ERROR';
  details: z.ZodIssue[];
};

const app = new Hono();

app.post(
  '/users',
  zValidator('json', createUserSchema),
  async (c) => {
    const body = c.req.valid('json'); // fully typed here

    try {
      const user = await db.users.create({
        data: body,
      });

      const response: UserResponse = {
        id: user.id,
        name: user.name,
        email: user.email,
        role: user.role,
        createdAt: user.createdAt.toISOString(),
      };

      return c.json(response, 201);
    } catch (error) {
      // Log internally, return safe error
      console.error('[POST /users] Database error:', error);
      return c.json({ error: 'INTERNAL_ERROR' }, 500);
    }
  }
);

Generate TypeScript interfaces from this OpenAPI 3.1 schema section. Use 
readonly where appropriate for response types, and make all response types 
immutable. [paste schema]

Create a discriminated union type for an async operation that can be:
- idle (no data)
- loading (has requestId: string)
- success (has data: T and timestamp: Date)
- error (has error: Error and retryCount: number)

Include a type guard for each state and a reducer function that transitions 
between states. Make it generic over T (the success data type).

I have a User type with 20+ fields. Generate a mapped type `FormErrors<T>` 
that takes any object type and produces a type where each key maps to 
string | undefined (for field-level error messages). Also generate a 
`FormTouched<T>` where each key maps to boolean.

typescripttype FormErrors<T> = {
  [K in keyof T]?: T[K] extends object ? FormErrors<T[K]> : string;
};

type FormTouched<T> = {
  [K in keyof T]?: T[K] extends object ? FormTouched<T[K]> : boolean;
};

// Usage
type UserFormErrors = FormErrors<User>;
// { name?: string; email?: string; profile?: { address?: { city?: string; } } }

bashclaude "Read the types in src/types/ and src/lib/api-client.ts, then help me 
add a new endpoint for paginated user search"

bash# Have Claude run tsc after each change
claude "Add the endpoint, run tsc --noEmit to check for errors, fix any issues"

bashclaude "Write Vitest tests for the new endpoint. Test the happy path, 
validation errors, and database errors. Use MSW to mock the database layer."

bashclaude "Review the new code for: (1) any remaining any types, (2) missing 
null checks, (3) error cases that aren't handled"