Cursor rule

1---
2description: Conventions and best practices for writing TypeScript code
3globs: *.ts,*.tsx
4alwaysApply: false
5---
6 
7# TypeScript Coding Standards
8 
9## Naming Conventions
10 
11- Interface names must start with `i` and use PascalCase.
12  - Example: `iUser`, `iAuthPayload`, `iComponentProps`
13- Type aliases must end with `Type` and use camelCase.
14  - Example: `authType`, `tokenResponseType`
15- Use self-explanatory names for:
16  - Variables (e.g., `currentUserId`, not `id`, `i`, or `k`)
17  - Functions (e.g., `calculateTotal`, not `calc`)
18  - Enums, types, and interfaces
19 
20## Function Style
21 
22- Avoid single-line arrow functions **without explicit `return`**. Always use a block body for clarity, even if it's one line.
23  - Preferred:
24```ts
25    const getUserName = (user: iUser): string => {
26      return user.name;
27    };
28```
29  - Avoid:
30```ts
31    const getUserName = (user: iUser): string => user.name;
32```
33 
34- Avoid using `.then()` for asynchronous code. Prefer `async/await` for better readability and error handling.
35 
36  - Preferred:
37```ts
38    const userName = await getUserNameById(id);
39```
40 
41  - Avoid:
42```ts
43    getUserNameById(id).then((name) => console.log(name));
44```
45 
46## Spacing & Grouping
47 
48- Add empty lines between:
49  - Logical code blocks
50  - Variable declarations and function calls
51  - Different hook calls in React (e.g., between `useState` and `useEffect`)
52- This improves readability and visual grouping of logic.
53 
54## Documentation
55 
56- Use JSDoc for all exported and non-exported functions and complex utilities.
57- Comment inside function bodies to explain:
58  - Non-obvious logic
59  - Side effects
60  - State or variable and constant's intent
61 
62## Readability & Maintainability
63 
64- Keep functions short and focused. Extract logic into helper functions if they do more than one thing.
65- Avoid deeply nested conditionals. Use early returns where appropriate.
66- Use `const` by default. Only use `let` when mutation is required.
67- Avoid magic numbers or strings. Replace with enums or named constants.
68- Avoid chaining `.map()`, `.filter()`, etc., inline. Prefer writing logic in a more declarative, readable structure, even if it spans multiple lines.
69 
70## Imports
71 
72- Group imports in the following order:
73  1. External libraries
74  2. Aliased internal modules (e.g., `@/services`)
75  3. Relative imports
76- Separate import groups with a blank line.
77 
78## Type Safety
79 
80- Always define types for props, return values, and function arguments.
81- Prefer TypeScript types/interfaces over `any`.
82- Avoid unnecessary `as` type assertions unless narrowing is required.
83 
84## Example
85 
86```ts
87import { getUserById } from "@/services/userService";
88 
89export enum UserRole {
90  Admin = "admin",
91  Editor = "editor",
92  Viewer = "viewer",
93}
94 
95interface iUserProps {
96  id: string;
97  name: string;
98  role: UserRole;
99}
100 
101/**
102 * Fetches the user name based on user ID.
103 */
104const getUserNameById = async (userId: string): Promise<string> => {
105  const user = await getUserById(userId);
106 
107  // Return the name of the user if found
108  return user.name;
109};
110```
111