VidyFoo/antigravity-skill-engine / .agent/skills/1-dev/fullstack-guide
fullstack-guide
Verified全栈开发规范百科全书 (React/TS/Node/Supabase). Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend/backend code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| resources/common-patterns.md | markdown | 4.8 KB |
| resources/component-patterns.md | markdown | 4.5 KB |
| resources/data-fetching.md | markdown | 5.4 KB |
| resources/file-organization.md | markdown | 4.9 KB |
| resources/loading-and-error-states.md | markdown | 5.5 KB |
| resources/resources/architecture-overview.md | markdown | 7.8 KB |
| resources/resources/async-and-errors.md | markdown | 6.1 KB |
| resources/resources/testing-guide.md | markdown | 6.9 KB |
| resources/resources/validation-patterns.md | markdown | 7.8 KB |
| resources/routing-guide.md | markdown | 4.7 KB |
| resources/styling-guide.md | markdown | 4.6 KB |
| resources/typescript-standards.md | markdown | 5.4 KB |
resources/resources/async-and-errors.md
View on GitHub# Async Patterns and Error Handling
Complete guide to async/await patterns and custom error handling.
## Table of Contents
- [Async/Await Best Practices](#asyncawait-best-practices)
- [Promise Error Handling](#promise-error-handling)
- [Custom Error Types](#custom-error-types)
- [asyncErrorWrapper Utility](#asyncerrorwrapper-utility)
- [Error Propagation](#error-propagation)
- [Common Async Pitfalls](#common-async-pitfalls)
---
## Async/Await Best Practices
### Always Use Try-Catch
```typescript
// ❌ NEVER: Unhandled async errors
async function fetchData() {
const data = await database.query(); // If throws, unhandled!
return data;
}
// ✅ ALWAYS: Wrap in try-catch
async function fetchData() {
try {
const data = await database.query();
return data;
} catch (error) {
Sentry.captureException(error);
throw error;
}
}
```
### Avoid .then() Chains
```typescript
// ❌ AVOID: Promise chains
function processData() {
return fetchData()
.then(data => transform(data))
.then(transformed => save(transformed))
.catch(error => {
console.error(error);
throw error;
});
}
// ✅ PREFER: async/await
async function processData() {
try {
const data = await fetchData();
const transformed = await transform(data);
return await save(transformed);
} catch (error) {
console.error(error);
throw error;
}
}
```
### Parallel vs Sequential
```typescript
// Sequential - slower
const user = await fetchUser(id);
const posts = await fetchPosts(id);
const comments = await fetchComments(id);
// Parallel - faster when operations are independent
const [user, posts, comments] = await Promise.all([
fetchUser(id),
fetchPosts(id),
fetchComments(id),
]);
```
---
## Custom Error Types
### Base AppError
```typescript
export class AppError extends Error {
public readonly statusCode: number;
public readonly isOperational: boolean;
public readonly details?: any;
constructor(message: string, statusCode = 500, details?: any) {
super(message);
this.statusCode = statusCode;
this.isOperational = true;
this.details = details;
Error.captureStackTrace(this, this.constructor);
}
}
```
### HTTP Errors
```typescript
export class NotFoundError extends AppError {
constructor(message = 'Resource not found') {
super(message, 404);
}
}
export class ValidationError extends AppError {
constructor(message: string, details?: any) {
super(message, 400, details);
}
}
export class UnauthorizedError extends AppError {
constructor(message = 'Unauthorized') {
super(message, 401);
}
}
export class ForbiddenError extends AppError {
constructor(message = 'Forbidden') {
super(message, 403);
}
}
export class ConflictError extends AppError {
constructor(message: string) {
super(message, 409);
}
}
```
### Usage in Services
```typescript
async function getUserById(id: string): Promise<User> {
const user = await userRepository.findById(id);
if (!user) {
throw new NotFoundError(`User ${id} not found`);
}
return user;
}
```
---
## asyncErrorWrapper Utility
### Implementation
```typescript
import { Request, Response, NextFunction, RequestHandler } from 'express';
export function asyncErrorWrapper(
fn: (req: Request, res: Response, next: NextFunction) => Promise<any>
): RequestHandler {
return (req, res, next) => {
fn(req, res, next).catch(next);
};
}
```
### Usage
```typescript
// Instead of try-catch in every route
router.get('/users/:id', asyncErrorWrapper(async (req, res) => {
const user = await userService.findById(req.params.id);
res.json(user);
}));
```
---
## Error Propagation
### Error Flow Through Layers
```
Repository throws → Service catches/re-throws → Controller handles → Response
```
### Example Flow
```typescript
// Repository
async findByEmail(email: string): Promise<User | null> {
return PrismaService.main.user.findUnique({ where: { email } });
}
// Service - business logic errors
async create(data: CreateUserDTO): Promise<User> {
const existing = await this.userRepository.findByEmail(data.email);
if (existing) {
throw new ConflictError('Email already exists'); // Throws
}
return this.userRepository.create(data);
}
// Controller - catches and handles
async create(req: Request, res: Response) {
try {
const validated = schema.parse(req.body);
const user = await this.userService.create(validated);
this.handleSuccess(res, user);
} catch (error) {
this.handleError(error, res, 'create'); // Catches
}
}
```
---
## Common Async Pitfalls
### Fire and Forget (Bad)
```typescript
// ❌ NEVER: Fire and forget
async function processRequest(req, res) {
sendEmail(user.email); // Fires async, errors unhandled!
res.json({ success: true });
}
// ✅ ALWAYS: Await or handle
async function processRequest(req, res) {
try {
await sendEmail(user.email);
res.json({ success: true });
} catch (error) {
Sentry.captureException(error);
res.status(500).json({ error: 'Failed to send email' });
}
}
// ✅ OR: Intentional background task
async function processRequest(req, res) {
sendEmail(user.email).catch(error => {
Sentry.captureException(error);
});
res.json({ success: true });
}
```
### Unhandled Rejections
```typescript
// ✅ Global handler for unhandled rejections
process.on('unhandledRejection', (reason, promise) => {
Sentry.captureException(reason, {
tags: { type: 'unhandled_rejection' }
});
console.error('Unhandled Rejection:', reason);
});
process.on('uncaughtException', (error) => {
Sentry.captureException(error, {
tags: { type: 'uncaught_exception' }
});
console.error('Uncaught Exception:', error);
process.exit(1);
});
```
---
**Related Files:**
- [SKILL.md](../SKILL.md)
- [validation-patterns.md](validation-patterns.md)
- [testing-guide.md](testing-guide.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |