You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/best-practices/core-principles.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,4 +14,4 @@ This section outlines the fundamental principles for writing high-quality TypeSc
14
14
- Prioritize pure functions (predictable output for the same input, no side effects).
15
15
- Avoid mutating data directly; prefer creating new data structures (immutability).
16
16
- Use higher-order functions (`map`, `filter`, `reduce`) and function composition for data manipulation.
17
-
- Utilize libraries like `fp-ts` or `Ramda` for robust functional patterns, composition, and managing side effects, especially in complex domains. Leverage `Immer` for easier immutable state updates where applicable.
17
+
- Utilize libraries like `fp-ts` or `Ramda` for robust functional patterns, composition, and managing side effects, especially in complex domains. Leverage `Immer` for easier immutable state updates where applicable.
Copy file name to clipboardExpand all lines: docs/best-practices/structure-patterns.md
+24-22Lines changed: 24 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,36 +44,38 @@ This section details the recommended project structure for TypeScript NPM packag
44
44
## 2. Advanced TypeScript Patterns (Encouraged)
45
45
46
46
-**Immutability**:
47
-
- Use `readonly` modifiers for properties and `Readonly<T>` / `ReadonlyArray<T>` (`@typescript-eslint/prefer-readonly`).
48
-
- Leverage TypeScript's `const` assertions (`as const`) for literal types when creating immutable constants.
47
+
- Use `readonly` modifiers for properties and `Readonly<T>` / `ReadonlyArray<T>` (`@typescript-eslint/prefer-readonly`).
48
+
- Leverage TypeScript's `const` assertions (`as const`) for literal types when creating immutable constants.
49
49
-**Type Safety**:
50
-
- Use branded types or nominal typing techniques for primitive type safety where applicable (e.g., distinguishing between different kinds of string IDs).
51
-
- Prefer discriminated unions for modeling state or variants over loose objects or class hierarchies.
50
+
- Use branded types or nominal typing techniques for primitive type safety where applicable (e.g., distinguishing between different kinds of string IDs).
51
+
- Prefer discriminated unions for modeling state or variants over loose objects or class hierarchies.
52
52
-**Object Creation**:
53
-
- Implement the Builder pattern for complex object creation to ensure valid states.
54
-
- Use factory functions or static methods instead of complex constructors.
53
+
- Implement the Builder pattern for complex object creation to ensure valid states.
54
+
- Use factory functions or static methods instead of complex constructors.
55
55
-**Operations on Types**:
56
-
- Apply the Visitor pattern for type-safe operations on discriminated unions.
57
-
- Leverage Mapped Types (`Pick`, `Omit`, `Partial`, `Required`, custom) for consistent type transformations.
58
-
- Use the `satisfies` operator for ensuring type compatibility without changing the inferred type.
56
+
- Apply the Visitor pattern for type-safe operations on discriminated unions.
57
+
- Leverage Mapped Types (`Pick`, `Omit`, `Partial`, `Required`, custom) for consistent type transformations.
58
+
- Use the `satisfies` operator for ensuring type compatibility without changing the inferred type.
59
59
60
60
## 3. Best Practices
61
61
62
62
-**Error Handling**:
63
-
- Primarily use discriminated union result types (e.g., `{ success: true, data: T } | { success: false, error: E }`, potentially using helper libraries) for handling predictable errors, making failure an explicit part of the function's contract.
64
-
- Reserve throwing exceptions for truly exceptional, unrecoverable situations (e.g., programming errors, critical infrastructure failures). When throwing, use custom error classes extending `Error`.
65
-
- Always include context and potentially the original error (`cause`) when creating errors or error results.
66
-
- Validate API boundaries and external data rigorously using runtime validation libraries (like Zod, io-ts) that integrate with TypeScript types to ensure data integrity.
63
+
64
+
- Primarily use discriminated union result types (e.g., `{ success: true, data: T } | { success: false, error: E }`, potentially using helper libraries) for handling predictable errors, making failure an explicit part of the function's contract.
65
+
- Reserve throwing exceptions for truly exceptional, unrecoverable situations (e.g., programming errors, critical infrastructure failures). When throwing, use custom error classes extending `Error`.
66
+
- Always include context and potentially the original error (`cause`) when creating errors or error results.
67
+
- Validate API boundaries and external data rigorously using runtime validation libraries (like Zod, io-ts) that integrate with TypeScript types to ensure data integrity.
67
68
68
69
-**Asynchronous Code**:
69
-
- Always prefer `async/await` for readability over raw `Promise.then/catch` chains.
70
-
- Ensure all Promises are handled (use `@typescript-eslint/no-floating-promises` lint rule).
71
-
- Use `Promise.all` / `Promise.allSettled` for concurrency.
72
-
- Avoid the `new Promise()` constructor anti-pattern; use `async` functions instead.
73
-
- Implement cancellation patterns (e.g., using `AbortController`) for long-running async operations where appropriate.
70
+
71
+
- Always prefer `async/await` for readability over raw `Promise.then/catch` chains.
72
+
- Ensure all Promises are handled (use `@typescript-eslint/no-floating-promises` lint rule).
73
+
- Use `Promise.all` / `Promise.allSettled` for concurrency.
74
+
- Avoid the `new Promise()` constructor anti-pattern; use `async` functions instead.
75
+
- Implement cancellation patterns (e.g., using `AbortController`) for long-running async operations where appropriate.
74
76
75
77
-**Performance Optimizations**:
76
-
- Be mindful of object and array allocations within loops or frequently called functions.
77
-
- Use `Set` and `Map` for efficient lookups (O(1) average) compared to array methods like `find` or `includes` (O(n)).
78
-
- Employ lazy initialization for expensive resources or computations.
79
-
- Profile code using Node.js inspector or other tools to identify bottlenecks before optimizing prematurely.
78
+
- Be mindful of object and array allocations within loops or frequently called functions.
79
+
- Use `Set` and `Map` for efficient lookups (O(1) average) compared to array methods like `find` or `includes` (O(n)).
80
+
- Employ lazy initialization for expensive resources or computations.
81
+
- Profile code using Node.js inspector or other tools to identify bottlenecks before optimizing prematurely.
0 commit comments