Copilot instructions

1---
2description: 'TypeScript and Node.js backend specific coding instructions for server-side development.'
3applyTo: '**.ts'
4---
5 
6# TypeScript / Node.js Backend Instructions
7 
8> **Note**: For React/TSX frontend code, see `react.instructions.md` which applies to `**.tsx` and `**.jsx` files.
9 
10## Code Style
11 
12- Enable strict mode in `tsconfig.json` (`"strict": true`)
13- Use ESM imports (`import`/`export`), not CommonJS (`require`)
14- Maximum line length: 100 characters (Prettier)
15- Use `biome` or `eslint` + `prettier` for linting and formatting
16 
17## Type Safety
18 
19```typescript
20// [PASS] Strict typing - no `any`
21interface CreateUserRequest {
22 readonly email: string;
23 readonly name: string;
24 readonly role: "admin" | "user" | "viewer";
25}
26 
27// [PASS] Use branded types for domain IDs
28type UserId = string & { readonly __brand: "UserId" };
29type OrderId = string & { readonly __brand: "OrderId" };
30 
31// [PASS] Use discriminated unions for state machines
32type RequestState =
33 | { status: "idle" }
34 | { status: "loading" }
35 | { status: "success"; data: Response }
36 | { status: "error"; error: Error };
37```
38 
39## Naming Conventions
40 
41| Type | Convention | Example |
42|------|------------|---------|
43| Interface | PascalCase | `UserService` |
44| Type alias | PascalCase | `CreateUserRequest` |
45| Function | camelCase | `getUserById` |
46| Variable | camelCase | `userCount` |
47| Constant | UPPER_SNAKE | `MAX_RETRIES` |
48| Enum | PascalCase | `HttpStatus.Ok` |
49| File | kebab-case | `user-service.ts` |
50 
51## Error Handling
52 
53```typescript
54// [PASS] Use custom error classes
55class AppError extends Error {
56 constructor(
57 message: string,
58 public readonly statusCode: number,
59 public readonly code: string,
60 ) {
61 super(message);
62 this.name = "AppError";
63 }
64}
65 
66class NotFoundError extends AppError {
67 constructor(resource: string, id: string) {
68 super(`${resource} with id ${id} not found`, 404, "NOT_FOUND");
69 }
70}
71 
72// [PASS] Catch specific errors, log and re-throw
73try {
74 const user = await userService.getById(id);
75} catch (error) {
76 if (error instanceof NotFoundError) {
77 logger.warn({ error, id }, "User not found");
78 return res.status(404).json({ error: error.message });
79 }
80 logger.error({ error }, "Unexpected error fetching user");
81 throw error; // Don't swallow unknown errors
82}
83```
84 
85## Async/Await
86 
87```typescript
88// [PASS] Always use async/await over raw Promises
89async function fetchUsers(ids: string[]): Promise<User[]> {
90 const results = await Promise.allSettled(
91 ids.map((id) => userRepository.findById(id)),
92 );
93 
94 return results
95 .filter((r): r is PromiseFulfilledResult<User> => r.status === "fulfilled")
96 .map((r) => r.value);
97}
98 
99// [PASS] Use AbortController for timeouts
100async function fetchWithTimeout(url: string, timeoutMs = 5000): Promise<Response> {
101 const controller = new AbortController();
102 const timeout = setTimeout(() => controller.abort(), timeoutMs);
103 
104 try {
105 return await fetch(url, { signal: controller.signal });
106 } finally {
107 clearTimeout(timeout);
108 }
109}
110```
111 
112## Project Structure (Backend)
113 
114```
115src/
116+-- routes/ # Route definitions (Express/Fastify/Hono)
117+-- controllers/ # Request handling (thin - delegates to services)
118+-- services/ # Business logic
119+-- repositories/ # Data access layer
120+-- middleware/ # Auth, logging, error handling
121+-- types/ # Shared TypeScript types/interfaces
122+-- utils/ # Pure utility functions
123+-- config/ # Environment and app configuration
124-- index.ts # Application entry point
125```
126 
127## Dependency Injection
128 
129```typescript
130// [PASS] Constructor injection with interfaces
131interface UserRepository {
132 findById(id: string): Promise<User | null>;
133 create(data: CreateUserRequest): Promise<User>;
134}
135 
136class UserService {
137 constructor(
138 private readonly userRepo: UserRepository,
139 private readonly logger: Logger,
140 ) {}
141 
142 async getById(id: string): Promise<User> {
143 const user = await this.userRepo.findById(id);
144 if (!user) throw new NotFoundError("User", id);
145 return user;
146 }
147}
148```
149 
150## Environment Configuration
151 
152```typescript
153// [PASS] Validate env at startup, fail fast
154import { z } from "zod";
155 
156const envSchema = z.object({
157 NODE_ENV: z.enum(["development", "production", "test"]),
158 PORT: z.coerce.number().default(3000),
159 DATABASE_URL: z.string().url(),
160 API_KEY: z.string().min(1),
161});
162 
163export const env = envSchema.parse(process.env);
164```
165 
166## Testing
167 
168- Use **Vitest** (preferred) or Jest for unit/integration tests
169- Use **Supertest** for HTTP endpoint testing
170- Name tests: `describe("UserService")` -> `it("should return user by id")`
171- Mock external dependencies, never call live APIs in tests
172 
173```typescript
174import { describe, it, expect, vi } from "vitest";
175 
176describe("UserService", () => {
177 it("should return user by id", async () => {
178 const mockRepo: UserRepository = {
179 findById: vi.fn().mockResolvedValue({ id: "1", name: "Test" }),
180 create: vi.fn(),
181 };
182 
183 const service = new UserService(mockRepo, mockLogger);
184 const user = await service.getById("1");
185 
186 expect(user.name).toBe("Test");
187 expect(mockRepo.findById).toHaveBeenCalledWith("1");
188 });
189 
190 it("should throw NotFoundError when user missing", async () => {
191 const mockRepo: UserRepository = {
192 findById: vi.fn().mockResolvedValue(null),
193 create: vi.fn(),
194 };
195 
196 const service = new UserService(mockRepo, mockLogger);
197 
198 await expect(service.getById("999")).rejects.toThrow(NotFoundError);
199 });
200});
201```
202 
203## Security
204 
205- Validate all inputs with `zod` schemas at the boundary (routes/controllers)
206- Use `helmet` middleware for HTTP security headers
207- Use `cors` with explicit origin allowlists (never `*` in production)
208- Rate limit API endpoints (`express-rate-limit` or framework equivalent)
209- Never log sensitive data (passwords, tokens, PII)
210