TypeScript Coding Standards

Basic Principles

One Function, One Responsibility

• •If function name connects with "and" or "or", it's a signal to split
• •If test cases are needed for each if branch, it's a signal to split

Conditional and Loop Depth Limited to 2 Levels

• •Minimize depth using early return whenever possible
• •If still heavy, extract into separate functions

Make Function Side Effects Explicit

• •Example: If getUser also runs updateLastAccess(), specify it in the function name

Convert Magic Numbers/Strings to Constants When Possible

• •Declare at the top of the file or class where used
• •Consider separating into a constants file if there are many

Function Order by Call Order

• •Follow class access modifier declaration order rules if clear
• •Otherwise, order top-to-bottom for easy reading by call order

Review External Libraries for Complex Implementations

• •When logic is complex and tests become bloated
• •If industry-standard libraries exist, use them
• •When security, accuracy, or performance optimization is critical
• •When browser/platform compatibility or edge cases are numerous

Modularization (Prevent Code Duplication and Pattern Repetition)

• •Absolutely forbid code repetition
• •Modularize similar patterns into reusable forms
• •Allow pre-modularization if reuse is confirmed
• •Avoid excessive abstraction
• •Modularization levels:
  • •Same file: Extract into separate function
  • •Multiple files: Separate into different file
  • •Multiple projects/domains: Separate into package

Variable and Function Names

• •Clear purpose while being concise
• •Forbid abbreviations outside industry standards (id, api, db, err, etc.)
• •Don't repeat context from the parent scope
• •Boolean variables use is, has, should prefixes
• •Function names are verbs or verb+noun forms
• •Plural rules:
  • •Pure arrays: "s" suffix (users)
  • •Wrapped object: "list" suffix (userList)
  • •Specific data structure: Explicit (userSet, userMap)
  • •Already plural words: Use as-is

Field Order

• •Alphabetically ascending by default
• •Maintain consistency in usage
• •Also alphabetically ordered in destructuring assignment

Error Handling

• •Error handling level: Handle where meaningful response is possible
• •Error messages: Technical details for logs, actionable guidance for users
• •Error classification: Distinguish between expected and unexpected errors
• •Error propagation: Add context when propagating up the call stack
• •Recovery vs. fast fail: Recover from expected errors with fallback
• •Error types: For domain-specific failures, create custom error classes extending Error. Never throw non-Error objects
• •Async errors: Always handle Promise rejection. Use try-catch for async/await, .catch() for promise chains

Package Management

Package Manager

• •Use pnpm as default package manager
• •Forbid npm, yarn (prevent lock file conflicts)

File Structure

Common for All Files

1. •Import statements (grouped)
2. •Constant definitions (alphabetically ordered if multiple)
3. •Type/Interface definitions (alphabetically ordered if multiple)
4. •Main content (see below)

Inside Classes

• •Decorators
• •private readonly members
• •readonly members
• •constructor
• •public methods (alphabetically ordered)
• •protected methods (alphabetically ordered)
• •private methods (alphabetically ordered)

Function Placement in Function-Based Files

• •Main exported function
• •Additional exported functions (alphabetically ordered, avoid many)
• •Helper functions

Function Writing

Use Arrow Functions

• •Always use arrow functions except for class methods
• •Forbid function keyword entirely (exceptions: generator function*, function hoisting etc. technically impossible cases only)

Function Arguments: Flat vs Object

• •Use flat if single argument or uncertain of future additions
• •Use object form for 2+ arguments in most cases. Allow flat form when:
  • •All required arguments without boolean arguments
  • •All required arguments with clear order (e.g., (width,height), (start,end), (min,max), (from,to))

Type System

Type Safety

• •Forbid unsafe type bypasses like any, as, !, @ts-ignore, @ts-expect-error
• •Exceptions: Missing or incorrect external library types, rapid development needed (clarify reason in comments)
• •Allow some unknown type when type guard is clear
• •Allow as assertion when literal type (as const) needed
• •Allow as assertion when widening literal/HTML types to broader types
• •Allow "!" assertion when type narrowing impossible after type guard due to TypeScript limitation
• •Allow @ts-ignore, @ts-expect-error in test code (absolutely forbid in production)

Interface vs Type

• •Prioritize Type in all cases by default
• •Use Interface only for these exceptions:
  • •Public API provided to external users like library public API
  • •Need to extend existing interface like external libraries
  • •Designing OOP-style classes where implementation contract must be clearly defined

null/undefined Handling

• •Actively use Optional Chaining (?.)
• •Provide defaults with Nullish Coalescing (??)
• •Distinguish between null and undefined by semantic meaning:
  • •undefined: Uninitialized state, optional parameters, value not assigned yet
  • •null: Intentional absence of value (similar to Go's nil)
• •Examples:
  • •Optional field: { name?: string } → can be undefined
  • •Intentionally cleared value: user.profileImage = null
  • •External API responses may use either convention

Code Style

Maintain Immutability

• •Use const whenever possible, minimize let
• •Create new values instead of directly modifying arrays/objects
• •Use spread, filter, map instead of push, splice
• •Exceptions: Extremely performance-critical cases

Recommended Libraries

• •Testing: Jest, Playwright
• •Utilities: es-toolkit, dayjs
• •HTTP: ky, @tanstack/query, @apollo/client
• •Form: React Hook Form
• •Type validation: zod
• •UI: Tailwind + shadcn/ui
• •ORM: Prisma (Drizzle if edge support important)
• •State management: zustand
• •Code formatting: prettier, eslint
• •Build: tsup