AgentX typescript.instructions.md

TypeScript / Node.js Backend Instructions

Note: For React/TSX frontend code, see react.instructions.md which applies to **.tsx and **.jsx files.

Code Style

• Enable strict mode in tsconfig.json ("strict": true)
• Use ESM imports (import/export), not CommonJS (require)
• Maximum line length: 100 characters (Prettier)
• Use biome or eslint + prettier for linting and formatting

Type Safety

// [PASS] Strict typing - no `any`
interface CreateUserRequest {
 readonly email: string;
 readonly name: string;
 readonly role: "admin" | "user" | "viewer";
}

// [PASS] Use branded types for domain IDs
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

// [PASS] Use discriminated unions for state machines
type RequestState =
 | { status: "idle" }
 | { status: "loading" }
 | { status: "success"; data: Response }
 | { status: "error"; error: Error };

Naming Conventions

Type	Convention	Example
Interface	PascalCase	UserService
Type alias	PascalCase	CreateUserRequest
Function	camelCase	getUserById
Variable	camelCase	userCount
Constant	UPPER_SNAKE	MAX_RETRIES
Enum	PascalCase	HttpStatus.Ok
File	kebab-case	user-service.ts

Error Handling

// [PASS] Use custom error classes
class AppError extends Error {
 constructor(
 message: string,
 public readonly statusCode: number,
 public readonly code: string,
 ) {
 super(message);
 this.name = "AppError";
 }
}

class NotFoundError extends AppError {
 constructor(resource: string, id: string) {
 super(`${resource} with id ${id} not found`, 404, "NOT_FOUND");
 }
}

// [PASS] Catch specific errors, log and re-throw
try {
 const user = await userService.getById(id);
} catch (error) {
 if (error instanceof NotFoundError) {
 logger.warn({ error, id }, "User not found");
 return res.status(404).json({ error: error.message });
 }
 logger.error({ error }, "Unexpected error fetching user");
 throw error; // Don't swallow unknown errors
}