# State Management Standards for TypeScript
This document outlines the standards for managing application state in TypeScript projects. It emphasizes modern approaches, best practices, and patterns to ensure maintainable, performant, and scalable applications.
## 1. General Principles
### 1.1. Immutability
* **Do This:** Prefer immutable data structures whenever possible.
* **Don't Do This:** Mutate state directly.
**Why:** Immutability simplifies reasoning about state changes, prevents unexpected side effects, and enhances debugging. It also enables techniques like time-travel debugging and optimized rendering in UI frameworks.
**Code Example:**
"""typescript
// Immutable update using the spread operator
interface User {
id: number;
name: string;
age: number;
}
let user: User = { id: 1, name: "Alice", age: 30 };
// Good: Create a new object with the updated age
let updatedUser: User = { ...user, age: 31 };
// Bad: Mutating the original object directly
// user.age = 31; // Avoid this
"""
### 1.2. Predictable State Transitions
* **Do This:** Use explicit actions or events to trigger state changes.
* **Don't Do This:** Rely on implicit or hidden state mutations.
**Why:** Predictable state transitions make it easier to understand how the application's state evolves over time, leading to increased maintainability and debuggability.
**Code Example (using a Redux-like pattern):**
"""typescript
// Define action types
type Action =
| { type: "INCREMENT" }
| { type: "DECREMENT" };
// Define the reducer function
type CounterState = { count: number };
const initialState: CounterState = { count: 0 };
function counterReducer(state: CounterState = initialState, action: Action): CounterState {
switch (action.type) {
case "INCREMENT":
return { ...state, count: state.count + 1 };
case "DECREMENT":
return { ...state, count: state.count - 1 };
default:
return state;
}
}
// Example usage (simplified)
let currentState = initialState;
currentState = counterReducer(currentState, { type: "INCREMENT" });
console.log(currentState); // Output: { count: 1 }
"""
### 1.3. Single Source of Truth
* **Do This:** Centralize application state into a single store or context.
* **Don't Do This:** Scatter state across multiple components or services without a clear hierarchy.
**Why:** A single source of truth ensures consistency and avoids data duplication. It makes it easier to manage complex state interactions and provides a clear picture of the application's overall state.
### 1.4. Separation of Concerns
* **Do This:** Separate state management logic from UI components and business logic.
* **Don't Do This:** Mix state updates directly within UI event handlers or business logic functions.
**Why:** Separation of concerns enhances testability, reusability, and maintainability. It allows you to modify state management mechanisms without affecting the rest of the application.
## 2. State Management Libraries and Patterns
### 2.1. Context API with "useReducer" (for simple to moderately complex state)
* **Do This:** Use the "useReducer" hook in conjunction with the Context API for managing localized, moderately complex state in React components.
* **Don't Do This:** Overuse the Context API for global state management in large applications, as it can lead to performance issues due to unnecessary re-renders.
**Why:** Well-suited for managing state that is localized to a specific part of the application. "useReducer" provides a structured way to update state, similar to Redux, but without the overhead of a global store. The Context API provides a means to distribute and consume state across React components.
**Code Example:**
"""typescript
import React, { createContext, useContext, useReducer } from 'react';
// Define the state type and action types
interface AuthState {
isAuthenticated: boolean;
user: { id: number; username: string } | null;
}
type AuthAction =
| { type: 'LOGIN'; payload: { id: number; username: string } }
| { type: 'LOGOUT' };
// Define the reducer function
const authReducer = (state: AuthState, action: AuthAction): AuthState => {
switch (action.type) {
case 'LOGIN':
return { ...state, isAuthenticated: true, user: action.payload };
case 'LOGOUT':
return { ...state, isAuthenticated: false, user: null };
default:
return state;
}
};
// Create the context
interface AuthContextType {
state: AuthState;
dispatch: React.Dispatch;
}
const AuthContext = createContext(undefined);
// Create the provider component
interface AuthProviderProps {
children: React.ReactNode;
}
const AuthProvider: React.FC = ({ children }) => {
const [state, dispatch] = useReducer(authReducer, { isAuthenticated: false, user: null });
return (
{children}
);
};
// Create a custom hook to consume the context
const useAuth = () => {
const context = useContext(AuthContext);
if (!context) {
throw new Error('useAuth must be used within an AuthProvider');
}
return context;
};
export { AuthProvider, useAuth };
// Usage in a component
const LoginComponent: React.FC = () => {
const { dispatch } = useAuth();
const handleLogin = () => {
// Simulate login
dispatch({ type: 'LOGIN', payload: { id: 1, username: 'testuser' } });
};
return (
Login
);
};
"""
### 2.2. Redux (for complex, application-wide state management)
* **Do This:** Use Redux for managing global application state, especially in large, complex applications. Combine with Redux Toolkit to simplify configuration and reduce boilerplate.
* **Don't Do This:** Use Redux for simple, component-local state. Opt for "useState" or "useReducer" in those cases. Avoid overly complex or deeply nested state structures that can hurt performance.
**Why:** Redux provides a centralized store, predictable state transitions, and a rich ecosystem of middleware and tools. Redux Toolkit provides conventions and utilities which make Redux easier to use.
**Code Example (using Redux Toolkit):**
"""typescript
import { configureStore, createSlice, PayloadAction } from '@reduxjs/toolkit';
import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux';
// Define the state type
interface CounterState {
value: number;
}
// Define the initial state
const initialState: CounterState = {
value: 0,
};
// Create a slice
const counterSlice = createSlice({
name: 'counter',
initialState,
reducers: {
increment: (state) => {
state.value += 1;
},
decrement: (state) => {
state.value -= 1;
},
incrementByAmount: (state, action: PayloadAction) => {
state.value += action.payload;
},
},
});
// Export actions and reducer
export const { increment, decrement, incrementByAmount } = counterSlice.actions;
export const counterReducer = counterSlice.reducer;
// Configure the store
const store = configureStore({
reducer: {
counter: counterReducer,
},
});
export default store;
// Define RootState type
export type RootState = ReturnType;
export type AppDispatch = typeof store.dispatch;
// Custom hooks for useSelector and useDispatch with proper typing
export const useAppDispatch: () => AppDispatch = useDispatch;
export const useAppSelector: TypedUseSelectorHook = useSelector;
// Usage in a component
import { useAppDispatch, useAppSelector } from './store';
const Counter: React.FC = () => {
const count = useAppSelector((state) => state.counter.value);
const dispatch = useAppDispatch();
return (
<p>Count: {count}</p>
dispatch(increment())}>Increment
dispatch(decrement())}>Decrement
dispatch(incrementByAmount(5))}>Increment by 5
);
};
export default Counter;
"""
### 2.3. Zustand (for manageable complexity and performance)
* **Do This:** Consider Zustand as a simple, unopinionated state management solution. Suitable for applications where Redux might be overkill but "useReducer" is insufficient. Leverage selectors to optimize component re-renders.
* **Don't Do This:** Use Zustand for highly complex global state scenarios requiring advanced features (e.g., time travel debugging, middleware). Over-rely on global state when component-local state is more appropriate.
**Why:** Zustand is known for its simplicity and ease of use. It combines the benefits of mutable state with controlled updates, leading to good performance. It's an excellent middle-ground option. Selectors ensure components can subscribe to specific parts of the store, reducing unnecessary re-renders.
**Code Example:**
"""typescript
import { create } from 'zustand';
interface BearState {
bears: number;
increasePopulation: () => void;
removeAllBears: () => void;
}
const useBearStore = create((set) => ({
bears: 0,
increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
removeAllBears: () => set({ bears: 0 }),
}));
// Example consumer
import useBearStore from './store';
const BearCounter = () => {
const bears = useBearStore((state) => state.bears); // Select only what is needed
return {bears} around here ...;
};
const Controls = () => {
const increasePopulation = useBearStore((state) => state.increasePopulation);
const removeAllBears = useBearStore((state) => state.removeAllBears);
return (
<>
one up
remove all
)
}
"""
### 2.4. Jotai (for atomic state management)
* **Do This:** Explore Jotai for its approach to state management based on atomic, derived state. It is valuable when needing fine-grained control over state dependencies.
* **Don't Do This:** Attempt to port large Redux codebases to Jotai without careful consideration. Avoid creating excessively granular atoms that lead to performance bottlenecks.
**Why:** Jotai is particularly well-suited for scenarios where components need to subscribe to very specific parts of the state, minimizing re-renders and improving performance. It promotes composition and code reuse.
**Code Example:**
"""typescript
import { atom, useAtom } from 'jotai';
// Create an atom
const countAtom = atom(0);
// Example consumer
const CounterComponent = () => {
const [count, setCount] = useAtom(countAtom);
return (
Count: {count}
setCount(count + 1)}>Increment
);
};
export default CounterComponent;
"""
### 2.5. XState (for managing complex state machines)
* **Do This:** Use XState for orchestrating complex, stateful logic, like multi-step forms, workflows, or UI interactions with clearly defined states and transitions. Leverage TypeScript's type system to fully define state structures and events.
* **Don't Do This:** Overuse XState for simple UI element state. Avoid creating state machines that are excessively complex or difficult to understand.
**Why:** XState helps to manage complexity by providing a visual and declarative way to define states and transitions. TypeScript integration further enhances the development experience and ensures type safety.
**Code Example:**
"""typescript
import { createMachine, assign } from 'xstate';
import { useMachine } from '@xstate/react';
// Define the state machine context
interface ContextType {
count: number;
}
// Define the state machine events
type EventType =
| { type: 'INCREMENT' }
| { type: 'DECREMENT' };
// Create the state machine
const counterMachine = createMachine(
{
id: 'counter',
initial: 'idle',
context: {
count: 0,
},
states: {
idle: {
on: {
INCREMENT: {
actions: assign({ count: (context) => context.count + 1 }),
},
DECREMENT: {
actions: assign({ count: (context) => context.count - 1 }),
},
},
},
},
}
);
// React component using the state machine
const CounterComponent = () => {
const [state, send] = useMachine(counterMachine);
return (
Count: {state.context.count}
send('INCREMENT')}>Increment
send('DECREMENT')}>Decrement
);
};
export default CounterComponent;
"""
## 3. Reactive Programming with RxJS
### 3.1. Observables for Asynchronous Data Streams
* **Do This:** Use RxJS Observables to handle asynchronous data streams, user input, and event-driven interactions.
* **Don't Do This:** Use RxJS for simple, synchronous operations that can be handled with standard JavaScript methods. Overuse or abuse Subjects, leading to uncontrolled side effects.
**Why:** Observables provide a powerful and flexible way to manage asynchronous data over time. RxJS offers a wide range of operators for transforming, filtering, and combining streams of data.
**Code Example:**
"""typescript
import { fromEvent, interval } from 'rxjs';
import { map, filter, take, scan } from 'rxjs/operators';
// Create an observable from a DOM event
const button = document.getElementById('myButton');
if (button) {
const click$ = fromEvent(button, 'click'); // Ensure button isn't null
click$.pipe(
map(() => 1),
scan((acc, val) => acc + val, 0)
).subscribe(count => {
console.log("Button clicked ${count} times");
});
}
// Create an observable from an interval
const interval$ = interval(1000);
interval$.pipe(
filter(value => value % 2 === 0),
map(value => "Tick: ${value}"),
take(5)
).subscribe(message => {
console.log(message);
});
"""
### 3.2. Subjects for Multicasting
* **Do This:** Use RxJS Subjects to multicast values to multiple observers. Use "BehaviorSubject" or "ReplaySubject" when you need to provide an initial value or replay past values, respectively.
* **Don't Do This:** Expose Subjects directly to components. Encapsulate them within services or state management solutions to control the flow of data.
**Why:** Subjects act as both an Observable and an Observer, allowing you to push values to multiple subscribers. They are useful for creating shared data streams or event buses.
**Code Example:**
"""typescript
import { Subject } from 'rxjs';
// Create a Subject
const mySubject = new Subject();
// Subscribe to the Subject
mySubject.subscribe(value => {
console.log("Observer 1: ${value}");
});
mySubject.subscribe(value => {
console.log("Observer 2: ${value}");
});
// Push values to the Subject
mySubject.next('Hello');
mySubject.next('World');
"""
## 4. Practical Implementation Considerations
### 4.1. TypeScript Typing
* **Do This:** Use strong typing to define the shape of your state, actions, and reducers.
* **Don't Do This:** Use "any" or "unknown" types excessively, which defeats the purpose of using TypeScript.
**Why:** Strong typing improves code maintainability, prevents runtime errors, and enhances code completion in IDEs.
**Code Example:**
"""typescript
interface Product {
id: number;
name: string;
price: number;
}
type ProductAction =
| { type: "ADD_PRODUCT"; payload: Product }
| { type: "REMOVE_PRODUCT"; payload: number };
interface ProductState {
products: Product[];
}
"""
### 4.2. Performance Optimization
* **Do This:** Use memoization techniques (e.g., "useMemo", "useCallback", "React.memo") to prevent unnecessary re-renders. Select only the necessary data from the state to avoid triggering updates when unrelated data changes.
* **Don't Do This:** Neglect performance optimization, especially in large applications with frequent state updates. Deeply nested state often triggers expensive rerenders.
**Why:** Optimizing performance ensures a smooth user experience and reduces resource consumption. Memoization and selective updates can significantly improve rendering performance.
### 4.3. Testing
* **Do This:** Write unit tests for your reducers, selectors, and effects to ensure they behave as expected.
* **Don't Do This:** Neglect testing state management logic, which can lead to unexpected behavior and difficult-to-debug issues.
**Why:** Thorough testing is essential for maintaining the integrity of your state management system. Unit tests provide confidence that your code is working correctly and prevent regressions when making changes.
### 4.4. Error Handling
* **Do This:** Properly handle errors that may occur during state updates, asynchronous operations, or API calls. Display user-friendly error messages and provide mechanisms for recovering from errors.
* **Don't Do This:** Ignore errors or allow them to propagate silently, which can lead to a poor user experience and data corruption.
**Why:** Robust error handling ensures that your application can gracefully recover from unexpected errors and prevents data loss or corruption.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# TypeScript Performance Optimization Standards: Best Practices for Efficient Applications This document outlines coding standards and best practices specifically for performance optimization in TypeScript projects. Adhering to these guidelines will improve the speed, responsiveness, efficient use of resources, and overall user experience of your applications. ## Table of Contents - [1. Architectural Considerations for Performance](#1-architectural-considerations-for-performance) - [1.1. Code Splitting](#11-code-splitting) - [1.2. Lazy Loading Modules](#12-lazy-loading-modules) - [1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG)](#13-server-side-rendering-ssr-or-static-site-generation-ssg) - [1.4. Data Structure Selection](#14-data-structure-selection) ## 1. Architectural Considerations for Performance ### 1.1. Code Splitting **Standard:** Implement code splitting to reduce the initial load time of your application. **Why:** Loading only the necessary code on initial page load significantly improves the user experience. **Do This:** * Utilize dynamic imports (`import()`) to load modules on demand. * Configure your bundler (Webpack, Parcel, Rollup) to create separate chunks for different parts of your application. **Don't Do This:** * Load the entire application code in a single bundle. * Use `require()` statements (CommonJS) in modern TypeScript projects where ES Modules are supported. **Example:** ```typescript // Before: Loading everything upfront import { featureA } from './featureA'; import { featureB } from './featureB'; // After: Code splitting with dynamic imports async function loadFeatureA() { const { featureA } = await import('./featureA'); featureA.init(); } async function loadFeatureB() { const { featureB } = await import('./featureB'); featureB.init(); } // Use loadFeatureA or loadFeatureB based on user interaction or route ``` **Bundler Configuration (Webpack example):** ```javascript // webpack.config.js module.exports = { entry: './src/index.ts', output: { filename: '[name].bundle.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/, }, ], }, resolve: { extensions: ['.tsx', '.ts', '.js'], }, optimization: { splitChunks: { chunks: 'all', // Split all chunks of code }, }, }; ``` ### 1.2. Lazy Loading Modules **Standard:** Employ lazy loading for non-critical modules or components. **Why:** Reduce the amount of code that needs to be parsed and compiled on initial load. **Do This:** * Load components or modules only when they are needed. * Utilize Intersection Observer API to load components when they become visible in the viewport. **Don't Do This:** * Load modules that are not immediately required for the current user interaction. **Example (Intersection Observer Lazy Loading):** ```typescript function lazyLoadComponent(element: HTMLElement, importPath: string) { const observer = new IntersectionObserver((entries) => { entries.forEach(async (entry) => { if (entry.isIntersecting) { const { default: Component } = await import(importPath); const componentInstance = new Component(); // Instantiate the component. element.appendChild(componentInstance.render()); // Append to the DOM (adjust according to your framework). observer.unobserve(element); } }); }); observer.observe(element); } // Usage: const lazyComponentElement = document.getElementById('lazy-component'); if (lazyComponentElement) { lazyLoadComponent(lazyComponentElement, './MyHeavyComponent'); } ``` ### 1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG) **Standard:** Consider using SSR or SSG for content-heavy, SEO-sensitive, or performance-critical applications. **Why:** Reduces the time to first paint (TTFP) and improves SEO by providing crawlers with pre-rendered content. **Do This:** * Evaluate the trade-offs between SSR, SSG, and client-side rendering (CSR) based on your application's needs. * Use frameworks like Next.js (React), Nuxt.js (Vue), or Angular Universal. * Implement appropriate caching strategies for SSR. **Don't Do This:** * Default to CSR when SSR or SSG could provide significant performance benefits. **Example (Next.js):** ```typescript // pages/index.tsx (Next.js example) import React from 'react'; interface Props { data: { title: string; description: string; }; } const HomePage: React.FC<Props> = ({ data }) => { return ( <div> <h1>{data.title}</h1> <p>{data.description}</p> </div> ); }; export async function getServerSideProps() { // Fetch data from an API, database, or file system. const data = { title: 'My Awesome Website', description: 'Welcome to my extremely performant website!', }; return { props: { data, }, }; } export default HomePage; ``` ### 1.4. Data Structure Selection **Standard:** Select the most appropriate data structure for each specific use case. **Why:** Using appropriate data structures will reduce the complexity and improve the execution speed of algorithms. **Do This:** * Use `Map` when you need to associate keys with values, especially when the keys are not strings or numbers. * Use `Set` when you need to store a collection of unique values. * Use `Record<K, V>` type for type-safe object mapping. * Consider specialized data structures for specific performance needs (e.g., priority queues, linked lists). **Don't Do This:** * Use generic arrays or objects when more specialized data structures would be more efficient. * Perform frequent lookups in arrays when using a Map or Set would be more performant. **Example:** ```typescript // Before: Using an array for lookups const users = [ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' } ]; // O(n) lookup operation const findUser = (id: number) => users.find(user => user.id === id); // After: Using Map for efficient lookups const userMap = new Map<number, {id: number, name: string}>(); userMap.set(1, { id: 1, name: 'Alice' }); userMap.set(2, { id: 2, name: 'Bob' }); userMap.set(3, { id: 3, name: 'Charlie' }); // O(1) lookup operation const getUser = (id: number) => userMap.get(id); ```
Debe preferir usar el gestor de versiones "pnpm" por sobre "npm" para la ejecución de los comandos.
# Code Style and Conventions Standards for TypeScript This document outlines coding style and conventions standards for TypeScript development. Adhering to these standards promotes code consistency, readability, maintainability, and collaboration within development teams. These guidelines are tailored for the latest version of TypeScript and aim to leverage modern best practices. ## 1. Formatting Consistent formatting is crucial for readability. We adopt the following standards for TypeScript code formatting: ### 1.1. Whitespace and Indentation * **Standard:** Use 2 spaces for indentation. Avoid tabs. * **Why:** Consistent indentation enhances readability and reduces visual clutter. * **Do This:** """typescript function calculateArea(width: number, height: number): number { const area = width * height; return area; } """ * **Don't Do This:** """typescript function calculateArea(width: number, height: number): number { const area = width * height; return area; } """ * **Standard:** Use blank lines to separate logical sections of code within functions and classes. * **Why:** Separating logical blocks improves code comprehension. * **Do This:** """typescript function processData(data: any[]): void { // Validate data if (!data || data.length === 0) { throw new Error("Data is invalid."); } // Transform data const transformedData = data.map(item => ({ ...item, processed: true, })); // Save data saveToDatabase(transformedData); } """ ### 1.2. Line Length * **Standard:** Limit lines to a maximum of 120 characters. * **Why:** Enforces readability on various screen sizes and IDE configurations. * **How:** Configure your editor or IDE to display a line length guide at 120 characters. Break long lines at logical points, such as after commas, operators, or before opening parentheses. * **Do This:** """typescript const veryLongVariableName = calculateSomethingComplicated( param1, param2, param3 ); """ * **Don't Do This:** """typescript const veryLongVariableName = calculateSomethingComplicated(param1, param2, param3); """ ### 1.3. Braces and Parentheses * **Standard:** Use braces for all control flow statements, even single-line statements. * **Why:** Improves code clarity and reduces potential errors when modifying code. * **Do This:** """typescript if (isValid) { console.log("Valid"); } else { console.log("Invalid"); } """ * **Don't Do This:** """typescript if (isValid) console.log("Valid"); else console.log("Invalid"); """ * **Standard:** Use parentheses to clarify operator precedence, where needed. * **Why:** Reduces ambiguity, especially in complex expressions. * **Example:** """typescript const result = (a + b) * c; """ ### 1.4. Semicolons * **Standard:** Always use semicolons to terminate statements. * **Why:** Prevents unexpected behavior due to JavaScript's automatic semicolon insertion (ASI). * **Do This:** """typescript const name = "John"; console.log(name); """ * **Don't Do This:** """typescript const name = "John" console.log(name) """ ## 2. Naming Conventions Consistent naming conventions are essential for code clarity and maintainability. ### 2.1. Variables and Constants * **Standard:** Use camelCase for variable and constant names. * **Why:** Widely adopted convention for JavaScript and TypeScript. * **Do This:** """typescript const userName = "Alice"; let itemCount = 0; """ * **Standard:** Use UPPER_SNAKE_CASE for constant values (i.e. values that may be inlined for performance or are known at compile time). * **Why:** Clearly distinguishes constants from variables. * **Do This:** """typescript const MAX_RETRIES = 3; const API_ENDPOINT = "https://example.com/api"; """ ### 2.2. Functions and Methods * **Standard:** Use camelCase for function and method names. * **Why:** Follows common JavaScript/TypeScript conventions. * **Do This:** """typescript function calculateTotal(price: number, quantity: number): number { return price * quantity; } class ShoppingCart { addItem(item: string): void { console.log("Adding ${item} to the cart."); } } """ ### 2.3. Classes and Interfaces * **Standard:** Use PascalCase for class and interface names. * **Why:** Clearly identifies classes and interfaces. * **Do This:** """typescript interface User { id: number; name: string; } class Product { constructor(public name: string, public price: number) {} } """ ### 2.4. Type Parameters * **Standard:** Use single uppercase letters, typically "T", "U", "V", etc., for generic type parameters. * **Why:** Follows established TypeScript conventions. * **Do This:** """typescript function identity<T>(arg: T): T { return arg; } """ ### 2.5. Boolean Variables * **Standard:** Prefix boolean variables with "is", "has", or "should" to indicate a boolean value. * **Why:** Improves readability by clearly indicating the purpose of the variable. * **Do This:** """typescript let isValid: boolean = true; let hasPermission: boolean = false; let shouldUpdate: boolean = true; """ ## 3. Stylistic Consistency Consistency in style is critical for code maintainability. ### 3.1. Type Annotations and Inference * **Standard:** Use explicit type annotations where type inference is not obvious, especially for function parameters and return types. * **Why:** Improves code clarity and helps catch type-related errors early. * **Do This:** """typescript function greet(name: string): string { return "Hello, ${name}!"; } const add: (x: number, y: number) => number = (x, y) => x + y; """ * **Don't Do This:** """typescript function greet(name) { // Implicit 'any' type return "Hello, ${name}!"; } """ * **Standard:** Leverage type inference for local variables when the type is immediately apparent. * **Why:** Reduces verbosity and keeps code concise. * **Do This:** """typescript const message = "Hello, world!"; // Type inferred as string const count = 10; // Type inferred as number """ * **Standard:** When initializing variables with "null" or "undefined", explicitly define the type. * **Why:** Helps avoid unexpected type-related issues later. * **Do This:** """typescript let user: User | null = null; let data: string[] | undefined = undefined; """ ### 3.2. String Usage * **Standard:** Prefer template literals for string concatenation and multi-line strings. * **Why:** More readable and easier to maintain compared to traditional string concatenation. * **Do This:** """typescript const name = "Alice"; const message = "Hello, ${name}!"; const multiLine = "This is a multi-line string."; """ * **Don't Do This:** """typescript const name = "Alice"; const message = "Hello, " + name + "!"; const multiLine = "This is a\n" + "multi-line string."; """ ### 3.3. Object Literals * **Standard:** Use shorthand notation for object properties when the property name matches the variable name. * **Why:** Improves code conciseness and readability. * **Do This:** """typescript const name = "Alice"; const age = 30; const user = { name, age }; // Shorthand notation """ * **Don't Do This:** """typescript const name = "Alice"; const age = 30; const user = { name: name, age: age }; """ * **Standard:** Use object spread syntax for creating copies of objects or merging objects. * **Why:** More concise and readable than older methods like "Object.assign()". * **Do This:** """typescript const original = { a: 1, b: 2 }; const copy = { ...original, c: 3 }; // Creates a new object with a, b, and c """ ### 3.4. Arrow Functions * **Standard:** Use arrow functions for concise function expressions, especially for callbacks and inline functions. * **Why:** More compact syntax and lexically binds "this". * **Do This:** """typescript const numbers = [1, 2, 3]; const squared = numbers.map(x => x * x); // Concise arrow function """ * **Don't Do This:** """typescript const numbers = [1, 2, 3]; const squared = numbers.map(function(x) { return x * x; }); """ * **Standard:** Omit parentheses for single-parameter arrow functions. * **Why:** Makes the code even more concise. * **Do This:** """typescript const increment = x => x + 1; """ * **Don't Do This:** """typescript const increment = (x) => x + 1; """ ### 3.5. Modern TypeScript Features * **Standard:** Leverage features like optional chaining ("?.") and nullish coalescing ("??") for safer and more concise code. Optional properties on interfaces may be relevant if these are in use. * **Why:** Reduces boilerplate and improves null/undefined handling. * **Do This:** """typescript interface User { profile?: { address?: { city?: string; } } } const user: User = {}; const city = user?.profile?.address?.city ?? "Unknown"; // Nullish coalescing console.log(city); interface Config { timeout?: number; } const defaultConfig: Config = { timeout: 5000, }; function initialize(config?: Config) { const timeout = config?.timeout ?? defaultConfig.timeout; console.log("Timeout: ${timeout}"); } initialize(); // Timeout: 5000 initialize({ timeout: 10000 }); // Timeout: 10000 """ * **Standard:** Utilize discriminated unions and exhaustive checks for increased type safety and maintainability. * **Why:** Improves type correctness and makes it easier to handle different states or object types. * **Do This:** """typescript interface Success { type: "success"; result: any; } interface Error { type: "error"; message: string; } type Result = Success | Error; function handleResult(result: Result) { switch (result.type) { case "success": console.log("Success:", result.result); break; case "error": console.error("Error:", result.message); break; default: // Exhaustive check: TypeScript will flag this if a new type is added to Result const _exhaustiveCheck: never = result; return _exhaustiveCheck; } } const successResult: Success = { type: "success", result: { data: "example" } }; const errorResult: Error = { type: "error", message: "Something went wrong" }; handleResult(successResult); handleResult(errorResult); """ ### 3.6. Asynchronous Code * **Standard:** Always use "async/await" syntax for asynchronous operations. * **Why:** Improves readability and simplifies error handling compared to traditional promise chains. * **Do This:** """typescript async function fetchData(): Promise<any> { try { const response = await fetch("https://example.com/api/data"); const data = await response.json(); return data; } catch (error) { console.error("Error fetching data:", error); throw error; } } """ * **Don't Do This:** """typescript function fetchData(): Promise<any> { return fetch("https://example.com/api/data") .then(response => response.json()) .then(data => data) .catch(error => { console.error("Error fetching data:", error); throw error; }); } """ * **Standard:** Use "Promise.all" for concurrent asynchronous operations that don't depend on each other. * **Why:** Improves performance by executing asynchronous tasks in parallel. * **Do This:** """typescript async function processData(): Promise<void> { const [result1, result2] = await Promise.all([ fetchData1(), fetchData2(), ]); console.log("Result 1:", result1); console.log("Result 2:", result2); } """ ### 3.7 Error Handling * **Standard:** Implement robust error handling using "try...catch" blocks, especially in asynchronous functions. * **Why:** Prevents unhandled exceptions and allows for graceful recovery. * **Do This:** """typescript async function doSomething() { try { const result = await someAsyncOperation(); console.log("Result:", result); } catch (error) { console.error("An error occurred:", error); // Implement specific error handling/logging } } """ * **Standard:** Create custom error classes to provide more context and specify error handling logic. * **Why:** Extends the built-in Error to communicate more specific information about the error to the outside world. * **Do This:** """typescript class CustomError extends Error { constructor(message: string, public errorCode: number) { super(message); this.name = "CustomError"; Object.setPrototypeOf(this, CustomError.prototype); } } async function performOperation() { try { // some operation throw new CustomError("Operation failed", 500); } catch (error) { if (error instanceof CustomError) { console.error("Custom Error ${error.errorCode}: ${error.message}"); } else { console.error("An unexpected error occurred:", error); } } } """ ### 3.8 Immutability * **Standard:** Strive for immutability whenever practical, using "const" for variables that should not be reassigned and avoiding direct modification of objects and arrays. * **Why:** Makes code more predictable and easier to reason about, reducing the risk of bugs. * **Do This:** """typescript const originalArray = [1, 2, 3]; const newArray = [...originalArray, 4]; // Creates a new array const originalObject = { a: 1, b: 2 }; const newObject = { ...originalObject, c: 3 }; // Creates a new object """ * **Don't Do This:** """typescript const originalArray = [1, 2, 3]; originalArray.push(4); // Modifies the original array const originalObject = { a: 1, b: 2 }; originalObject.c = 3; // Modifies the original object """ ### 3.9 Comments * **Standard:** Add comments to explain complex or non-obvious logic, but prioritize writing self-documenting code. * **Why:** Comments should supplement, not replace, clear code. * **Guidelines:** * Use JSDoc-style comments for documenting functions, classes, and interfaces. * Explain the *why*, not the *what*. The code should explain what it does. * Keep comments concise and up-to-date. * Remove outdated or redundant comments. * **Example:** """typescript /** * Calculates the area of a rectangle. * @param width The width of the rectangle. * @param height The height of the rectangle. * @returns The area of the rectangle. */ function calculateArea(width: number, height: number): number { return width * height; } """ ## 4. Technology Specific Details (Distinguishing Good from Great) * **Standard:** Take advantage of TypeScript's advanced type features to create robust and maintainable code structures. * **Guidelines:** * **Utility Types:** Employ TypeScript's utility types ("Partial", "Readonly", "Pick", "Omit", "Record", etc.) to manipulate types and generate new types efficiently. """typescript interface User { id: number; name: string; email: string; age: number; } // Make all properties optional type PartialUser = Partial<User>; // Make specified properties required type RequiredIdAndName = Required<Pick<User, 'id' | 'name'>>; // Type with only certain properties type UserInfo = Pick<User, 'name' | 'email'>; // Type without certain properties type UserWithoutId = Omit<User, 'id'>; """ * **Mapped Types:** Utilize mapped types to transform the properties of an existing type, providing a dynamic way to define new types based on existing ones. """typescript interface Product { id: string; name: string; price: number; } // Create a read-only version of Product type ReadonlyProduct = Readonly<Product>; // Create a type where all properties of Product are nullable type NullableProduct = { [K in keyof Product]: Product[K] | null; }; """ * **Conditional Types:** Conditional types allow to define types based on conditions, adding yet another powerful layer of abstraction to type definitions. They help to ensure type safety throughout an application. """typescript type NonNullableProperty<T, K extends keyof T> = T[K] extends null | undefined ? never : K; type RequiredProperties<T> = Pick<T, NonNullableProperty<T, keyof T>>; interface Configuration { host?: string; port?: number; // Port can be potentially undefined or null timeout?: number; } // Extracts properties that are guaranteed to be assigned during runtime. type RuntimeProperties = RequiredProperties<Configuration>; // Result equivalent to {timeout: number;} """ * **Decorators:** Use decorators to add metadata or modify the behavior of classes, methods, properties, or parameters. * **Why:** Provide a declarative and reusable way to add functionality, such as logging, validation, or dependency injection. * **Example:** """typescript function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; descriptor.value = function(...args: any[]) { console.log("Calling method ${propertyKey} with arguments: ${JSON.stringify(args)}"); const result = originalMethod.apply(this, args); console.log("Method ${propertyKey} returned: ${result}"); return result; }; return descriptor; } class Calculator { @logMethod add(a: number, b: number): number { return a + b; } } const calculator = new Calculator(); calculator.add(2, 3); // Output: // Calling method add with arguments: [2,3] // Method add returned: 5 """ ## 5. Tooling * **Standard:** Use Prettier for automatic code formatting and ESLint with recommended TypeScript rules for linting. * **Why:** Automates formatting and enforces code quality, reducing manual effort and improving consistency. * **Configuration:** Configure Prettier and ESLint to work seamlessly with your IDE and CI/CD pipeline. * **Example ".eslintrc.js" configuration:** """javascript module.exports = { parser: "@typescript-eslint/parser", parserOptions: { ecmaVersion: 2020, sourceType: "module", project: './tsconfig.json', }, plugins: ["@typescript-eslint"], extends: [ "eslint:recommended", "plugin:@typescript-eslint/recommended", "plugin:@typescript-eslint/recommended-requiring-type-checking", "prettier", ], rules: { // Add or override rules here }, }; """ By adhering to these coding standards, TypeScript projects will benefit from improved code quality, readability, and maintainability, fostering a collaborative and productive development environment.
# Core Architecture Standards for TypeScript This document outlines coding standards specifically for the core architecture of TypeScript projects. It focuses on fundamental architectural patterns, project structure, and organization principles essential for large, maintainable, and scalable TypeScript applications. ## 1. Architectural Patterns ### 1.1 Microservices Architecture **Standard:** When building large-scale applications, consider a microservices architecture. * **Do This:** Decompose the application into independent, deployable services. Each service should own a specific business domain. * **Don't Do This:** Create a monolithic application that combines disparate functionalities into a single codebase, leading to tightly coupled components and scalability bottlenecks. **Why:** Microservices enable independent scaling, deployment, and technology choices for different parts of the application, significantly boosting agility and resilience. **Code Example:** Illustrating a simple microservice interface """typescript // microservice-interface.ts export interface UserService { getUser(id: string): Promise<{ id: string; name: string; email: string }>; createUser(user: { name: string; email: string }): Promise<string>; } export class UserServiceClient implements UserService { private baseUrl: string; constructor(baseUrl: string) { this.baseUrl = baseUrl; } async getUser(id: string): Promise<{ id: string; name: string; email: string }> { const response = await fetch("${this.baseUrl}/users/${id}"); return response.json(); } async createUser(user: { name: string; email: string }): Promise<string> { const response = await fetch("${this.baseUrl}/users", { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(user), }); const newUser = await response.json(); return newUser.id; } } """ ### 1.2 Layered Architecture **Standard:** Organize code into distinct layers (presentation, application, domain, infrastructure). * **Do This:** Separate concerns by grouping related functionality into loosely coupled layers. * **Don't Do This:** Mix presentation logic with business rules or database access code. **Why:** Layered architecture improves testability, maintainability, and reusability by isolating dependencies and responsibilities. **Code Example:** Layered approach to data handling with repositories """typescript // domain/user.ts export interface User { id: string; name: string; email: string; } // infrastructure/user-repository.ts import { User } from '../domain/user'; export interface UserRepository { getUserById(id: string): Promise<User | null>; saveUser(user: User): Promise<void>; } export class InMemoryUserRepository implements UserRepository { private users: { [id: string]: User } = {}; async getUserById(id: string): Promise<User | null> { return this.users[id] || null; } async saveUser(user: User): Promise<void> { this.users[user.id] = user; } } // application/user-service.ts import { UserRepository, InMemoryUserRepository } from '../infrastructure/user-repository'; import { User } from '../domain/user'; export class UserService { private userRepository: UserRepository; constructor(userRepository: UserRepository) { this.userRepository = userRepository; } async getUser(id: string): Promise<User | null> { return this.userRepository.getUserById(id); } async createUser(name: string, email: string): Promise<User> { const id = Math.random().toString(36).substring(2, 15); // generate a more robust ID for real applications const user: User = { id, name, email }; await this.userRepository.saveUser(user); return user; } } // presentation/user-controller.ts import { UserService } from '../application/user-service'; import { InMemoryUserRepository } from '../infrastructure/user-repository'; const userRepository = new InMemoryUserRepository(); const userService = new UserService(userRepository); async function main() { const newUser = await userService.createUser("John Doe", "john.doe@example.com"); const retrievedUser = await userService.getUser(newUser.id); console.log(retrievedUser); } main(); """ ### 1.3 Hexagonal Architecture (Ports and Adapters) **Standard:** Decouple the core business logic from external dependencies using ports and adapters. * **Do This:** Define interfaces (ports) for interacting with external systems (databases, APIs, UI). Implement adapters that translate between these interfaces and the specific technologies. * **Don't Do This:** Directly embed database queries or API calls within the core domain logic. **Why:** Hexagonal architecture makes it easier to switch technologies, test the core logic in isolation, and adapt to changing requirements. **Code Example:** Hexagonal Architecture using TypeScript interfaces & implementations """typescript // Interface -> Port interface PaymentGateway { processPayment(amount: number, creditCard: string): Promise<boolean>; } // Implementation -> Adapter for Stripe class StripePaymentGateway implements PaymentGateway { async processPayment(amount: number, creditCard: string): Promise<boolean> { // integrate with Stripe API here. For example: console.log("Processing $${amount} via Stripe with credit card ${creditCard}"); return true; // Simulated result } } // Implementation -> Adapter for PayPal class PayPalPaymentGateway implements PaymentGateway { async processPayment(amount: number, creditCard: string): Promise<boolean> { // integrate with PayPal API here console.log("Processing $${amount} via PayPal with credit card ${creditCard}"); return true; // Simulated result } } // Core Application Logic class PaymentService { private paymentGateway: PaymentGateway; constructor(paymentGateway: PaymentGateway) { this.paymentGateway = paymentGateway; } async charge(amount: number, creditCard: string): Promise<boolean> { return await this.paymentGateway.processPayment(amount, creditCard); } } // Usage: async function main() { const stripeGateway = new StripePaymentGateway(); const payPalGateway = new PayPalPaymentGateway(); const paymentServiceStripe = new PaymentService(stripeGateway); // Inject Stripe const paymentServicePayPal = new PaymentService(payPalGateway); // Inject PayPal const stripeResult = await paymentServiceStripe.charge(100, "1234-5678-9012-3456"); const paypalResult = await paymentServicePayPal.charge(50, "9876-5432-1098-7654"); console.log("Stripe Payment Result: ${stripeResult}"); console.log("PayPal Payment Result: ${paypalResult}"); } main(); """ ### 1.4 CQRS (Command Query Responsibility Segregation) **Standard:** Separate read operations (queries) from write operations (commands). * **Do This:** Define dedicated models and data access patterns for reading and writing data. * **Don't Do This:** Use the same data model and database queries for both reads and writes, potentially leading to performance issues and complex code. **Why:** CQRS allows optimizing read and write operations independently. This is particularly useful in scenarios with high read/write ratios. **Code Example:** Implementing CQRS pattern in TypeScript """typescript // Command: CreateUserCommand interface CreateUserCommand { type: 'CreateUser'; name: string; email: string; } // Query: GetUserQuery interface GetUserQuery { type: 'GetUser'; id: string; } // Command Handler class UserCommandHandler { async handle(command: CreateUserCommand): Promise<string> { if (command.type === 'CreateUser') { // Create user logic (e.g., save to database) const userId = Math.random().toString(36).substring(2, 15); console.log("Creating user with name ${command.name} and email ${command.email} (ID: ${userId})"); return userId // Return the new User ID } throw new Error('Invalid command'); } } // Query Handler class UserQueryHandler { async handle(query: GetUserQuery): Promise<{ id: string; name: string; email: string } | null > { if (query.type === 'GetUser') { // Retrieve user logic (e.g., fetch from database) console.log("Retrieving user with ID ${query.id}"); return { id: query.id, name: 'Example User', email: 'user@example.com' }; } throw new Error('Invalid query'); } } // Usage example: async function main() { const commandHandler = new UserCommandHandler(); const queryHandler = new UserQueryHandler(); const createUserCommand: CreateUserCommand = { type: 'CreateUser', name: 'John Doe', email: 'john.doe@example.com' }; const userId = await commandHandler.handle(createUserCommand); // creates a theoretical user console.log("User created with ID: ${userId}"); const getUserQuery: GetUserQuery = { type: 'GetUser', id: userId // Using the generated user ID }; const user = await queryHandler.handle(getUserQuery); if(user){ console.log("Retrieved user: ${JSON.stringify(user)}"); } else { console.log("User with ID ${getUserQuery.id} not found."); } } main(); """ ## 2. Project Structure and Organization ### 2.1 Modular File Structure **Standard:** Organize code into modules based on functionality, following a logical directory structure. * **Do This:** Group related files (components, services, interfaces) within dedicated directories. Use meaningful names for files and directories. Consider feature-based or layer-based structuring. * **Don't Do This:** Place all files in a single directory or create a folder structure that mirrors implementation details rather than business logic. **Why:** A modular structure improves code discoverability, maintainability, and collaboration among developers. """ src/ ├── components/ # Reusable UI components │ ├── button/ # Specific Button component │ │ ├── button.tsx # JSX code │ │ ├── button.module.css # Styles using CSS modules │ │ └── index.ts # Exports │ ├── input/ # Specific Input component │ │ ├── input.tsx # JSX code │ │ ├── input.module.css # Styles using CSS modules │ │ └── index.ts # Exports │ └── index.ts # Exports all reusable components ├── services/ # Business logic and API interactions │ ├── auth/ # Authentication-specific logic │ │ ├── auth-service.ts # Authentication service │ │ └── index.ts # Exports │ ├── api/ # API client │ │ ├── api-client.ts # API client │ │ └── index.ts # Exports │ └── index.ts # Exports all services ├── models/ # Data models / Types │ ├── user.ts # User model │ └── product.ts # Product model ├── utils/ # Utility functions │ ├── helper-functions.ts # Various utility functions │ └── index.ts # Exports ├── app.tsx # Main application component ├── styles/ # Global styles │ └── global.css ├── index.tsx # Entry point └── tsconfig.json # TypeScript configuration """ ### 2.2 Explicit Dependencies **Standard:** Declare all dependencies explicitly using "import" statements. * **Do This:** Import only the necessary modules or functions. Use named imports where possible. * **Don't Do This:** Rely on implicit global variables or wildcard imports ("import * as ..."). **Why:** Explicit dependencies allow for better code analysis, refactoring, and dependency management. **Code Example:** Named vs. wildcard imports """typescript // Good: Named imports import { useState, useEffect } from 'react'; import { calculateTotal } from './utils'; // Bad: Wildcard imports (less explicit) import * as React from 'react'; // Avoid unless necessary import * as Utils from './utils';// Avoid unless necessary """ ### 2.3 Single Responsibility Principle (SRP) **Standard:** Each module (class, function, component) should have one, and only one, reason to change. * **Do This:** Decompose complex functionalities into smaller, focused modules. * **Don't Do This:** Create "god classes" or functions that handle multiple unrelated tasks. **Why:** SRP simplifies code, improves testability, and reduces the risk of introducing unintended side effects when modifying existing code. **Code Example:** Adhering to Single Responsibility Principle """typescript // Good: Separate classes for user authentication and profile management // Class to Handle Authentication class AuthenticationService { async login(username: string, password: string): Promise<boolean> { // Authentication logic here console.log("Authenticating user ${username}"); return true; // Simulate successful authentication } async logout(): Promise<void> { // Logout logic here console.log('Logging out user'); } } // Class to Handle User Profiles class UserProfileService { async getUserProfile(userId: string): Promise<{ id: string; username: string; }> { // Logic to retrieve user profile console.log("Fetching profile for user ID ${userId}"); return { id: userId, username: 'exampleUser' }; // Simulate profile data } async updateUserProfile(userId: string, newData: any): Promise<void> { // Logic to update user profile console.log("Updating profile for user ID ${userId} with data:", newData); } } const authService = new AuthenticationService(); const profileService = new UserProfileService(); async function main() { const isLoggedIn = await authService.login('user123', 'password'); if (isLoggedIn) { const userProfile = await profileService.getUserProfile('user123'); console.log('User Profile:', userProfile); } } main(); """ ### 2.4 Separation of Concerns (SoC) **Standard:** Divide the application into distinct sections, each addressing a separate concern. * **Do This:** Isolate UI rendering from data fetching, business logic from infrastructure code, etc. * **Don't Do This:** Mix different concerns within the same module or component, leading to tightly coupled and difficult-to-maintain code. **Why:** SoC promotes modularity, testability, and reusability. **Code Example:** Separating data fetching concerns from UI """typescript // Bad: Mixing data fetching with UI rendering within the same component // (Leads to tight coupling and makes it difficult to test and reuse) // Consider isolating data fetching logic using custom hooks or services. import React, { useState, useEffect } from 'react'; interface User { id: number; name: string; email: string; } function UserProfileComponent({ userId }: { userId: string }) { const [user, setUser] = useState<User | null>(null); const [loading, setLoading] = useState(true); useEffect(() => { async function fetchUser() { try { const response = await fetch("https://jsonplaceholder.typicode.com/users/${userId}"); if (!response.ok) { throw new Error("HTTP error! Status: ${response.status}"); } const data: User = await response.json(); setUser(data); } catch (error) { console.error('Error fetching user:', error); } finally { setLoading(false); } } fetchUser(); }, [userId]); if (loading) { return <div>Loading user profile...</div>; } if (!user) { return <div>Failed to load user profile.</div>; } // Rendering the user profile return ( <div> <h2>User Profile</h2> <p>Name: {user.name}</p> <p>Email: {user.email}</p> </div> ); } export default UserProfileComponent; // More robust example using custom hook import React from 'react'; import { useUser } from './useUser'; // Custom hook interface User { id: number; name: string; email: string; } function UserProfileComponentHooked({ userId }: { userId: string }) { const { user, loading, error } = useUser(userId); // Use the custom hook if (loading) { return <div>Loading user profile...</div>; } if (error) { return <div>Error: {error.message}</div>; } if (!user) { return <div>User not found.</div>; } return ( <div> <h2>User Profile</h2> <p>Name: {user.name}</p> <p>Email: {user.email}</p> </div> ); } export default UserProfileComponentHooked; // Custom hook import { useState, useEffect } from 'react'; interface User { id: number; name: string; email: string; } interface UseUserResult { user: User | null; loading: boolean; error: Error | null; } export function useUser(userId: string): UseUserResult { const [user, setUser] = useState<User | null>(null); const [loading, setLoading] = useState(true); const [error, setError] = useState<Error | null>(null); useEffect(() => { async function fetchUser() { setLoading(true); setError(null); try { const response = await fetch("https://jsonplaceholder.typicode.com/users/${userId}"); if (!response.ok) { throw new Error("HTTP error! Status: ${response.status}"); } const data: User = await response.json(); setUser(data); } catch (e:any) { setError(e); } finally { setLoading(false); } } fetchUser(); }, [userId]); return { user, loading, error }; } """ ## 3. Design Patterns ### 3.1 Factory Pattern **Standard:** Use factory functions or classes to create objects, abstracting away the concrete implementation details. * **Do This:** Define a factory interface or abstract class and create concrete factories that implement the interface. * **Don't Do This:** Directly instantiate concrete classes throughout the codebase, tightly coupling code to specific implementations. **Why:** The Factory Pattern promotes loose coupling and allows for easy substitution of object implementations. **Code Example:** Factory pattern in typescript """typescript // Interface for different payment methods interface PaymentMethod { processPayment(amount: number): void; } // Concrete implementation for Credit Card payment class CreditCardPayment implements PaymentMethod { processPayment(amount: number): void { console.log("Processing credit card payment of $${amount}"); } } // Concrete implementation for PayPal payment class PayPalPayment implements PaymentMethod { processPayment(amount: number): void { console.log("Processing PayPal payment of $${amount}"); } } // Factory interface interface PaymentMethodFactory { createPaymentMethod(): PaymentMethod; } // Concrete factory for creating Credit Card payments class CreditCardPaymentFactory implements PaymentMethodFactory { createPaymentMethod(): PaymentMethod { return new CreditCardPayment(); } } // Concrete factory for creating PayPal payments class PayPalPaymentFactory implements PaymentMethodFactory { createPaymentMethod(): PaymentMethod { return new PayPalPayment(); } } // The client code that uses the factory to create payment methods class PaymentProcessor { private factory: PaymentMethodFactory; constructor(factory: PaymentMethodFactory) { this.factory = factory; } processOrder(amount: number): void { const paymentMethod = this.factory.createPaymentMethod(); paymentMethod.processPayment(amount); } } // Usage async function main() { const creditCardFactory = new CreditCardPaymentFactory(); const payPalFactory = new PayPalPaymentFactory(); const paymentProcessor1 = new PaymentProcessor(creditCardFactory); paymentProcessor1.processOrder(100); // Output: Processing credit card payment of $100 const paymentProcessor2 = new PaymentProcessor(payPalFactory); paymentProcessor2.processOrder(50); // Output: Processing PayPal payment of $50 } main(); """ ### 3.2 Observer Pattern **Standard:** Define a one-to-many dependency between objects, so that when one object changes state, all its dependents are notified and updated automatically. * **Do This:** Create a "Subject" interface that provides methods for attaching and detaching observers * **Don't Do This:** Have tight coupling between objects by directly calling methods on other objects. **Why:** The Observer Pattern decouples the subject from its observers, making it easier to add or remove observers without modifying the subject. **Code Example:** Implementation """typescript // Observer Interface interface Observer { update(message: string): void; } // Subject Interface interface Subject { attach(observer: Observer): void; detach(observer: Observer): void; notify(message: string): void; } // Concrete Observer class ConcreteObserver implements Observer { private id: number; constructor(id: number) { this.id = id; } update(message: string): void { console.log("Observer ${this.id}: Received message - ${message}"); } } // Concrete Subject class ConcreteSubject implements Subject { private observers: Observer[] = []; attach(observer: Observer): void { this.observers.push(observer); } detach(observer: Observer): void { this.observers = this.observers.filter(obs => obs !== observer); } notify(message: string): void { this.observers.forEach(observer => observer.update(message)); } // Method to update state and notify observers someBusinessLogic(): void { console.log('Subject: Doing something important.'); this.notify('Important message from Subject!'); } } // Usage async function main() { const subject = new ConcreteSubject(); const observer1 = new ConcreteObserver(1); const observer2 = new ConcreteObserver(2); const observer3 = new ConcreteObserver(3); subject.attach(observer1); subject.attach(observer2); subject.someBusinessLogic(); subject.detach(observer2); // Detach observer2 subject.attach(observer3); subject.someBusinessLogic(); } main(); """ ### 3.3 Strategy Pattern **Standard:** Define a family of algorithms, encapsulate each one, and make them interchangeable. Strategy lets the algorithm vary independently from clients that use it. * **Do This:** Create a strategy interface that defines a method the strategies must implement, then each concrete strategy implements this interface. * **Don't Do This:** Hardcode the execution path. **Why:** To encapsulate variation. **Code Example:** Implementation """typescript // Strategy Interface interface SortStrategy { sort(data: number[]): number[]; } // Concrete Strategy 1: Bubble Sort class BubbleSortStrategy implements SortStrategy { sort(data: number[]): number[] { console.log('Sorting using bubble sort'); // Bubble Sort implementation const n = data.length; for (let i = 0; i < n - 1; i++) { for (let j = 0; j < n - i - 1; j++) { if (data[j] > data[j + 1]) { // Swap data[j] and data[j+1] const temp = data[j]; data[j] = data[j + 1]; data[j + 1] = temp; } } } return data; } } // Concrete Strategy 2: Quick Sort class QuickSortStrategy implements SortStrategy { sort(data: number[]): number[] { console.log('Sorting using quick sort'); // Quick Sort implementation if (data.length <= 1) { return data; } const pivot = data[0]; const left = []; const right = []; for (let i = 1; i < data.length; i++) { if (data[i] < pivot) { left.push(data[i]); } else { right.push(data[i]); } } return this.sort(left).concat(pivot, this.sort(right)); } } // Context class Sorter { private strategy: SortStrategy; constructor(strategy: SortStrategy) { this.strategy = strategy; } setStrategy(strategy: SortStrategy): void { this.strategy = strategy; } sort(data: number[]): number[] { return this.strategy.sort(data); } } // Usage async function main() { const data = [5, 2, 8, 1, 9, 4]; const bubbleSort = new BubbleSortStrategy(); const quickSort = new QuickSortStrategy(); const sorter = new Sorter(bubbleSort); // Initial strategy is Bubble Sort console.log('Sorted array using Bubble Sort:', sorter.sort([...data])); sorter.setStrategy(quickSort); // Change the strategy to Quick Sort console.log('Sorted array using Quick Sort:', sorter.sort([...data])); } main(); """ ## 4. TypeScript Specific Considerations ### 4.1 Strict Mode **Standard:** Enable TypeScript's strict mode ("strict: true" in "tsconfig.json"). * **Do This:** Embrace strict null checks, no implicit "any", and other strictness flags. Fix related typing issues. * **Don't Do This:** Disable strict mode to avoid compiler errors, as this can hide potential runtime bugs. **Why:** Strict mode enforces stricter type checking, leading to more robust and maintainable code. ### 4.2 Utility Types **Standard:** Leverage TypeScript's utility types (e.g., "Partial", "Readonly", "Pick", "Omit") to manipulate types and improve code clarity. """typescript interface User { id: string; name: string; email: string; createdAt: Date; } // Make all properties optional type PartialUser = Partial<User>; // Make all properties readonly type ReadonlyUser = Readonly<User>; // Pick only id and name properties type UserName = Pick<User, 'id' | 'name'>; // Omit the createdAt property type UserWithoutCreatedAt = Omit<User, 'createdAt'>; """ ### 4.3 Type Inference **Standard:** Take advantage of TypeScript's type inference capabilities to reduce boilerplate and improve code readability. **Code Example:** """typescript // TypeScript infers the type of 'message' to be string const message = "Hello, TypeScript!"; // TypeScript infers the return type of the function function add(a: number, b: number) { return a + b; } """ ### 4.4 Declaration Files **Standard:** Provide declaration files (".d.ts") for libraries or modules to enable type checking and code completion for consumers. * **Do This:** Use automatic declaration generation ("declaration: true" in "tsconfig.json") or manually create declaration files when necessary. * **Don't Do This:** Ship JavaScript code without corresponding declaration files, limiting the usability of the code in TypeScript projects. ### 4.5 Advanced Types **Standard:** Use advanced TypeScript features like discriminated unions, conditional types, and mapped types where appropriate to model complex data structures and relationships. """typescript // Discriminated Union interface Circle { kind: 'circle'; radius: number; } interface Square { kind: 'square'; sideLength: number; } type Shape = Circle | Square; function getArea(shape: Shape): number { switch (shape.kind) { case 'circle': return Math.PI * shape.radius ** 2; case 'square': return shape.sideLength ** 2; } } """ ### 4.6 Decorators **Standard:** Use decorators to add metadata or modify the behavior of classes, methods, or properties, but adhere to a consistent style, avoid complex implementations, and be aware of potential performance implications. """typescript function LogClass(constructor: Function) { console.log("Class ${constructor.name} is being decorated."); } @LogClass class MyClass { constructor() { console.log('MyClass constructor called.'); } } function LogMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; descriptor.value = function(...args: any[]) { console.log("Method ${propertyKey} is being called with arguments:", args); const result = originalMethod.apply(this, args); console.log("Method ${propertyKey} returned:", result); return result; }; return descriptor; } class Calculator { @LogMethod add(a: number, b: number): number { return a + b; } } """ ### 4.7 Use "unknown" type where appropriate **Standard:** Use "unknown" instead of "any" when you need to represent a value of any type but want to ensure type safety. "unknown" forces you to perform type narrowing before using the value, providing better type safety than casually using "any", while not necessarily knowing the implementation types at compile time. """typescript function processData(data: unknown): void { if (typeof data === 'string') { console.log(data.toUpperCase()); // OK, data is string here } else if (typeof data === 'number') { console.log(data * 2); // OK, data is number here } else { console.log('Data is of unknown type'); } } """ These core architecture standards provide a comprehensive foundation for building robust, scalable, and maintainable TypeScript applications. By adhering to these guidelines, development teams can improve code quality, reduce technical debt, and accelerate development.
# Component Design Standards for TypeScript This document outlines the component design standards for TypeScript, focusing on creating reusable, maintainable, and efficient components. These standards aim to guide developers in building robust and scalable applications using modern TypeScript practices. ## I. General Component Design Principles ### 1. Reusability **Standard:** Design components to be reusable across different parts of the application or even different projects. **Why:** Reusability reduces code duplication, simplifies maintenance, and promotes consistency. **Do This:** * **Parameterize:** Accept properties (props) to configure behavior and appearance. * **Separate Concerns:** Avoid tightly coupling components to specific application contexts. * **Use Interfaces:** Define clear interfaces for props and component interactions. **Don't Do This:** * Hardcode values that could vary in different contexts. * Include business logic that is specific to one part of the application within a generic component. **Example:** """typescript // Good - Reusable Button component interface ButtonProps { label: string; onClick: () => void; variant?: "primary" | "secondary"; } const Button: React.FC<ButtonProps> = ({ label, onClick, variant = "primary" }) => { return ( <button className={"button ${variant}"} onClick={onClick}> {label} </button> ); }; // Bad - Button tightly coupled to a specific event const DeleteButton = () => { const handleDelete = () => { // Complex delete logic here... tightly coupled to a specific part of the app } return <button onClick={handleDelete}>Delete Item</button> } """ ### 2. Maintainability **Standard:** Write components that are easy to understand, modify, and debug. **Why:** Well-maintained code reduces the cost of future development and minimizes the risk of introducing bugs. **Do This:** * **Keep Components Small:** Break down large components into smaller, more manageable pieces. * **Use Descriptive Names:** Name components, props, and methods clearly and consistently. * **Add Comments:** Explain complex logic or non-obvious behavior. * **Follow SOLID Principles:** Adhere to the SOLID principles of object-oriented design where applicable. **Don't Do This:** * Create monolithic components that are hard to navigate and understand. * Use cryptic or ambiguous names. * Neglect to document complex or critical sections of code. """typescript // Good - Small and focused component interface InputProps { label: string; value: string; onChange: (newValue: string) => void; type?: string; } const Input: React.FC<InputProps> = ({ label, value, onChange, type = "text" }) => { return ( <div> <label htmlFor={label}>{label}</label> <input type={type} id={label} value={value} onChange={(e) => onChange(e.target.value)} /> </div> ); }; // Bad - Large component with multiple responsibilities const UserForm = () => { //Lots of state management, validation, and rendering logic inside one component = difficult to maintain return ( <div> {/* Form elements and logic for handling user input, validation, and submission */} </div> ) } """ ### 3. Composability **Standard:** Design components that can be easily composed together to create more complex UI elements. **Why:** Composition allows developers to build complex functionalities by combining simple, independent components. **Do This:** * **Use Children Props:** Allow components to render child elements passed as props. * **Provide Configuration Options:** Offer flexibility in how components can be composed. * **Design for Extensibility:** Allow adding new features or behaviors without modifying existing code. **Don't Do This:** * Prevent components from being nested or combined with other components. * Make assumptions about the parent or child components. """typescript // Good - Component that accepts children interface LayoutProps { children: React.ReactNode; } const Layout: React.FC<LayoutProps> = ({ children }) => { return ( <div className="layout"> <header>Header</header> <main>{children}</main> <footer>Footer</footer> </div> ); }; // Usage <Layout> <p>Content inside the layout</p> </Layout> // Bad - Component that tightly controls its content const RestrictedLayout = () => { return ( <div> {/* Only allows specific content, hindering composability */} <p>Specific content here</p> </div> ) } """ ## II. TypeScript-Specific Standards ### 1. Explicit Typing **Standard:** Use explicit types for all component props, state variables, and return types. **Why:** TypeScript's static typing helps catch errors early, improves code readability, and makes refactoring easier. **Do This:** * Always define interfaces or types for component props. * Use type annotations for all state variables. * Specify return types for functions and methods. * Leverage TypeScript's "unknown" and "any" types judiciously. **Don't Do This:** * Rely on implicit "any" types. * Avoid type annotations altogether. """typescript // Good - Explicitly typed component interface ProfileProps { name: string; age: number; occupation: string; } const Profile: React.FC<ProfileProps> = ({ name, age, occupation }) => { return ( <div> <h2>{name}</h2> <p>Age: {age}</p> <p>Occupation: {occupation}</p> </div> ); }; // Example of using "unknown" function processData(data: unknown): void { if (typeof data === 'string') { console.log(data.toUpperCase()); } else if (typeof data === 'number') { console.log(data * 2); } else { console.log("Unsupported data type.") } } // Bad - Implicit any types const BadProfile = (props) => { return ( <div> <h2>{props.name}</h2> // 'props' has an implicit 'any' type. <p>Age: {props.age}</p> <p>Occupation: {props.occupation}</p> </div> ); }; """ ### 2. Interface vs. Type **Standard:** Use interfaces to define the shape of objects, and types for type aliases and unions. **Why:** Interfaces are generally preferred for defining object shapes because they are more extensible and mergeable. **Do This:** * Use "interface" for describing the structure of component props and state. * Use "type" for creating aliases, unions, and mapped types. **Don't Do This:** * Inconsistently use "interface" and "type" without a clear rationale. """typescript // Good - Using interface for props interface ProductProps { name: string; price: number; description?: string; } const Product: React.FC<ProductProps> = ({ name, price, description }) => { return ( <div> <h3>{name}</h3> <p>Price: ${price}</p> {description && <p>{description}</p>} </div> ); }; // Good - Using type for union type ButtonVariant = "primary" | "secondary" | "tertiary"; interface ButtonProps { label: string; onClick: () => void; variant: ButtonVariant; } const NewButton: React.FC<ButtonProps> = ({ label, onClick, variant }) => { return ( <button className={"button ${variant}"} onClick={onClick}> {label} </button> ); }; // Bad - Inconsistent use type AnotherProductProps = { name: string; price: number; }; """ ### 3. Generics **Standard:** Use generics to create reusable components that can work with different types of data. **Why:** Generics provide type safety while maintaining flexibility, reducing the need for type casting and improving code reusability. **Do This:** * Use generics for components that operate on different data types. * Provide default type parameters when appropriate. **Don't Do This:** * Avoid using generics when they can provide better type safety. * Overuse generics, making code unnecessarily complex. """typescript // Good - Generic List component interface ListProps<T> { items: T[]; renderItem: (item: T) => React.ReactNode; } const List = <T,>({ items, renderItem }: ListProps<T>) => { return ( <ul> {items.map((item, index) => ( <li key={index}>{renderItem(item)}</li> ))} </ul> ); }; // Usage interface User { id: number; name: string; } const users: User[] = [{ id: 1, name: "John" }, { id: 2, name: "Jane" }]; const UserList = () => { return ( <List<User> items={users} renderItem={(user) => ( <div> {user.id}: {user.name} </div> )} /> ); }; // Bad - Not using generics interface NumberListProps { items: number[]; renderItem: (item: number) => React.ReactNode; } """ ### 4. Utility Types **Standard:** Utilize TypeScript's utility types ("Partial", "Readonly", "Pick", "Omit", "Record", etc.) to manipulate types effectively. **Why:** Utility types simplify type transformations and reduce boilerplate code. **Do This:** * Use "Partial<T>" to create a type where all properties of "T" are optional. * Use "Readonly<T>" to create a type where all properties of "T" are read-only. * Use "Pick<T, K>" to create a type by picking a set of properties "K" from "T". * Use "Omit<T, K>" to create a type by excluding a set of properties "K" from "T". * USE "Record<K, T>" to create a type defining an object with key type "K" and value type "T". **Don't Do This:** * Manually create types that can be derived using utility types. * Overuse utility types, leading to overly complex type definitions. """typescript // Good - Using utility types interface Task { id: number; title: string; completed: boolean; } // Partial<Task> - all props optional type PartialTask = Partial<Task>; // Readonly<Task> - all props readonly type ReadonlyTask = Readonly<Task>; // Pick<Task, 'id' | 'title'> - only id and title type TaskIdAndTitle = Pick<Task, 'id' | 'title'>; // Omit<Task, 'completed'> - all but completed type TaskWithoutCompleted = Omit<Task, 'completed'>; // Record<string, number> - object with string keys and number values type StringNumberMap = Record<string, number>; // Bad - Manually creating similar types interface BadPartialTask { id?: number; title?: string; completed?: boolean; } """ ### 5. Enums **Standard:** Use enums for defining a set of named constants, but be mindful of their limitations in TypeScript. Consider using union types with const assertions for more flexibility. **Why:** Enums provide a way to organize and document related values, improving code readability. **Do This:** * Use enums for representing a fixed set of options. * Use const enums to avoid generating unnecessary JavaScript code. **Don't Do This:** * Overuse enums when union types or literal types might be more appropriate. * Rely on enums for values that may change frequently. """typescript // Good - Using enum enum Color { Red, Green, Blue, } interface ColoredItem { name: string; color: Color; } function printColor(item: ColoredItem) { console.log("The color of ${item.name} is ${Color[item.color]}"); } const apple: ColoredItem = { name: "Apple", color: Color.Red }; printColor(apple); // const enum - inlined const enum Direction { Up, Down, Left, Right } function move(dir: Direction) { // ... } move(Direction.Left); // Access compiles directly to the number "2" with no enum object """ """typescript // Alternative with Union Types and Const Assertions (more modern approach) const Status = { OPEN: 'OPEN', IN_PROGRESS: 'IN_PROGRESS', CLOSED: 'CLOSED', } as const; type StatusType = typeof Status[keyof typeof Status]; interface Task { status: StatusType; } const newTask:Task = {status: Status.OPEN} """ ### 6. Nullability and Optional Properties **Standard:** Handle null and undefined values explicitly to prevent runtime errors. Utilize optional properties and non-null assertion operators judiciously. **Why:** Explicit handling of nullability improves code safety and reliability. **Do This:** * Use optional properties ("?") to indicate that a property may be undefined. * Use union types ("string | undefined") to allow a property to be either a specific type or undefined. * Use non-null assertion operators ("!") only when you are absolutely sure that a value is not null or undefined. **Don't Do This:** * Ignore potential null or undefined values. * Overuse non-null assertion operators without proper justification. """typescript // Good - Handling nullability interface Config { apiUrl: string; timeout?: number; // Optional property } function fetchData(config: Config) { const timeoutValue = config.timeout ?? 5000; // Default value if undefined. Nullish coalescing operator console.log("Timeout: ${timeoutValue}"); console.log("API URL: ${config.apiUrl}") } // Bad - Ignoring nullability function potentiallyReturnsNull(input: string): string | null { if (input === "error") return null return "Valid" } const result = potentiallyReturnsNull("test"); //console.log(result.toUpperCase()); // Potential error: result might be null if (result) { console.log(result.toUpperCase()) // safe } """ ### 7. React Component Specifics **Standard:** When using TypeScript with React, follow established best practices for typing components, hooks, and events. **Why:** React, combined with TypeScript, introduces its own set of type-related challenges that require specific solutions. **Do This:** * Use "React.FC" (or "React.FunctionComponent") to define functional components with type safety. Note however, that explicit props typing is frequently preferred over "React.FC" as it provides more control and readability. * Use "React.useState", "React.useEffect", and other hooks with proper type annotations. * Type event handlers correctly using "React.ChangeEvent", "React.MouseEvent", etc. **Don't Do This:** * Use JavaScript-style React components without any TypeScript annotations. * Ignore the types of event handlers or hooks. * Use "any" excessively in React components, especially for event handlers. """typescript // Good - React component with TypeScript import React, { useState, useEffect } from 'react'; interface CounterProps { initialCount: number; } const Counter: React.FC<CounterProps> = ({ initialCount }) => { const [count, setCount] = useState<number>(initialCount); useEffect(() => { console.log('Count updated:', count); }, [count]); const increment = () => { setCount((prevCount) => prevCount + 1); }; return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> </div> ); }; // Properly typed event handler const InputComponent : React.FC = () => { const [inputValue, setInputValue] = useState<string>(""); const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => { setInputValue(event.target.value); } return <input type="text" value={inputValue} onChange={handleChange} /> } // Bad - React component without TypeScript const BadCounter = (props) => { // Implicit any const [count, setCount] = useState(props.initialCount); // Implicit any useEffect(() => { console.log('Count updated:', count); }, [count]); const increment = () => { setCount(count + 1); }; return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> </div> ); }; """ ### 8. Modern ECMAScript Features **Standard**: Embrace modern ECMAScript features supported by TypeScript to write concise and expressive code. **Why:** Modern features improve code readability and reduce boilerplate, leading to more maintainable and efficient components. **Do This:** * Use arrow functions for concise function definitions, especially for callbacks. * Use destructuring to extract values from objects and arrays. * Use the spread operator ("...") to create copies of objects and arrays. * Use template literals for string interpolation. * Use optional chaining ("?.") to safely access nested properties. * Use nullish coalescing operator ("??") to provide default values for null or undefined values. **Don't Do This:** * Avoid using modern features because of unfamiliarity. * Overuse features to make code hard to understand. """typescript // Good - Modern ECMAScript features interface Person { firstName: string; lastName?: string; address?: { city: string; country: string; } } const greet = (person: Person) => { const { firstName, lastName = "Doe" } = person; // Destructuring with default value const city = person.address?.city ?? "Unknown City"; // Optional chaining and nullish coalescing return "Hello, ${firstName} ${lastName} from ${city}!"; }; const user: Person = { firstName: "John", address: { city: "New York", country: "USA" } }; console.log(greet(user)); const numbers = [1, 2, 3]; const newNumbers = [...numbers, 4, 5]; // Spread operator """ ## III. Advanced Component Design Patterns ### 1. Higher-Order Components (HOCs) **Standard:** Use HOCs to share logic between components, but be aware of the potential for prop name collisions and decreased readability. Consider alternatives like render props or hooks in modern React. **Why:** HOCs enhance code reusability by wrapping components with additional functionality. **Do This:** * Use HOCs for cross-cutting concerns like authentication, logging, or data fetching. * Ensure HOCs pass through relevant props to the wrapped component. **Don't Do This:** * Overuse HOCs, leading to deeply nested component trees. * Create HOCs that tightly couple the wrapped component to specific logic. * Shadow original props. """typescript // Good - Higher-Order Component function withLogging<P extends object>(WrappedComponent: React.ComponentType<P>) { return (props: P) => { console.log("Component is rendering:", WrappedComponent.name); return <WrappedComponent {...props} />; }; } interface MyComponentProps { name: string; } const MyComponent: React.FC<MyComponentProps> = ({ name }) => { return <div>Hello, {name}!</div>; }; const EnhancedComponent = withLogging(MyComponent); // Usage: <EnhancedComponent name="John" /> """ ### 2. Render Props **Standard:** Use render props to share rendering logic between components. Consider using hooks as a more modern and flexible alternative. **Why:** Render props provide a way to inject custom rendering behavior into a component. **Do This:** * Parameterize the render prop with the necessary data or functions. * Keep the render function pure and predictable. **Don't Do This:** * Create render props with complex side effects. * Hardcode the render prop name. """typescript // Good - Render Props interface MouseTrackerProps { render: (props: { x: number; y: number }) => React.ReactNode; } class MouseTracker extends React.Component<MouseTrackerProps> { state = { x: 0, y: 0 }; handleMouseMove = (event: React.MouseEvent) => { this.setState({ x: event.clientX, y: event.clientY, }); }; render() { return ( <div style={{ height: '100vh' }} onMouseMove={this.handleMouseMove}> {this.props.render(this.state)} </div> ); } } // Usage: // <MouseTracker render={({ x, y }) => <h1>Mouse position: {x}, {y}</h1>} /> """ ### 3. Custom Hooks **Standard:** Use custom hooks to extract stateful logic and side effects from functional components. **Why:** Custom hooks promote code reusability and simplify component logic. **Do This:** * Name custom hooks with the "use" prefix. * Use hooks to encapsulate complex state management or side effects. * Ensure custom hooks are pure and predictable. **Don't Do This:** * Call hooks outside of functional components or other hooks. * Create overly complex hooks that are difficult to maintain. """typescript // Good - Custom Hook - Fetch Data import { useState, useEffect } from 'react'; function useFetch<T>(url: string): { data: T | null; loading: boolean; error: string | null } { const [data, setData] = useState<T | null>(null); const [loading, setLoading] = useState<boolean>(true); const [error, setError] = useState<string | null>(null); useEffect(() => { const fetchData = async () => { try { const response = await fetch(url); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const json = await response.json(); setData(json); } catch (e: any) { setError(e.message); } finally { setLoading(false); } }; fetchData(); }, [url]); return { data, loading, error }; } // Usage interface Data { userId: number; id: number; title: string; completed: boolean; } function MyComponent() { const { data, loading, error } = useFetch<Data[]>('https://jsonplaceholder.typicode.com/todos'); if (loading) return <p>Loading...</p>; if (error) return <p>Error: {error}</p>; return ( <ul> {data?.map(item => ( <li key={item.id}>{item.title}</li> ))} </ul> ); } """ ## IV. Performance Optimization ### 1. Memoization **Standard:** Use "React.memo" for functional components and "shouldComponentUpdate" for class components to prevent unnecessary re-renders. **Why:** Memoization optimizes performance by skipping re-renders when the props have not changed. **Do This:** * Wrap pure functional components with "React.memo". * Implement "shouldComponentUpdate" in class components to compare props and state. **Don't Do This:** * Memoize components that are frequently updated. * Forget to compare all relevant props and state in "shouldComponentUpdate". """typescript // Good - Memoization import React from 'react'; interface MyComponentProps { name: string; onClick: () => void; } const MyComponent: React.FC<MyComponentProps> = ({ name, onClick }) => { console.log('MyComponent is rendering'); return ( <div onClick={onClick}> Hello, {name}! </div> ); }; const MemoizedComponent = React.memo(MyComponent); // Usage // <MemoizedComponent name="John" onClick={() => console.log('Clicked')} /> """ ### 2. Code Splitting **Standard:** Use dynamic "import()" statements to split code into smaller chunks that are loaded on demand. **Why:** Code splitting reduces the initial load time of the application. **Do This:** * Split large components or modules into separate chunks. * Use "React.lazy" and "Suspense" for lazy-loading components. **Don't Do This:** * Create too many small chunks, leading to excessive network requests. * Forget to provide a fallback UI while loading the chunks. """typescript // Good - Code Splitting import React, { Suspense } from 'react'; const LazyComponent = React.lazy(() => import('./MyComponent')); function MyPage() { return ( <div> <h1>My Page</h1> <Suspense fallback={<p>Loading...</p>}> <LazyComponent /> </Suspense> </div> ); } """ ## V. Security Considerations ### 1. Input Validation **Standard:** Validate all user inputs to prevent security vulnerabilities like cross-site scripting (XSS) and SQL injection. **Why:** Input validation ensures that only valid data is processed by the application. **Do This:** * Use server-side validation for critical data. * Sanitize user inputs to remove potentially harmful characters. **Don't Do This:** * Trust user inputs without validation. * Rely solely on client-side validation. ### 2. Secure Data Handling **Standard:** Store sensitive data securely and avoid exposing it in client-side code. **Why:** Secure data handling protects user information from unauthorized access. **Do This:** * Use encryption to protect sensitive data. * Store API keys and secrets securely in environment variables. * Avoid storing sensitive data in local storage or cookies. ###3. Dependency Management **Standard:** Regularly audit and update dependencies to address known security vulnerabilities. **Why:** Using outdated dependencies can expose your application to known security exploits. **Do This:** * Use tools like "npm audit" or "yarn audit" to identify vulnerabilities in your dependencies. * Regularly update dependencies to their latest versions, or apply security patches when available. """bash npm audit yarn audit """ ## VI. Conclusion Adhering to these component design standards will help developers build robust, maintainable, and efficient TypeScript applications. By focusing on reusability, maintainability, composability, and security, development teams can create high-quality software that meets the needs of their users. Continuously reviewing and updating these standards will ensure they remain relevant and effective as the TypeScript ecosystem evolves.