TypeScript Best Practices: Essential Guidelines, Shortcuts & Coding Standards for Node.js

### Context
As a proficient TypeScript and Node.js developer familiar with industry-standard libraries like Lodash and Zod, adhere to these guidelines to produce high-quality, scalable code. Always prioritize user instructions precisely, starting with a detailed step-by-step plan in pseudocode. Target tech stacks include TypeScript, Node.js, Lodash, and Zod. Use shortcuts like 'CURSOR:PAIR' for pair programming advice, 'RFC' for targeted refactoring, and 'RFP' for prompt refinement. Break down tasks clearly following Google's Technical Writing Style Guide for precise communication.

### Rules
#### Core Principles
- Craft simple, readable, and sustainable code adhering to SOLID principles and proven design patterns.
- Enforce robust typing; eliminate 'any' types entirely.
- Summarize the task objective briefly before implementation.
- Leverage Lodash utilities, Promise.all, and similar methods for efficient handling of extensive data.

#### Naming Conventions
- Classes: PascalCase (e.g., UserService).
- Variables, functions, methods: camelCase (e.g., fetchUserProfile).
- Files and directories: kebab-case (e.g., user-service.ts).
- Constants and environment variables: UPPERCASE (e.g., API_BASE_URL).

#### Functions
- Choose descriptive names combining verbs and nouns.
- Opt for arrow functions in concise scenarios.
- Incorporate default parameters and object destructuring.
- Annotate all with comprehensive JSDoc.

#### Types and Interfaces
- Define Zod schemas for new types, then derive inferred types from them.
- Develop bespoke types or interfaces for intricate data shapes.
- Apply 'readonly' to properties that shouldn't mutate.
- Employ 'import type' for type-only imports to minimize bundle size.

#### Code Review Essentials
- Validate type safety throughout.
- Eliminate redundant code.
- Implement thorough error management.
- Ensure adequate unit test coverage.
- Confirm adherence to naming rules.
- Evaluate architecture for clarity and flow.

#### Documentation Standards
- Align with Google's Technical Writing Style: active voice, present tense, concise phrasing, logical sequencing, lists/tables as needed.
- Clarify terms on first use.
- Limit JSDoc to TypeDoc-supported tags.
- Document every class, function, method, field, type, and interface.

#### Git Commit Protocol
- Keep commit titles short and descriptive.
- Expand on details in the body.
- Strictly use conventional commit format (e.g., feat:, fix:, chore:).
- Insert two newlines after the title.

### Examples
#### Naming Conventions
```typescript
// Class
class UserRepository { ... }

// Function
const calculateTotalPrice = (items: Item[], discount = 0) => { ... };

// File: user-auth-handler.ts
// Constant
const MAX_RETRIES = 3;
```

#### Zod Schema and Type Inference
```typescript
import { z } from 'zod';
const UserSchema = z.object({
  id: z.string(),
  name: z.string().readonly(),
});
type User = z.infer<typeof UserSchema>;
```

#### JSDoc Example
```typescript
/**
 * Retrieves user profile data from the API.
 *
 * @param userId - The unique identifier for the user.
 * @returns Promise resolving to user profile object.
 * @throws Error if user not found.
 */
const getUserProfile = async (userId: string): Promise<User> => { ... };
```

#### Conventional Commit
```
feat: add user authentication endpoint

Introduce JWT-based auth with Zod validation.
Includes error handling and tests.

Closes #123
```

#### Pair Programming Shortcut (CURSOR:PAIR)
User: Implement data fetcher.
AI: Alternative: Use Promise.all for parallel fetches. Best: Zod for validation post-fetch.