Type Definition Rules

11.1.1. interface vs type Usage Criteria

Use interface when defining the shape of objects. Use type for unions, intersections, and conditional types.

// Object shape — use interface
interface User {
  id: number
  name: string
  email: string
  role: UserRole
}

// Union type — use type
type UserRole = 'admin' | 'editor' | 'viewer'

// Intersection type — use type
type AuditableUser = User & { createdAt: Date; updatedAt: Date }

// Conditional type — use type
type ApiResult<T> = T extends void ? { success: boolean } : { success: boolean; data: T }

• interface supports declaration merging, making it suitable for object types that require extension.
• type is specialized for type operations and must not be used for simple object definitions.

---

11.1.2. Type Naming Rules

All types and interfaces must be named in PascalCase. The Hungarian notation I prefix must not be used.

// Correct
interface UserProfile { id: number; displayName: string }

// Incorrect — I prefix is prohibited
interface IUserProfile { id: number; displayName: string }

The following suffix patterns must be applied to API-related types:

Suffix	Purpose	Example
Request	API request parameters	CreateOrderRequest
Response	API response data	OrderListResponse
Dto	Data transfer objects between layers	UserDto
Params	Query parameters	SearchParams

---

11.1.3. Type File Management

Type definition files must be organized by domain in the src/types/ directory. All types in each file must be exported.

src/types/
├── user.ts        # User-related types
├── product.ts     # Product-related types
├── order.ts       # Order-related types
├── common.ts      # Common utility types
└── index.ts       # Barrel file (re-export)

// src/types/user.ts
export interface User {
  id: number
  name: string
  email: string
  role: UserRole
}

export type UserRole = 'admin' | 'editor' | 'viewer'

// src/types/index.ts
export type { User, UserRole } from './user'
export type { Product } from './product'

• Component-specific types may be defined within the SFC itself. However, types referenced by 2 or more files must be moved to src/types/.

---

11.1.4. Prohibition of any

any disables type safety and must not be used. When the type cannot be determined, use unknown instead.

// Incorrect
function parseData(raw: any): any {
  return JSON.parse(raw)
}

// Correct
function parseData(raw: string): unknown {
  return JSON.parse(raw)
}

Apply the ESLint rule @typescript-eslint/no-explicit-any: warn. When unavoidable, a justification comment is mandatory.

// eslint-disable-next-line @typescript-eslint/no-explicit-any -- legacy-chart-lib has no type definitions
const chart = new LegacyChart(canvas) as any

• Using eslint-disable without a justification comment is not permitted.
• All uses of any must be included as mandatory review items during code review.