from104 qcalc .cursorrules file for TypeScript (stars: 1)

**Extremely Important!!**
When generating or modifying code, *never* omit any part of the code, no matter how long it is. Omissions can lead to the code failing to function as intended or cause critical errors. **Do not omit anything under any circumstances.**
---
**Top Priorities for Code Generation**
1. Ensure a linear dependency structure whenever possible.
2. Build a structure that facilitates seamless maintenance.
3. Write the code, including comments, in a way that makes its intent and logic **easily understandable** and interpretable by anyone.
4. Design the code with a **clear and simple structure**, prioritizing reusability for future purposes.
--- 
Use TypeScript best practices:
- Prefer interfaces over type aliases for object types
- Use const assertions for literal values
- Utilize strict null checks
- Implement proper error handling with union types
- Follow the naming conventions:
  - UpperCamelCase for types, interfaces, classes
  - lowerCamelCase for variables, functions, methods
  - CONSTANT_CASE for global constants and enum values
- Avoid using 'any' type, prefer 'unknown' for maximum type safety
- Utilize TypeScript's built-in utility types when appropriate
---
**Vue 3 Best Practices:**
1. **Adopt the Composition API:**
   - Utilize the Composition API for better code organization and reusability.
   - Encapsulate related logic into composable functions for modularity.
2. **Implement TypeScript:**
   - Integrate TypeScript to catch errors early and improve code quality.
   - Define explicit types for props, state, and events to enhance maintainability.
3. **Employ Single-File Components (SFCs):**
   - Use SFCs to encapsulate template, logic, and styles within a single file.
   - Ensure styles are scoped to prevent unintended global CSS conflicts.
4. **Optimize State Management:**
   - For global state, consider using Pinia, the recommended state management library for Vue 3.
   - For local component state, leverage the Composition API's `reactive` and `ref` functions.
5. **Enhance Performance:**
   - Implement lazy loading for components and routes to reduce initial load times.
   - Use the `v-once` directive for static content to prevent unnecessary re-renders.
6. **Maintain Consistent Coding Standards:**
   - Follow the official Vue.js style guide to ensure code consistency and readability.
   - Utilize linters and formatters to enforce coding standards across the codebase.
---
**Quasar Framework Best Practices:**
1. **Leverage Quasar's UI Components:**
   - Utilize Quasar's pre-built responsive components to maintain design consistency and enhance user experience.
2. **Optimize for Performance:**
   - Implement code splitting and lazy loading to improve application load times.
   - Use Quasar's built-in performance optimization features, such as tree shaking and minification.
3. **Ensure Security Compliance:**
   - Avoid using `v-html` with untrusted content to prevent XSS vulnerabilities.
   - Regularly review and adhere to Quasar's security best practices to safeguard your application.
4. **Design for Mobile First:**
   - Prioritize mobile design to ensure responsiveness across various devices.
   - Utilize Quasar's layout and grid system to create adaptable interfaces.
5. **Implement Effective State Management:**
   - Use Vuex or Pinia for managing complex state within your Quasar applications.
   - Structure your state management to align with Quasar's architecture for optimal performance.
6. **Test Across Multiple Devices:**
   - Conduct thorough testing on various devices and browsers to ensure consistent functionality and appearance.
   - Utilize Quasar's development tools to facilitate efficient testing and debugging.
---
To enhance the readability and maintainability of your TypeScript and Vue 3 codebase, consider the following expert guidelines for writing documentation-level comments:

**1. Use JSDoc for Detailed Documentation:**

Employ JSDoc comments to provide comprehensive descriptions of code elements such as functions, classes, and variables. This practice improves code readability and facilitates the generation of automated documentation.

```typescript
/**
 * Fetches user data from the API.
 * @param userId - Unique identifier for the user.
 * @returns A promise that resolves to the user's data.
 */
async function fetchUserData(userId: string): Promise<UserData> {
    // Implementation
}
```

**2. Write Comments in Korean Using Simple Language:**

Ensure all comments are written in Korean, utilizing straightforward vocabulary and sentence structures to facilitate easy translation into other languages.

```typescript
/**
 * API에서 사용자 데이터를 가져옵니다.
 * @param userId - 사용자의 고유 식별자.
 * @returns 사용자 데이터로 해결되는 프로미스.
 */
async function fetchUserData(userId: string): Promise<UserData> {
    // 구현
}
```

**3. Maintain Consistency and Clarity in Comments:**

Ensure that comments are clear, concise, and consistently formatted throughout the codebase. Avoid redundancy and focus on providing valuable information that aids in understanding the code's purpose and functionality.

```typescript
// 애플리케이션을 기본 설정으로 초기화합니다.
function initializeApp(): void {
    // 구현
}
```

**4. Keep Comments Updated with Code Changes:**

Regularly update comments to reflect any modifications in the code. Outdated or incorrect comments can lead to confusion and potential errors, undermining the benefits of documentation.

```typescript
/**
 * 할인 후 총 가격을 계산합니다.
 * @param price - 상품의 원래 가격.
 * @param discount - 적용할 할인율.
 * @returns 할인을 적용한 최종 가격.
 */
function calculateDiscountedPrice(price: number, discount: number): number {
    // 구현
}
```

**5. Document Complex Logic and Decision-Making Processes:**

For intricate algorithms or non-obvious code segments, provide explanatory comments that elucidate the logic and reasoning behind specific implementations. This practice is invaluable for code reviews and future maintenance.

```typescript
/**
 * 제공된 함수에 디바운스를 적용하여 마지막 호출 후
 * 지정된 지연 시간이 경과한 후에만 실행되도록 합니다.
 * @param func - 디바운스할 함수.
 * @param delay - 지연 시간(밀리초).
 * @returns 원본 함수의 디바운스된 버전.
 */
function debounce<T extends (...args: any[]) => void>(func: T, delay: number): T {
    let timeoutId: ReturnType<typeof setTimeout> | null = null;
    return function(this: any, ...args: Parameters<T>): void {
        if (timeoutId !== null) {
            clearTimeout(timeoutId);
        }
        timeoutId = setTimeout(() => {
            func.apply(this, args);
        }, delay);
    } as T;
}
```

**6. Leverage Vue 3's Composition API with Proper Typing and Documentation:**

When utilizing Vue 3's Composition API, ensure that composables and reactive references are well-documented, including their purpose, parameters, and return types. This clarity promotes better understanding and reuse of composable functions.

```typescript
import { ref, Ref } from 'vue';

/**
 * 증가 및 감소 기능이 있는 카운터의 상태를 관리합니다.
 * @param initialValue - 카운터의 초기 값.
 * @returns 카운터 상태와 이를 수정하는 함수들을 포함하는 객체.
 */
export function useCounter(initialValue: number = 0): {
    counter: Ref<number>;
    increment: () => void;
    decrement: () => void;
} {
    const counter = ref<number>(initialValue);

    const increment = (): void => {
        counter.value++;
    };

    const decrement = (): void => {
        counter.value--;
    };

    return {
        counter,
        increment,
        decrement,
    };
}
```

By implementing these best practices, you will enhance the readability, maintainability, and scalability of your TypeScript and Vue 3 projects, ensuring that both current and future developers can effectively work with your codebase.